@quereus/quereus 4.3.1 → 4.4.0

package/dist/src/util/key-serializer.js

@@ -1,3 +1,4 @@
+import { canonicalJsonString } from './json-canonical.js';
 /** Identity normalizer for BINARY collation (no-op). */
 const IDENTITY_NORMALIZER = (s) => s;
 /** Strip trailing ASCII space (0x20) only, matching `RTRIM_COLLATION`'s
@@ -10,26 +11,54 @@ const RTRIM_NORMALIZER = (s) => {
     return end === s.length ? s : s.slice(0, end);
 };
 const NOCASE_NORMALIZER = (s) => s.toLowerCase();
-/** Map a collation name to a string normalizer for key serialization. */
-export function resolveKeyNormalizer(collationName) {
-    if (!collationName || collationName === 'BINARY')
-        return IDENTITY_NORMALIZER;
-    switch (collationName.toUpperCase()) {
-        case 'NOCASE': return NOCASE_NORMALIZER;
-        case 'RTRIM': return RTRIM_NORMALIZER;
-        default: return IDENTITY_NORMALIZER;
-    }
-}
 /** Built-in normalizers, exported so the `Database` collation registry can seed
- *  them alongside the comparators. Keys match the SQL canonical names. */
+ *  them alongside the comparators, and so a caller with no `Database` in scope (the
+ *  store's default key-normalizer resolver) can build a built-ins-only resolver over
+ *  the same three functions rather than a divergent local copy. Keys match the SQL
+ *  canonical names.
+ *
+ *  Any caller that DOES hold a `Database` must resolve through
+ *  `db.getKeyNormalizerResolver()` (or `EmissionContext.resolveKeyNormalizer()` from an
+ *  emitter) — indexing this map directly cannot see a collation registered with
+ *  `db.registerCollation`, so it buckets rows the database's own comparator considers
+ *  equal into different groups. */
 export const BUILTIN_NORMALIZERS = {
     BINARY: IDENTITY_NORMALIZER,
     NOCASE: NOCASE_NORMALIZER,
     RTRIM: RTRIM_NORMALIZER,
 };
+/**
+ * Normalize a numeric SQL value (number | bigint | boolean) to a decimal string
+ * so that values equal under {@link import('./comparison.js').compareSqlValues}
+ * (numeric storage class: `5n` == `5`, `true` == `1`) serialize identically.
+ *
+ * Integer-valued numbers route through `BigInt(n)` so `5`, `5.0`, and `5n` all
+ * yield `"5"` — and `BigInt` captures a float's exact mathematical value, so an
+ * imprecise integer float (e.g. `1e30`) matches whatever the mixed number/bigint
+ * comparator sees. Non-integer numbers keep their `String(n)` form.
+ *
+ * NOTE: NaN/±Infinity fall to `String(n)` ("NaN"/"Infinity"), so two NaN key
+ * alike but NaN never keys equal to a finite value — the numeric comparator
+ * treats NaN as equal to everything, a degenerate edge not worth splitting keys
+ * over. If NaN-valued numeric keys ever matter, revisit here.
+ */
+function canonicalNumeric(val) {
+    if (typeof val === 'boolean')
+        return val ? '1' : '0';
+    if (typeof val === 'bigint')
+        return val.toString();
+    if (Number.isInteger(val))
+        return BigInt(val).toString();
+    return String(val);
+}
 /**
  * Core serialization of a single SQL value with type tag and optional collation normalizer.
  * Appends to the key accumulator.  Returns false if the value is NULL (caller decides semantics).
+ *
+ * The tag/normalization rules mirror `compareSqlValues`: numeric-class values
+ * (number/bigint/boolean) share the `n:` tag via {@link canonicalNumeric} so
+ * equal-but-differently-typed numerics key alike, and OBJECT-class values route
+ * through {@link canonicalJsonString} so reorder-equal JSON objects key alike.
  */
 function appendValue(val, normalizer) {
     if (val === null || val === undefined)
@@ -37,17 +66,14 @@ function appendValue(val, normalizer) {
     if (typeof val === 'string') {
         return 's:' + normalizer(val);
     }
-    else if (typeof val === 'number') {
-        return 'n:' + val;
-    }
-    else if (typeof val === 'bigint') {
-        return 'b:' + val;
+    else if (typeof val === 'number' || typeof val === 'bigint' || typeof val === 'boolean') {
+        return 'n:' + canonicalNumeric(val);
     }
     else if (val instanceof Uint8Array) {
         return 'x:' + Array.from(val).join(',');
     }
     else {
-        return 'o:' + String(val);
+        return 'o:' + canonicalJsonString(val);
     }
 }
 /**

package/dist/src/util/key-serializer.js.map

@@ -1 +1 @@
-{"version":3,"file":"key-serializer.js","sourceRoot":"","sources":["../../../src/util/key-serializer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"key-serializer.js","sourceRoot":"","sources":["../../../src/util/key-serializer.ts"],"names":[],"mappings":"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"}

package/dist/src/util/key-tuple-codec.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Reversible, type-faithful codec for a tuple of `SqlValue`s, used to key the
+ * transaction change log by its primary-key (or captured-column) tuple.
+ *
+ * WHY NOT canonical JSON: the change log formerly keyed via
+ * `canonicalJsonString` (`JSON.stringify` under the hood), which throws
+ * "Do not know how to serialize a BigInt" the moment a PK value is a JS bigint
+ * (any integer beyond `Number.MAX_SAFE_INTEGER`). It is also not reversible for
+ * bigint/blob (a decoded number loses the low bits; a blob decodes as an object).
+ *
+ * WHY NOT `key-serializer.ts` (`serializeKey`): that encoder *unifies* numerics
+ * (`5`, `5.0`, `5n` all collapse to one key), is one-way (no decoder), and
+ * returns null on any NULL element. The change log needs a decoder
+ * (`decodeKeyTuple` feeds `getChangedKeyTuples`) and must stay type-distinct so
+ * its keys agree with `delta-executor`'s `tupleKey` (which keys bigint and
+ * number separately) when watch literals are intersected against changes.
+ *
+ * NOTE: this codec intentionally keeps `5n` (bigint) and `5` (number) as
+ * DISTINCT keys — matching `delta-executor` `tupleKey`, and unlike
+ * `compareSqlValues` (which treats `5n == 5`). If a single logical row's PK were
+ * ever presented as differently-typed numerics across two ops in one
+ * transaction, its INSERT/DELETE would not coalesce. Not reachable today (a
+ * table's PK storage type is stable per row); if it ever becomes reachable,
+ * unify numerics in BOTH this codec and `delta-executor` `tupleKey` together.
+ *
+ * Encoding: a JSON array of type-tagged element strings (first char = tag), then
+ * `JSON.stringify`d. The tag makes the encoding collision-free across types and
+ * the whole string reversible. Scalar-tuple keys stay stable across a decode/
+ * encode round-trip; JSON-object components keep the canonical (recursively
+ * key-sorted) form so reorder-equal objects still coalesce to one entry.
+ */
+import type { SqlValue } from '../common/types.js';
+/** Encode a tuple of `SqlValue`s to a stable, reversible string key. */
+export declare function encodeKeyTuple(values: readonly SqlValue[]): string;
+/** Decode a key produced by {@link encodeKeyTuple} back to its tuple. */
+export declare function decodeKeyTuple(key: string): SqlValue[];
+//# sourceMappingURL=key-tuple-codec.d.ts.map

package/dist/src/util/key-tuple-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-tuple-codec.d.ts","sourceRoot":"","sources":["../../../src/util/key-tuple-codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAuDnD,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAIlE;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,EAAE,CAGtD"}

package/dist/src/util/key-tuple-codec.js

@@ -0,0 +1,65 @@
+import { canonicalJsonString } from './json-canonical.js';
+import { QuereusError } from '../common/errors.js';
+import { StatusCode } from '../common/types.js';
+function toHex(bytes) {
+    let s = '';
+    for (let i = 0; i < bytes.length; i++)
+        s += bytes[i].toString(16).padStart(2, '0');
+    return s;
+}
+function fromHex(hex) {
+    const out = new Uint8Array(hex.length >> 1);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return out;
+}
+/** Encode a single element to a tag-prefixed string. */
+function encodeElement(value) {
+    if (value === null || value === undefined)
+        return '0';
+    switch (typeof value) {
+        case 'string': return 's' + value;
+        // NOTE: JSON.stringify(NaN|±Infinity) → "null" and -0 → "0", so those
+        // degenerate number PKs decode lossily (NaN→null, -0→0). Matches the prior
+        // canonical-JSON keying (no regression); a NaN/±Inf PK is nonsensical and
+        // unreachable via real DML. Fix here + in decodeElement together if it ever matters.
+        case 'number': return 'n' + JSON.stringify(value); // round-trips via JSON.parse
+        case 'bigint': return 'i' + value.toString(); // decode: BigInt(rest)
+        case 'boolean': return value ? 'b1' : 'b0';
+        default:
+            if (value instanceof Uint8Array)
+                return 'x' + toHex(value);
+            // JSON object/array — keep canonical (recursively key-sorted) form so
+            // reorder-equal objects coalesce.
+            return 'j' + canonicalJsonString(value);
+    }
+}
+/** Decode a single tag-prefixed element string back to its `SqlValue`. */
+function decodeElement(part) {
+    const tag = part[0];
+    const rest = part.slice(1);
+    switch (tag) {
+        case '0': return null;
+        case 's': return rest;
+        case 'n': return JSON.parse(rest);
+        case 'i': return BigInt(rest);
+        case 'b': return rest === '1';
+        case 'x': return fromHex(rest);
+        case 'j': return JSON.parse(rest);
+        default:
+            throw new QuereusError(`key-tuple-codec: unknown element tag '${tag}'`, StatusCode.INTERNAL);
+    }
+}
+/** Encode a tuple of `SqlValue`s to a stable, reversible string key. */
+export function encodeKeyTuple(values) {
+    const parts = new Array(values.length);
+    for (let i = 0; i < values.length; i++)
+        parts[i] = encodeElement(values[i]);
+    return JSON.stringify(parts);
+}
+/** Decode a key produced by {@link encodeKeyTuple} back to its tuple. */
+export function decodeKeyTuple(key) {
+    const parts = JSON.parse(key);
+    return parts.map(decodeElement);
+}
+//# sourceMappingURL=key-tuple-codec.js.map

package/dist/src/util/key-tuple-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-tuple-codec.js","sourceRoot":"","sources":["../../../src/util/key-tuple-codec.ts"],"names":[],"mappings":"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"}

package/dist/src/util/latches.d.ts

@@ -1,16 +1,42 @@
 /**
- * Lightweight implementation of a mutex lock queue for managing concurrent access.
+ * Lightweight mutex lock queue for serializing concurrent access by string key.
+ *
+ * Each `Latches` instance owns its own queue map, so two independent owners (e.g.
+ * two `Database` instances) never share a latch even when they pass the same key.
+ * The engine holds one instance per `Database` (`db.latches`); callers namespace
+ * their key with `schema.table` to keep intra-database collisions to genuinely
+ * same-named tables.
+ *
+ * A process-global default instance backs the {@link Latches.acquire} *static*
+ * method, preserving the original shared-queue entry point for standalone
+ * callers (e.g. external store modules) that hold no `Database`.
  */
 export declare class Latches {
-    private static lockQueues;
+    private readonly lockQueues;
     /**
      * Acquires a lock for the given key. Waits if another operation holds the lock.
      * Returns a release function that must be called to release the lock.
      *
      * @param key A unique string identifier for the resource to lock.
      *            Should use `ClassName.methodName:${id}` format to avoid conflicts.
+     * @param timeoutMs Optional deadlock guard. When set and the predecessor does not
+     *            release within this many milliseconds, the wait is abandoned: a warning
+     *            is logged naming the contended key, this waiter's queue slot is released
+     *            so the queue behind it does not wedge, and the returned promise rejects
+     *            with a `QuereusError` (StatusCode.BUSY). Omit (the default) for the
+     *            original never-reject behavior.
      * @returns A function that must be called to release the lock
      */
-    static acquire(key: string): Promise<() => void>;
+    acquire(key: string, timeoutMs?: number): Promise<() => void>;
+    /** Process-global default instance backing the static {@link Latches.acquire}. */
+    private static readonly global;
+    /**
+     * Backward-compatible static entry point delegating to a single process-global
+     * instance. Same shared-queue semantics this class had before it became
+     * instance-based — kept for standalone callers (external store modules) that
+     * hold no `Database`. Engine call sites should prefer the owned per-database
+     * instance (`db.latches`) so two databases never contend on the same key.
+     */
+    static acquire(key: string, timeoutMs?: number): Promise<() => void>;
 }
 //# sourceMappingURL=latches.d.ts.map

package/dist/src/util/latches.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"latches.d.ts","sourceRoot":"","sources":["../../../src/util/latches.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,OAAO;IAEnB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAoC;IAE7D;;;;;;;OAOG;WACU,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;CA+BtD"}
+{"version":3,"file":"latches.d.ts","sourceRoot":"","sources":["../../../src/util/latches.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,qBAAa,OAAO;IAGnB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAE/D;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAsDnE,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAiB;IAE/C;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;CAGpE"}

package/dist/src/util/latches.js

@@ -1,18 +1,40 @@
+import { createLogger } from '../common/logger.js';
+import { QuereusError } from '../common/errors.js';
+import { StatusCode } from '../common/types.js';
+const log = createLogger('util:latches');
+const warnLog = log.extend('warn');
 /**
- * Lightweight implementation of a mutex lock queue for managing concurrent access.
+ * Lightweight mutex lock queue for serializing concurrent access by string key.
+ *
+ * Each `Latches` instance owns its own queue map, so two independent owners (e.g.
+ * two `Database` instances) never share a latch even when they pass the same key.
+ * The engine holds one instance per `Database` (`db.latches`); callers namespace
+ * their key with `schema.table` to keep intra-database collisions to genuinely
+ * same-named tables.
+ *
+ * A process-global default instance backs the {@link Latches.acquire} *static*
+ * method, preserving the original shared-queue entry point for standalone
+ * callers (e.g. external store modules) that hold no `Database`.
  */
 export class Latches {
-    // Stores the promise representing the completion of the last queued operation for a key.
-    static lockQueues = new Map();
+    // Stores the promise representing the completion of the last queued operation
+    // for a key. Instance-scoped: one map per Latches instance.
+    lockQueues = new Map();
     /**
      * Acquires a lock for the given key. Waits if another operation holds the lock.
      * Returns a release function that must be called to release the lock.
      *
      * @param key A unique string identifier for the resource to lock.
      *            Should use `ClassName.methodName:${id}` format to avoid conflicts.
+     * @param timeoutMs Optional deadlock guard. When set and the predecessor does not
+     *            release within this many milliseconds, the wait is abandoned: a warning
+     *            is logged naming the contended key, this waiter's queue slot is released
+     *            so the queue behind it does not wedge, and the returned promise rejects
+     *            with a `QuereusError` (StatusCode.BUSY). Omit (the default) for the
+     *            original never-reject behavior.
      * @returns A function that must be called to release the lock
      */
-    static async acquire(key) {
+    async acquire(key, timeoutMs) {
         // Get the promise the current operation needs to wait for (if any)
         const currentTail = this.lockQueues.get(key) ?? Promise.resolve();
         let resolveNewTail;
@@ -22,8 +44,6 @@ export class Latches {
         });
         // Immediately set the new promise as the tail for this key
         this.lockQueues.set(key, newTail);
-        // Wait for the previous operation (if any) to complete
-        await currentTail;
         // Return the function to release *this* lock
         const release = () => {
             // Signal that this operation is complete
@@ -35,7 +55,41 @@ export class Latches {
                 this.lockQueues.delete(key);
             }
         };
+        if (timeoutMs === undefined) {
+            // Wait for the previous operation (if any) to complete
+            await currentTail;
+            return release;
+        }
+        // Opt-in deadlock guard: bound the wait for the predecessor.
+        let timer;
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                warnLog('latch acquire timed out after %dms for key %s (possible deadlock); releasing waiter slot', timeoutMs, key);
+                // Release our own slot so the queue behind us is not wedged by the abandoned wait.
+                release();
+                reject(new QuereusError(`Latch acquire timed out after ${timeoutMs}ms for '${key}' (possible deadlock)`, StatusCode.BUSY));
+            }, timeoutMs);
+        });
+        try {
+            await Promise.race([currentTail, timeout]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
         return release;
     }
+    /** Process-global default instance backing the static {@link Latches.acquire}. */
+    static global = new Latches();
+    /**
+     * Backward-compatible static entry point delegating to a single process-global
+     * instance. Same shared-queue semantics this class had before it became
+     * instance-based — kept for standalone callers (external store modules) that
+     * hold no `Database`. Engine call sites should prefer the owned per-database
+     * instance (`db.latches`) so two databases never contend on the same key.
+     */
+    static acquire(key, timeoutMs) {
+        return this.global.acquire(key, timeoutMs);
+    }
 }
 //# sourceMappingURL=latches.js.map

package/dist/src/util/latches.js.map

@@ -1 +1 @@
-{"version":3,"file":"latches.js","sourceRoot":"","sources":["../../../src/util/latches.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,OAAO;IACnB,yFAAyF;IACjF,MAAM,CAAC,UAAU,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE7D;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,GAAW;QAC/B,mEAAmE;QACnE,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAElE,IAAI,cAA2B,CAAC;QAChC,6DAA6D;QAC7D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE;YAC3C,cAAc,GAAG,OAAO,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,2DAA2D;QAC3D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAElC,uDAAuD;QACvD,MAAM,WAAW,CAAC;QAElB,6CAA6C;QAC7C,MAAM,OAAO,GAAG,GAAG,EAAE;YACpB,yCAAyC;YACzC,cAAc,EAAE,CAAC;YAEjB,wDAAwD;YACxD,8EAA8E;YAC9E,2EAA2E;YAC3E,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC;gBAC1C,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;QACF,CAAC,CAAC;QAEF,OAAO,OAAO,CAAC;IAChB,CAAC"}
+{"version":3,"file":"latches.js","sourceRoot":"","sources":["../../../src/util/latches.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,MAAM,GAAG,GAAG,YAAY,CAAC,cAAc,CAAC,CAAC;AACzC,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAEnC;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,OAAO;IACnB,8EAA8E;IAC9E,4DAA4D;IAC3C,UAAU,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE/D;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,CAAC,GAAW,EAAE,SAAkB;QAC5C,mEAAmE;QACnE,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAElE,IAAI,cAA2B,CAAC;QAChC,6DAA6D;QAC7D,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE;YAC3C,cAAc,GAAG,OAAO,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,2DAA2D;QAC3D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAElC,6CAA6C;QAC7C,MAAM,OAAO,GAAG,GAAG,EAAE;YACpB,yCAAyC;YACzC,cAAc,EAAE,CAAC;YAEjB,wDAAwD;YACxD,8EAA8E;YAC9E,2EAA2E;YAC3E,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC;gBAC1C,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;QACF,CAAC,CAAC;QAEF,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC7B,uDAAuD;YACvD,MAAM,WAAW,CAAC;YAClB,OAAO,OAAO,CAAC;QAChB,CAAC;QAED,6DAA6D;QAC7D,IAAI,KAAgD,CAAC;QACrD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;YACvD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACvB,OAAO,CAAC,0FAA0F,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;gBACpH,mFAAmF;gBACnF,OAAO,EAAE,CAAC;gBACV,MAAM,CAAC,IAAI,YAAY,CACtB,iCAAiC,SAAS,WAAW,GAAG,uBAAuB,EAC/E,UAAU,CAAC,IAAI,CACf,CAAC,CAAC;YACJ,CAAC,EAAE,SAAS,CAAC,CAAC;QACf,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC;YACJ,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;QAC5C,CAAC;gBAAS,CAAC;YACV,IAAI,KAAK,KAAK,SAAS;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAED,kFAAkF;IAC1E,MAAM,CAAU,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;IAE/C;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,GAAW,EAAE,SAAkB;QAC7C,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC5C,CAAC"}

package/dist/src/util/patterns.d.ts

@@ -1,8 +1,24 @@
 /**
- * Simple LIKE pattern matching implementation.
- * Supports SQL LIKE patterns:
- * - % matches any sequence of characters (including empty sequence)
- * - _ matches any single character
+ * A compiled pattern matcher: given some text, returns whether it matches the
+ * pattern the matcher was compiled from. Compilation (pattern → RegExp) happens
+ * once; the returned closure is cheap to call per row.
+ */
+export type PatternMatcher = (text: string) => boolean;
+/**
+ * Compile (memoized) a LIKE pattern into a reusable matcher. Prefer this over
+ * {@link simpleLike} when matching many texts against a pattern that is known
+ * once (e.g. a literal-constant pattern captured at emit time): compile once,
+ * call the returned matcher per row.
+ */
+export declare const compileLikeMatcher: (pattern: string) => PatternMatcher;
+/**
+ * Compile (memoized) a GLOB pattern into a reusable matcher. See
+ * {@link compileLikeMatcher}.
+ */
+export declare const compileGlobMatcher: (pattern: string) => PatternMatcher;
+/**
+ * Simple LIKE pattern matching. Compilation is memoized, so repeated calls with
+ * the same pattern reuse a single compiled matcher.
  *
  * @param pattern The LIKE pattern
  * @param text The text to match against
@@ -10,10 +26,8 @@
  */
 export declare function simpleLike(pattern: string, text: string): boolean;
 /**
- * Simple GLOB pattern matching implementation.
- * Supports SQL GLOB patterns:
- * - * matches any sequence of characters (including empty sequence)
- * - ? matches any single character
+ * Simple GLOB pattern matching. Compilation is memoized, so repeated calls with
+ * the same pattern reuse a single compiled matcher.
  *
  * @param pattern The GLOB pattern
  * @param text The text to match against

package/dist/src/util/patterns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../../src/util/patterns.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAcjE;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CA4CjE"}
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../../src/util/patterns.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;AA2HvD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,YArGkD,MAAM,KAAK,cAqG/B,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,kBAAkB,YA3GkD,MAAM,KAAK,cA2G/B,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/src/util/patterns.js

@@ -1,17 +1,57 @@
 import { createLogger } from '../common/logger.js';
 const log = createLogger('util:patterns');
 const errorLog = log.extend('error');
+/** Matcher used when a pattern fails to compile — matches nothing (as before). */
+const NEVER_MATCH = () => false;
 /**
- * Simple LIKE pattern matching implementation.
+ * Small bounded (LRU) cap for each compiled-pattern cache. A workload with many
+ * distinct patterns evicts the least-recently-used entry rather than growing
+ * the cache unboundedly.
+ *
+ * NOTE: 256 is an untuned guess. If a real workload thrashes distinct patterns
+ * (cache-miss rate stays high), raise the cap or make it configurable.
+ */
+const PATTERN_CACHE_CAP = 256;
+/**
+ * Wrap a `compile` function with a bounded LRU cache so the same pattern string
+ * is compiled at most once (until evicted). A `Map` preserves insertion order,
+ * which gives a cheap LRU: on a hit re-insert the key to mark it most-recently
+ * used; on overflow evict the oldest (first) key.
+ *
+ * NOTE: the cache key is the pattern string alone. LIKE and GLOB each get their
+ * own cache (via separate `memoizeCompile` calls) so identical strings in the
+ * two different pattern languages never collide. If LIKE `ESCAPE` or
+ * case-insensitive matching is ever added, the escape char / case-fold flag
+ * MUST become part of the key (or key each variant into its own cache), else
+ * compiled matchers will collide across those variants.
+ */
+function memoizeCompile(compile) {
+    const cache = new Map();
+    return (pattern) => {
+        const cached = cache.get(pattern);
+        if (cached !== undefined) {
+            // Mark most-recently-used.
+            cache.delete(pattern);
+            cache.set(pattern, cached);
+            return cached;
+        }
+        const matcher = compile(pattern);
+        cache.set(pattern, matcher);
+        if (cache.size > PATTERN_CACHE_CAP) {
+            const oldest = cache.keys().next().value;
+            if (oldest !== undefined)
+                cache.delete(oldest);
+        }
+        return matcher;
+    };
+}
+/**
+ * Compile a SQL LIKE pattern into a matcher.
  * Supports SQL LIKE patterns:
  * - % matches any sequence of characters (including empty sequence)
  * - _ matches any single character
- *
- * @param pattern The LIKE pattern
- * @param text The text to match against
- * @returns true if the text matches the pattern, false otherwise
  */
-export function simpleLike(pattern, text) {
+function compileLike(pattern) {
     // Escape regex special characters except % and _
     const escapedPattern = pattern.replace(/[.*+^${}()|[\]\\]/g, '\\$&');
     // Convert SQL LIKE wildcards to regex equivalents
@@ -19,24 +59,20 @@ export function simpleLike(pattern, text) {
     try {
         // 'u' flag: match by Unicode code point so `_` matches one code point (incl. non-BMP)
         const regex = new RegExp(`^${regexPattern}$`, 'u');
-        return regex.test(text);
+        return (text) => regex.test(text);
     }
     catch (e) {
         errorLog('Invalid LIKE pattern converted to regex: ^%s$, %O', regexPattern, e);
-        return false;
+        return NEVER_MATCH;
     }
 }
 /**
- * Simple GLOB pattern matching implementation.
+ * Compile a SQL GLOB pattern into a matcher.
  * Supports SQL GLOB patterns:
  * - * matches any sequence of characters (including empty sequence)
  * - ? matches any single character
- *
- * @param pattern The GLOB pattern
- * @param text The text to match against
- * @returns true if the text matches the pattern, false otherwise
  */
-export function simpleGlob(pattern, text) {
+function compileGlob(pattern) {
     const chars = [...pattern]; // iterate by Unicode code point so non-BMP chars survive intact
     const regexMeta = '\\^$.|?*+()[]{}';
     let regex = '';
@@ -92,11 +128,46 @@ export function simpleGlob(pattern, text) {
     }
     try {
         // 'u' flag: code-point ranges like `[😀-😎]` and `?`/`.` matching by code point.
-        return new RegExp(`^${regex}$`, 'u').test(text);
+        const compiled = new RegExp(`^${regex}$`, 'u');
+        return (text) => compiled.test(text);
     }
     catch (e) {
         errorLog('Invalid GLOB pattern compiled to regex: ^%s$, %O', regex, e);
-        return false;
+        return NEVER_MATCH;
     }
 }
+/**
+ * Compile (memoized) a LIKE pattern into a reusable matcher. Prefer this over
+ * {@link simpleLike} when matching many texts against a pattern that is known
+ * once (e.g. a literal-constant pattern captured at emit time): compile once,
+ * call the returned matcher per row.
+ */
+export const compileLikeMatcher = memoizeCompile(compileLike);
+/**
+ * Compile (memoized) a GLOB pattern into a reusable matcher. See
+ * {@link compileLikeMatcher}.
+ */
+export const compileGlobMatcher = memoizeCompile(compileGlob);
+/**
+ * Simple LIKE pattern matching. Compilation is memoized, so repeated calls with
+ * the same pattern reuse a single compiled matcher.
+ *
+ * @param pattern The LIKE pattern
+ * @param text The text to match against
+ * @returns true if the text matches the pattern, false otherwise
+ */
+export function simpleLike(pattern, text) {
+    return compileLikeMatcher(pattern)(text);
+}
+/**
+ * Simple GLOB pattern matching. Compilation is memoized, so repeated calls with
+ * the same pattern reuse a single compiled matcher.
+ *
+ * @param pattern The GLOB pattern
+ * @param text The text to match against
+ * @returns true if the text matches the pattern, false otherwise
+ */
+export function simpleGlob(pattern, text) {
+    return compileGlobMatcher(pattern)(text);
+}
 //# sourceMappingURL=patterns.js.map

package/dist/src/util/patterns.js.map

@@ -1 +1 @@
-{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../../../src/util/patterns.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../../../src/util/patterns.ts"],"names":[],"mappings":"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"}

package/dist/src/util/qualified-name.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Recover the (schema, table) pair from a flat lowercased base key
+ * `` `${schema}.${table}` ``. Splits on the FIRST dot only, so a quoted
+ * table name that legally contains a dot (e.g. `"a.b"` → key `main.a.b`)
+ * survives intact. NOTE: a dotted *schema* name is still ambiguous; dotted
+ * schema names are effectively unreachable in practice and intentionally
+ * unsupported — see bug-core-fq-name-split-mis-routes-dotted-table-names.
+ */
+export declare function splitBaseKey(base: string): [schema: string, table: string];
+//# sourceMappingURL=qualified-name.d.ts.map

package/dist/src/util/qualified-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qualified-name.d.ts","sourceRoot":"","sources":["../../../src/util/qualified-name.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAI1E"}

package/dist/src/util/qualified-name.js

@@ -0,0 +1,15 @@
+/**
+ * Recover the (schema, table) pair from a flat lowercased base key
+ * `` `${schema}.${table}` ``. Splits on the FIRST dot only, so a quoted
+ * table name that legally contains a dot (e.g. `"a.b"` → key `main.a.b`)
+ * survives intact. NOTE: a dotted *schema* name is still ambiguous; dotted
+ * schema names are effectively unreachable in practice and intentionally
+ * unsupported — see bug-core-fq-name-split-mis-routes-dotted-table-names.
+ */
+export function splitBaseKey(base) {
+    const dot = base.indexOf('.');
+    if (dot < 0)
+        return ['', base]; // defensive: no schema segment
+    return [base.slice(0, dot), base.slice(dot + 1)];
+}
+//# sourceMappingURL=qualified-name.js.map

package/dist/src/util/qualified-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qualified-name.js","sourceRoot":"","sources":["../../../src/util/qualified-name.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACxC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,+BAA+B;IAC/D,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC"}