@lovrozagar/oat 0.10.0 → 0.11.0

package/dist/reference/query.js

@@ -1,39 +1,31 @@
 /**
- * PostgREST-shaped query engine for the reference backend.
+ * The reference backend's query language, parsed once.
  *
- * Deliberately simple and readable — its job is to be *obviously* correct so that any finding
- * oat reports against the clean baseline is oat's fault, not the reference's. Defects are
- * applied as explicit, local deviations rather than woven into the logic.
+ * Filter, sort, select and search arrive as text in the canonical grammar (`field.op.value`,
+ * `and(...)`, `field.desc`). They are parsed here into an AST that every store consumes: the
+ * in-memory store evaluates it, the SQL stores compile it. Defects that change what a predicate
+ * *means* are applied here as rewrites of the tree, so a defect is defined exactly once and every
+ * engine exhibits the same bug.
+ *
+ * Values are coerced by the field's declared type, never by what the text looks like. A string
+ * field filtered on `123` compares against the string "123"; a numeric field filtered on `abc`
+ * matches nothing (or is rejected with a 400 when the backend is strictly typed).
+ *
+ * Null semantics, decided once and held by every store:
+ *   - `eq`, `gt`, `gte`, `lt`, `lte`, `in`, `like`, `ilike` never match a null value.
+ *   - `neq` and `nin` do match a null value: null is not equal to, and not a member of, anything.
+ *   - `is.null` / `is.notnull` test for null explicitly. `eq.null` is not a null test: on a
+ *     text field it compares against the text "null", as PostgREST does.
  */
+import { DefectSet } from "./defects.js";
+import { OVERCLAIMED_FIELD, fieldsWhere } from "./model.js";
 import { SqlError } from "./store-api.js";
-/* One error type across every store, so the HTTP layer has a single thing to catch. Two
- * separate classes meant a rejected filter surfaced as 400 on the SQL stores and 500 here — the
- * conformance suite reported it as a defect, correctly. */
-export { SqlError as QueryError } from "./store-api.js";
-const COMPARATORS = new Set([
-    "eq",
-    "ne",
-    "neq",
-    "gt",
-    "gte",
-    "lt",
-    "lte",
-    "in",
-    "nin",
-    "like",
-    "ilike",
-    "is",
-    "contains",
-]);
-function countFilterTerms(expression) {
-    const group = /^(and|or)\((.*)\)$/s.exec(expression.trim());
-    if (group?.[2] !== undefined) {
-        return splitTopLevel(group[2]).reduce((sum, part) => sum + countFilterTerms(part), 0);
-    }
-    return 1;
-}
-/** Splits on commas that sit at paren depth zero. */
-function splitTopLevel(input) {
+export const SEARCH_MODES = ["contains", "prefix"];
+export const DEFAULT_CONVENTIONS = { collation: "binary", nulls: "first", strictTypes: false };
+/* ------------------------------------------------------------------ parsing */
+const OPERATORS = new Set(["eq", "ne", "neq", "gt", "gte", "lt", "lte", "in", "nin", "like", "ilike", "is", "contains"]);
+/** Splits on commas at paren depth zero — shared by the filter and order grammars. */
+export function splitTopLevel(input) {
     const parts = [];
     let depth = 0;
     let start = 0;
@@ -51,353 +43,443 @@ function splitTopLevel(input) {
     parts.push(input.slice(start));
     return parts.map((p) => p.trim()).filter((p) => p.length > 0);
 }
-function parseFilter(expression, options, defects) {
-    if (options.maxFilterConditions !== undefined && countFilterTerms(expression) > options.maxFilterConditions) {
-        throw new SqlError("invalid_filter", `more than ${options.maxFilterConditions} filter conditions`);
+function stripParens(value) {
+    return value.startsWith("(") && value.endsWith(")") ? value.slice(1, -1) : value;
+}
+function countTerms(expression) {
+    const group = /^(and|or)\((.*)\)$/s.exec(expression.trim());
+    if (group?.[2] !== undefined)
+        return splitTopLevel(group[2]).reduce((sum, part) => sum + countTerms(part), 0);
+    return 1;
+}
+function fieldOf(entity, name) {
+    return entity.fields.find((field) => field.name === name);
+}
+function filterableFields(entity, defects) {
+    const declared = fieldsWhere(entity, "filterable");
+    /* Under the overclaim the backend refuses a field the document still declares filterable. The
+     * backend is not wrong to refuse — the document is wrong to promise. */
+    return defects.has("SPEC_OVERCLAIMS_FILTERABLE") ? declared.filter((f) => f !== OVERCLAIMED_FIELD) : declared;
+}
+function sortableFields(entity, defects) {
+    const declared = fieldsWhere(entity, "sortable");
+    return defects.has("SPEC_OVERCLAIMS_SORTABLE") ? declared.filter((f) => f !== OVERCLAIMED_FIELD) : declared;
+}
+function isNumeric(field) {
+    return field?.type === "integer" || field?.type === "number";
+}
+/**
+ * The value a filter term compares against, read as the field's declared type.
+ *
+ * `undefined` means the text does not denote a value of that type at all. A lenient backend turns
+ * that into a predicate matching nothing; a strict one rejects the request.
+ */
+function coerce(raw, field) {
+    if (field.type === "integer" || field.type === "number") {
+        if (raw.trim() === "")
+            return undefined;
+        const n = Number(raw);
+        if (!Number.isFinite(n))
+            return undefined;
+        if (field.type === "integer" && !Number.isInteger(n))
+            return undefined;
+        return n;
+    }
+    if (field.type === "boolean") {
+        if (raw === "true")
+            return true;
+        if (raw === "false")
+            return false;
+        return undefined;
     }
-    return parseFilterInner(expression, options, defects);
+    return raw;
 }
-function parseFilterInner(expression, options, defects) {
+function likePattern(raw, unescaped) {
+    const segments = [];
+    let text = "";
+    const flush = () => {
+        if (text !== "")
+            segments.push({ kind: "text", text });
+        text = "";
+    };
+    for (const ch of raw) {
+        /* `*` is the grammar's wildcard. `%` and `_` are literals — unless the backend interpolates
+         * the value into a LIKE pattern without escaping it, which is the LIKE_UNESCAPED defect. */
+        if (ch === "*" || (unescaped && ch === "%")) {
+            flush();
+            segments.push({ kind: "any" });
+        }
+        else if (unescaped && ch === "_") {
+            flush();
+            segments.push({ kind: "one" });
+        }
+        else {
+            text += ch;
+        }
+    }
+    flush();
+    return segments;
+}
+/** Parses a canonical filter expression. Throws `SqlError` for anything a correct backend rejects. */
+export function parseFilter(expression, ctx) {
+    const catalog = ctx.entity.filterCatalog;
+    if (catalog?.maxFilterConditions !== undefined &&
+        countTerms(expression) > catalog.maxFilterConditions &&
+        !ctx.defects.has("FILTER_CONDITION_CAP_IGNORED")) {
+        throw new SqlError("invalid_filter", `more than ${catalog.maxFilterConditions} filter conditions`);
+    }
+    return parseNode(expression, ctx);
+}
+function parseNode(expression, ctx) {
+    const { defects, entity } = ctx;
     const trimmed = expression.trim();
     const group = /^(and|or)\((.*)\)$/s.exec(trimmed);
-    if (group?.[1] && group[2] !== undefined) {
-        const combinator = group[1];
-        const children = splitTopLevel(group[2]).map((part) => parseFilterInner(part, options, defects));
-        if (children.length === 0) {
-            throw new SqlError("invalid_filter", `empty ${combinator}() group`);
+    if (group?.[1] !== undefined && group[2] !== undefined) {
+        const children = splitTopLevel(group[2]).map((part) => parseNode(part, ctx));
+        if (children.length === 0)
+            throw new SqlError("invalid_filter", `empty ${group[1]}() group`);
+        /* The joiner is swapped, not the parse: the expression is read correctly and evaluated with
+         * the other combinator's semantics. */
+        const named = group[1];
+        let kind = defects.has("FILTER_GROUP_COMBINATOR_SWAPPED") ? (named === "and" ? "or" : "and") : named;
+        /* One shared "current joiner": the last nested group to set it decides how this group joins. */
+        if (defects.has("FILTER_NESTED_COMBINATOR_LEAKS")) {
+            const nested = children.filter((child) => child.kind === "and" || child.kind === "or").at(-1);
+            if (nested !== undefined && (nested.kind === "and" || nested.kind === "or"))
+                kind = nested.kind;
         }
-        /* The joiner is swapped, not the parse: the expression is still read correctly, it is just
-         * evaluated with the other combinator's semantics. */
-        const effective = defects.has("FILTER_GROUP_COMBINATOR_SWAPPED")
-            ? combinator === "and"
-                ? "or"
-                : "and"
-            : combinator;
-        return effective === "and"
-            ? (row) => children.every((child) => child(row))
-            : (row) => children.some((child) => child(row));
+        return { children, kind };
     }
     const segments = trimmed.split(".");
-    if (segments.length < 3) {
+    if (segments.length < 3)
         throw new SqlError("invalid_filter", `malformed filter term "${trimmed}"`);
+    const [name, rawOp] = segments;
+    const raw = segments.slice(2).join(".");
+    if (!OPERATORS.has(rawOp)) {
+        if (defects.has("FILTER_ILLEGAL_OP_IGNORED"))
+            return { kind: "const", value: true };
+        throw new SqlError("invalid_filter", `unknown operator "${rawOp}"`);
     }
-    const [field, op] = segments;
-    const rawValue = segments.slice(2).join(".");
-    const canonical = op === "ne" ? "neq" : op;
-    const allowed = options.allowedOpsByField?.[field];
-    if (!COMPARATORS.has(op) || (allowed !== undefined && !allowed.includes(op) && !allowed.includes(canonical))) {
+    const aliases = entity.filterCatalog?.aliases;
+    const alias = aliases !== undefined && Object.hasOwn(aliases, rawOp) ? aliases[rawOp] : undefined;
+    /* The alias table maps `ne` to the wrong operator. */
+    const mapped = alias !== undefined && defects.has("FILTER_ALIAS_MISMAPPED") ? "eq" : alias;
+    const op = mapped ?? (rawOp === "ne" ? "neq" : rawOp);
+    const opsByField = entity.filterCatalog?.opsByField;
+    const allowed = opsByField !== undefined && Object.hasOwn(opsByField, name) ? opsByField[name] : undefined;
+    if (allowed !== undefined && !allowed.includes(rawOp) && !allowed.includes(op)) {
         if (defects.has("FILTER_ILLEGAL_OP_IGNORED"))
-            return () => true;
-        throw new SqlError("invalid_filter", `unknown operator "${op}"`);
+            return { kind: "const", value: true };
+        throw new SqlError("invalid_filter", `operator "${rawOp}" is not allowed on "${name}"`);
     }
-    if (!options.filterable.includes(field)) {
+    /* The document lists `like` on `slug`; under the overclaim the backend no longer supports it. */
+    if (defects.has("SPEC_OVERCLAIMS_FILTER_OP") && name === "slug" && op === "like") {
+        throw new SqlError("invalid_filter", `operator "like" is not supported on "slug"`);
+    }
+    if (!filterableFields(entity, defects).includes(name)) {
         /* Correct behaviour is to reject. The defect drops the term instead — the single most
          * common real-world filter bug, and invisible to schema validation. */
         if (defects.has("FILTER_IGNORED"))
-            return () => true;
-        throw new SqlError("invalid_filter", `field "${field}" is not filterable`);
+            return { kind: "const", value: true };
+        throw new SqlError("invalid_filter", `field "${name}" is not filterable`);
     }
-    return buildComparator(field, canonical, rawValue, defects, options);
+    const field = fieldOf(entity, name);
+    return buildTerm(field, op, raw, ctx);
 }
-function buildComparator(field, op, rawValue, defects, options) {
-    const value = coerce(rawValue);
+function buildTerm(field, op, raw, ctx) {
+    const { defects, conventions } = ctx;
+    const asText = isNumeric(field) && defects.has("NUMERIC_COMPARED_AS_TEXT");
+    /* A value that is not of the field's type: lenient backends match nothing, strict ones say so. */
+    const typed = (text) => {
+        const value = coerce(text, field);
+        if (value === undefined && conventions.strictTypes) {
+            throw new SqlError("invalid_filter", `"${text}" is not a valid ${field.type} for "${field.name}"`);
+        }
+        return value;
+    };
+    const never = { kind: "const", value: false };
+    /* An array is filtered by membership and by nothing else. */
+    if (field.type === "array" || op === "contains") {
+        if (field.type !== "array" || op !== "contains") {
+            throw new SqlError("invalid_filter", `operator "${op}" is not supported on "${field.name}"`);
+        }
+        return { field: field.name, kind: "contains", substring: defects.has("CONTAINS_MATCHES_SUBSTRING"), value: raw };
+    }
     switch (op) {
-        case "eq":
+        case "eq": {
             if (defects.has("FILTER_EQ_NOT_APPLIED"))
-                return () => true;
-            return (row) => looseEqual(row[field], value);
-        case "ne":
-        case "neq":
-            /* Three-valued logic leaking through: in SQL, `col <> x` is NULL — not true — when col
-             * is NULL, so those rows silently vanish unless the query says `OR col IS NULL`. */
-            if (defects.has("NEQ_DROPS_NULLS")) {
-                return (row) => row[field] !== null && row[field] !== undefined && !looseEqual(row[field], value);
+                return { kind: "const", value: true };
+            const value = typed(raw);
+            return value === undefined ? never : { asText, field: field.name, kind: "cmp", nullsMatch: false, op, value };
+        }
+        case "neq": {
+            const value = typed(raw);
+            /* Three-valued logic leaking through: in SQL `col <> x` is NULL — not true — when col is
+             * NULL, so null rows silently vanish unless the query also tests `col IS NULL`. */
+            const nullsMatch = !defects.has("NEQ_DROPS_NULLS");
+            if (value === undefined) {
+                /* Nothing equals a value of the wrong type, so everything — nulls included — differs. */
+                return nullsMatch ? { kind: "const", value: true } : { field: field.name, kind: "isnull", negate: true };
             }
-            return (row) => !looseEqual(row[field], value);
+            return { asText, field: field.name, kind: "cmp", nullsMatch, op, value };
+        }
         case "gt":
-            return (row) => compare(row[field], value) > 0;
         case "gte":
-            if (defects.has("FILTER_GTE_IS_GT"))
-                return (row) => compare(row[field], value) > 0;
-            return (row) => compare(row[field], value) >= 0;
         case "lt":
-            return (row) => compare(row[field], value) < 0;
-        case "lte":
-            return (row) => compare(row[field], value) <= 0;
+        case "lte": {
+            const value = typed(raw);
+            if (value === undefined)
+                return never;
+            const effective = op === "gte" && defects.has("FILTER_GTE_IS_GT")
+                ? "gt"
+                : op === "lte" && defects.has("FILTER_LTE_IS_LT")
+                    ? "lt"
+                    : op === "lt" && defects.has("FILTER_LT_IS_LTE")
+                        ? "lte"
+                        : op;
+            return { asText, field: field.name, kind: "cmp", nullsMatch: false, op: effective, value };
+        }
         case "in":
         case "nin": {
-            const members = stripParens(rawValue)
+            const members = stripParens(raw)
                 .split(",")
                 .map((s) => s.trim())
-                .filter((s) => s.length > 0)
-                .map((s) => coerce(s));
+                .filter((s) => s.length > 0);
             if (members.length === 0) {
-                if (options.emptyIn === "reject")
-                    throw new SqlError("invalid_filter", "empty in() is not allowed");
-                return op === "in" ? () => false : () => true;
+                if (ctx.entity.filterCatalog?.emptyIn === "reject")
+                    throw new SqlError("invalid_filter", "empty in()");
+                return { kind: "const", value: op === "nin" };
             }
-            if (options.maxInValues !== undefined && members.length > options.maxInValues) {
-                throw new SqlError("invalid_filter", `in() exceeds maxInValues=${options.maxInValues}`);
+            const max = ctx.entity.filterCatalog?.maxInValues;
+            if (max !== undefined && members.length > max && !defects.has("FILTER_IN_CAP_IGNORED")) {
+                throw new SqlError("invalid_filter", `in() exceeds maxInValues=${max}`);
             }
-            const effective = defects.has("FILTER_IN_FIRST_ONLY") && op === "in" && members[0] !== undefined ? [members[0]] : members;
-            return (row) => {
-                const hit = effective.some((member) => looseEqual(row[field], member));
-                return op === "in" ? hit : !hit;
-            };
+            const values = members.map(typed).filter((value) => value !== undefined);
+            const firstOnly = (defects.has("FILTER_IN_FIRST_ONLY") && op === "in") || (defects.has("FILTER_NIN_FIRST_ONLY") && op === "nin");
+            const effective = firstOnly ? values.slice(0, 1) : values;
+            return { asText, field: field.name, kind: "in", negate: op === "nin", values: effective };
         }
         case "is": {
-            if (rawValue === "null") {
+            if (raw === "null") {
                 if (defects.has("FILTER_IS_NULL_MATCHES_ALL"))
-                    return () => true;
-                return (row) => row[field] === null || row[field] === undefined;
+                    return { kind: "const", value: true };
+                return { field: field.name, kind: "isnull", negate: false };
             }
-            if (rawValue === "notnull" || rawValue === "not.null") {
-                return (row) => row[field] !== null && row[field] !== undefined;
+            if (raw === "notnull" || raw === "not.null")
+                return { field: field.name, kind: "isnull", negate: true };
+            if ((raw === "true" || raw === "false") && field.type === "boolean") {
+                return { asText: false, field: field.name, kind: "cmp", nullsMatch: false, op: "eq", value: raw === "true" };
             }
-            if (rawValue === "true")
-                return (row) => row[field] === true;
-            if (rawValue === "false")
-                return (row) => row[field] === false;
-            throw new SqlError("invalid_filter", `is.${rawValue} is not a recognised predicate`);
+            throw new SqlError("invalid_filter", `is.${raw} is not a recognised predicate`);
         }
-        case "contains":
-            return (row) => Array.isArray(row[field]) && row[field].some((v) => looseEqual(v, value));
         case "like":
         case "ilike": {
-            const insensitive = op === "ilike" && !defects.has("FILTER_ILIKE_IS_LIKE");
-            const pattern = likeToRegExp(rawValue, insensitive, defects);
-            return (row) => typeof row[field] === "string" && pattern.test(row[field]);
+            if (field.type !== "string")
+                throw new SqlError("invalid_filter", `${op} needs a text field`);
+            return {
+                field: field.name,
+                insensitive: op === "ilike" && !defects.has("FILTER_ILIKE_IS_LIKE"),
+                kind: "like",
+                pattern: likePattern(raw, defects.has("LIKE_UNESCAPED")),
+            };
         }
         default:
             throw new SqlError("invalid_filter", `unhandled operator "${op}"`);
     }
 }
 /**
- * `*` is the wildcard. Everything else — notably `%` and `_`, which users type constantly —
- * must be escaped so it matches literally. Forgetting to is a real bug class: a value
- * containing `%` then matches every row.
+ * Parses a canonical order expression (`field.desc.nullslast,other`).
+ *
+ * `trusted` is for the server's own default order: it is not a request, so the request's
+ * validation — and the defects that corrupt it — do not apply to it.
  */
-function likeToRegExp(pattern, insensitive, defects) {
-    const escaped = defects.has("LIKE_UNESCAPED")
-        ? pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/[%_]/g, ".*")
-        : pattern.replace(/[.+^${}()|[\]\\%_]/g, "\\$&");
-    return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`, insensitive ? "i" : "");
-}
-function stripParens(value) {
-    return value.startsWith("(") && value.endsWith(")") ? value.slice(1, -1) : value;
+export function parseOrder(expression, ctx, trusted = false) {
+    const { entity, conventions } = ctx;
+    const defects = trusted ? new DefectSet() : ctx.defects;
+    const sortable = trusted ? fieldsWhere(entity, "sortable") : sortableFields(entity, defects);
+    const terms = splitTopLevel(expression).flatMap((term) => {
+        const [name, ...parsed] = term.split(".");
+        if (name === undefined || !sortable.includes(name)) {
+            /* Correct is to reject; the defect drops a term naming a field that does not exist. */
+            const exists = entity.fields.some((field) => field.name === name);
+            if (defects.has("SORT_UNKNOWN_FIELD_IGNORED") && !exists)
+                return [];
+            throw new SqlError("invalid_order", `field "${name ?? ""}" is not sortable`);
+        }
+        const modifiers = defects.has("SORT_NULLS_MODIFIER_IGNORED")
+            ? parsed.filter((modifier) => modifier !== "nullsfirst" && modifier !== "nullslast")
+            : parsed;
+        for (const modifier of modifiers) {
+            if (!["asc", "desc", "nullsfirst", "nullslast"].includes(modifier)) {
+                throw new SqlError("invalid_order", `unknown sort modifier "${modifier}"`);
+            }
+        }
+        const descending = modifiers.includes("desc");
+        /* The default placement is stated for ascending order; descending reverses it, so a
+         * descending sort is exactly the ascending one read backwards. */
+        const defaultFirst = conventions.nulls === "first" ? !descending : descending;
+        const numeric = isNumeric(fieldOf(entity, name));
+        return [
+            {
+                asText: numeric && (defects.has("SORT_NUMERIC_AS_TEXT") || defects.has("NUMERIC_COMPARED_AS_TEXT")),
+                descending,
+                field: name,
+                nullsFirst: modifiers.includes("nullsfirst") ? true : modifiers.includes("nullslast") ? false : defaultFirst,
+            },
+        ];
+    });
+    return defects.has("SORT_MULTI_KEY_IGNORED") ? terms.slice(0, 1) : terms;
 }
-function coerce(raw) {
-    if (raw === "null")
+/**
+ * Search tokens: every token must occur, case-insensitively, in some searchable field — as a
+ * substring under `contains`, at the start of the value under `prefix`. A blank query matches
+ * everything.
+ */
+export function parseSearch(q, entity, defects, mode) {
+    const split = q
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0);
+    const fields = fieldsWhere(entity, "searchable");
+    if (split.length === 0)
+        return defects.has("SEARCH_EMPTY_MATCHES_NONE") ? { kind: "const", value: false } : null;
+    if (fields.length === 0)
         return null;
-    if (raw === "true")
-        return true;
-    if (raw === "false")
-        return false;
-    if (raw !== "" && !Number.isNaN(Number(raw)))
-        return Number(raw);
-    return raw;
+    const tokens = defects.has("SEARCH_ONLY_FIRST_TOKEN") ? split.slice(0, 1) : split;
+    const caseSensitive = defects.has("SEARCH_CASE_SENSITIVE");
+    return {
+        children: tokens.map((token) => ({ caseSensitive, fields, kind: "search", mode, token })),
+        kind: "and",
+    };
+}
+export function and(...nodes) {
+    const children = nodes.filter((node) => node !== null);
+    if (children.length === 0)
+        return { kind: "const", value: true };
+    if (children.length === 1)
+        return children[0];
+    return { children, kind: "and" };
+}
+/** Fields a filter expression names, for the tombstone rule (an explicit mention lifts it). */
+export function fieldsIn(node) {
+    switch (node.kind) {
+        case "and":
+        case "or":
+            return node.children.flatMap(fieldsIn);
+        case "const":
+            return [];
+        case "search":
+            return node.fields;
+        default:
+            return [node.field];
+    }
 }
-function looseEqual(a, b) {
-    if (a === b)
-        return true;
-    if (a === null || a === undefined || b === null || b === undefined)
-        return false;
-    return String(a) === String(b);
+function isNull(value) {
+    return value === null || value === undefined;
 }
-function compare(a, b, asText = false) {
-    if (a === null || a === undefined)
-        return -1;
-    if (b === null || b === undefined)
-        return 1;
+function compareScalar(a, b, asText) {
     if (!asText && typeof a === "number" && typeof b === "number")
         return a - b;
+    if (!asText && typeof a === "boolean" && typeof b === "boolean")
+        return Number(a) - Number(b);
     const as = String(a);
     const bs = String(b);
     return as < bs ? -1 : as > bs ? 1 : 0;
 }
-function parseOrder(expression, options, defects) {
-    const terms = splitTopLevel(expression).map((term) => {
-        const [field, ...modifiers] = term.split(".");
-        if (field === undefined || !options.sortable.includes(field)) {
-            throw new SqlError("invalid_order", `field "${field ?? ""}" is not sortable`);
-        }
-        const descending = modifiers.includes("desc");
-        return {
-            descending,
-            field,
-            /* Postgres default: NULLs sort last ascending, first descending. */
-            nullsFirst: modifiers.includes("nullsfirst") ? true : modifiers.includes("nullslast") ? false : descending,
-        };
-    });
-    return defects.has("SORT_MULTI_KEY_IGNORED") ? terms.slice(0, 1) : terms;
+function equal(a, b, asText) {
+    if (asText)
+        return String(a) === String(b);
+    return a === b;
+}
+export function likeToRegExp(pattern, insensitive) {
+    const source = pattern
+        .map((segment) => segment.kind === "any"
+        ? "[\\s\\S]*"
+        : segment.kind === "one"
+            ? "[\\s\\S]"
+            : segment.text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join("");
+    return new RegExp(`^${source}$`, insensitive ? "iu" : "u");
 }
-/** Advances per query so tied rows land differently each time — see UNSTABLE_SORT below. */
-let unstableRotation = 0;
-function applyOrder(rows, terms, options, defects) {
-    /* A sort without a total order is not a sort — equal keys may come back in any order, and
-     * keyset pagination built on it silently loses rows. The tiebreak is what makes paging sound.
-     *
-     * Array.prototype.sort is stable, so simply dropping the tiebreak would still yield a
-     * deterministic order and the defect would be unobservable. A real database without a
-     * tiebreak returns tied rows in whatever order the plan produced, varying between queries —
-     * so the defect rotates the input to reproduce that. */
-    const effective = defects.has("UNSTABLE_SORT")
-        ? terms
-        : [...terms, { descending: false, field: options.identity, nullsFirst: false }];
-    let input = [...rows];
-    if (defects.has("UNSTABLE_SORT") && input.length > 1) {
-        unstableRotation = (unstableRotation + 1) % input.length;
-        input = [...input.slice(unstableRotation), ...input.slice(0, unstableRotation)];
+/** The in-memory evaluation of a filter — the reference semantics the SQL compilers match. */
+export function evaluate(node, row) {
+    switch (node.kind) {
+        case "const":
+            return node.value;
+        case "and":
+            return node.children.every((child) => evaluate(child, row));
+        case "or":
+            return node.children.some((child) => evaluate(child, row));
+        case "isnull":
+            return isNull(row[node.field]) !== node.negate;
+        case "cmp": {
+            const value = row[node.field];
+            if (isNull(value))
+                return node.nullsMatch;
+            if (node.op === "eq")
+                return equal(value, node.value, node.asText);
+            if (node.op === "neq")
+                return !equal(value, node.value, node.asText);
+            const delta = compareScalar(value, node.value, node.asText);
+            if (node.op === "gt")
+                return delta > 0;
+            if (node.op === "gte")
+                return delta >= 0;
+            if (node.op === "lt")
+                return delta < 0;
+            return delta <= 0;
+        }
+        case "in": {
+            const value = row[node.field];
+            if (isNull(value))
+                return node.negate;
+            const hit = node.values.some((member) => equal(value, member, node.asText));
+            return hit !== node.negate;
+        }
+        case "like": {
+            const value = row[node.field];
+            return typeof value === "string" && likeToRegExp(node.pattern, node.insensitive).test(value);
+        }
+        case "contains": {
+            const value = row[node.field];
+            if (!Array.isArray(value))
+                return false;
+            return node.substring
+                ? value.some((element) => String(element).includes(node.value))
+                : value.some((element) => String(element) === node.value);
+        }
+        case "search": {
+            const fold = (text) => (node.caseSensitive ? text : text.toLowerCase());
+            const needle = fold(node.token);
+            return node.fields.some((field) => {
+                const value = row[field];
+                if (isNull(value))
+                    return false;
+                const text = fold(String(value));
+                return node.mode === "prefix" ? text.startsWith(needle) : text.includes(needle);
+            });
+        }
     }
-    return input.sort((left, right) => {
-        for (const term of effective) {
+}
+/** Orders rows under the plan. Ties the plan leaves open keep their input order. */
+export function compareRows(order, collation) {
+    return (left, right) => {
+        for (const term of order) {
             const a = left[term.field];
             const b = right[term.field];
-            const aNull = a === null || a === undefined;
-            const bNull = b === null || b === undefined;
+            const aNull = isNull(a);
+            const bNull = isNull(b);
             if (aNull && bNull)
                 continue;
-            if (aNull || bNull) {
-                const nullRank = aNull ? -1 : 1;
-                return term.nullsFirst ? nullRank : -nullRank;
-            }
-            const delta = compare(a, b, defects.has("SORT_NUMERIC_AS_TEXT"));
+            if (aNull || bNull)
+                return aNull === term.nullsFirst ? -1 : 1;
+            const delta = collation === "insensitive" && typeof a === "string" && typeof b === "string"
+                ? compareScalar(a.toLowerCase(), b.toLowerCase(), true)
+                : compareScalar(a, b, term.asText);
             if (delta !== 0)
                 return term.descending ? -delta : delta;
         }
         return 0;
-    });
-}
-/* ------------------------------------------------------------------ execution */
-export function runQuery(source, params, options, defects, 
-/** Applied before the sparse fieldset, so a derived value cannot reintroduce a deselected
- * column. Mirrors the SQL stores so every backend projects identically. */
-transform) {
-    let rows = [...source];
-    if (options.softDeleteField !== undefined && !defects.has("SOFT_DELETE_LEAK")) {
-        const field = options.softDeleteField;
-        const mentionsTombstones = params.filter?.includes(field) === true;
-        if (!mentionsTombstones)
-            rows = rows.filter((row) => row[field] === null || row[field] === undefined);
-    }
-    const unfilteredCount = rows.length;
-    if (params.filter !== undefined && params.filter !== "") {
-        let predicate;
-        try {
-            predicate = parseFilter(params.filter, options, defects);
-        }
-        catch (error) {
-            /* Correct behaviour is a 400. The defect lets the parser's own exception escape,
-             * which the transport surfaces as a 500 — validation confused with crashing. */
-            if (defects.has("ERROR_500_ON_BAD_FILTER")) {
-                throw new Error(`unhandled filter parse failure: ${String(error)}`);
-            }
-            throw error;
-        }
-        const filtered = rows.filter(predicate);
-        /* The "no results must mean the query was wrong" guard — falls back to the unfiltered set
-         * and makes an empty result impossible to express. */
-        rows = defects.has("EMPTY_RESULT_RETURNS_ALL") && filtered.length === 0 ? rows : filtered;
-    }
-    if (params.q !== undefined && params.q.trim() === "") {
-        /* empty q is a no-op here; reject is the store's job when the catalog says so. */
-    }
-    else if (params.q !== undefined && params.q !== "" && !defects.has("SEARCH_IGNORED")) {
-        const tokens = params.q
-            .toLowerCase()
-            .split(/\s+/)
-            .filter((token) => token.length > 0);
-        rows = rows.filter((row) => tokens.every((needle) => options.searchable.some((field) => String(row[field] ?? "")
-            .toLowerCase()
-            .includes(needle))));
-    }
-    const terms = params.order === undefined || params.order === "" ? [] : parseOrder(params.order, options, defects);
-    if (defects.has("SORT_DESC_DROPS_NULLS")) {
-        for (const term of terms) {
-            if (!term.descending)
-                continue;
-            rows = rows.filter((row) => row[term.field] !== null && row[term.field] !== undefined);
-        }
-    }
-    rows = applyOrder(rows, defects.has("ORDER_IGNORED") ? [] : terms, options, defects);
-    const requestedLimit = params.limit ?? options.defaultLimit;
-    const limit = defects.has("LIMIT_EXCEEDS_MAX") ? requestedLimit : Math.min(requestedLimit, options.maxLimit);
-    const total = defects.has("COUNT_ALWAYS_ZERO")
-        ? 0
-        : defects.has("COUNT_IGNORES_FILTER")
-            ? unfilteredCount
-            : rows.length;
-    let offset;
-    let page;
-    if (params.cursor !== undefined && params.cursor !== "") {
-        const afterId = decodeCursor(params.cursor);
-        const index = rows.findIndex((row) => String(row[options.identity]) === afterId);
-        /* Under CURSOR_DRIFT the cursor resolves one row early, so the cursor walk and the
-         * offset walk disagree — each looks self-consistent in isolation. */
-        offset = index === -1 ? 0 : index + (defects.has("CURSOR_DRIFT") ? 0 : 1);
-        page = null;
-    }
-    else {
-        const requested = Math.max(params.page ?? 1, 1);
-        offset = (requested - 1) * limit + (defects.has("OFF_BY_ONE_PAGE") && requested > 1 ? 1 : 0);
-        page = requested;
-    }
-    /* LIMIT_IGNORED serves the whole set regardless of the requested page size — the caller's
-     * paging loop then appears to complete in one request. */
-    const window = defects.has("LIMIT_IGNORED") ? rows.slice(offset) : rows.slice(offset, offset + limit);
-    const last = window.at(-1);
-    const hasMore = defects.has("HASMORE_ALWAYS_FALSE") ? false : offset + window.length < rows.length;
-    const projected = window
-        .map((row) => (transform === undefined ? row : transform(row)))
-        .map((row) => project(row, params.select, defects, options.excludedSelect ?? [], options.identity, options.selectUnknown));
-    return {
-        count: total,
-        hasMore,
-        items: projected,
-        limit,
-        nextCursor: hasMore && last !== undefined ? encodeCursor(String(last[options.identity])) : null,
-        page,
     };
 }
-function project(row, select, defects, excluded = [], identity = "id", selectUnknown) {
-    if (select === undefined || select === "" || select === "*")
-        return { ...row };
-    if (defects.has("SELECT_IGNORED"))
-        return { ...row };
-    const fields = select
-        .split(",")
-        .map((s) => s.trim())
-        .filter(Boolean);
-    const rejected = fields.find((f) => excluded.includes(f));
-    if (rejected !== undefined) {
-        throw new SqlError("invalid_select", `field "${rejected}" is not selectable`);
-    }
-    if (selectUnknown === "reject") {
-        const bogus = fields.find((field) => !Object.hasOwn(row, field) && !field.includes("("));
-        if (bogus !== undefined)
-            throw new SqlError("invalid_select", `field "${bogus}" is not selectable`);
-    }
-    const out = {};
-    for (const field of fields) {
-        if (defects.has("SELECT_FIELD_MISSING") && field !== identity && Object.hasOwn(row, field))
-            continue;
-        if (Object.hasOwn(row, field))
-            out[field] = row[field];
-    }
-    return out;
-}
-export function encodeCursor(id) {
-    return Buffer.from(JSON.stringify({ id }), "utf8").toString("base64url");
-}
-export function decodeCursor(cursor) {
-    try {
-        const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
-        if (typeof parsed.id !== "string")
-            throw new Error("missing id");
-        return parsed.id;
-    }
-    catch {
-        throw new SqlError("invalid_cursor", "cursor is not a value produced by this API");
-    }
-}
 //# sourceMappingURL=query.js.map