@stll/text-search 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/text-search",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Multi-engine text search orchestrator. Routes patterns to optimal engines: Aho-Corasick, RegexSet, or FuzzySearch.",
   "keywords": [
     "text-search",
@@ -26,7 +26,7 @@
     ".": "./src/index.ts"
   },
   "files": [
-    "dist"
+    "src"
   ],
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --target node",

package/src/classify.ts

@@ -0,0 +1,217 @@
+import type { PatternEntry } from "./types";
+
+/**
+ * Normalized pattern with metadata for routing.
+ */
+export type ClassifiedPattern = {
+  /** Original index in the input array. */
+  originalIndex: number;
+  /** The regex-compatible pattern string. */
+  pattern: string | RegExp;
+  /** Optional name. */
+  name?: string;
+  /**
+   * Number of top-level alternation branches.
+   * Used to detect large alternations that should
+   * be isolated into their own RegexSet instance.
+   */
+  alternationCount: number;
+  /**
+   * True if the pattern is a pure literal string
+   * (no regex metacharacters). These can be routed
+   * to Aho-Corasick for SIMD-accelerated matching.
+   */
+  isLiteral: boolean;
+  /**
+   * Fuzzy distance if this is a fuzzy pattern.
+   * Routes to @stll/fuzzy-search.
+   */
+  fuzzyDistance?: number | "auto";
+  /**
+   * Per-pattern AC options. When set, this literal
+   * is grouped with others that have the same
+   * options into a separate AC engine instance.
+   */
+  acOptions?: {
+    caseInsensitive?: boolean;
+    wholeWords?: boolean;
+  };
+};
+
+/**
+ * Check if a string is a pure literal (no regex
+ * metacharacters). Pure literals are routed to
+ * Aho-Corasick instead of the regex DFA.
+ */
+export function isLiteralPattern(
+  pattern: string,
+): boolean {
+  // All standard regex metacharacters cause a
+  // pattern to be classified as regex (→ RegexSet).
+  // To force literal AC routing for patterns with
+  // dots/parens (e.g., "s.r.o.", "č.p."), use the
+  // explicit { literal: true } PatternEntry flag.
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]!;
+    if (
+      ch === "\\" ||
+      ch === "." ||
+      ch === "^" ||
+      ch === "$" ||
+      ch === "*" ||
+      ch === "+" ||
+      ch === "?" ||
+      ch === "{" ||
+      ch === "}" ||
+      ch === "(" ||
+      ch === ")" ||
+      ch === "[" ||
+      ch === "]" ||
+      ch === "|"
+    ) {
+      return false;
+    }
+  }
+  return pattern.length > 0;
+}
+
+/**
+ * Count the maximum alternation branches at any
+ * depth in a regex string. Used to detect patterns
+ * with large alternations (even nested inside
+ * groups) that should be isolated into their own
+ * RegexSet to prevent DFA state explosion.
+ *
+ * "a|b|c" → 3
+ * "(a|b)|c" → 2 (max of top=2, depth1=2)
+ * "(?:Ing\\.|Mgr\\.|Dr\\.)" → 3 (depth 1)
+ */
+export function countAlternations(
+  pattern: string,
+): number {
+  let depth = 0;
+  let inClass = false;
+  let i = 0;
+
+  // Track max alternation count seen at any depth.
+  // Each time we enter a group, start a fresh count.
+  // When we leave, update the global max.
+  let max = 1;
+  let currentCount = 1; // count for current group
+  const stack: number[] = []; // saved counts
+
+  while (i < pattern.length) {
+    const ch = pattern[i];
+
+    if (ch === "\\" && i + 1 < pattern.length) {
+      i += 2;
+      continue;
+    }
+
+    if (ch === "[") inClass = true;
+    if (ch === "]") inClass = false;
+
+    if (!inClass) {
+      if (ch === "(") {
+        stack.push(currentCount);
+        currentCount = 1;
+        depth++;
+      }
+      if (ch === ")") {
+        if (currentCount > max) max = currentCount;
+        currentCount = stack.pop() ?? 1;
+        depth--;
+      }
+      if (ch === "|") {
+        currentCount++;
+      }
+    }
+
+    i++;
+  }
+  // Check top-level count too
+  if (currentCount > max) max = currentCount;
+  return max;
+}
+
+/**
+ * Classify and normalize pattern entries.
+ */
+export function classifyPatterns(
+  entries: PatternEntry[],
+  allLiteral = false,
+): ClassifiedPattern[] {
+  return entries.map((entry, i) => {
+    if (typeof entry === "string") {
+      return {
+        originalIndex: i,
+        pattern: entry,
+        alternationCount: allLiteral
+          ? 0
+          : countAlternations(entry),
+        isLiteral: allLiteral ||
+          isLiteralPattern(entry),
+      };
+    }
+
+    if (entry instanceof RegExp) {
+      return {
+        originalIndex: i,
+        pattern: entry,
+        alternationCount: countAlternations(
+          entry.source,
+        ),
+        isLiteral: false, // RegExp is never literal
+      };
+    }
+
+    // Fuzzy pattern: has `distance` field
+    if ("distance" in entry) {
+      return {
+        originalIndex: i,
+        pattern: entry.pattern,
+        name: entry.name,
+        alternationCount: 0,
+        isLiteral: false,
+        fuzzyDistance: entry.distance,
+      };
+    }
+
+    // Explicit literal: skip metachar detection
+    if ("literal" in entry && entry.literal) {
+      const hasPerPatternOpts =
+        "caseInsensitive" in entry ||
+        "wholeWords" in entry;
+      return {
+        originalIndex: i,
+        pattern: entry.pattern,
+        name: entry.name,
+        alternationCount: 0,
+        isLiteral: true,
+        acOptions: hasPerPatternOpts
+          ? {
+              caseInsensitive:
+                entry.caseInsensitive,
+              wholeWords: entry.wholeWords,
+            }
+          : undefined,
+      };
+    }
+
+    const pat = entry.pattern;
+    const source =
+      pat instanceof RegExp ? pat.source : pat;
+
+    return {
+      originalIndex: i,
+      pattern: pat,
+      name: entry.name,
+      alternationCount: allLiteral
+        ? 0
+        : countAlternations(source),
+      isLiteral:
+        typeof pat === "string" &&
+        (allLiteral || isLiteralPattern(pat)),
+    };
+  });
+}

package/src/merge.ts

@@ -0,0 +1,34 @@
+import type { Match } from "./types";
+
+/**
+ * Merge matches from multiple engines, sort by
+ * position, and select non-overlapping (longest
+ * first at ties). Same algorithm as regex-set's
+ * internal select_non_overlapping.
+ */
+export function mergeAndSelect(
+  matches: Match[],
+): Match[] {
+  if (matches.length <= 1) return matches;
+
+  // Sort: start ascending, longest first at ties
+  matches.sort((a, b) => {
+    if (a.start !== b.start) {
+      return a.start - b.start;
+    }
+    return b.end - b.start - (a.end - a.start);
+  });
+
+  // Greedily select non-overlapping
+  const selected: Match[] = [];
+  let lastEnd = 0;
+
+  for (const m of matches) {
+    if (m.start >= lastEnd) {
+      selected.push(m);
+      lastEnd = m.end;
+    }
+  }
+
+  return selected;
+}

package/src/text-search.ts

@@ -0,0 +1,525 @@
+import { AhoCorasick } from "@stll/aho-corasick";
+import { FuzzySearch } from "@stll/fuzzy-search";
+import { RegexSet } from "@stll/regex-set";
+
+import type { ClassifiedPattern } from "./classify";
+import { classifyPatterns } from "./classify";
+import { mergeAndSelect } from "./merge";
+import type {
+  Match,
+  PatternEntry,
+  TextSearchOptions,
+} from "./types";
+
+/**
+ * An engine instance with pattern index mapping.
+ */
+type RegexSlot = {
+  type: "regex";
+  rs: RegexSet;
+  indexMap: number[];
+  nameMap: (string | undefined)[];
+};
+
+type AcSlot = {
+  type: "ac";
+  ac: AhoCorasick;
+  indexMap: number[];
+  nameMap: (string | undefined)[];
+};
+
+type FuzzySlot = {
+  type: "fuzzy";
+  fs: FuzzySearch;
+  indexMap: number[];
+  nameMap: (string | undefined)[];
+};
+
+type EngineSlot = RegexSlot | AcSlot | FuzzySlot;
+
+/**
+ * Multi-engine text search orchestrator.
+ *
+ * Routes patterns to the optimal engine
+ * configuration:
+ * - Large alternation patterns get their own
+ *   RegexSet instance (prevents DFA state explosion)
+ * - Normal patterns share a single RegexSet
+ *   (single-pass multi-pattern DFA)
+ *
+ * Merges results from all engines into a unified
+ * non-overlapping Match[] sorted by position.
+ */
+export class TextSearch {
+  private engines: EngineSlot[] = [];
+  private patternCount: number;
+  private overlapAll: boolean;
+  /**
+   * True when there's exactly one engine and all
+   * patterns map to identity indices (0→0, 1→1, ...).
+   * Enables zero-overhead findIter: return raw engine
+   * output without remapping or object allocation.
+   */
+  private zeroOverhead: boolean = false;
+
+  constructor(
+    patterns: PatternEntry[],
+    options?: TextSearchOptions,
+  ) {
+    this.patternCount = patterns.length;
+    this.overlapAll =
+      options?.overlapStrategy === "all";
+    const maxAlt = options?.maxAlternations ?? 50;
+    const classified = classifyPatterns(
+      patterns,
+      options?.allLiteral ?? false,
+    );
+
+    // Four buckets:
+    // 1. Fuzzy patterns → FuzzySearch (Levenshtein)
+    // 2. Pure literals → Aho-Corasick (SIMD)
+    // 3. Normal regex → shared RegexSet (DFA)
+    // 4. Large alternations → isolated RegexSet
+    const fuzzy: ClassifiedPattern[] = [];
+    const literals: ClassifiedPattern[] = [];
+    const shared: ClassifiedPattern[] = [];
+    const isolated: ClassifiedPattern[] = [];
+
+    for (const cp of classified) {
+      if (cp.fuzzyDistance !== undefined) {
+        fuzzy.push(cp);
+      } else if (cp.isLiteral) {
+        literals.push(cp);
+      } else if (cp.alternationCount > maxAlt) {
+        isolated.push(cp);
+      } else {
+        shared.push(cp);
+      }
+    }
+
+    const rsOptions = {
+      unicodeBoundaries:
+        options?.unicodeBoundaries ?? true,
+      wholeWords: options?.wholeWords ?? false,
+      caseInsensitive:
+        options?.caseInsensitive ?? false,
+    };
+
+    // Build fuzzy engine
+    if (fuzzy.length > 0) {
+      this.engines.push(
+        buildFuzzyEngine(fuzzy, {
+          unicodeBoundaries:
+            rsOptions.unicodeBoundaries,
+          wholeWords: rsOptions.wholeWords,
+          metric: options?.fuzzyMetric,
+          normalizeDiacritics:
+            options?.normalizeDiacritics,
+          caseInsensitive:
+            options?.caseInsensitive,
+        }),
+      );
+    }
+
+    // Build AC engine(s) for pure literals.
+    // Group by per-pattern AC options so patterns
+    // with different caseInsensitive/wholeWords
+    // settings get separate AC instances.
+    if (literals.length > 0) {
+      const groups = new Map<
+        string,
+        ClassifiedPattern[]
+      >();
+      for (const cp of literals) {
+        const ci =
+          cp.acOptions?.caseInsensitive ??
+          rsOptions.caseInsensitive;
+        const ww =
+          cp.acOptions?.wholeWords ??
+          rsOptions.wholeWords;
+        const key = `${ci ? 1 : 0}:${ww ? 1 : 0}`;
+        const group = groups.get(key);
+        if (group) {
+          group.push(cp);
+        } else {
+          groups.set(key, [cp]);
+        }
+      }
+      for (const [key, group] of groups) {
+        const [ci, ww] = key.split(":");
+        this.engines.push(
+          buildAcEngine(group, {
+            ...rsOptions,
+            caseInsensitive: ci === "1",
+            wholeWords: ww === "1",
+          }),
+        );
+      }
+    }
+
+    // Adaptive regex grouping: try combining shared
+    // patterns, measure actual search time on a
+    // probe string. If combined is slower than
+    // individual, fall back to isolation.
+    if (shared.length > 1) {
+      const combined = buildRegexEngine(
+        shared,
+        rsOptions,
+      );
+      // Probe: 1KB of mixed content
+      const probe = (
+        "Hello World 123 test@example.com " +
+        "2025-01-01 +420 123 456 789 " +
+        "Ing. Jan Novák, s.r.o. Praha 1 "
+      ).repeat(10);
+      const t0 = performance.now();
+      combined.rs.findIter(probe);
+      const combinedMs = performance.now() - t0;
+
+      // Individual baseline (sum of isolated scans)
+      let individualMs = 0;
+      const individualEngines: RegexSlot[] = [];
+      for (const cp of shared) {
+        const eng = buildRegexEngine(
+          [cp],
+          rsOptions,
+        );
+        const t1 = performance.now();
+        eng.rs.findIter(probe);
+        individualMs += performance.now() - t1;
+        individualEngines.push(eng);
+      }
+
+      if (combinedMs > individualMs * 1.5) {
+        // Combined is >1.5x slower — isolate
+        for (const eng of individualEngines) {
+          this.engines.push(eng);
+        }
+      } else {
+        this.engines.push(combined);
+      }
+    } else if (shared.length === 1) {
+      this.engines.push(
+        buildRegexEngine(shared, rsOptions),
+      );
+    }
+
+    for (const cp of isolated) {
+      this.engines.push(
+        buildRegexEngine([cp], rsOptions),
+      );
+    }
+
+    // Zero-overhead fast path: when all patterns
+    // land in a single engine, the indexMap is
+    // identity (0→0, 1→1, ...) and no names need
+    // attaching. findIter can return raw engine
+    // output without any JS-side remapping.
+    if (this.engines.length === 1) {
+      const engine = this.engines[0]!;
+      const hasNames = engine.nameMap.some(
+        (n) => n !== undefined,
+      );
+      if (!hasNames) {
+        this.zeroOverhead = true;
+      }
+    }
+  }
+
+  /** Number of patterns. */
+  get length(): number {
+    return this.patternCount;
+  }
+
+  /** Returns true if any pattern matches. */
+  isMatch(haystack: string): boolean {
+    for (const engine of this.engines) {
+      if (engineIsMatch(engine, haystack)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Find matches in text.
+   *
+   * With `overlapStrategy: "longest"` (default):
+   * returns non-overlapping matches, longest wins.
+   *
+   * With `overlapStrategy: "all"`: returns all
+   * matches including overlaps, sorted by position.
+   */
+  findIter(haystack: string): Match[] {
+    // Fast path: single engine, identity indexMap,
+    // no names → return raw engine output directly.
+    // Zero JS overhead: no remapping, no allocation.
+    if (this.zeroOverhead) {
+      return engineFindIter(
+        this.engines[0]!,
+        haystack,
+      );
+    }
+
+    // Single engine but needs name remapping
+    if (this.engines.length === 1) {
+      return remapMatches(
+        engineFindIter(this.engines[0]!, haystack),
+        this.engines[0]!,
+      );
+    }
+
+    // Multi-engine: collect from all, remap in-place
+    const all: Match[] = [];
+    for (const engine of this.engines) {
+      const matches = engineFindIter(
+        engine,
+        haystack,
+      );
+      // In-place remapping avoids .map() allocation
+      for (const m of remapMatches(matches, engine)) {
+        all.push(m);
+      }
+    }
+
+    if (this.overlapAll) {
+      return all.sort(
+        (a, b) => a.start - b.start,
+      );
+    }
+
+    return mergeAndSelect(all);
+  }
+
+  /** Which pattern indices matched (not where). */
+  whichMatch(haystack: string): number[] {
+    const seen = new Set<number>();
+
+    for (const engine of this.engines) {
+      // AC doesn't have whichMatch — use findIter
+      const matches = engineFindIter(
+        engine,
+        haystack,
+      );
+      for (const m of matches) {
+        seen.add(engine.indexMap[m.pattern]!);
+      }
+    }
+
+    return [...seen];
+  }
+
+  /**
+   * Replace all non-overlapping matches.
+   * replacements[i] replaces pattern i.
+   */
+  replaceAll(
+    haystack: string,
+    replacements: string[],
+  ): string {
+    if (replacements.length !== this.patternCount) {
+      throw new Error(
+        `Expected ${this.patternCount} ` +
+          `replacements, got ${replacements.length}`,
+      );
+    }
+
+    // Always use non-overlapping matches for
+    // replacement, even if overlapStrategy is "all".
+    const all: Match[] = [];
+    for (const engine of this.engines) {
+      const matches = engineFindIter(
+        engine,
+        haystack,
+      );
+      for (const m of remapMatches(matches, engine)) {
+        all.push(m);
+      }
+    }
+    const matches = mergeAndSelect(all);
+
+    let result = "";
+    let last = 0;
+
+    for (const m of matches) {
+      result += haystack.slice(last, m.start);
+      result += replacements[m.pattern]!;
+      last = m.end;
+    }
+
+    result += haystack.slice(last);
+    return result;
+  }
+}
+
+/**
+ * Build a RegexSet engine from classified patterns.
+ */
+function buildRegexEngine(
+  patterns: ClassifiedPattern[],
+  options: {
+    unicodeBoundaries: boolean;
+    wholeWords: boolean;
+    caseInsensitive: boolean;
+  },
+): RegexSlot {
+  const rsPatterns: (string | RegExp | {
+    pattern: string | RegExp;
+    name?: string;
+  })[] = [];
+  const indexMap: number[] = [];
+  const nameMap: (string | undefined)[] = [];
+
+  for (const cp of patterns) {
+    if (cp.name !== undefined) {
+      rsPatterns.push({
+        pattern: cp.pattern,
+        name: cp.name,
+      });
+    } else {
+      rsPatterns.push(cp.pattern);
+    }
+    indexMap.push(cp.originalIndex);
+    nameMap.push(cp.name);
+  }
+
+  const rs = new RegexSet(rsPatterns, options);
+
+  return { type: "regex", rs, indexMap, nameMap };
+}
+
+/**
+ * Build an Aho-Corasick engine from literal patterns.
+ */
+function buildAcEngine(
+  patterns: ClassifiedPattern[],
+  options: {
+    unicodeBoundaries: boolean;
+    wholeWords: boolean;
+    caseInsensitive: boolean;
+  },
+): AcSlot {
+  const literals: string[] = [];
+  const indexMap: number[] = [];
+  const nameMap: (string | undefined)[] = [];
+
+  for (const cp of patterns) {
+    literals.push(cp.pattern as string);
+    indexMap.push(cp.originalIndex);
+    nameMap.push(cp.name);
+  }
+
+  const ac = new AhoCorasick(literals, {
+    wholeWords: options.wholeWords,
+    unicodeBoundaries: options.unicodeBoundaries,
+    caseInsensitive: options.caseInsensitive,
+  });
+
+  return { type: "ac", ac, indexMap, nameMap };
+}
+
+/**
+ * Build a FuzzySearch engine from fuzzy patterns.
+ */
+function buildFuzzyEngine(
+  patterns: ClassifiedPattern[],
+  options: {
+    unicodeBoundaries: boolean;
+    wholeWords: boolean;
+    metric?: "levenshtein" | "damerau-levenshtein";
+    normalizeDiacritics?: boolean;
+    caseInsensitive?: boolean;
+  },
+): FuzzySlot {
+  const fsPatterns: {
+    pattern: string;
+    distance?: number | "auto";
+    name?: string;
+  }[] = [];
+  const indexMap: number[] = [];
+  const nameMap: (string | undefined)[] = [];
+
+  for (const cp of patterns) {
+    fsPatterns.push({
+      pattern: cp.pattern as string,
+      distance: cp.fuzzyDistance,
+      name: cp.name,
+    });
+    indexMap.push(cp.originalIndex);
+    nameMap.push(cp.name);
+  }
+
+  const fs = new FuzzySearch(fsPatterns, {
+    unicodeBoundaries: options.unicodeBoundaries,
+    wholeWords: options.wholeWords,
+    metric: options.metric,
+    normalizeDiacritics:
+      options.normalizeDiacritics,
+    caseInsensitive: options.caseInsensitive,
+  });
+
+  return { type: "fuzzy", fs, indexMap, nameMap };
+}
+
+/**
+ * Dispatch isMatch to the correct engine.
+ */
+function engineIsMatch(
+  engine: EngineSlot,
+  haystack: string,
+): boolean {
+  switch (engine.type) {
+    case "ac":
+      return engine.ac.isMatch(haystack);
+    case "fuzzy":
+      return engine.fs.isMatch(haystack);
+    case "regex":
+      return engine.rs.isMatch(haystack);
+  }
+}
+
+/**
+ * Dispatch findIter to the correct engine.
+ */
+function engineFindIter(
+  engine: EngineSlot,
+  haystack: string,
+): Match[] {
+  switch (engine.type) {
+    case "ac":
+      return engine.ac.findIter(haystack);
+    case "fuzzy":
+      return engine.fs.findIter(haystack);
+    case "regex":
+      return engine.rs.findIter(haystack);
+  }
+}
+
+/**
+ * Remap engine-local match indices to original
+ * input indices and add names.
+ */
+function remapMatches(
+  matches: Match[],
+  engine: EngineSlot,
+): Match[] {
+  return matches.map((m) => {
+    const originalIdx =
+      engine.indexMap[m.pattern]!;
+    const name = engine.nameMap[m.pattern];
+    const result: Match = {
+      pattern: originalIdx,
+      start: m.start,
+      end: m.end,
+      text: m.text,
+    };
+    if (name !== undefined) {
+      result.name = name;
+    }
+    // Preserve edit distance from fuzzy matches
+    if ("distance" in m && m.distance !== undefined) {
+      result.distance = m.distance as number;
+    }
+    return result;
+  });
+}

package/src/types.ts

@@ -0,0 +1,114 @@
+/**
+ * A single match result. Same shape as
+ * @stll/regex-set and @stll/aho-corasick.
+ */
+export type Match = {
+  /** Index of the pattern that matched. */
+  pattern: number;
+  /** Start UTF-16 code unit offset. */
+  start: number;
+  /** End offset (exclusive). */
+  end: number;
+  /** The matched text. */
+  text: string;
+  /** Pattern name (if provided). */
+  name?: string;
+  /** Edit distance (fuzzy matches only). */
+  distance?: number;
+};
+
+/** A pattern entry for TextSearch. */
+export type PatternEntry =
+  | string
+  | RegExp
+  | {
+      pattern: string | RegExp;
+      name?: string;
+    }
+  | {
+      pattern: string;
+      name?: string;
+      /** Fuzzy matching distance. Routes to
+       *  @stll/fuzzy-search instead of regex. */
+      distance: number | "auto";
+    }
+  | {
+      pattern: string;
+      name?: string;
+      /** Force literal matching via Aho-Corasick.
+       *  Skips regex metacharacter detection so
+       *  patterns like "č.p." or "s.r.o." are
+       *  matched literally, not as regex. */
+      literal: true;
+      /** Per-pattern case-insensitive for AC.
+       *  Overrides the global option for this
+       *  pattern only. */
+      caseInsensitive?: boolean;
+      /** Per-pattern whole-word matching for AC. */
+      wholeWords?: boolean;
+    };
+
+/** Options for TextSearch. */
+export type TextSearchOptions = {
+  /**
+   * Use Unicode word boundaries.
+   * @default true
+   */
+  unicodeBoundaries?: boolean;
+
+  /**
+   * Only match whole words.
+   * @default false
+   */
+  wholeWords?: boolean;
+
+  /**
+   * Max alternation branches before auto-splitting
+   * into a separate engine instance. Prevents DFA
+   * state explosion when large-alternation patterns
+   * are combined with other patterns.
+   * @default 50
+   */
+  maxAlternations?: number;
+
+  /**
+   * Fuzzy matching metric.
+   * @default "levenshtein"
+   */
+  fuzzyMetric?: "levenshtein" | "damerau-levenshtein";
+
+  /**
+   * Normalize diacritics for fuzzy matching.
+   * @default false
+   */
+  normalizeDiacritics?: boolean;
+
+  /**
+   * Case-insensitive matching for AC literals
+   * and fuzzy patterns.
+   * @default false
+   */
+  caseInsensitive?: boolean;
+
+  /**
+   * How to handle overlapping matches from
+   * different engines or patterns.
+   *
+   * - "longest": keep longest non-overlapping match
+   *   at each position (default).
+   * - "all": return all matches including overlaps.
+   *   Useful when the caller applies its own dedup.
+   *
+   * @default "longest"
+   */
+  overlapStrategy?: "longest" | "all";
+
+  /**
+   * Treat ALL string patterns as literals (route
+   * to AC, skip metacharacter detection). Useful
+   * for deny-list patterns where "s.r.o." means
+   * the literal string, not a regex with wildcards.
+   * @default false
+   */
+  allLiteral?: boolean;
+};