namespace-guard 0.4.0 → 0.6.1

package/README.md

@@ -298,21 +298,15 @@ No words are bundled — use any word list you like (e.g., the `bad-words` npm p
 
 ## Conflict Suggestions
 
-When a slug is taken, automatically suggest available alternatives:
+When a slug is taken, automatically suggest available alternatives using pluggable strategies:
 
 ```typescript
 const guard = createNamespaceGuard({
   sources: [/* ... */],
   suggest: {
-    // Optional: custom generator (default appends -1 through -9)
-    generate: (identifier) => [
-      `${identifier}-1`,
-      `${identifier}-2`,
-      `${identifier}-io`,
-      `${identifier}-app`,
-      `${identifier}-hq`,
-    ],
-    // Optional: max suggestions to return (default: 3)
+    // Named strategy (default: ["sequential", "random-digits"])
+    strategy: "suffix-words",
+    // Max suggestions to return (default: 3)
     max: 3,
   },
 }, adapter);
@@ -323,11 +317,48 @@ const result = await guard.check("acme-corp");
 //   reason: "taken",
 //   message: "That name is already in use.",
 //   source: "organization",
-//   suggestions: ["acme-corp-1", "acme-corp-2", "acme-corp-io"]
+//   suggestions: ["acme-corp-dev", "acme-corp-io", "acme-corp-app"]
 // }
 ```
 
-Suggestions are verified against format, reserved names, and database collisions. Only available suggestions are returned.
+### Built-in Strategies
+
+| Strategy | Example Output | Description |
+|----------|---------------|-------------|
+| `"sequential"` | `sarah-1`, `sarah1`, `sarah-2` | Hyphenated and compact numeric suffixes |
+| `"random-digits"` | `sarah-4821`, `sarah-1037` | Random 3-4 digit suffixes |
+| `"suffix-words"` | `sarah-dev`, `sarah-hq`, `sarah-app` | Common word suffixes |
+| `"short-random"` | `sarah-x7k`, `sarah-m2p` | Short 3-char alphanumeric suffixes |
+| `"scramble"` | `asrah`, `sarha` | Adjacent character transpositions |
+| `"similar"` | `sara`, `darah`, `thesarah` | Edit-distance-1 mutations (deletions, keyboard-adjacent substitutions, prefix/suffix) |
+
+### Composing Strategies
+
+Combine multiple strategies — candidates are interleaved round-robin:
+
+```typescript
+suggest: {
+  strategy: ["random-digits", "suffix-words"],
+  max: 4,
+}
+// → ["sarah-4821", "sarah-dev", "sarah-1037", "sarah-io"]
+```
+
+### Custom Strategy Function
+
+Pass a function that returns candidate slugs:
+
+```typescript
+suggest: {
+  strategy: (identifier) => [
+    `${identifier}-io`,
+    `${identifier}-app`,
+    `the-real-${identifier}`,
+  ],
+}
+```
+
+Suggestions are verified against format, reserved names, validators, and database collisions using a progressive batched pipeline. Only available suggestions are returned.
 
 ## Batch Checking
 
@@ -641,6 +672,7 @@ import {
   type CheckResult,
   type FindOneOptions,
   type OwnershipScope,
+  type SuggestStrategyName,
 } from "namespace-guard";
 ```
 

package/dist/cli.js

@@ -36,29 +36,51 @@ var DEFAULT_MESSAGES = {
 };
 function extractMaxLength(pattern) {
   const testStrings = ["a", "1", "a1", "a-1"];
-  for (let len = 100; len >= 1; len--) {
+  let lo = 1;
+  let hi = 100;
+  let best = 30;
+  while (lo <= hi) {
+    const mid = Math.floor((lo + hi) / 2);
+    let anyMatch = false;
     for (const chars of testStrings) {
-      const s = chars.repeat(Math.ceil(len / chars.length)).slice(0, len);
-      if (pattern.test(s)) return len;
+      const s = chars.repeat(Math.ceil(mid / chars.length)).slice(0, mid);
+      if (pattern.test(s)) {
+        anyMatch = true;
+        break;
+      }
+    }
+    if (anyMatch) {
+      best = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
     }
   }
-  return 30;
+  return best;
 }
 function createDefaultSuggest(pattern) {
   const maxLen = extractMaxLength(pattern);
   return (identifier) => {
+    const seen = /* @__PURE__ */ new Set();
     const candidates = [];
     for (let i = 1; i <= 9; i++) {
       const hyphenated = `${identifier}-${i}`;
-      if (hyphenated.length <= maxLen) candidates.push(hyphenated);
+      if (hyphenated.length <= maxLen) {
+        seen.add(hyphenated);
+        candidates.push(hyphenated);
+      }
       const compact = `${identifier}${i}`;
-      if (compact.length <= maxLen) candidates.push(compact);
+      if (compact.length <= maxLen) {
+        seen.add(compact);
+        candidates.push(compact);
+      }
     }
     if (identifier.length >= maxLen - 1) {
       for (let i = 1; i <= 9; i++) {
         const suffix = String(i);
         const truncated = identifier.slice(0, maxLen - suffix.length) + suffix;
-        if (truncated !== identifier && !candidates.includes(truncated)) {
+        if (truncated !== identifier && !seen.has(truncated)) {
+          seen.add(truncated);
           candidates.push(truncated);
         }
       }
@@ -66,6 +88,184 @@ function createDefaultSuggest(pattern) {
     return candidates;
   };
 }
+var SUFFIX_WORDS = ["dev", "io", "app", "hq", "pro", "team", "labs", "hub", "go", "one"];
+function createRandomDigitsStrategy(pattern) {
+  const maxLen = extractMaxLength(pattern);
+  return (identifier) => {
+    const seen = /* @__PURE__ */ new Set();
+    const candidates = [];
+    for (let i = 0; i < 15; i++) {
+      const digits = String(Math.floor(100 + Math.random() * 9900));
+      const candidate = `${identifier}-${digits}`;
+      if (candidate.length <= maxLen && !seen.has(candidate)) {
+        seen.add(candidate);
+        candidates.push(candidate);
+      }
+    }
+    return candidates;
+  };
+}
+function createSuffixWordsStrategy(pattern) {
+  const maxLen = extractMaxLength(pattern);
+  return (identifier) => {
+    const candidates = [];
+    for (const word of SUFFIX_WORDS) {
+      const candidate = `${identifier}-${word}`;
+      if (candidate.length <= maxLen) {
+        candidates.push(candidate);
+      }
+    }
+    return candidates;
+  };
+}
+function createShortRandomStrategy(pattern) {
+  const maxLen = extractMaxLength(pattern);
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  return (identifier) => {
+    const seen = /* @__PURE__ */ new Set();
+    const candidates = [];
+    for (let i = 0; i < 10; i++) {
+      let suffix = "";
+      for (let j = 0; j < 3; j++) {
+        suffix += chars[Math.floor(Math.random() * chars.length)];
+      }
+      const candidate = `${identifier}-${suffix}`;
+      if (candidate.length <= maxLen && !seen.has(candidate)) {
+        seen.add(candidate);
+        candidates.push(candidate);
+      }
+    }
+    return candidates;
+  };
+}
+function createScrambleStrategy(_pattern) {
+  return (identifier) => {
+    const seen = /* @__PURE__ */ new Set();
+    const candidates = [];
+    const chars = identifier.split("");
+    for (let i = 0; i < chars.length - 1; i++) {
+      if (chars[i] !== chars[i + 1]) {
+        const swapped = [...chars];
+        [swapped[i], swapped[i + 1]] = [swapped[i + 1], swapped[i]];
+        const candidate = swapped.join("");
+        if (candidate !== identifier && !seen.has(candidate)) {
+          seen.add(candidate);
+          candidates.push(candidate);
+        }
+      }
+    }
+    return candidates;
+  };
+}
+function createSimilarStrategy(pattern) {
+  const maxLen = extractMaxLength(pattern);
+  const nearby = {
+    a: "sqwz",
+    b: "vngh",
+    c: "xdfv",
+    d: "sfce",
+    e: "wrd",
+    f: "dgcv",
+    g: "fhtb",
+    h: "gjyn",
+    i: "uko",
+    j: "hknm",
+    k: "jli",
+    l: "kop",
+    m: "njk",
+    n: "bmhj",
+    o: "ipl",
+    p: "ol",
+    q: "wa",
+    r: "eft",
+    s: "adwz",
+    t: "rgy",
+    u: "yij",
+    v: "cfgb",
+    w: "qase",
+    x: "zsdc",
+    y: "tuh",
+    z: "xas",
+    "0": "19",
+    "1": "02",
+    "2": "13",
+    "3": "24",
+    "4": "35",
+    "5": "46",
+    "6": "57",
+    "7": "68",
+    "8": "79",
+    "9": "80"
+  };
+  const prefixes = ["the", "my", "x", "i"];
+  const suffixes = ["x", "o", "i", "z"];
+  return (identifier) => {
+    const seen = /* @__PURE__ */ new Set();
+    const candidates = [];
+    function add(c) {
+      if (c.length >= 2 && c.length <= maxLen && c !== identifier && pattern.test(c) && !seen.has(c)) {
+        seen.add(c);
+        candidates.push(c);
+      }
+    }
+    for (let i = 0; i < identifier.length; i++) {
+      add(identifier.slice(0, i) + identifier.slice(i + 1));
+    }
+    for (let i = 0; i < identifier.length; i++) {
+      const ch = identifier[i];
+      const neighbours = nearby[ch] ?? "";
+      for (const n of neighbours) {
+        add(identifier.slice(0, i) + n + identifier.slice(i + 1));
+      }
+    }
+    for (const p of prefixes) {
+      add(p + identifier);
+    }
+    for (const s of suffixes) {
+      add(identifier + s);
+    }
+    return candidates;
+  };
+}
+function createStrategy(name, pattern) {
+  switch (name) {
+    case "sequential":
+      return createDefaultSuggest(pattern);
+    case "random-digits":
+      return createRandomDigitsStrategy(pattern);
+    case "suffix-words":
+      return createSuffixWordsStrategy(pattern);
+    case "short-random":
+      return createShortRandomStrategy(pattern);
+    case "scramble":
+      return createScrambleStrategy(pattern);
+    case "similar":
+      return createSimilarStrategy(pattern);
+  }
+}
+function resolveGenerator(suggest, pattern) {
+  if (suggest?.generate) return suggest.generate;
+  const strategyInput = suggest?.strategy ?? ["sequential", "random-digits"];
+  if (typeof strategyInput === "function") return strategyInput;
+  const names = Array.isArray(strategyInput) ? strategyInput : [strategyInput];
+  const generators = names.map((name) => createStrategy(name, pattern));
+  if (generators.length === 1) return generators[0];
+  return (identifier) => {
+    const lists = generators.map((g) => g(identifier));
+    const seen = /* @__PURE__ */ new Set();
+    const result = [];
+    const maxListLen = Math.max(...lists.map((l) => l.length));
+    for (let i = 0; i < maxListLen; i++) {
+      for (const list of lists) {
+        if (i < list.length && !seen.has(list[i])) {
+          seen.add(list[i]);
+          result.push(list[i]);
+        }
+      }
+    }
+    return result;
+  };
+}
 function normalize(raw) {
   return raw.trim().toLowerCase().replace(/^@+/, "");
 }
@@ -104,6 +304,8 @@ function createNamespaceGuard(config, adapter) {
     const cached = cacheMap.get(key);
     if (cached && cached.expires > now) {
       cacheHits++;
+      cacheMap.delete(key);
+      cacheMap.set(key, cached);
       return cached.promise;
     }
     cacheMisses++;
@@ -131,6 +333,24 @@ function createNamespaceGuard(config, adapter) {
     }
     return null;
   }
+  async function checkDbOnly(value, scope) {
+    const findOptions = config.caseInsensitive ? { caseInsensitive: true } : void 0;
+    const checks = config.sources.map(async (source) => {
+      const existing = await cachedFindOne(source, value, findOptions);
+      if (!existing) return null;
+      if (source.scopeKey) {
+        const scopeValue = scope[source.scopeKey];
+        const idColumn = source.idColumn ?? "id";
+        const existingId = existing[idColumn];
+        if (scopeValue && existingId && scopeValue === String(existingId)) {
+          return null;
+        }
+      }
+      return source.name;
+    });
+    const results = await Promise.all(checks);
+    return !results.some((r) => r !== null);
+  }
   async function check(identifier, scope = {}, options) {
     const normalized = normalize(identifier);
     if (!pattern.test(normalized)) {
@@ -180,16 +400,45 @@ function createNamespaceGuard(config, adapter) {
         source: collision
       };
       if (config.suggest && !options?.skipSuggestions) {
-        const generate = config.suggest.generate ?? createDefaultSuggest(pattern);
+        const generate = resolveGenerator(config.suggest, pattern);
         const max = config.suggest.max ?? 3;
         const candidates = generate(normalized);
         const suggestions = [];
-        for (const candidate of candidates) {
-          if (suggestions.length >= max) break;
-          if (!pattern.test(candidate)) continue;
-          const candidateResult = await check(candidate, scope, { skipSuggestions: true });
-          if (candidateResult.available) {
-            suggestions.push(candidate);
+        const passedSync = candidates.filter(
+          (c) => pattern.test(c) && !reservedMap.has(c)
+        );
+        for (let i = 0; i < passedSync.length && suggestions.length < max; i += max) {
+          const batch = passedSync.slice(i, i + max);
+          let validated = batch;
+          if (validators.length > 0) {
+            const validationResults = await Promise.all(
+              batch.map(async (c) => {
+                for (const validator of validators) {
+                  try {
+                    const rejection = await validator(c);
+                    if (rejection) return null;
+                  } catch {
+                    return null;
+                  }
+                }
+                return c;
+              })
+            );
+            validated = validationResults.filter(
+              (c) => c !== null
+            );
+          }
+          if (validated.length > 0) {
+            const dbResults = await Promise.all(
+              validated.map(async (c) => ({
+                candidate: c,
+                available: await checkDbOnly(c, scope)
+              }))
+            );
+            for (const { candidate, available } of dbResults) {
+              if (suggestions.length >= max) break;
+              if (available) suggestions.push(candidate);
+            }
           }
         }
         if (suggestions.length > 0) {