namespace-guard 0.10.0 → 0.11.0

package/README.md

@@ -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
@@ -623,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.
+
+**Parameters:**
+- `identifiers` - Array of slugs/handles to check
+- `scope` - Optional ownership scope applied to all checks
+- `options` - Optional `{ skipSuggestions?: boolean }` (default: `true`)
 
-Check multiple identifiers in parallel.
+Pass `{ skipSuggestions: false }` to include suggestions for taken identifiers.
 
 **Returns:** `Record<string, CheckResult>`
 
@@ -639,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 }`
 
 ---
 
@@ -813,6 +880,7 @@ import {
   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

@@ -82,6 +82,11 @@ 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.
@@ -250,7 +255,7 @@ declare function areConfusable(a: string, b: string, options?: SkeletonOptions):
  *
  * @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
@@ -277,11 +282,12 @@ declare function areConfusable(a: string, b: string, options?: SkeletonOptions):
 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;
@@ -292,4 +298,4 @@ declare function createNamespaceGuard(config: NamespaceConfig, adapter: Namespac
 /** The guard instance returned by `createNamespaceGuard`. */
 type NamespaceGuard = ReturnType<typeof createNamespaceGuard>;
 
-export { CONFUSABLE_MAP, CONFUSABLE_MAP_FULL, type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, type SkeletonOptions, type SuggestStrategyName, areConfusable, createHomoglyphValidator, createNamespaceGuard, createProfanityValidator, normalize, skeleton };
+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

@@ -82,6 +82,11 @@ 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.
@@ -250,7 +255,7 @@ declare function areConfusable(a: string, b: string, options?: SkeletonOptions):
  *
  * @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
@@ -277,11 +282,12 @@ declare function areConfusable(a: string, b: string, options?: SkeletonOptions):
 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;
@@ -292,4 +298,4 @@ declare function createNamespaceGuard(config: NamespaceConfig, adapter: Namespac
 /** The guard instance returned by `createNamespaceGuard`. */
 type NamespaceGuard = ReturnType<typeof createNamespaceGuard>;
 
-export { CONFUSABLE_MAP, CONFUSABLE_MAP_FULL, type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, type SkeletonOptions, type SuggestStrategyName, areConfusable, createHomoglyphValidator, createNamespaceGuard, createProfanityValidator, normalize, skeleton };
+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.js

@@ -2837,6 +2837,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];
@@ -2955,10 +2965,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];
       })
     );
@@ -2975,6 +2986,7 @@ function createNamespaceGuard(config, adapter) {
   return {
     normalize,
     validateFormat,
+    validateFormatOnly,
     check,
     assertAvailable,
     checkMany,

package/dist/index.mjs

@@ -2806,6 +2806,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];
@@ -2924,10 +2934,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];
       })
     );
@@ -2944,6 +2955,7 @@ function createNamespaceGuard(config, adapter) {
   return {
     normalize,
     validateFormat,
+    validateFormatOnly,
     check,
     assertAvailable,
     checkMany,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "namespace-guard",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Check slug/handle uniqueness across multiple database tables with reserved name protection",
   "main": "dist/index.js",
   "module": "dist/index.mjs",