A lightweight utility for validating and blocking reserved names.
npm install @uhpenry/guard-namesNameReservers is a TypeScript/JavaScript utility for managing and validating reserved names, usernames, or strings in your application. It supports exact matches, prefix/suffix rules, contains rules, and regex rules, along with a bypass system for flexible exclusions.
bash
npm install @uhpenry/guard-names
or
yarn add @uhpenry/guard-names
or
pnpm add @uhpenry/guard-names
`
---
Usage
`ts
import { NameReservers } from '@uhpenry/guard-names';
// Create a new guard
const guard = new NameReservers(['admin', 'panel', 'test']);
`
---
Creating a Guard
`ts
import { NameReservers } from '@uhpenry/guard-names';
const guard = new NameReservers(
[
'root', // Exact match
'admin*', // Prefix match
'*panel', // Suffix match
'sys', // Contains match
{ pattern: '^test[0-9]+$', mode: 'regex' }, // Regex match
],
[
'*panel', // bypass list
],
{
includeBypass: false,
}
);
`
$3
- newList – array of rules to add (strings with wildcards or objects with pattern and mode)
- bypassList – array of strings to bypass unless includeBypass = true
- options.includeBypass – if true, bypass rules are ignored
---
Rule System
NameReservers supports 5 types of rules:
| Mode | Format Example | Description |
| -------- | ------------------------------------------ | ------------------------------------------------------ |
| exact | "admin" | Blocks only the exact name "admin" |
| prefix | "admin*" | Blocks any name starting with "admin" |
| suffix | "*panel" | Blocks any name ending with "panel" |
| contains | "sys" | Blocks any name containing "sys" anywhere inside |
| regex | {pattern: '^test[0-9]+$', mode: 'regex'} | Blocks any name matching a custom regular expression |
- ⚠️ Prefix = "admin*" → blocks "admin123"
- ⚠️ Suffix = "*panel" → blocks "controlpanel"
- ⚠️ Contains = "sys" → blocks "mysystem"
---
API Methods
$3
Checks if a name is reserved.
`ts
guard.isReserved('admin'); // true
guard.isReserved('systempanel'); // false if bypassed
`
---
$3
Returns the rule that blocks a given name, or null if none.
`ts
guard.getBlockingRule('admin123');
// { pattern: 'admin', mode: 'prefix' }
`
---
$3
Returns all active rules (excluding bypassed rules).
includeNewLists – if true, also includes user-added rules.
`ts
guard.getReserved(); // Returns active normalized rules
`
---
$3
Returns all active rules as a comma-separated string.
`ts
guard.getAllReservesCsv(); // "root,admin,panel,..."
`
---
$3
Returns all active rules as plain text, one per line.
`ts
guard.getAllReservesPlainText();
/*
root
admin
panel
...
*/
`
---
$3
Returns all active rules as a JSON array of strings (patterns).
`ts
guard.getAllReservesJson();
// ["root","admin","panel",...]
`
---
$3
Returns only custom rules added by the user.
---
$3
Returns the list of rules in the bypass list.
---
$3
Returns whether the guard ignores the bypass list (true) or not (false).
---
Advanced Examples
`ts
const guard = new NameReservers(
['admin', 'panel', 'test', { pattern: '^user[0-9]+$', mode: 'regex' }],
['*panel'],
{ includeBypass: false }
);
// Exact match
console.log(guard.isReserved('root')); // true
// Prefix match
console.log(guard.isReserved('admin123')); // true
// Suffix match
console.log(guard.isReserved('controlpanel')); // false (bypassed)
// Contains match
console.log(guard.isReserved('mysystem')); // true
// Regex match
console.log(guard.isReserved('user42')); // true
`
---
Bypass System
The bypass system allows you to ignore certain rules:
`ts
const guard = new NameReservers(['panel'], ['panel'], {
includeBypass: false,
});
console.log(guard.isReserved('controlpanel')); // false → bypassed
const guard2 = new NameReservers(['panel'], ['panel'], {
includeBypass: true,
});
console.log(guard2.isReserved('controlpanel')); // true → bypass ignored
`
---
Debug Helpers
`ts
guard.getUserAdded(); // returns user-added rules
guard.getBypassList(); // returns bypass list
guard.getIncludeBypass(); // returns true/false
`
---
Edge Cases
- Case insensitive: "Admin" is treated the same as "admin"
- Multiple matches: the first rule that applies blocks the name
- Regex rules must be valid JS regex
- Bypass list only affects active rules unless includeBypass = true
---
Contribution
If you want to improve NameReservers:
`bash
git clone https://github.com/uhpenry/guard-names.git
pnpm install
pnpm log
``