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