NameGuard / NameReservers

NameReservers 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.

It is ideal for platforms where you want to prevent users from choosing restricted names such as admin, root, system words, or any sensitive identifiers.

Table of Contents

1. Installation
2. Usage
3. Creating a Guard
4. Rule System
5. API Methods
6. Advanced Examples
7. Bypass System
8. Debug Helpers
9. Edge Cases
10. Contribution

Installation

npm install @uhpenry/guard-names
# or
yarn add @uhpenry/guard-names

# or
pnpm add @uhpenry/guard-names

Usage

import { NameReservers } from '@uhpenry/guard-names';

// Create a new guard
const guard = new NameReservers(['admin*', '*panel', '*test*']);

Creating a Guard

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,
  }
);

Parameters

• 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

isReserved(name: string): boolean

Checks if a name is reserved.

guard.isReserved('admin'); // true
guard.isReserved('systempanel'); // false if bypassed

getBlockingRule(name: string): Rule | null

Returns the rule that blocks a given name, or null if none.

guard.getBlockingRule('admin123');
// { pattern: 'admin', mode: 'prefix' }

getReserved(includeNewLists?: boolean): Rule[]

Returns all active rules (excluding bypassed rules). includeNewLists – if true, also includes user-added rules.

guard.getReserved(); // Returns active normalized rules

getAllReservesCsv(includeNewLists?: boolean): string

Returns all active rules as a comma-separated string.

guard.getAllReservesCsv(); // "root,admin,panel,..."

getAllReservesPlainText(includeNewLists?: boolean): string

Returns all active rules as plain text, one per line.

guard.getAllReservesPlainText();
/*
root
admin
panel
...
*/

getAllReservesJson(includeNewLists?: boolean): string[]

Returns all active rules as a JSON array of strings (patterns).

guard.getAllReservesJson();
// ["root","admin","panel",...]

getUserAdded(): Rule[]

Returns only custom rules added by the user.

getBypassList(): string[]

Returns the list of rules in the bypass list.

getIncludeBypass(): boolean

Returns whether the guard ignores the bypass list (true) or not (false).

Advanced Examples

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:

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

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:

git clone https://github.com/uhpenry/guard-names.git
pnpm install
pnpm log