namespace-guard 0.1.2 → 0.2.0

package/README.md

@@ -430,52 +430,129 @@ normalize("  @Sarah  "); // "sarah"
 normalize("ACME-Corp"); // "acme-corp"
 ```
 
-## Real-World Example
+## Case-Insensitive Matching
 
-Here's how you might use this in a signup flow:
+By default, slug lookups are case-sensitive. Enable case-insensitive matching to catch collisions regardless of stored casing:
 
 ```typescript
-// In your API route / server action
-async function createUser(handle: string, email: string) {
-  // Normalize first
-  const normalizedHandle = guard.normalize(handle);
+const guard = createNamespaceGuard({
+  sources: [/* ... */],
+  caseInsensitive: true,
+}, adapter);
+```
 
-  // Check availability (will also validate format)
-  const result = await guard.check(normalizedHandle);
+Each adapter handles this differently:
+- **Prisma**: Uses `mode: "insensitive"` on the where clause
+- **Drizzle**: Uses `ilike` instead of `eq` (pass `ilike` to the adapter: `createDrizzleAdapter(db, tables, { eq, ilike })`)
+- **Kysely**: Uses `ilike` operator
+- **Knex**: Uses `LOWER()` in a raw where clause
+- **Raw SQL**: Wraps both sides in `LOWER()`
 
-  if (!result.available) {
-    return { error: result.message };
-  }
+## Caching
+
+Enable in-memory caching to reduce database calls during rapid checks (e.g., live form validation, suggestion generation):
+
+```typescript
+const guard = createNamespaceGuard({
+  sources: [/* ... */],
+  cache: {
+    ttl: 5000, // milliseconds (default: 5000)
+  },
+}, adapter);
+
+// Manually clear the cache after writes
+guard.clearCache();
+```
+
+## Framework Integration
+
+### Next.js (Server Actions)
+
+```typescript
+// lib/guard.ts
+import { createNamespaceGuard } from "namespace-guard";
+import { createPrismaAdapter } from "namespace-guard/adapters/prisma";
+import { prisma } from "./db";
+
+export const guard = createNamespaceGuard({
+  reserved: ["admin", "api", "settings"],
+  sources: [
+    { name: "user", column: "handle", scopeKey: "id" },
+    { name: "organization", column: "slug", scopeKey: "id" },
+  ],
+  suggest: {},
+}, createPrismaAdapter(prisma));
+
+// app/signup/actions.ts
+"use server";
+
+import { guard } from "@/lib/guard";
+
+export async function checkHandle(handle: string) {
+  return guard.check(handle);
+}
+
+export async function createUser(handle: string, email: string) {
+  const result = await guard.check(handle);
+  if (!result.available) return { error: result.message };
 
-  // Safe to create
   const user = await prisma.user.create({
-    data: { handle: normalizedHandle, email },
+    data: { handle: guard.normalize(handle), email },
   });
-
   return { user };
 }
 ```
 
-Or in an update flow with ownership scoping:
+### Express Middleware
 
 ```typescript
-async function updateUserHandle(userId: string, newHandle: string) {
-  const normalized = guard.normalize(newHandle);
+import express from "express";
+import { guard } from "./lib/guard";
 
-  // Pass userId to avoid collision with own current handle
-  const result = await guard.check(normalized, { id: userId });
+const app = express();
 
-  if (!result.available) {
-    return { error: result.message };
-  }
+// Reusable middleware
+function validateSlug(req, res, next) {
+  const slug = req.body.handle || req.body.slug;
+  if (!slug) return res.status(400).json({ error: "Slug is required" });
 
-  await prisma.user.update({
-    where: { id: userId },
-    data: { handle: normalized },
+  guard.check(slug, { id: req.user?.id }).then((result) => {
+    if (!result.available) return res.status(409).json(result);
+    req.normalizedSlug = guard.normalize(slug);
+    next();
   });
-
-  return { success: true };
 }
+
+app.post("/api/users", validateSlug, async (req, res) => {
+  const user = await db.user.create({ handle: req.normalizedSlug, ... });
+  res.json({ user });
+});
+```
+
+### tRPC
+
+```typescript
+import { z } from "zod";
+import { router, protectedProcedure } from "./trpc";
+import { guard } from "./lib/guard";
+
+export const namespaceRouter = router({
+  check: protectedProcedure
+    .input(z.object({ slug: z.string() }))
+    .query(async ({ input, ctx }) => {
+      return guard.check(input.slug, { id: ctx.user.id });
+    }),
+
+  claim: protectedProcedure
+    .input(z.object({ slug: z.string() }))
+    .mutation(async ({ input, ctx }) => {
+      await guard.assertAvailable(input.slug, { id: ctx.user.id });
+      return ctx.db.user.update({
+        where: { id: ctx.user.id },
+        data: { handle: guard.normalize(input.slug) },
+      });
+    }),
+});
 ```
 
 ## TypeScript
@@ -489,6 +566,7 @@ import type {
   NamespaceAdapter,
   NamespaceGuard,
   CheckResult,
+  FindOneOptions,
   OwnershipScope,
 } from "namespace-guard";
 ```

package/dist/adapters/drizzle.d.mts

@@ -13,7 +13,13 @@ type DrizzleDb = {
         };
     };
 };
-type EqFn = (column: unknown, value: unknown) => unknown;
+type ComparisonFn = (column: unknown, value: unknown) => unknown;
+type DrizzleAdapterOptions = {
+    /** The `eq` function from drizzle-orm */
+    eq: ComparisonFn;
+    /** The `ilike` function from drizzle-orm (required when using caseInsensitive) */
+    ilike?: ComparisonFn;
+};
 /**
  * Create a namespace adapter for Drizzle ORM
  *
@@ -37,6 +43,6 @@ type EqFn = (column: unknown, value: unknown) => unknown;
  * );
  * ```
  */
-declare function createDrizzleAdapter(db: DrizzleDb, tables: Record<string, DrizzleTable>, eq: EqFn): NamespaceAdapter;
+declare function createDrizzleAdapter(db: DrizzleDb, tables: Record<string, DrizzleTable>, eqOrOptions: ComparisonFn | DrizzleAdapterOptions): NamespaceAdapter;
 
 export { createDrizzleAdapter };

package/dist/adapters/drizzle.d.ts

@@ -13,7 +13,13 @@ type DrizzleDb = {
         };
     };
 };
-type EqFn = (column: unknown, value: unknown) => unknown;
+type ComparisonFn = (column: unknown, value: unknown) => unknown;
+type DrizzleAdapterOptions = {
+    /** The `eq` function from drizzle-orm */
+    eq: ComparisonFn;
+    /** The `ilike` function from drizzle-orm (required when using caseInsensitive) */
+    ilike?: ComparisonFn;
+};
 /**
  * Create a namespace adapter for Drizzle ORM
  *
@@ -37,6 +43,6 @@ type EqFn = (column: unknown, value: unknown) => unknown;
  * );
  * ```
  */
-declare function createDrizzleAdapter(db: DrizzleDb, tables: Record<string, DrizzleTable>, eq: EqFn): NamespaceAdapter;
+declare function createDrizzleAdapter(db: DrizzleDb, tables: Record<string, DrizzleTable>, eqOrOptions: ComparisonFn | DrizzleAdapterOptions): NamespaceAdapter;
 
 export { createDrizzleAdapter };

package/dist/adapters/drizzle.js

@@ -23,9 +23,10 @@ __export(drizzle_exports, {
   createDrizzleAdapter: () => createDrizzleAdapter
 });
 module.exports = __toCommonJS(drizzle_exports);
-function createDrizzleAdapter(db, tables, eq) {
+function createDrizzleAdapter(db, tables, eqOrOptions) {
+  const ops = typeof eqOrOptions === "function" ? { eq: eqOrOptions } : eqOrOptions;
   return {
-    async findOne(source, value) {
+    async findOne(source, value, findOptions) {
       const queryHandler = db.query[source.name];
       if (!queryHandler) {
         throw new Error(`Drizzle query handler for "${source.name}" not found. Make sure relational queries are set up.`);
@@ -39,8 +40,15 @@ function createDrizzleAdapter(db, tables, eq) {
         throw new Error(`Column "${source.column}" not found in table "${source.name}"`);
       }
       const idColumn = source.idColumn ?? "id";
+      let compareFn = ops.eq;
+      if (findOptions?.caseInsensitive) {
+        if (!ops.ilike) {
+          throw new Error("caseInsensitive requires passing ilike to createDrizzleAdapter");
+        }
+        compareFn = ops.ilike;
+      }
       return queryHandler.findFirst({
-        where: eq(column, value),
+        where: compareFn(column, value),
         columns: {
           [idColumn]: true,
           ...source.scopeKey && source.scopeKey !== idColumn ? { [source.scopeKey]: true } : {}

package/dist/adapters/drizzle.mjs

@@ -1,7 +1,8 @@
 // src/adapters/drizzle.ts
-function createDrizzleAdapter(db, tables, eq) {
+function createDrizzleAdapter(db, tables, eqOrOptions) {
+  const ops = typeof eqOrOptions === "function" ? { eq: eqOrOptions } : eqOrOptions;
   return {
-    async findOne(source, value) {
+    async findOne(source, value, findOptions) {
       const queryHandler = db.query[source.name];
       if (!queryHandler) {
         throw new Error(`Drizzle query handler for "${source.name}" not found. Make sure relational queries are set up.`);
@@ -15,8 +16,15 @@ function createDrizzleAdapter(db, tables, eq) {
         throw new Error(`Column "${source.column}" not found in table "${source.name}"`);
       }
       const idColumn = source.idColumn ?? "id";
+      let compareFn = ops.eq;
+      if (findOptions?.caseInsensitive) {
+        if (!ops.ilike) {
+          throw new Error("caseInsensitive requires passing ilike to createDrizzleAdapter");
+        }
+        compareFn = ops.ilike;
+      }
       return queryHandler.findFirst({
-        where: eq(column, value),
+        where: compareFn(column, value),
         columns: {
           [idColumn]: true,
           ...source.scopeKey && source.scopeKey !== idColumn ? { [source.scopeKey]: true } : {}

package/dist/adapters/knex.d.mts

@@ -3,6 +3,7 @@ import { NamespaceAdapter } from '../index.mjs';
 type KnexQueryBuilder = {
     select: (columns: string[]) => KnexQueryBuilder;
     where: (column: string, value: unknown) => KnexQueryBuilder;
+    whereRaw: (raw: string, bindings: unknown[]) => KnexQueryBuilder;
     first: () => Promise<Record<string, unknown> | undefined>;
 };
 type KnexInstance = {

package/dist/adapters/knex.d.ts

@@ -3,6 +3,7 @@ import { NamespaceAdapter } from '../index.js';
 type KnexQueryBuilder = {
     select: (columns: string[]) => KnexQueryBuilder;
     where: (column: string, value: unknown) => KnexQueryBuilder;
+    whereRaw: (raw: string, bindings: unknown[]) => KnexQueryBuilder;
     first: () => Promise<Record<string, unknown> | undefined>;
 };
 type KnexInstance = {

package/dist/adapters/knex.js

@@ -25,10 +25,16 @@ __export(knex_exports, {
 module.exports = __toCommonJS(knex_exports);
 function createKnexAdapter(knex) {
   return {
-    async findOne(source, value) {
+    async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
       const columns = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
-      const row = await knex(source.name).select(columns).where(source.column, value).first();
+      let query = knex(source.name).select(columns);
+      if (options?.caseInsensitive) {
+        query = query.whereRaw(`LOWER("${source.column}") = LOWER(?)`, [value]);
+      } else {
+        query = query.where(source.column, value);
+      }
+      const row = await query.first();
       return row ?? null;
     }
   };

package/dist/adapters/knex.mjs

@@ -1,10 +1,16 @@
 // src/adapters/knex.ts
 function createKnexAdapter(knex) {
   return {
-    async findOne(source, value) {
+    async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
       const columns = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
-      const row = await knex(source.name).select(columns).where(source.column, value).first();
+      let query = knex(source.name).select(columns);
+      if (options?.caseInsensitive) {
+        query = query.whereRaw(`LOWER("${source.column}") = LOWER(?)`, [value]);
+      } else {
+        query = query.where(source.column, value);
+      }
+      const row = await query.first();
       return row ?? null;
     }
   };

package/dist/adapters/kysely.d.mts

@@ -3,6 +3,7 @@ import { NamespaceAdapter } from '../index.mjs';
 type KyselyQueryBuilder = {
     select: (columns: string[]) => KyselyQueryBuilder;
     where: (column: string, operator: string, value: unknown) => KyselyQueryBuilder;
+    whereRaw: (raw: unknown) => KyselyQueryBuilder;
     limit: (limit: number) => KyselyQueryBuilder;
     executeTakeFirst: () => Promise<Record<string, unknown> | undefined>;
 };

package/dist/adapters/kysely.d.ts

@@ -3,6 +3,7 @@ import { NamespaceAdapter } from '../index.js';
 type KyselyQueryBuilder = {
     select: (columns: string[]) => KyselyQueryBuilder;
     where: (column: string, operator: string, value: unknown) => KyselyQueryBuilder;
+    whereRaw: (raw: unknown) => KyselyQueryBuilder;
     limit: (limit: number) => KyselyQueryBuilder;
     executeTakeFirst: () => Promise<Record<string, unknown> | undefined>;
 };

package/dist/adapters/kysely.js

@@ -25,10 +25,16 @@ __export(kysely_exports, {
 module.exports = __toCommonJS(kysely_exports);
 function createKyselyAdapter(db) {
   return {
-    async findOne(source, value) {
+    async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
       const columns = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
-      const row = await db.selectFrom(source.name).select(columns).where(source.column, "=", value).limit(1).executeTakeFirst();
+      let query = db.selectFrom(source.name).select(columns);
+      if (options?.caseInsensitive) {
+        query = query.where(source.column, "ilike", value);
+      } else {
+        query = query.where(source.column, "=", value);
+      }
+      const row = await query.limit(1).executeTakeFirst();
       return row ?? null;
     }
   };

package/dist/adapters/kysely.mjs

@@ -1,10 +1,16 @@
 // src/adapters/kysely.ts
 function createKyselyAdapter(db) {
   return {
-    async findOne(source, value) {
+    async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
       const columns = source.scopeKey && source.scopeKey !== idColumn ? [idColumn, source.scopeKey] : [idColumn];
-      const row = await db.selectFrom(source.name).select(columns).where(source.column, "=", value).limit(1).executeTakeFirst();
+      let query = db.selectFrom(source.name).select(columns);
+      if (options?.caseInsensitive) {
+        query = query.where(source.column, "ilike", value);
+      } else {
+        query = query.where(source.column, "=", value);
+      }
+      const row = await query.limit(1).executeTakeFirst();
       return row ?? null;
     }
   };

package/dist/adapters/prisma.js

@@ -25,14 +25,15 @@ __export(prisma_exports, {
 module.exports = __toCommonJS(prisma_exports);
 function createPrismaAdapter(prisma) {
   return {
-    async findOne(source, value) {
+    async findOne(source, value, options) {
       const model = prisma[source.name];
       if (!model) {
         throw new Error(`Prisma model "${source.name}" not found`);
       }
       const idColumn = source.idColumn ?? "id";
+      const whereValue = options?.caseInsensitive ? { equals: value, mode: "insensitive" } : value;
       return model.findFirst({
-        where: { [source.column]: value },
+        where: { [source.column]: whereValue },
         select: {
           [idColumn]: true,
           ...source.scopeKey ? { [source.scopeKey]: true } : {}

package/dist/adapters/prisma.mjs

@@ -1,14 +1,15 @@
 // src/adapters/prisma.ts
 function createPrismaAdapter(prisma) {
   return {
-    async findOne(source, value) {
+    async findOne(source, value, options) {
       const model = prisma[source.name];
       if (!model) {
         throw new Error(`Prisma model "${source.name}" not found`);
       }
       const idColumn = source.idColumn ?? "id";
+      const whereValue = options?.caseInsensitive ? { equals: value, mode: "insensitive" } : value;
       return model.findFirst({
-        where: { [source.column]: value },
+        where: { [source.column]: whereValue },
         select: {
           [idColumn]: true,
           ...source.scopeKey ? { [source.scopeKey]: true } : {}

package/dist/adapters/raw.js

@@ -25,10 +25,11 @@ __export(raw_exports, {
 module.exports = __toCommonJS(raw_exports);
 function createRawAdapter(execute) {
   return {
-    async findOne(source, value) {
+    async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
       const columns = source.scopeKey && source.scopeKey !== idColumn ? `"${idColumn}", "${source.scopeKey}"` : `"${idColumn}"`;
-      const sql = `SELECT ${columns} FROM "${source.name}" WHERE "${source.column}" = $1 LIMIT 1`;
+      const whereClause = options?.caseInsensitive ? `LOWER("${source.column}") = LOWER($1)` : `"${source.column}" = $1`;
+      const sql = `SELECT ${columns} FROM "${source.name}" WHERE ${whereClause} LIMIT 1`;
       const result = await execute(sql, [value]);
       return result.rows[0] ?? null;
     }

package/dist/adapters/raw.mjs

@@ -1,10 +1,11 @@
 // src/adapters/raw.ts
 function createRawAdapter(execute) {
   return {
-    async findOne(source, value) {
+    async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
       const columns = source.scopeKey && source.scopeKey !== idColumn ? `"${idColumn}", "${source.scopeKey}"` : `"${idColumn}"`;
-      const sql = `SELECT ${columns} FROM "${source.name}" WHERE "${source.column}" = $1 LIMIT 1`;
+      const whereClause = options?.caseInsensitive ? `LOWER("${source.column}") = LOWER($1)` : `"${source.column}" = $1`;
+      const sql = `SELECT ${columns} FROM "${source.name}" WHERE ${whereClause} LIMIT 1`;
       const result = await execute(sql, [value]);
       return result.rows[0] ?? null;
     }

package/dist/cli.js

@@ -62,6 +62,22 @@ function createNamespaceGuard(config, adapter) {
   const invalidMsg = configMessages.invalid ?? DEFAULT_MESSAGES.invalid;
   const takenMsg = configMessages.taken ?? DEFAULT_MESSAGES.taken;
   const validators = config.validators ?? [];
+  const cacheEnabled = !!config.cache;
+  const cacheTtl = config.cache?.ttl ?? 5e3;
+  const cacheMap = /* @__PURE__ */ new Map();
+  function cachedFindOne(source, value, options) {
+    if (!cacheEnabled) return adapter.findOne(source, value, options);
+    const key = `${source.name}:${value}:${options?.caseInsensitive ? "i" : "s"}`;
+    const now = Date.now();
+    const cached = cacheMap.get(key);
+    if (cached && cached.expires > now) {
+      return Promise.resolve(cached.value);
+    }
+    return adapter.findOne(source, value, options).then((result) => {
+      cacheMap.set(key, { value: result, expires: now + cacheTtl });
+      return result;
+    });
+  }
   function getReservedMessage(category) {
     const rm = configMessages.reserved;
     if (typeof rm === "string") return rm;
@@ -98,8 +114,9 @@ function createNamespaceGuard(config, adapter) {
         return { available: false, reason: "invalid", message: rejection.message };
       }
     }
+    const findOptions = config.caseInsensitive ? { caseInsensitive: true } : void 0;
     const checks = config.sources.map(async (source) => {
-      const existing = await adapter.findOne(source, normalized);
+      const existing = await cachedFindOne(source, normalized, findOptions);
       if (!existing) return null;
       if (source.scopeKey) {
         const scopeValue = scope[source.scopeKey];
@@ -155,22 +172,27 @@ function createNamespaceGuard(config, adapter) {
     );
     return Object.fromEntries(entries);
   }
+  function clearCache() {
+    cacheMap.clear();
+  }
   return {
     normalize,
     validateFormat,
     check,
     assertAvailable,
-    checkMany
+    checkMany,
+    clearCache
   };
 }
 
 // src/adapters/raw.ts
 function createRawAdapter(execute) {
   return {
-    async findOne(source, value) {
+    async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
       const columns = source.scopeKey && source.scopeKey !== idColumn ? `"${idColumn}", "${source.scopeKey}"` : `"${idColumn}"`;
-      const sql = `SELECT ${columns} FROM "${source.name}" WHERE "${source.column}" = $1 LIMIT 1`;
+      const whereClause = options?.caseInsensitive ? `LOWER("${source.column}") = LOWER($1)` : `"${source.column}" = $1`;
+      const sql = `SELECT ${columns} FROM "${source.name}" WHERE ${whereClause} LIMIT 1`;
       const result = await execute(sql, [value]);
       return result.rows[0] ?? null;
     }

package/dist/cli.mjs

@@ -39,6 +39,22 @@ function createNamespaceGuard(config, adapter) {
   const invalidMsg = configMessages.invalid ?? DEFAULT_MESSAGES.invalid;
   const takenMsg = configMessages.taken ?? DEFAULT_MESSAGES.taken;
   const validators = config.validators ?? [];
+  const cacheEnabled = !!config.cache;
+  const cacheTtl = config.cache?.ttl ?? 5e3;
+  const cacheMap = /* @__PURE__ */ new Map();
+  function cachedFindOne(source, value, options) {
+    if (!cacheEnabled) return adapter.findOne(source, value, options);
+    const key = `${source.name}:${value}:${options?.caseInsensitive ? "i" : "s"}`;
+    const now = Date.now();
+    const cached = cacheMap.get(key);
+    if (cached && cached.expires > now) {
+      return Promise.resolve(cached.value);
+    }
+    return adapter.findOne(source, value, options).then((result) => {
+      cacheMap.set(key, { value: result, expires: now + cacheTtl });
+      return result;
+    });
+  }
   function getReservedMessage(category) {
     const rm = configMessages.reserved;
     if (typeof rm === "string") return rm;
@@ -75,8 +91,9 @@ function createNamespaceGuard(config, adapter) {
         return { available: false, reason: "invalid", message: rejection.message };
       }
     }
+    const findOptions = config.caseInsensitive ? { caseInsensitive: true } : void 0;
     const checks = config.sources.map(async (source) => {
-      const existing = await adapter.findOne(source, normalized);
+      const existing = await cachedFindOne(source, normalized, findOptions);
       if (!existing) return null;
       if (source.scopeKey) {
         const scopeValue = scope[source.scopeKey];
@@ -132,22 +149,27 @@ function createNamespaceGuard(config, adapter) {
     );
     return Object.fromEntries(entries);
   }
+  function clearCache() {
+    cacheMap.clear();
+  }
   return {
     normalize,
     validateFormat,
     check,
     assertAvailable,
-    checkMany
+    checkMany,
+    clearCache
   };
 }
 
 // src/adapters/raw.ts
 function createRawAdapter(execute) {
   return {
-    async findOne(source, value) {
+    async findOne(source, value, options) {
       const idColumn = source.idColumn ?? "id";
       const columns = source.scopeKey && source.scopeKey !== idColumn ? `"${idColumn}", "${source.scopeKey}"` : `"${idColumn}"`;
-      const sql = `SELECT ${columns} FROM "${source.name}" WHERE "${source.column}" = $1 LIMIT 1`;
+      const whereClause = options?.caseInsensitive ? `LOWER("${source.column}") = LOWER($1)` : `"${source.column}" = $1`;
+      const sql = `SELECT ${columns} FROM "${source.name}" WHERE ${whereClause} LIMIT 1`;
       const result = await execute(sql, [value]);
       return result.rows[0] ?? null;
     }

package/dist/index.d.mts

@@ -15,6 +15,8 @@ type NamespaceConfig = {
     sources: NamespaceSource[];
     /** Regex pattern for valid identifiers (default: lowercase alphanumeric + hyphens, 2-30 chars) */
     pattern?: RegExp;
+    /** Use case-insensitive matching in database queries (default: false) */
+    caseInsensitive?: boolean;
     /** Custom error messages */
     messages?: {
         invalid?: string;
@@ -33,9 +35,18 @@ type NamespaceConfig = {
         /** Max suggestions to return (default: 3) */
         max?: number;
     };
+    /** Enable in-memory caching of adapter lookups */
+    cache?: {
+        /** Time-to-live in milliseconds (default: 5000) */
+        ttl?: number;
+    };
+};
+type FindOneOptions = {
+    /** Use case-insensitive matching */
+    caseInsensitive?: boolean;
 };
 type NamespaceAdapter = {
-    findOne: (source: NamespaceSource, value: string) => Promise<Record<string, unknown> | null>;
+    findOne: (source: NamespaceSource, value: string, options?: FindOneOptions) => Promise<Record<string, unknown> | null>;
 };
 type OwnershipScope = Record<string, string | null | undefined>;
 type CheckResult = {
@@ -63,7 +74,8 @@ declare function createNamespaceGuard(config: NamespaceConfig, adapter: Namespac
     }) => Promise<CheckResult>;
     assertAvailable: (identifier: string, scope?: OwnershipScope) => Promise<void>;
     checkMany: (identifiers: string[], scope?: OwnershipScope) => Promise<Record<string, CheckResult>>;
+    clearCache: () => void;
 };
 type NamespaceGuard = ReturnType<typeof createNamespaceGuard>;
 
-export { type CheckResult, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, createNamespaceGuard, normalize };
+export { type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, createNamespaceGuard, normalize };

package/dist/index.d.ts

@@ -15,6 +15,8 @@ type NamespaceConfig = {
     sources: NamespaceSource[];
     /** Regex pattern for valid identifiers (default: lowercase alphanumeric + hyphens, 2-30 chars) */
     pattern?: RegExp;
+    /** Use case-insensitive matching in database queries (default: false) */
+    caseInsensitive?: boolean;
     /** Custom error messages */
     messages?: {
         invalid?: string;
@@ -33,9 +35,18 @@ type NamespaceConfig = {
         /** Max suggestions to return (default: 3) */
         max?: number;
     };
+    /** Enable in-memory caching of adapter lookups */
+    cache?: {
+        /** Time-to-live in milliseconds (default: 5000) */
+        ttl?: number;
+    };
+};
+type FindOneOptions = {
+    /** Use case-insensitive matching */
+    caseInsensitive?: boolean;
 };
 type NamespaceAdapter = {
-    findOne: (source: NamespaceSource, value: string) => Promise<Record<string, unknown> | null>;
+    findOne: (source: NamespaceSource, value: string, options?: FindOneOptions) => Promise<Record<string, unknown> | null>;
 };
 type OwnershipScope = Record<string, string | null | undefined>;
 type CheckResult = {
@@ -63,7 +74,8 @@ declare function createNamespaceGuard(config: NamespaceConfig, adapter: Namespac
     }) => Promise<CheckResult>;
     assertAvailable: (identifier: string, scope?: OwnershipScope) => Promise<void>;
     checkMany: (identifiers: string[], scope?: OwnershipScope) => Promise<Record<string, CheckResult>>;
+    clearCache: () => void;
 };
 type NamespaceGuard = ReturnType<typeof createNamespaceGuard>;
 
-export { type CheckResult, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, createNamespaceGuard, normalize };
+export { type CheckResult, type FindOneOptions, type NamespaceAdapter, type NamespaceConfig, type NamespaceGuard, type NamespaceSource, type OwnershipScope, createNamespaceGuard, normalize };

package/dist/index.js

@@ -58,6 +58,22 @@ function createNamespaceGuard(config, adapter) {
   const invalidMsg = configMessages.invalid ?? DEFAULT_MESSAGES.invalid;
   const takenMsg = configMessages.taken ?? DEFAULT_MESSAGES.taken;
   const validators = config.validators ?? [];
+  const cacheEnabled = !!config.cache;
+  const cacheTtl = config.cache?.ttl ?? 5e3;
+  const cacheMap = /* @__PURE__ */ new Map();
+  function cachedFindOne(source, value, options) {
+    if (!cacheEnabled) return adapter.findOne(source, value, options);
+    const key = `${source.name}:${value}:${options?.caseInsensitive ? "i" : "s"}`;
+    const now = Date.now();
+    const cached = cacheMap.get(key);
+    if (cached && cached.expires > now) {
+      return Promise.resolve(cached.value);
+    }
+    return adapter.findOne(source, value, options).then((result) => {
+      cacheMap.set(key, { value: result, expires: now + cacheTtl });
+      return result;
+    });
+  }
   function getReservedMessage(category) {
     const rm = configMessages.reserved;
     if (typeof rm === "string") return rm;
@@ -94,8 +110,9 @@ function createNamespaceGuard(config, adapter) {
         return { available: false, reason: "invalid", message: rejection.message };
       }
     }
+    const findOptions = config.caseInsensitive ? { caseInsensitive: true } : void 0;
     const checks = config.sources.map(async (source) => {
-      const existing = await adapter.findOne(source, normalized);
+      const existing = await cachedFindOne(source, normalized, findOptions);
       if (!existing) return null;
       if (source.scopeKey) {
         const scopeValue = scope[source.scopeKey];
@@ -151,12 +168,16 @@ function createNamespaceGuard(config, adapter) {
     );
     return Object.fromEntries(entries);
   }
+  function clearCache() {
+    cacheMap.clear();
+  }
   return {
     normalize,
     validateFormat,
     check,
     assertAvailable,
-    checkMany
+    checkMany,
+    clearCache
   };
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.mjs

@@ -33,6 +33,22 @@ function createNamespaceGuard(config, adapter) {
   const invalidMsg = configMessages.invalid ?? DEFAULT_MESSAGES.invalid;
   const takenMsg = configMessages.taken ?? DEFAULT_MESSAGES.taken;
   const validators = config.validators ?? [];
+  const cacheEnabled = !!config.cache;
+  const cacheTtl = config.cache?.ttl ?? 5e3;
+  const cacheMap = /* @__PURE__ */ new Map();
+  function cachedFindOne(source, value, options) {
+    if (!cacheEnabled) return adapter.findOne(source, value, options);
+    const key = `${source.name}:${value}:${options?.caseInsensitive ? "i" : "s"}`;
+    const now = Date.now();
+    const cached = cacheMap.get(key);
+    if (cached && cached.expires > now) {
+      return Promise.resolve(cached.value);
+    }
+    return adapter.findOne(source, value, options).then((result) => {
+      cacheMap.set(key, { value: result, expires: now + cacheTtl });
+      return result;
+    });
+  }
   function getReservedMessage(category) {
     const rm = configMessages.reserved;
     if (typeof rm === "string") return rm;
@@ -69,8 +85,9 @@ function createNamespaceGuard(config, adapter) {
         return { available: false, reason: "invalid", message: rejection.message };
       }
     }
+    const findOptions = config.caseInsensitive ? { caseInsensitive: true } : void 0;
     const checks = config.sources.map(async (source) => {
-      const existing = await adapter.findOne(source, normalized);
+      const existing = await cachedFindOne(source, normalized, findOptions);
       if (!existing) return null;
       if (source.scopeKey) {
         const scopeValue = scope[source.scopeKey];
@@ -126,12 +143,16 @@ function createNamespaceGuard(config, adapter) {
     );
     return Object.fromEntries(entries);
   }
+  function clearCache() {
+    cacheMap.clear();
+  }
   return {
     normalize,
     validateFormat,
     check,
     assertAvailable,
-    checkMany
+    checkMany,
+    clearCache
   };
 }
 export {

package/package.json

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