namespace-guard 0.8.2 → 0.11.0

package/README.md

@@ -5,7 +5,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**[Live Demo](https://paultendo.github.io/namespace-guard/)** — try it in your browser | **[Blog Post](https://paultendo.github.io/posts/namespace-guard-launch/)** — why this exists
+**[Live Demo](https://paultendo.github.io/namespace-guard/)** - try it in your browser | **[Blog Post](https://paultendo.github.io/posts/namespace-guard-launch/)** - why this exists
 
 **Check slug/handle uniqueness across multiple database tables with reserved name protection.**
 
@@ -92,6 +92,8 @@ const adapter = createPrismaAdapter(prisma);
 
 ### Drizzle
 
+> **Note:** The Drizzle adapter uses `db.query` (the relational query API). Make sure your Drizzle client is set up with `drizzle(client, { schema })` so that `db.query.<tableName>` is available.
+
 ```typescript
 import { eq } from "drizzle-orm";
 import { createDrizzleAdapter } from "namespace-guard/adapters/drizzle";
@@ -163,7 +165,9 @@ import { User, Organization } from "./models";
 const adapter = createMongooseAdapter({ user: User, organization: Organization });
 ```
 
-### Raw SQL (pg, mysql2, etc.)
+### Raw SQL (pg, mysql2, better-sqlite3, etc.)
+
+The raw adapter generates PostgreSQL-style SQL (`$1` placeholders, double-quoted identifiers). For pg this works directly. For MySQL or SQLite, translate the parameter syntax in your executor wrapper.
 
 ```typescript
 import { Pool } from "pg";
@@ -173,6 +177,34 @@ const pool = new Pool();
 const adapter = createRawAdapter((sql, params) => pool.query(sql, params));
 ```
 
+**MySQL2 wrapper** (translates `$1` to `?` and `"col"` to `` `col` ``):
+
+```typescript
+import mysql from "mysql2/promise";
+import { createRawAdapter } from "namespace-guard/adapters/raw";
+
+const pool = mysql.createPool({ uri: process.env.DATABASE_URL });
+const adapter = createRawAdapter(async (sql, params) => {
+  const mysqlSql = sql.replace(/\$\d+/g, "?").replace(/"/g, "`");
+  const [rows] = await pool.execute(mysqlSql, params);
+  return { rows: rows as Record<string, unknown>[] };
+});
+```
+
+**better-sqlite3 wrapper** (translates `$1` to `?` and strips identifier quotes):
+
+```typescript
+import Database from "better-sqlite3";
+import { createRawAdapter } from "namespace-guard/adapters/raw";
+
+const db = new Database("app.db");
+const adapter = createRawAdapter(async (sql, params) => {
+  const sqliteSql = sql.replace(/\$\d+/g, "?").replace(/"/g, "");
+  const rows = db.prepare(sqliteSql).all(...params);
+  return { rows: rows as Record<string, unknown>[] };
+});
+```
+
 ## Configuration
 
 ```typescript
@@ -249,7 +281,7 @@ const result = await guard.check("admin");
 // { available: false, reason: "reserved", category: "system", message: "That's a system route." }
 ```
 
-You can also use a single string message for all categories, or mix — categories without a specific message fall back to the default.
+You can also use a single string message for all categories, or mix - categories without a specific message fall back to the default.
 
 ## Async Validators
 
@@ -279,7 +311,7 @@ Validators run sequentially and stop at the first rejection. They receive the no
 
 ### Built-in Profanity Validator
 
-Use `createProfanityValidator` for a turnkey profanity filter — supply your own word list:
+Use `createProfanityValidator` for a turnkey profanity filter - supply your own word list:
 
 ```typescript
 import { createNamespaceGuard, createProfanityValidator } from "namespace-guard";
@@ -295,7 +327,7 @@ const guard = createNamespaceGuard({
 }, adapter);
 ```
 
-No words are bundled — use any word list you like (e.g., the `bad-words` npm package, your own list, or an external API wrapped in a custom validator).
+No words are bundled - use any word list you like (e.g., the `bad-words` npm package, your own list, or an external API wrapped in a custom validator).
 
 ### Built-in Homoglyph Validator
 
@@ -324,6 +356,44 @@ createHomoglyphValidator({
 
 The built-in `CONFUSABLE_MAP` contains 613 character pairs generated from [Unicode TR39 confusables.txt](https://unicode.org/reports/tr39/) plus supplemental Latin small capitals. It covers Cyrillic, Greek, Armenian, Cherokee, IPA, Coptic, Lisu, Canadian Syllabics, Georgian, and 20+ other scripts. The map is exported for inspection or extension, and is regenerable for new Unicode versions with `npx tsx scripts/generate-confusables.ts`.
 
+#### CONFUSABLE_MAP_FULL
+
+For standalone use without NFKC normalization, `CONFUSABLE_MAP_FULL` (~1,400 entries) includes every single-character-to-Latin mapping from TR39 with no NFKC filtering. This is the right map when your pipeline does not run NFKC before confusable detection, which is the case for most real-world systems: TR39's skeleton algorithm uses NFD, Chromium's IDN spoof checker uses NFD, Rust's `confusable_idents` lint runs on NFC, and django-registration applies the confusable map to raw input with no normalization at all.
+
+```typescript
+import { CONFUSABLE_MAP_FULL } from "namespace-guard";
+
+// Contains everything in CONFUSABLE_MAP, plus:
+// - ~766 entries where NFKC agrees with TR39 (mathematical alphanumerics, fullwidth forms)
+// - 31 entries where TR39 and NFKC disagree on the target letter
+CONFUSABLE_MAP_FULL["\u017f"]; // "f" (Long S: TR39 visual mapping)
+CONFUSABLE_MAP_FULL["\u{1D41A}"]; // "a" (Mathematical Bold Small A)
+```
+
+#### `skeleton()` and `areConfusable()`
+
+The TR39 Section 4 skeleton algorithm computes a normalized form of a string for confusable comparison. Two strings that look alike will produce the same skeleton. This is the same algorithm used by ICU's SpoofChecker, Chromium's IDN spoof checker, and the Rust compiler's `confusable_idents` lint.
+
+```typescript
+import { skeleton, areConfusable, CONFUSABLE_MAP } from "namespace-guard";
+
+// Compute skeletons for comparison
+skeleton("paypal");           // "paypal"
+skeleton("\u0440\u0430ypal"); // "paypal" (Cyrillic р and а)
+skeleton("pay\u200Bpal");     // "paypal" (zero-width space stripped)
+skeleton("\u017f");            // "f"      (Long S via TR39 visual mapping)
+
+// Compare two strings directly
+areConfusable("paypal", "\u0440\u0430ypal"); // true
+areConfusable("google", "g\u043e\u043egle"); // true  (Cyrillic о)
+areConfusable("hello", "world");             // false
+
+// Use CONFUSABLE_MAP for NFKC-first pipelines
+skeleton("\u017f", { map: CONFUSABLE_MAP }); // "\u017f" (Long S not in filtered map)
+```
+
+By default, `skeleton()` uses `CONFUSABLE_MAP_FULL` (the complete TR39 map), which matches the NFD-based pipeline specified by TR39. Pass `{ map: CONFUSABLE_MAP }` if your pipeline runs NFKC normalization before calling `skeleton()`.
+
 ### How the anti-spoofing pipeline works
 
 Most confusable-detection libraries apply a character map in isolation. namespace-guard uses a three-stage pipeline where each stage is aware of the others:
@@ -335,13 +405,13 @@ Input  →  NFKC normalize  →  Confusable map  →  Mixed-script reject
 
 **Stage 1: NFKC normalization** collapses full-width characters (`Ｉ` → `I`), ligatures (`fi` → `fi`), superscripts, and other Unicode compatibility forms to their canonical equivalents. This runs first, before any confusable check.
 
-**Stage 2: Confusable map** catches characters that survive NFKC but visually mimic Latin letters — Cyrillic `а` for `a`, Greek `ο` for `o`, Cherokee `Ꭺ` for `A`, and 600+ others from the Unicode Consortium's [confusables.txt](https://unicode.org/Public/security/latest/confusables.txt).
+**Stage 2: Confusable map** catches characters that survive NFKC but visually mimic Latin letters - Cyrillic `а` for `a`, Greek `ο` for `o`, Cherokee `Ꭺ` for `A`, and 600+ others from the Unicode Consortium's [confusables.txt](https://unicode.org/Public/security/latest/confusables.txt).
 
 **Stage 3: Mixed-script rejection** (`rejectMixedScript: true`) blocks identifiers that mix Latin with non-Latin scripts (Hebrew, Arabic, Devanagari, Thai, Georgian, Ethiopic, etc.) even if the specific characters aren't in the confusable map. This catches novel homoglyphs that the map doesn't cover.
 
 #### Why NFKC-aware filtering matters
 
-The key insight: TR39's confusables.txt and NFKC normalization sometimes disagree. For example, Unicode says capital `I` (U+0049) is confusable with lowercase `l` — visually true in many fonts. But NFKC maps Mathematical Bold `𝐈` (U+1D408) to `I`, not `l`. If you naively ship the TR39 mapping (`𝐈` → `l`), the confusable check will never see that character — NFKC already converted it to `I` in stage 1.
+The key insight: TR39's confusables.txt and NFKC normalization sometimes disagree. For example, Unicode says capital `I` (U+0049) is confusable with lowercase `l` - visually true in many fonts. But NFKC maps Mathematical Bold `𝐈` (U+1D408) to `I`, not `l`. If you naively ship the TR39 mapping (`𝐈` → `l`), the confusable check will never see that character - NFKC already converted it to `I` in stage 1.
 
 We found 31 entries where this happens:
 
@@ -354,7 +424,7 @@ We found 31 entries where this happens:
 | 11 Mathematical I variants | `l` | `i` | NFKC |
 | 12 Mathematical 0/1 variants | `o`/`l` | `0`/`1` | NFKC |
 
-These entries are dead code in any pipeline that runs NFKC first — and worse, they encode the *wrong* mapping. The generate script (`scripts/generate-confusables.ts`) automatically detects and excludes them.
+These entries are dead code in any pipeline that runs NFKC first - and worse, they encode the *wrong* mapping. The generate script (`scripts/generate-confusables.ts`) automatically detects and excludes them.
 
 ## Unicode Normalization
 
@@ -429,7 +499,7 @@ const result = await guard.check("acme-corp");
 
 ### Composing Strategies
 
-Combine multiple strategies — candidates are interleaved round-robin:
+Combine multiple strategies - candidates are interleaved round-robin:
 
 ```typescript
 suggest: {
@@ -503,10 +573,10 @@ npx namespace-guard check acme-corp
 # ✓ acme-corp is available
 
 npx namespace-guard check admin
-# ✗ admin — That name is reserved. Try another one.
+# ✗ admin - That name is reserved. Try another one.
 
 npx namespace-guard check "a"
-# ✗ a — Use 2-30 lowercase letters, numbers, or hyphens.
+# ✗ a - Use 2-30 lowercase letters, numbers, or hyphens.
 ```
 
 ### With a config file
@@ -585,9 +655,16 @@ Check if an identifier is available.
 
 ---
 
-### `guard.checkMany(identifiers, scope?)`
+### `guard.checkMany(identifiers, scope?, options?)`
+
+Check multiple identifiers in parallel. Suggestions are skipped by default for performance.
 
-Check multiple identifiers in parallel.
+**Parameters:**
+- `identifiers` - Array of slugs/handles to check
+- `scope` - Optional ownership scope applied to all checks
+- `options` - Optional `{ skipSuggestions?: boolean }` (default: `true`)
+
+Pass `{ skipSuggestions: false }` to include suggestions for taken identifiers.
 
 **Returns:** `Record<string, CheckResult>`
 
@@ -601,9 +678,37 @@ Same as `check()`, but throws an `Error` if not available.
 
 ### `guard.validateFormat(identifier)`
 
-Validate format only (no database queries).
+Validate format, purely-numeric restriction, and reserved name status without querying the database.
+
+**Returns:** Error message string if invalid or reserved, `null` if OK.
+
+---
+
+### `guard.validateFormatOnly(identifier)`
+
+Validate only the identifier's format and purely-numeric restriction. Does not check reserved names or query the database. Useful for instant client-side feedback on input shape.
+
+**Returns:** Error message string if the format is invalid, `null` if OK.
+
+---
+
+### `guard.normalize(identifier)`
+
+Convenience re-export of the standalone `normalize()` function. Note: always applies NFKC normalization regardless of the guard's `normalizeUnicode` setting. Use `normalize(id, { unicode: false })` directly if you need to skip NFKC.
+
+---
+
+### `guard.clearCache()`
+
+Clear the in-memory cache and reset hit/miss counters. No-op if caching is not enabled.
+
+---
+
+### `guard.cacheStats()`
+
+Get cache performance statistics.
 
-**Returns:** Error message string if invalid, `null` if valid.
+**Returns:** `{ size: number; hits: number; misses: number }`
 
 ---
 
@@ -761,7 +866,10 @@ import {
   createNamespaceGuard,
   createProfanityValidator,
   createHomoglyphValidator,
+  skeleton,
+  areConfusable,
   CONFUSABLE_MAP,
+  CONFUSABLE_MAP_FULL,
   normalize,
   type NamespaceConfig,
   type NamespaceSource,
@@ -771,6 +879,8 @@ import {
   type FindOneOptions,
   type OwnershipScope,
   type SuggestStrategyName,
+  type SkeletonOptions,
+  type CheckManyOptions,
 } from "namespace-guard";
 ```
 

package/dist/cli.js

@@ -339,6 +339,16 @@ function createNamespaceGuard(config, adapter) {
     }
     return null;
   }
+  function validateFormatOnly(identifier) {
+    const normalized = normalize(identifier, normalizeOpts);
+    if (!pattern.test(normalized)) {
+      return invalidMsg;
+    }
+    if (!allowPurelyNumeric && /^\d+(-\d+)*$/.test(normalized)) {
+      return purelyNumericMsg;
+    }
+    return null;
+  }
   function isOwnedByScope(existing, source, scope) {
     if (!source.scopeKey) return false;
     const scopeValue = scope[source.scopeKey];
@@ -457,10 +467,11 @@ function createNamespaceGuard(config, adapter) {
       throw new Error(result.message);
     }
   }
-  async function checkMany(identifiers, scope = {}) {
+  async function checkMany(identifiers, scope = {}, options) {
+    const skip = options?.skipSuggestions ?? true;
     const entries = await Promise.all(
       identifiers.map(async (id) => {
-        const result = await check(id, scope, { skipSuggestions: true });
+        const result = await check(id, scope, { skipSuggestions: skip });
         return [id, result];
       })
     );
@@ -477,6 +488,7 @@ function createNamespaceGuard(config, adapter) {
   return {
     normalize,
     validateFormat,
+    validateFormatOnly,
     check,
     assertAvailable,
     checkMany,

package/dist/cli.mjs

@@ -316,6 +316,16 @@ function createNamespaceGuard(config, adapter) {
     }
     return null;
   }
+  function validateFormatOnly(identifier) {
+    const normalized = normalize(identifier, normalizeOpts);
+    if (!pattern.test(normalized)) {
+      return invalidMsg;
+    }
+    if (!allowPurelyNumeric && /^\d+(-\d+)*$/.test(normalized)) {
+      return purelyNumericMsg;
+    }
+    return null;
+  }
   function isOwnedByScope(existing, source, scope) {
     if (!source.scopeKey) return false;
     const scopeValue = scope[source.scopeKey];
@@ -434,10 +444,11 @@ function createNamespaceGuard(config, adapter) {
       throw new Error(result.message);
     }
   }
-  async function checkMany(identifiers, scope = {}) {
+  async function checkMany(identifiers, scope = {}, options) {
+    const skip = options?.skipSuggestions ?? true;
     const entries = await Promise.all(
       identifiers.map(async (id) => {
-        const result = await check(id, scope, { skipSuggestions: true });
+        const result = await check(id, scope, { skipSuggestions: skip });
         return [id, result];
       })
     );
@@ -454,6 +465,7 @@ function createNamespaceGuard(config, adapter) {
   return {
     normalize,
     validateFormat,
+    validateFormatOnly,
     check,
     assertAvailable,
     checkMany,

package/dist/index.d.mts

@@ -6,14 +6,14 @@ type NamespaceSource = {
     column: string;
     /** Column name for the primary key (default: "id", or "_id" for Mongoose) */
     idColumn?: string;
-    /** Scope key for ownership checks — allows users to update their own slug without a false collision */
+    /** Scope key for ownership checks - allows users to update their own slug without a false collision */
     scopeKey?: string;
 };
 /** Built-in suggestion strategy names. */
 type SuggestStrategyName = "sequential" | "random-digits" | "suffix-words" | "short-random" | "scramble" | "similar";
 /** Configuration for a namespace guard instance. */
 type NamespaceConfig = {
-    /** Reserved names — flat list, Set, or categorized record */
+    /** Reserved names - flat list, Set, or categorized record */
     reserved?: Set<string> | string[] | Record<string, string[]>;
     /** Data sources to check for collisions */
     sources: NamespaceSource[];
@@ -35,7 +35,7 @@ type NamespaceConfig = {
         /** Message shown when a purely numeric identifier is rejected (default: "Identifiers cannot be purely numeric.") */
         purelyNumeric?: string;
     };
-    /** Async validation hooks — run after format/reserved checks, before DB */
+    /** Async validation hooks - run after format/reserved checks, before DB */
     validators?: Array<(value: string) => Promise<{
         available: false;
         message: string;
@@ -62,7 +62,7 @@ type FindOneOptions = {
     /** Use case-insensitive matching */
     caseInsensitive?: boolean;
 };
-/** Database adapter interface — implement this for your ORM or query builder. */
+/** Database adapter interface - implement this for your ORM or query builder. */
 type NamespaceAdapter = {
     findOne: (source: NamespaceSource, value: string, options?: FindOneOptions) => Promise<Record<string, unknown> | null>;
 };
@@ -82,6 +82,18 @@ type CheckResult = {
     category?: string;
     suggestions?: string[];
 };
+/** Options for `checkMany()`. */
+type CheckManyOptions = {
+    /** Skip suggestion generation for taken identifiers (default: `true`). */
+    skipSuggestions?: boolean;
+};
+/** Options for the `skeleton()` and `areConfusable()` functions. */
+type SkeletonOptions = {
+    /** Confusable character map to use.
+     *  Default: `CONFUSABLE_MAP_FULL` (complete TR39 map, no NFKC filtering).
+     *  Pass `CONFUSABLE_MAP` if your pipeline runs NFKC before calling skeleton(). */
+    map?: Record<string, string>;
+};
 /**
  * Normalize a raw identifier: trims whitespace, applies NFKC Unicode normalization,
  * lowercases, and strips leading `@` symbols.
@@ -108,7 +120,7 @@ declare function normalize(raw: string, options?: {
 /**
  * Create a validator that rejects identifiers containing profanity or offensive words.
  *
- * Supply your own word list — no words are bundled with the library.
+ * Supply your own word list - no words are bundled with the library.
  * The returned function is compatible with `config.validators`.
  *
  * @param words - Array of words to block
@@ -146,6 +158,22 @@ declare function createProfanityValidator(words: string[], options?: {
  * Regenerate: `npx tsx scripts/generate-confusables.ts`
  */
 declare const CONFUSABLE_MAP: Record<string, string>;
+/**
+ * Complete TR39 confusable mapping: every single-character mapping to a
+ * lowercase Latin letter or digit from confusables.txt, with no NFKC filtering.
+ *
+ * Use this when your pipeline does NOT run NFKC normalization before confusable
+ * detection (which is most real-world systems: TR39 skeleton uses NFD, Chromium
+ * uses NFD, Rust uses NFC, django-registration uses no normalization at all).
+ *
+ * Includes ~1,400 entries vs CONFUSABLE_MAP's ~613 NFKC-deduped entries.
+ * The additional entries cover characters that NFKC normalization would handle
+ * (mathematical alphanumerics, fullwidth forms, etc.) plus the 31 entries where
+ * TR39 and NFKC disagree on the target letter.
+ *
+ * Regenerate: `npx tsx scripts/generate-confusables.ts`
+ */
+declare const CONFUSABLE_MAP_FULL: Record<string, string>;
 /**
  * Create a validator that rejects identifiers containing homoglyph/confusable characters.
  *
@@ -179,13 +207,55 @@ declare function createHomoglyphValidator(options?: {
     available: false;
     message: string;
 } | null>;
+/**
+ * Compute the TR39 Section 4 skeleton of a string for confusable comparison.
+ *
+ * Implements `internalSkeleton`:
+ * 1. NFD normalize
+ * 2. Remove Default_Ignorable_Code_Point characters
+ * 3. Replace each character via the confusable map
+ * 4. Reapply NFD
+ * 5. Lowercase
+ *
+ * The default map is `CONFUSABLE_MAP_FULL` (the complete TR39 mapping without
+ * NFKC filtering), which matches the NFD-based pipeline used by ICU, Chromium,
+ * and the TR39 spec itself. Pass `{ map: CONFUSABLE_MAP }` if your pipeline
+ * runs NFKC normalization before calling skeleton().
+ *
+ * @param input - The string to skeletonize
+ * @param options - Optional settings (custom confusable map)
+ * @returns The skeleton string for comparison
+ *
+ * @example
+ * ```ts
+ * skeleton("paypal") === skeleton("\u0440\u0430ypal") // true (Cyrillic р/а)
+ * skeleton("pay\u200Bpal") === skeleton("paypal")     // true (zero-width stripped)
+ * ```
+ */
+declare function skeleton(input: string, options?: SkeletonOptions): string;
+/**
+ * Check whether two strings are visually confusable by comparing their TR39 skeletons.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @param options - Optional settings (custom confusable map)
+ * @returns `true` if the strings produce the same skeleton
+ *
+ * @example
+ * ```ts
+ * areConfusable("paypal", "\u0440\u0430ypal") // true
+ * areConfusable("google", "g\u043e\u043egle") // true
+ * areConfusable("hello", "world")             // false
+ * ```
+ */
+declare function areConfusable(a: string, b: string, options?: SkeletonOptions): boolean;
 /**
  * Create a namespace guard instance for checking slug/handle uniqueness
  * across multiple database tables with reserved name protection.
  *
  * @param config - Reserved names, data sources, validation pattern, and optional features
  * @param adapter - Database adapter implementing the `findOne` lookup (use a built-in adapter or write your own)
- * @returns A guard with `check`, `checkMany`, `assertAvailable`, `validateFormat`, `clearCache`, and `cacheStats` methods
+ * @returns A guard with `check`, `checkMany`, `assertAvailable`, `validateFormat`, `validateFormatOnly`, `clearCache`, and `cacheStats` methods
  *
  * @example
  * ```ts
@@ -212,11 +282,12 @@ declare function createHomoglyphValidator(options?: {
 declare function createNamespaceGuard(config: NamespaceConfig, adapter: NamespaceAdapter): {
     normalize: typeof normalize;
     validateFormat: (identifier: string) => string | null;
+    validateFormatOnly: (identifier: string) => string | null;
     check: (identifier: string, scope?: OwnershipScope, options?: {
         skipSuggestions?: boolean;
     }) => Promise<CheckResult>;
     assertAvailable: (identifier: string, scope?: OwnershipScope) => Promise<void>;
-    checkMany: (identifiers: string[], scope?: OwnershipScope) => Promise<Record<string, CheckResult>>;
+    checkMany: (identifiers: string[], scope?: OwnershipScope, options?: CheckManyOptions) => Promise<Record<string, CheckResult>>;
     clearCache: () => void;
     cacheStats: () => {
         size: number;
@@ -227,4 +298,4 @@ declare function createNamespaceGuard(config: NamespaceConfig, adapter: Namespac
 /** The guard instance returned by `createNamespaceGuard`. */
 type NamespaceGuard = ReturnType<typeof createNamespaceGuard>;
 
-export { CONFUSABLE_MAP, type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, type SuggestStrategyName, createHomoglyphValidator, createNamespaceGuard, createProfanityValidator, normalize };
+export { CONFUSABLE_MAP, CONFUSABLE_MAP_FULL, type CheckManyOptions, type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, type SkeletonOptions, type SuggestStrategyName, areConfusable, createHomoglyphValidator, createNamespaceGuard, createProfanityValidator, normalize, skeleton };

package/dist/index.d.ts

@@ -6,14 +6,14 @@ type NamespaceSource = {
     column: string;
     /** Column name for the primary key (default: "id", or "_id" for Mongoose) */
     idColumn?: string;
-    /** Scope key for ownership checks — allows users to update their own slug without a false collision */
+    /** Scope key for ownership checks - allows users to update their own slug without a false collision */
     scopeKey?: string;
 };
 /** Built-in suggestion strategy names. */
 type SuggestStrategyName = "sequential" | "random-digits" | "suffix-words" | "short-random" | "scramble" | "similar";
 /** Configuration for a namespace guard instance. */
 type NamespaceConfig = {
-    /** Reserved names — flat list, Set, or categorized record */
+    /** Reserved names - flat list, Set, or categorized record */
     reserved?: Set<string> | string[] | Record<string, string[]>;
     /** Data sources to check for collisions */
     sources: NamespaceSource[];
@@ -35,7 +35,7 @@ type NamespaceConfig = {
         /** Message shown when a purely numeric identifier is rejected (default: "Identifiers cannot be purely numeric.") */
         purelyNumeric?: string;
     };
-    /** Async validation hooks — run after format/reserved checks, before DB */
+    /** Async validation hooks - run after format/reserved checks, before DB */
     validators?: Array<(value: string) => Promise<{
         available: false;
         message: string;
@@ -62,7 +62,7 @@ type FindOneOptions = {
     /** Use case-insensitive matching */
     caseInsensitive?: boolean;
 };
-/** Database adapter interface — implement this for your ORM or query builder. */
+/** Database adapter interface - implement this for your ORM or query builder. */
 type NamespaceAdapter = {
     findOne: (source: NamespaceSource, value: string, options?: FindOneOptions) => Promise<Record<string, unknown> | null>;
 };
@@ -82,6 +82,18 @@ type CheckResult = {
     category?: string;
     suggestions?: string[];
 };
+/** Options for `checkMany()`. */
+type CheckManyOptions = {
+    /** Skip suggestion generation for taken identifiers (default: `true`). */
+    skipSuggestions?: boolean;
+};
+/** Options for the `skeleton()` and `areConfusable()` functions. */
+type SkeletonOptions = {
+    /** Confusable character map to use.
+     *  Default: `CONFUSABLE_MAP_FULL` (complete TR39 map, no NFKC filtering).
+     *  Pass `CONFUSABLE_MAP` if your pipeline runs NFKC before calling skeleton(). */
+    map?: Record<string, string>;
+};
 /**
  * Normalize a raw identifier: trims whitespace, applies NFKC Unicode normalization,
  * lowercases, and strips leading `@` symbols.
@@ -108,7 +120,7 @@ declare function normalize(raw: string, options?: {
 /**
  * Create a validator that rejects identifiers containing profanity or offensive words.
  *
- * Supply your own word list — no words are bundled with the library.
+ * Supply your own word list - no words are bundled with the library.
  * The returned function is compatible with `config.validators`.
  *
  * @param words - Array of words to block
@@ -146,6 +158,22 @@ declare function createProfanityValidator(words: string[], options?: {
  * Regenerate: `npx tsx scripts/generate-confusables.ts`
  */
 declare const CONFUSABLE_MAP: Record<string, string>;
+/**
+ * Complete TR39 confusable mapping: every single-character mapping to a
+ * lowercase Latin letter or digit from confusables.txt, with no NFKC filtering.
+ *
+ * Use this when your pipeline does NOT run NFKC normalization before confusable
+ * detection (which is most real-world systems: TR39 skeleton uses NFD, Chromium
+ * uses NFD, Rust uses NFC, django-registration uses no normalization at all).
+ *
+ * Includes ~1,400 entries vs CONFUSABLE_MAP's ~613 NFKC-deduped entries.
+ * The additional entries cover characters that NFKC normalization would handle
+ * (mathematical alphanumerics, fullwidth forms, etc.) plus the 31 entries where
+ * TR39 and NFKC disagree on the target letter.
+ *
+ * Regenerate: `npx tsx scripts/generate-confusables.ts`
+ */
+declare const CONFUSABLE_MAP_FULL: Record<string, string>;
 /**
  * Create a validator that rejects identifiers containing homoglyph/confusable characters.
  *
@@ -179,13 +207,55 @@ declare function createHomoglyphValidator(options?: {
     available: false;
     message: string;
 } | null>;
+/**
+ * Compute the TR39 Section 4 skeleton of a string for confusable comparison.
+ *
+ * Implements `internalSkeleton`:
+ * 1. NFD normalize
+ * 2. Remove Default_Ignorable_Code_Point characters
+ * 3. Replace each character via the confusable map
+ * 4. Reapply NFD
+ * 5. Lowercase
+ *
+ * The default map is `CONFUSABLE_MAP_FULL` (the complete TR39 mapping without
+ * NFKC filtering), which matches the NFD-based pipeline used by ICU, Chromium,
+ * and the TR39 spec itself. Pass `{ map: CONFUSABLE_MAP }` if your pipeline
+ * runs NFKC normalization before calling skeleton().
+ *
+ * @param input - The string to skeletonize
+ * @param options - Optional settings (custom confusable map)
+ * @returns The skeleton string for comparison
+ *
+ * @example
+ * ```ts
+ * skeleton("paypal") === skeleton("\u0440\u0430ypal") // true (Cyrillic р/а)
+ * skeleton("pay\u200Bpal") === skeleton("paypal")     // true (zero-width stripped)
+ * ```
+ */
+declare function skeleton(input: string, options?: SkeletonOptions): string;
+/**
+ * Check whether two strings are visually confusable by comparing their TR39 skeletons.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @param options - Optional settings (custom confusable map)
+ * @returns `true` if the strings produce the same skeleton
+ *
+ * @example
+ * ```ts
+ * areConfusable("paypal", "\u0440\u0430ypal") // true
+ * areConfusable("google", "g\u043e\u043egle") // true
+ * areConfusable("hello", "world")             // false
+ * ```
+ */
+declare function areConfusable(a: string, b: string, options?: SkeletonOptions): boolean;
 /**
  * Create a namespace guard instance for checking slug/handle uniqueness
  * across multiple database tables with reserved name protection.
  *
  * @param config - Reserved names, data sources, validation pattern, and optional features
  * @param adapter - Database adapter implementing the `findOne` lookup (use a built-in adapter or write your own)
- * @returns A guard with `check`, `checkMany`, `assertAvailable`, `validateFormat`, `clearCache`, and `cacheStats` methods
+ * @returns A guard with `check`, `checkMany`, `assertAvailable`, `validateFormat`, `validateFormatOnly`, `clearCache`, and `cacheStats` methods
  *
  * @example
  * ```ts
@@ -212,11 +282,12 @@ declare function createHomoglyphValidator(options?: {
 declare function createNamespaceGuard(config: NamespaceConfig, adapter: NamespaceAdapter): {
     normalize: typeof normalize;
     validateFormat: (identifier: string) => string | null;
+    validateFormatOnly: (identifier: string) => string | null;
     check: (identifier: string, scope?: OwnershipScope, options?: {
         skipSuggestions?: boolean;
     }) => Promise<CheckResult>;
     assertAvailable: (identifier: string, scope?: OwnershipScope) => Promise<void>;
-    checkMany: (identifiers: string[], scope?: OwnershipScope) => Promise<Record<string, CheckResult>>;
+    checkMany: (identifiers: string[], scope?: OwnershipScope, options?: CheckManyOptions) => Promise<Record<string, CheckResult>>;
     clearCache: () => void;
     cacheStats: () => {
         size: number;
@@ -227,4 +298,4 @@ declare function createNamespaceGuard(config: NamespaceConfig, adapter: Namespac
 /** The guard instance returned by `createNamespaceGuard`. */
 type NamespaceGuard = ReturnType<typeof createNamespaceGuard>;
 
-export { CONFUSABLE_MAP, type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, type SuggestStrategyName, createHomoglyphValidator, createNamespaceGuard, createProfanityValidator, normalize };
+export { CONFUSABLE_MAP, CONFUSABLE_MAP_FULL, type CheckManyOptions, type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, type SkeletonOptions, type SuggestStrategyName, areConfusable, createHomoglyphValidator, createNamespaceGuard, createProfanityValidator, normalize, skeleton };