@minnowdb/core 0.2.1 → 0.4.0

package/dist/engine/sql-json.js

@@ -1,6 +1,11 @@
 import { stringArgument } from "./sql-semantics.js";
+import { externalSqlDomainValue } from "./sql-domains.js";
+import { MAX_CACHEABLE_TEXT_CHARACTERS, MAX_SQL_SCALAR_RESULT_CHARACTERS } from "./cache-limits.js";
 export function parseJsonPath(path, caller) {
     const text = stringArgument(caller, path).trim();
+    if (text.length > MAX_CACHEABLE_TEXT_CHARACTERS) {
+        throw new RangeError(`${caller} path exceeds ${String(MAX_CACHEABLE_TEXT_CHARACTERS)} characters`);
+    }
     if (!text.startsWith("$"))
         throw new TypeError(`${caller} paths start at $`);
     const steps = [];
@@ -41,8 +46,9 @@ export function parseJsonPath(path, caller) {
 export function jsonAtPath(document, path, caller) {
     const steps = parseJsonPath(path, caller);
     let current;
+    const source = boundedJsonDocument(document, caller);
     try {
-        current = JSON.parse(stringArgument(caller, document));
+        current = JSON.parse(source);
     }
     catch {
         // A document that is not JSON selects nothing rather than failing the whole statement,
@@ -71,8 +77,12 @@ export function jsonAtPath(document, path, caller) {
 }
 /** Whether a value is JSON text of the requested shape (T825). */
 export function jsonIsValid(document, kind) {
+    document = externalSqlDomainValue(document);
     if (typeof document !== "string")
         return false;
+    if (document.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+        throw new RangeError(`JSON document exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+    }
     let parsed;
     try {
         parsed = JSON.parse(document);
@@ -94,27 +104,77 @@ export function jsonIsValid(document, kind) {
 }
 /** A SQL value as its JSON counterpart: datetimes serialize as ISO text, like every cast. */
 export function jsonValueOf(value) {
-    return value instanceof Date ? value.toISOString() : value;
+    const external = externalSqlDomainValue(value);
+    return external instanceof Date ? dateIsoString(external) : external;
 }
 /**
- * JSON_ARRAY(v, ...) and JSON_OBJECT(k, v, ...) (T811/T812). Both skip NULL members, which is
- * the standard's default (ABSENT ON NULL for objects, NULL ON NULL for arrays is the other
- * spelling), and both return JSON text.
+ * JSON_ARRAY(v, ...) and JSON_OBJECT(k, v, ...) (T811/T812). The omitted null-handling clause is
+ * `NULL ON NULL`: SQL NULL becomes a JSON null. `ABSENT ON NULL` is a separate spelling rather
+ * than the default. Constructors return JSON text at the JavaScript boundary.
  */
 export function jsonConstructor(name, values) {
     if (name === "JSON_ARRAY") {
-        return JSON.stringify(values.filter((value) => value !== null && value !== undefined).map(jsonValueOf));
+        const members = values.map((value) => boundedJsonValue(value ?? null, "JSON_ARRAY value"));
+        return joinBoundedJson("[", members, "]", "JSON_ARRAY result");
     }
-    const entries = {};
+    const members = [];
     for (let index = 0; index + 1 < values.length; index += 2) {
-        const key = values[index];
-        if (typeof key !== "string")
-            throw new TypeError("JSON_OBJECT keys must be strings");
+        const rawKey = values[index];
+        if (rawKey === null || rawKey === undefined) {
+            throw new TypeError("JSON_OBJECT keys cannot be NULL");
+        }
+        let key;
+        if (rawKey instanceof Date)
+            key = dateIsoString(rawKey);
+        else if (typeof rawKey === "string")
+            key = rawKey;
+        else if (typeof rawKey === "number" || typeof rawKey === "boolean")
+            key = String(rawKey);
+        else
+            throw new TypeError("JSON_OBJECT keys must be scalar values");
         const member = values[index + 1];
-        if (member === null || member === undefined)
-            continue;
-        entries[key] = jsonValueOf(member);
+        // Build JSON text directly. WITHOUT UNIQUE KEYS is the default, so duplicate names must be
+        // preserved; assigning through a JavaScript object would collapse them and mishandle
+        // special names such as "__proto__".
+        const encodedKey = boundedJsonValue(key, "JSON_OBJECT key");
+        const encodedValue = boundedJsonValue(member ?? null, "JSON_OBJECT value");
+        members.push(`${encodedKey}:${encodedValue}`);
+    }
+    return joinBoundedJson("{", members, "}", "JSON_OBJECT result");
+}
+function boundedJsonDocument(value, caller) {
+    const document = stringArgument(caller, externalSqlDomainValue(value));
+    if (document.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+        throw new RangeError(`${caller} document exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+    }
+    return document;
+}
+function boundedJsonValue(value, label) {
+    const normalized = jsonValueOf(value);
+    if (typeof normalized === "string" && normalized.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+        throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+    }
+    const encoded = JSON.stringify(normalized);
+    if (typeof encoded !== "string")
+        throw new TypeError(`${label} is not JSON serializable`);
+    if (encoded.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+        throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+    }
+    return encoded;
+}
+function joinBoundedJson(prefix, members, suffix, label) {
+    let length = prefix.length + suffix.length;
+    for (const member of members) {
+        length += member.length;
+        if (!Number.isSafeInteger(length) || length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+            throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+        }
+    }
+    if (members.length > 1)
+        length += members.length - 1;
+    if (!Number.isSafeInteger(length) || length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+        throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
     }
-    return JSON.stringify(entries);
+    return `${prefix}${members.join(",")}${suffix}`;
 }
-//# sourceMappingURL=sql-json.js.map
+import { dateIsoString } from "../date-value.js";

package/dist/engine/sql-semantics.d.ts

@@ -18,8 +18,14 @@ export declare function encodeSqlEqualityValue(value: unknown): readonly unknown
  * integer and clamps to 0..30, with ties rounded away from zero.
  */
 export declare function roundSqlNumber(value: number, precision?: number): number;
-/** Compiles SQL LIKE (% = any run, _ = one codepoint) into a bounded cached RegExp. */
-export declare function compileLikePattern(pattern: string, caseInsensitive?: boolean, escape?: string): RegExp;
+/** A whole-string SQL pattern matcher. Unlike RegExp, test never coerces its input. */
+export interface SqlPatternMatcher {
+    test(value: string): boolean;
+}
+/** Compiles SQL LIKE without exposing input to the host regular-expression engine. */
+export declare function compileLikePattern(pattern: string, caseInsensitive?: boolean, escape?: string): SqlPatternMatcher;
+/** PostgreSQL SIMILAR TO compiled to a Thompson NFA with bounded deterministic work. */
+export declare function compileSimilarPattern(pattern: string, escape?: string): SqlPatternMatcher;
 /** Defines an own enumerable result-column property, including the special name `__proto__`. */
 export declare function defineSqlResultProperty(target: Record<string, unknown>, name: string, value: unknown): void;
 /**
@@ -28,4 +34,3 @@ export declare function defineSqlResultProperty(target: Record<string, unknown>,
  * a silent coercion here would make `LENGTH(42)` answer instead of failing.
  */
 export declare function stringArgument(name: string, value: unknown): string;
-//# sourceMappingURL=sql-semantics.d.ts.map

package/dist/engine/sql-semantics.js

@@ -1,3 +1,7 @@
+import { dateMilliseconds } from "../date-value.js";
+import { assertWellFormedString } from "../block-format/unicode.js";
+import { MAX_SQL_NESTING_DEPTH, MAX_SQL_PATTERN_CHARACTERS, MAX_SQL_PATTERN_MATCH_STEPS, } from "./cache-limits.js";
+import { collatedDomainCompare, enumDomainCompare, exactNumericCompare, externalSqlDomainValue, externalSqlTextValue, } from "./sql-domains.js";
 /**
  * SQL value semantics shared by the row and vector executors.
  *
@@ -9,8 +13,26 @@
  * and signed zero compares equal because SQL numeric equality does not distinguish it.
  */
 export function compareSqlValues(left, right) {
-    const a = left instanceof Date ? left.getTime() : left;
-    const b = right instanceof Date ? right.getTime() : right;
+    const plainLeft = externalSqlTextValue(left);
+    const plainRight = externalSqlTextValue(right);
+    if ((typeof left === "string" && plainLeft !== left) ||
+        (typeof right === "string" && plainRight !== right)) {
+        if (typeof plainLeft !== "string" || typeof plainRight !== "string") {
+            throw new TypeError("Values must have comparable SQL types");
+        }
+        return compareSqlStrings(plainLeft, plainRight);
+    }
+    const collated = collatedDomainCompare(left, right);
+    if (collated !== undefined)
+        return collated;
+    const enumOrder = enumDomainCompare(left, right);
+    if (enumOrder !== undefined)
+        return enumOrder;
+    const exact = exactNumericCompare(left, right);
+    if (exact !== undefined)
+        return exact;
+    const a = left instanceof Date ? dateMilliseconds(left) : left;
+    const b = right instanceof Date ? dateMilliseconds(right) : right;
     if (a === b)
         return 0;
     if (a === null || a === undefined)
@@ -45,9 +67,9 @@ export function encodeSqlEqualityValue(value) {
     if (typeof value === "number")
         return [2, String(value === 0 ? 0 : value)];
     if (typeof value === "string")
-        return [3, value];
+        return [3, externalSqlTextValue(value)];
     if (value instanceof Date)
-        return [4, value.getTime()];
+        return [4, dateMilliseconds(value)];
     throw new TypeError("Query produced an unsupported value");
 }
 /**
@@ -61,43 +83,449 @@ export function roundSqlNumber(value, precision = 0) {
     const rounded = Number(value.toFixed(digits));
     return rounded === 0 ? 0 : rounded;
 }
+const MAX_PATTERN_CACHE_ENTRIES = 128;
+const MAX_PATTERN_CACHE_RETAINED_SIZE = 64 * 1024;
 const likeCache = new Map();
-/** Compiles SQL LIKE (% = any run, _ = one codepoint) into a bounded cached RegExp. */
-export function compileLikePattern(pattern, caseInsensitive = false, escape) {
-    const key = JSON.stringify([caseInsensitive, escape ?? null, pattern]);
-    const cached = likeCache.get(key);
-    if (cached !== undefined)
-        return cached;
-    let source = "^";
+const similarCache = new Map();
+let likeCacheRetainedSize = 0;
+let similarCacheRetainedSize = 0;
+function cachedPattern(cache, key) {
+    const entry = cache.get(key);
+    if (entry === undefined)
+        return undefined;
+    cache.delete(key);
+    cache.set(key, entry);
+    return entry[0];
+}
+function retainPattern(cache, key, matcher, retainedSize, setRetainedSize) {
+    const entrySize = key.length + matcher.retainedSize;
+    if (entrySize > MAX_PATTERN_CACHE_RETAINED_SIZE)
+        return;
+    while (cache.size >= MAX_PATTERN_CACHE_ENTRIES ||
+        retainedSize + entrySize > MAX_PATTERN_CACHE_RETAINED_SIZE) {
+        const oldest = cache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        const removed = cache.get(oldest);
+        cache.delete(oldest);
+        retainedSize -= removed?.[1] ?? 0;
+    }
+    cache.set(key, [matcher, entrySize]);
+    setRetainedSize(retainedSize + entrySize);
+}
+function throwPatternWorkLimit() {
+    throw new RangeError(`SQL pattern match exceeds ${String(MAX_SQL_PATTERN_MATCH_STEPS)} deterministic steps`);
+}
+function exactSingleCharacter(value, label) {
+    assertBoundedPattern(value, label, 2);
+    const characters = value[Symbol.iterator]();
+    const first = characters.next();
+    if (first.done === true || characters.next().done !== true) {
+        throw new TypeError(`${label.replace(" escape", " ESCAPE")} takes one character`);
+    }
+    return first.value;
+}
+function tokenizeLike(pattern, escape) {
+    const tokens = [];
     let escaped = false;
     for (const character of pattern) {
         if (escaped) {
-            source += escapeRegExp(character);
+            tokens.push(character);
             escaped = false;
-            continue;
         }
-        if (escape !== undefined && character === escape) {
+        else if (escape !== undefined && character === escape) {
             escaped = true;
-            continue;
         }
-        if (character === "%")
-            source += "[\\s\\S]*";
+        else if (character === "%") {
+            if (tokens.at(-1) !== 0)
+                tokens.push(0);
+        }
         else if (character === "_")
-            source += "[\\s\\S]";
+            tokens.push(1);
         else
-            source += escapeRegExp(character);
+            tokens.push(character);
     }
     if (escaped)
         throw new TypeError("LIKE pattern ends with a dangling escape character");
-    source += "$";
-    const regExp = new RegExp(source, caseInsensitive ? "iu" : "u");
-    if (likeCache.size >= 128)
-        likeCache.clear();
-    likeCache.set(key, regExp);
-    return regExp;
+    return tokens;
+}
+/** Unicode simple-case approximation used consistently by row and vector LIKE execution. */
+function simpleCaseFold(character) {
+    const upper = character.toUpperCase();
+    const codePoints = upper[Symbol.iterator]();
+    return codePoints.next().done !== true && codePoints.next().done === true ? upper : character;
+}
+function likeCharactersEqual(left, right, caseInsensitive) {
+    return left === right || (caseInsensitive && simpleCaseFold(left) === simpleCaseFold(right));
+}
+function literalLikeMatcher(tokens, caseInsensitive) {
+    if (tokens.includes(1))
+        return undefined;
+    const leading = tokens[0] === 0;
+    const trailing = tokens.at(-1) === 0;
+    const begin = leading ? 1 : 0;
+    const end = trailing ? tokens.length - 1 : tokens.length;
+    if (tokens.slice(begin, end).some((token) => typeof token !== "string"))
+        return undefined;
+    const body = tokens
+        .slice(begin, end)
+        .map((token) => (typeof token === "string" ? token : ""))
+        .join("");
+    if (!caseInsensitive) {
+        const test = (value) => {
+            if (typeof value !== "string")
+                throw new TypeError("LIKE input must be a string");
+            if (leading && trailing)
+                return value.includes(body);
+            if (leading)
+                return value.endsWith(body);
+            if (trailing)
+                return value.startsWith(body);
+            return value === body;
+        };
+        return { test, retainedSize: tokens.length * 16 + body.length * 2 };
+    }
+    const needle = Array.from(body, simpleCaseFold);
+    const prefix = new Uint32Array(needle.length);
+    for (let index = 1, matched = 0; index < needle.length; index += 1) {
+        while (matched > 0 && needle[index] !== needle[matched])
+            matched = prefix[matched - 1] ?? 0;
+        if (needle[index] === needle[matched])
+            matched += 1;
+        prefix[index] = matched;
+    }
+    const test = (value) => {
+        if (typeof value !== "string")
+            throw new TypeError("LIKE input must be a string");
+        if (needle.length === 0)
+            return leading || trailing || value.length === 0;
+        let matched = 0;
+        let position = 0;
+        let matchedAtEnd = false;
+        for (const rawCharacter of value) {
+            matchedAtEnd = false;
+            const character = simpleCaseFold(rawCharacter);
+            while (matched > 0 && character !== needle[matched])
+                matched = prefix[matched - 1] ?? 0;
+            if (character === needle[matched])
+                matched += 1;
+            position += 1;
+            if (matched === needle.length) {
+                const startsAt = position - needle.length;
+                if (leading && trailing)
+                    return true;
+                if (!leading && startsAt === 0) {
+                    if (trailing)
+                        return true;
+                    matchedAtEnd = true;
+                }
+                else if (leading && !trailing)
+                    matchedAtEnd = true;
+                matched = prefix[matched - 1] ?? 0;
+            }
+        }
+        return matchedAtEnd;
+    };
+    return {
+        test,
+        retainedSize: tokens.length * 16 + body.length * 2 + prefix.byteLength,
+    };
+}
+function generalLikeMatcher(tokens, caseInsensitive) {
+    const test = (value) => {
+        if (typeof value !== "string")
+            throw new TypeError("LIKE input must be a string");
+        let remaining = MAX_SQL_PATTERN_MATCH_STEPS;
+        let tokenIndex = 0;
+        let valueIndex = 0;
+        let manyIndex = -1;
+        let retryValueIndex = 0;
+        while (valueIndex < value.length) {
+            if (--remaining < 0)
+                throwPatternWorkLimit();
+            const token = tokens[tokenIndex];
+            if (token === 0) {
+                manyIndex = tokenIndex;
+                tokenIndex += 1;
+                retryValueIndex = valueIndex;
+                continue;
+            }
+            const codePoint = value.codePointAt(valueIndex);
+            if (codePoint === undefined)
+                break;
+            const character = String.fromCodePoint(codePoint);
+            if (token === 1 ||
+                (typeof token === "string" && likeCharactersEqual(token, character, caseInsensitive))) {
+                tokenIndex += 1;
+                valueIndex += character.length;
+                continue;
+            }
+            if (manyIndex < 0)
+                return false;
+            const retryCodePoint = value.codePointAt(retryValueIndex);
+            if (retryCodePoint === undefined)
+                return false;
+            retryValueIndex += String.fromCodePoint(retryCodePoint).length;
+            valueIndex = retryValueIndex;
+            tokenIndex = manyIndex + 1;
+        }
+        while (tokens[tokenIndex] === 0) {
+            if (--remaining < 0)
+                throwPatternWorkLimit();
+            tokenIndex += 1;
+        }
+        return tokenIndex === tokens.length;
+    };
+    return { test, retainedSize: tokens.length * 16 };
+}
+/** Compiles SQL LIKE without exposing input to the host regular-expression engine. */
+export function compileLikePattern(pattern, caseInsensitive = false, escape) {
+    assertBoundedPattern(pattern, "LIKE pattern");
+    const exactEscape = escape === undefined ? undefined : exactSingleCharacter(escape, "LIKE escape");
+    const key = JSON.stringify([caseInsensitive, exactEscape ?? null, pattern]);
+    const cached = cachedPattern(likeCache, key);
+    if (cached !== undefined)
+        return cached;
+    const tokens = tokenizeLike(pattern, exactEscape);
+    const matcher = literalLikeMatcher(tokens, caseInsensitive) ?? generalLikeMatcher(tokens, caseInsensitive);
+    retainPattern(likeCache, key, matcher, likeCacheRetainedSize, (size) => {
+        likeCacheRetainedSize = size;
+    });
+    return matcher;
+}
+const ANY_CHARACTER = () => true;
+/** Parses SIMILAR TO directly into an NFA, avoiding an allocation-heavy intermediate AST. */
+class SimilarCompiler {
+    escape;
+    #characters;
+    states = [];
+    #index = 0;
+    constructor(pattern, escape) {
+        this.escape = escape;
+        this.#characters = Array.from(pattern);
+    }
+    compile() {
+        const fragment = this.#alternative(0);
+        if (this.#index !== this.#characters.length) {
+            throw new TypeError("SIMILAR TO pattern has an unmatched closing parenthesis");
+        }
+        return fragment;
+    }
+    #state() {
+        this.states.push([[]]);
+        return this.states.length - 1;
+    }
+    #empty() {
+        const start = this.#state();
+        const end = this.#state();
+        this.states[start]?.[0].push(end);
+        return [start, end];
+    }
+    #consume(matches) {
+        const start = this.#state();
+        const end = this.#state();
+        const state = this.states[start];
+        if (state !== undefined)
+            state[1] = [end, matches];
+        return [start, end];
+    }
+    #repeat(fragment, plus) {
+        const start = this.#state();
+        const end = this.#state();
+        this.states[start]?.[0].push(fragment[0]);
+        if (!plus)
+            this.states[start]?.[0].push(end);
+        this.states[fragment[1]]?.[0].push(fragment[0], end);
+        return [start, end];
+    }
+    #alternative(depth) {
+        const first = this.#sequence(depth);
+        if (this.#characters[this.#index] !== "|" || this.#characters[this.#index] === this.escape) {
+            return first;
+        }
+        const start = this.#state();
+        const end = this.#state();
+        this.states[start]?.[0].push(first[0]);
+        this.states[first[1]]?.[0].push(end);
+        while (this.#characters[this.#index] === "|" && this.#characters[this.#index] !== this.escape) {
+            this.#index += 1;
+            const next = this.#sequence(depth);
+            this.states[start]?.[0].push(next[0]);
+            this.states[next[1]]?.[0].push(end);
+        }
+        return [start, end];
+    }
+    #sequence(depth) {
+        let result;
+        for (;;) {
+            const character = this.#characters[this.#index];
+            if (character === undefined ||
+                ((character === "|" || character === ")") && character !== this.escape)) {
+                return result ?? this.#empty();
+            }
+            let fragment = this.#atom(depth);
+            const quantifier = this.#characters[this.#index];
+            if ((quantifier === "*" || quantifier === "+") && quantifier !== this.escape) {
+                this.#index += 1;
+                fragment = this.#repeat(fragment, quantifier === "+");
+                const repeated = this.#characters[this.#index];
+                if ((repeated === "*" || repeated === "+") && repeated !== this.escape) {
+                    throw new TypeError("SIMILAR TO pattern repeats a quantifier");
+                }
+            }
+            if (result === undefined)
+                result = fragment;
+            else {
+                this.states[result[1]]?.[0].push(fragment[0]);
+                result = [result[0], fragment[1]];
+            }
+        }
+    }
+    #atom(depth) {
+        const character = this.#characters[this.#index];
+        if (character === undefined)
+            return this.#empty();
+        this.#index += 1;
+        if (character === this.escape) {
+            const literal = this.#characters[this.#index];
+            if (literal === undefined) {
+                throw new TypeError("SIMILAR TO pattern ends with its escape character");
+            }
+            this.#index += 1;
+            return this.#consume((candidate) => candidate === literal);
+        }
+        if (character === "*" || character === "+") {
+            throw new TypeError("SIMILAR TO quantifier has no preceding expression");
+        }
+        if (character === "(") {
+            if (depth >= MAX_SQL_NESTING_DEPTH) {
+                throw new RangeError(`SIMILAR TO nesting exceeds ${String(MAX_SQL_NESTING_DEPTH)} levels`);
+            }
+            const child = this.#alternative(depth + 1);
+            if (this.#characters[this.#index] !== ")") {
+                throw new TypeError("SIMILAR TO pattern has an unmatched opening parenthesis");
+            }
+            this.#index += 1;
+            return child;
+        }
+        if (character === "[")
+            return this.#consume(this.#characterClass());
+        if (character === "%")
+            return this.#repeat(this.#consume(ANY_CHARACTER), false);
+        if (character === "_")
+            return this.#consume(ANY_CHARACTER);
+        return this.#consume((candidate) => candidate === character);
+    }
+    #characterClass() {
+        let source = "[";
+        let closed = false;
+        let hasMember = false;
+        while (this.#index < this.#characters.length) {
+            const character = this.#characters[this.#index] ?? "";
+            this.#index += 1;
+            if (character === this.escape) {
+                const literal = this.#characters[this.#index];
+                if (literal === undefined) {
+                    throw new TypeError("SIMILAR TO pattern ends with its escape character");
+                }
+                this.#index += 1;
+                source += ["\\", "]", "^", "-"].includes(literal) ? `\\${literal}` : literal;
+                hasMember = true;
+                continue;
+            }
+            if (character === "]") {
+                closed = true;
+                break;
+            }
+            source += character;
+            if (character !== "^" || source.length > 2)
+                hasMember = true;
+        }
+        if (!closed)
+            throw new TypeError("SIMILAR TO pattern has an unterminated character class");
+        if (!hasMember)
+            throw new TypeError("SIMILAR TO pattern has an empty character class");
+        source += "]";
+        let expression;
+        try {
+            // The host expression is deliberately limited to one character class and one codepoint.
+            // It cannot contain repetition, grouping, or alternation, so backtracking work is constant.
+            expression = new RegExp(`^(?:${source})$`, "u");
+        }
+        catch {
+            throw new TypeError("SIMILAR TO pattern has an invalid character class");
+        }
+        return (candidate) => expression.test(candidate);
+    }
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function nfaMatcher(pattern, escape) {
+    const compiler = new SimilarCompiler(pattern, escape);
+    const fragment = compiler.compile();
+    const { states } = compiler;
+    const test = (value) => {
+        if (typeof value !== "string")
+            throw new TypeError("SIMILAR TO input must be a string");
+        let remaining = MAX_SQL_PATTERN_MATCH_STEPS;
+        const marks = new Uint32Array(states.length);
+        const stack = [];
+        let active = [];
+        let next = [];
+        let generation = 1;
+        const addClosure = (seed, output) => {
+            stack.push(seed);
+            while (stack.length > 0) {
+                if (--remaining < 0)
+                    throwPatternWorkLimit();
+                const stateIndex = stack.pop();
+                if (stateIndex === undefined || marks[stateIndex] === generation)
+                    continue;
+                marks[stateIndex] = generation;
+                output.push(stateIndex);
+                for (const target of states[stateIndex]?.[0] ?? [])
+                    stack.push(target);
+            }
+        };
+        addClosure(fragment[0], active);
+        for (const character of value) {
+            generation += 1;
+            next.length = 0;
+            for (const stateIndex of active) {
+                if (--remaining < 0)
+                    throwPatternWorkLimit();
+                const transition = states[stateIndex]?.[1];
+                if (transition?.[1](character) === true)
+                    addClosure(transition[0], next);
+            }
+            if (next.length === 0)
+                return false;
+            [active, next] = [next, active];
+        }
+        return active.includes(fragment[1]);
+    };
+    // State objects, epsilon arrays, transition objects, and matcher closures all cost materially
+    // more than their integer payload. A conservative model keeps large compiled patterns out of
+    // the cache instead of pretending their Uint32-sized indexes are the whole retained graph.
+    return { test, retainedSize: states.length * 32 };
+}
+/** PostgreSQL SIMILAR TO compiled to a Thompson NFA with bounded deterministic work. */
+export function compileSimilarPattern(pattern, escape = "\\") {
+    assertBoundedPattern(pattern, "SIMILAR TO pattern");
+    const exactEscape = exactSingleCharacter(escape, "SIMILAR TO escape");
+    const key = JSON.stringify([exactEscape, pattern]);
+    const cached = cachedPattern(similarCache, key);
+    if (cached !== undefined)
+        return cached;
+    const matcher = nfaMatcher(pattern, exactEscape);
+    retainPattern(similarCache, key, matcher, similarCacheRetainedSize, (size) => {
+        similarCacheRetainedSize = size;
+    });
+    return matcher;
+}
+function assertBoundedPattern(value, label, limit = MAX_SQL_PATTERN_CHARACTERS) {
+    if (value.length > limit) {
+        throw new RangeError(`${label} exceeds ${String(limit)} characters`);
+    }
+    assertWellFormedString(value, label);
 }
 /** Defines an own enumerable result-column property, including the special name `__proto__`. */
 export function defineSqlResultProperty(target, name, value) {
@@ -114,8 +542,8 @@ export function defineSqlResultProperty(target, name, value) {
  * a silent coercion here would make `LENGTH(42)` answer instead of failing.
  */
 export function stringArgument(name, value) {
-    if (typeof value !== "string")
+    const external = externalSqlDomainValue(value);
+    if (typeof external !== "string")
         throw new TypeError(`${name} requires a string argument`);
-    return value;
+    return external;
 }
-//# sourceMappingURL=sql-semantics.js.map