@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/reference/model/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Single source of truth for the reference backend: the server implements these descriptors and
+ * the OpenAPI document is generated from them. Keeping both sides derived from one definition
+ * mirrors how real backends emit their spec, and means a drift between spec and behavior has to
+ * be introduced deliberately (as a defect) rather than by accident.
+ */
+export interface FieldDef {
+    name: string;
+    type: "string" | "number" | "integer" | "boolean" | "object" | "array";
+    /** For an array field: the values its elements may take. */
+    items?: readonly string[];
+    /** Declared `format`; the server rejects a value that does not match it. */
+    format?: "date-time" | "uuid";
+    minimum?: number;
+    maximum?: number;
+    multipleOf?: number;
+    const?: string;
+    /** Accepted on write and never returned. */
+    writeOnly?: boolean;
+    /** For an object field: the component schema it references. */
+    ref?: "Point" | "TreeNode";
+    nullable?: boolean;
+    enum?: readonly string[];
+    maxLength?: number;
+    minLength?: number;
+    /** Patterns a string must match, each with the `u` flag; more than one is declared as an `allOf`. */
+    patterns?: readonly string[];
+    /** Server-assigned; never accepted from a client. */
+    generated?: boolean;
+    /** Present in responses but rejected as a write after creation. */
+    immutable?: boolean;
+    /** Accepted at create but not at update. */
+    createOnly?: boolean;
+    /** Only the highest rank may set it: emitted as `x-privileged`. */
+    privileged?: boolean;
+    required?: boolean;
+    filterable?: boolean;
+    sortable?: boolean;
+    searchable?: boolean;
+}
+export interface EntityDef {
+    name: string;
+    plural: string;
+    /** Path template relative to the API root, with `{param}` placeholders. */
+    collectionPath: string;
+    itemPath: string;
+    itemParam: string;
+    /** The entity has no list operation: its collection route takes a create alone, in the document and the server. */
+    unlisted?: true;
+    /** Path parameters that must be resolved from an ancestor. */
+    parents: string[];
+    identity: string;
+    softDeleteField?: string;
+    fields: FieldDef[];
+    defaultLimit: number;
+    maxLimit: number;
+    /** Optional closed filter/select catalog for conformance of declared-or-skip checks. */
+    filterCatalog?: {
+        emptyIn?: "reject" | "match-none";
+        maxInValues?: number;
+        maxFilterConditions?: number;
+        opsByField?: Record<string, readonly string[]>;
+        selectUnknown?: "reject" | "ignore";
+        aliases?: Record<string, string>;
+    };
+    /** Column sets that must stay unique. Emitted as `x-unique` and enforced as HTTP 409. */
+    unique?: string[][];
+    /** The order a listing takes when the request names none, canonical `field.dir`. */
+    defaultOrder: string;
+    /** Related records a sparse fieldset may embed: `table(name)` on a row. */
+    relations?: Record<string, {
+        entity: string;
+        via: string;
+        fields: readonly string[];
+    }>;
+}
+/** What a shape changes about the records themselves; see `ReferenceShape`. */
+export interface EntityShape {
+    ids?: "uuid" | "integer";
+    writeOnlyField?: boolean;
+    richSchema?: boolean;
+    largeRecords?: boolean;
+    specLayout?: boolean;
+    clientIds?: {
+        min: number;
+        max: number;
+    };
+    identityField?: string;
+    tableKey?: "slug";
+    stringGuard?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/reference/model/types.js

@@ -0,0 +1,8 @@
+/**
+ * Single source of truth for the reference backend: the server implements these descriptors and
+ * the OpenAPI document is generated from them. Keeping both sides derived from one definition
+ * mirrors how real backends emit their spec, and means a drift between spec and behavior has to
+ * be introduced deliberately (as a defect) rather than by accident.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/reference/model/webhook.d.ts

@@ -0,0 +1,8 @@
+import type { EntityDef } from "./types.ts";
+/**
+ * A project's webhook: registered, read back, changed and removed by its id, and never listed.
+ * Present so an entity with no list operation has something to exercise: its cohort is the
+ * records its creates return, and its teardown reads each one back to show it gone.
+ */
+export declare const WEBHOOK: EntityDef;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/api/reference/model/webhook.js

@@ -0,0 +1,29 @@
+import { TIMESTAMPS } from "./timestamps.js";
+/**
+ * A project's webhook: registered, read back, changed and removed by its id, and never listed.
+ * Present so an entity with no list operation has something to exercise: its cohort is the
+ * records its creates return, and its teardown reads each one back to show it gone.
+ */
+export const WEBHOOK = {
+    collectionPath: "/v1/projects/{project_id}/webhooks",
+    defaultLimit: 20,
+    defaultOrder: "created_at.desc",
+    fields: [
+        { generated: true, immutable: true, name: "id", required: true, type: "string" },
+        { generated: true, immutable: true, name: "project_id", required: true, type: "string" },
+        { maxLength: 128, name: "name", required: true, type: "string" },
+        { maxLength: 512, name: "url", required: true, type: "string" },
+        { maxLength: 256, name: "description", nullable: true, type: "string" },
+        { enum: ["active", "paused"], name: "status", type: "string" },
+        ...TIMESTAMPS,
+    ],
+    identity: "id",
+    itemParam: "webhook_id",
+    itemPath: "/v1/projects/{project_id}/webhooks/{webhook_id}",
+    maxLimit: 100,
+    name: "webhook",
+    parents: ["project_id"],
+    plural: "webhooks",
+    unlisted: true,
+};
+//# sourceMappingURL=webhook.js.map

package/dist/api/reference/query/coerce.d.ts

@@ -0,0 +1,10 @@
+import type { FieldDef } from "../model/types.ts";
+import type { Scalar } from "../query-types.ts";
+/**
+ * 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.
+ */
+export declare function coerce(raw: string, field: FieldDef): Scalar | undefined;
+//# sourceMappingURL=coerce.d.ts.map

package/dist/api/reference/query/coerce.js

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+export 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 raw;
+}
+//# sourceMappingURL=coerce.js.map

package/dist/api/reference/query/compare.d.ts

@@ -0,0 +1,6 @@
+import type { Collation, OrderTerm } from "../query-types.ts";
+type Row = Record<string, unknown>;
+/** Orders rows under the plan. Ties the plan leaves open keep their input order. */
+export declare function compareRows(order: OrderTerm[], collation: Collation): (left: Row, right: Row) => number;
+export {};
+//# sourceMappingURL=compare.d.ts.map

package/dist/api/reference/query/compare.js

@@ -0,0 +1,23 @@
+import { compareScalar, isNull } from "./scalar.js";
+/** 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 = isNull(a);
+            const bNull = isNull(b);
+            if (aNull && bNull)
+                continue;
+            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;
+    };
+}
+//# sourceMappingURL=compare.js.map

package/dist/api/reference/query/conventions.d.ts

@@ -0,0 +1,20 @@
+import type { DefectSet } from "../defects/defect-set.ts";
+import type { EntityDef } from "../model/types.ts";
+import type { Collation, SearchMode } from "../query-types.ts";
+export declare const SEARCH_MODES: readonly SearchMode[];
+/** Behavior of a correct backend that varies between real APIs — see `ReferenceShape`. */
+export interface QueryConventions {
+    /** Where nulls sort when the request does not say. */
+    nulls: "first" | "last";
+    collation: Collation;
+    /** Reject a filter value that does not parse as the field's type, instead of matching nothing. */
+    strictTypes: boolean;
+}
+export declare const DEFAULT_CONVENTIONS: QueryConventions;
+/** What every parse reads: the entity, the defects the backend carries, and its conventions. */
+export interface ParseContext {
+    entity: EntityDef;
+    defects: DefectSet;
+    conventions: QueryConventions;
+}
+//# sourceMappingURL=conventions.d.ts.map

package/dist/api/reference/query/conventions.js

@@ -0,0 +1,3 @@
+export const SEARCH_MODES = ["contains", "prefix"];
+export const DEFAULT_CONVENTIONS = { collation: "binary", nulls: "first", strictTypes: false };
+//# sourceMappingURL=conventions.js.map

package/dist/api/reference/query/evaluate.d.ts

@@ -0,0 +1,6 @@
+import type { FilterNode } from "../query-types.ts";
+type Row = Record<string, unknown>;
+/** The in-memory evaluation of a filter — the reference semantics the SQL compilers match. */
+export declare function evaluate(node: FilterNode, row: Row): boolean;
+export {};
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/api/reference/query/evaluate.js

@@ -0,0 +1,69 @@
+import { likeToRegExp } from "./like.js";
+import { compareScalar, equal, isNull } from "./scalar.js";
+/** 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":
+            return evaluateCmp(node, row);
+        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":
+            return evaluateContains(node, row);
+        case "search":
+            return evaluateSearch(node, row);
+    }
+}
+function evaluateCmp(node, row) {
+    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;
+}
+function evaluateContains(node, row) {
+    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);
+}
+function evaluateSearch(node, row) {
+    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);
+    });
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/api/reference/query/fields.d.ts

@@ -0,0 +1,7 @@
+import type { DefectSet } from "../defects/defect-set.ts";
+import type { EntityDef, FieldDef } from "../model/types.ts";
+export declare function fieldOf(entity: EntityDef, name: string): FieldDef | undefined;
+export declare function filterableFields(entity: EntityDef, defects: DefectSet): string[];
+export declare function sortableFields(entity: EntityDef, defects: DefectSet): string[];
+export declare function isNumeric(field: FieldDef | undefined): boolean;
+//# sourceMappingURL=fields.d.ts.map

package/dist/api/reference/query/fields.js

@@ -0,0 +1,18 @@
+import { fieldsWhere, OVERCLAIMED_FIELD } from "../model/fields.js";
+export function fieldOf(entity, name) {
+    return entity.fields.find((field) => field.name === name);
+}
+export 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;
+}
+export function sortableFields(entity, defects) {
+    const declared = fieldsWhere(entity, "sortable");
+    return defects.has("SPEC_OVERCLAIMS_SORTABLE") ? declared.filter((f) => f !== OVERCLAIMED_FIELD) : declared;
+}
+export function isNumeric(field) {
+    return field?.type === "integer" || field?.type === "number";
+}
+//# sourceMappingURL=fields.js.map

package/dist/api/reference/query/filter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The reference backend's query language, parsed once.
+ *
+ * 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).
+ */
+import type { FilterNode } from "../query-types.ts";
+import type { ParseContext } from "./conventions.ts";
+/** Parses a canonical filter expression. Throws `SqlError` for anything a correct backend rejects. */
+export declare function parseFilter(expression: string, ctx: ParseContext): FilterNode;
+//# sourceMappingURL=filter.d.ts.map

package/dist/api/reference/query/filter.js

@@ -0,0 +1,75 @@
+/**
+ * The reference backend's query language, parsed once.
+ *
+ * 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).
+ */
+import { SqlError } from "../store-api.js";
+import { fieldOf, filterableFields } from "./fields.js";
+import { operatorFor } from "./operator.js";
+import { countTerms, GROUP, splitTopLevel } from "./split.js";
+import { buildTerm } from "./term.js";
+/** 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 trimmed = expression.trim();
+    const group = GROUP.exec(trimmed);
+    if (group !== null)
+        return parseGroup(group[1], group[2], ctx);
+    return parseTerm(trimmed, ctx);
+}
+function parseGroup(named, inner, ctx) {
+    const { defects } = ctx;
+    const children = splitTopLevel(inner).map((part) => parseNode(part, ctx));
+    if (children.length === 0)
+        throw new SqlError("invalid_filter", `empty ${named}() group`);
+    /* The joiner is swapped, not the parse: the expression is read correctly and evaluated with
+     * the other combinator's semantics. */
+    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)
+            kind = nested.kind;
+    }
+    return { children, kind };
+}
+function parseTerm(trimmed, ctx) {
+    const { defects, entity } = ctx;
+    const segments = trimmed.split(".");
+    if (segments.length < 3) {
+        if (defects.has("IGNORES_MALFORMED_FILTER"))
+            return { kind: "const", value: true };
+        throw new SqlError("invalid_filter", `malformed filter term "${trimmed}"`);
+    }
+    const [name, rawOp] = segments;
+    const raw = segments.slice(2).join(".");
+    const op = operatorFor(name, rawOp, ctx);
+    if (op === null)
+        return { kind: "const", value: true };
+    if (!filterableFields(entity, defects).includes(name)) {
+        /* Correct behavior 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 { kind: "const", value: true };
+        throw new SqlError("invalid_filter", `field "${name}" is not filterable`);
+    }
+    const field = fieldOf(entity, name);
+    return buildTerm({ ctx, field, op, raw });
+}
+//# sourceMappingURL=filter.js.map

package/dist/api/reference/query/like.d.ts

@@ -0,0 +1,5 @@
+import type { LikeSegment } from "../query-types.ts";
+/** A `like` value as segments: text, and the wildcards it holds. */
+export declare function likePattern(raw: string, unescaped: boolean): LikeSegment[];
+export declare function likeToRegExp(pattern: LikeSegment[], insensitive: boolean): RegExp;
+//# sourceMappingURL=like.d.ts.map

package/dist/api/reference/query/like.js

@@ -0,0 +1,38 @@
+/** A `like` value as segments: text, and the wildcards it holds. */
+export 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;
+}
+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");
+}
+//# sourceMappingURL=like.js.map

package/dist/api/reference/query/operator.d.ts

@@ -0,0 +1,7 @@
+import type { ParseContext } from "./conventions.ts";
+/**
+ * The operator a term's `rawOp` names on `name`, after the entity's alias table, or `null` when a
+ * defect drops the term instead of refusing it. Throws for an operator a correct backend refuses.
+ */
+export declare function operatorFor(name: string, rawOp: string, ctx: ParseContext): string | null;
+//# sourceMappingURL=operator.d.ts.map

package/dist/api/reference/query/operator.js

@@ -0,0 +1,54 @@
+import { SqlError } from "../store-api.js";
+const OPERATORS = /* @__PURE__ */ new Set([
+    "eq",
+    "ne",
+    "neq",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "nin",
+    "like",
+    "ilike",
+    "is",
+    "contains",
+]);
+/**
+ * The operator a term's `rawOp` names on `name`, after the entity's alias table, or `null` when a
+ * defect drops the term instead of refusing it. Throws for an operator a correct backend refuses.
+ */
+export function operatorFor(name, rawOp, ctx) {
+    const { defects, entity } = ctx;
+    if (!OPERATORS.has(rawOp)) {
+        if (defects.has("FILTER_ILLEGAL_OP_IGNORED"))
+            return null;
+        throw new SqlError("invalid_filter", `unknown operator "${rawOp}"`);
+    }
+    const op = aliased(rawOp, ctx);
+    if (!allowedOn(entity, name, [rawOp, op])) {
+        if (defects.has("FILTER_ILLEGAL_OP_IGNORED"))
+            return null;
+        throw new SqlError("invalid_filter", `operator "${rawOp}" is not allowed on "${name}"`);
+    }
+    /* 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"`);
+    }
+    return op;
+}
+/* `rawOp` through the entity's alias table; `ne` is `neq` with or without one. */
+function aliased(rawOp, { defects, entity }) {
+    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;
+    return mapped ?? (rawOp === "ne" ? "neq" : rawOp);
+}
+/* Whether the field's operator allowlist, where it has one, names the operator in either spelling. */
+function allowedOn(entity, name, [rawOp, op]) {
+    const opsByField = entity.filterCatalog?.opsByField;
+    const allowed = opsByField !== undefined && Object.hasOwn(opsByField, name) ? opsByField[name] : undefined;
+    return allowed === undefined || allowed.includes(rawOp) || allowed.includes(op);
+}
+//# sourceMappingURL=operator.js.map

package/dist/api/reference/query/order.d.ts

@@ -0,0 +1,10 @@
+import type { OrderTerm } from "../query-types.ts";
+import type { ParseContext } from "./conventions.ts";
+/**
+ * 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.
+ */
+export declare function parseOrder(expression: string, ctx: ParseContext, trusted?: boolean): OrderTerm[];
+//# sourceMappingURL=order.d.ts.map

package/dist/api/reference/query/order.js

@@ -0,0 +1,59 @@
+import { DefectSet } from "../defects/defect-set.js";
+import { fieldsWhere } from "../model/fields.js";
+import { SqlError } from "../store-api.js";
+import { fieldOf, isNumeric, sortableFields } from "./fields.js";
+import { splitTopLevel } from "./split.js";
+const MODIFIERS = ["asc", "desc", "nullsfirst", "nullslast"];
+/**
+ * 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.
+ */
+export function parseOrder(expression, ctx, trusted = false) {
+    const defects = trusted ? new DefectSet() : ctx.defects;
+    const sortable = trusted ? fieldsWhere(ctx.entity, "sortable") : sortableFields(ctx.entity, defects);
+    const terms = splitTopLevel(expression).flatMap((term) => orderTerm(term, { ctx, defects, sortable }));
+    return defects.has("SORT_MULTI_KEY_IGNORED") ? terms.slice(0, 1) : terms;
+}
+function orderTerm(term, { ctx, defects, sortable }) {
+    const { entity, conventions } = ctx;
+    const [name, ...parsed] = term.split(".");
+    if (!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 = readModifiers(parsed, defects);
+    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,
+        },
+    ];
+}
+/* The modifiers after the field name, as the backend reads them. Throws on one it does not know. */
+function readModifiers(parsed, defects) {
+    /* The defect reads a direction it does not know as no direction at all: ascending. */
+    const read = defects.has("IGNORES_BAD_SORT_DIRECTION")
+        ? parsed.filter((modifier) => MODIFIERS.includes(modifier))
+        : parsed;
+    const modifiers = defects.has("SORT_NULLS_MODIFIER_IGNORED")
+        ? read.filter((modifier) => modifier !== "nullsfirst" && modifier !== "nullslast")
+        : read;
+    for (const modifier of modifiers) {
+        if (!MODIFIERS.includes(modifier))
+            throw new SqlError("invalid_order", `unknown sort modifier "${modifier}"`);
+    }
+    return modifiers;
+}
+//# sourceMappingURL=order.js.map

package/dist/api/reference/query/scalar.d.ts

@@ -0,0 +1,5 @@
+import type { Scalar } from "../query-types.ts";
+export declare function isNull(value: unknown): boolean;
+export declare function compareScalar(a: unknown, b: unknown, asText: boolean): number;
+export declare function equal(a: unknown, b: Scalar, asText: boolean): boolean;
+//# sourceMappingURL=scalar.d.ts.map

package/dist/api/reference/query/scalar.js

@@ -0,0 +1,19 @@
+/* The comparisons the in-memory evaluation and ordering share. */
+export function isNull(value) {
+    return value === null || value === undefined;
+}
+export 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;
+}
+export function equal(a, b, asText) {
+    if (asText)
+        return String(a) === String(b);
+    return a === b;
+}
+//# sourceMappingURL=scalar.js.map