@workerstack/testing 0.0.0-stage → 0.31.0

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

@@ -0,0 +1,9 @@
+import type { FilterNode, SearchMode } from "../query-types.ts";
+import type { ParseContext } from "./conventions.ts";
+/**
+ * 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 declare function parseSearch(q: string, mode: SearchMode, { defects, entity }: Pick<ParseContext, "defects" | "entity">): FilterNode | null;
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1,24 @@
+import { fieldsWhere } from "../model/fields.js";
+/**
+ * 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, mode, { defects, entity }) {
+    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;
+    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",
+    };
+}
+//# sourceMappingURL=search.js.map

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

@@ -0,0 +1,7 @@
+/** `and(...)` or `or(...)`: the combinator and what it holds. Both groups take part in every match. */
+export declare const GROUP: RegExp;
+/** Splits on commas at paren depth zero — shared by the filter and order grammars. */
+export declare function splitTopLevel(input: string): string[];
+/** How many terms a filter expression holds, counted through every group. */
+export declare function countTerms(expression: string): number;
+//# sourceMappingURL=split.d.ts.map

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

@@ -0,0 +1,29 @@
+/** `and(...)` or `or(...)`: the combinator and what it holds. Both groups take part in every match. */
+export const GROUP = /^(and|or)\((.*)\)$/s;
+/** 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;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch === "(")
+            depth++;
+        else if (ch === ")")
+            depth--;
+        else if (ch === "," && depth === 0) {
+            parts.push(input.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(input.slice(start));
+    return parts.map((p) => p.trim()).filter((p) => p.length > 0);
+}
+/** How many terms a filter expression holds, counted through every group. */
+export function countTerms(expression) {
+    const group = GROUP.exec(expression.trim());
+    if (group !== null)
+        return splitTopLevel(group[2]).reduce((sum, part) => sum + countTerms(part), 0);
+    return 1;
+}
+//# sourceMappingURL=split.js.map

package/dist/api/reference/query/term-list.d.ts

@@ -0,0 +1,7 @@
+import type { FilterNode } from "../query-types.ts";
+import type { TermRead } from "./term-types.ts";
+/** `in` and `nin`: membership in a parenthesized, comma-separated list. */
+export declare function listTerm({ asText, ctx, field, op, raw, typed }: TermRead): FilterNode;
+/** `is.null`, `is.notnull`, and `is.true` / `is.false` on a boolean. */
+export declare function isTerm({ ctx, field, raw }: TermRead): FilterNode;
+//# sourceMappingURL=term-list.d.ts.map

package/dist/api/reference/query/term-list.js

@@ -0,0 +1,40 @@
+import { SqlError } from "../store-api.js";
+function stripParens(value) {
+    return value.startsWith("(") && value.endsWith(")") ? value.slice(1, -1) : value;
+}
+/** `in` and `nin`: membership in a parenthesized, comma-separated list. */
+export function listTerm({ asText, ctx, field, op, raw, typed }) {
+    const { defects, entity } = ctx;
+    const members = stripParens(raw)
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (members.length === 0) {
+        if (entity.filterCatalog?.emptyIn === "reject")
+            throw new SqlError("invalid_filter", "empty in()");
+        return { kind: "const", value: op === "nin" };
+    }
+    const max = 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 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 };
+}
+/** `is.null`, `is.notnull`, and `is.true` / `is.false` on a boolean. */
+export function isTerm({ ctx, field, raw }) {
+    if (raw === "null") {
+        if (ctx.defects.has("FILTER_IS_NULL_MATCHES_ALL"))
+            return { kind: "const", value: true };
+        return { field: field.name, kind: "isnull", negate: false };
+    }
+    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" };
+    }
+    throw new SqlError("invalid_filter", `is.${raw} is not a recognized predicate`);
+}
+//# sourceMappingURL=term-list.js.map

package/dist/api/reference/query/term-types.d.ts

@@ -0,0 +1,17 @@
+import type { FieldDef } from "../model/types.ts";
+import type { Scalar } from "../query-types.ts";
+import type { ParseContext } from "./conventions.ts";
+/** One filter term, its operator already resolved: what a term builder reads. */
+export interface TermInput {
+    ctx: ParseContext;
+    field: FieldDef;
+    op: string;
+    raw: string;
+}
+export interface TermRead extends TermInput {
+    /** Compare the textual form of both sides: the numeric-as-text defect. */
+    asText: boolean;
+    /** Text read as the field's type: a lenient backend answers `undefined`, a strict one throws. */
+    typed: (text: string) => Scalar | undefined;
+}
+//# sourceMappingURL=term-types.d.ts.map

package/dist/api/reference/query/term-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=term-types.js.map

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

@@ -0,0 +1,5 @@
+import type { FilterNode } from "../query-types.ts";
+import type { TermInput } from "./term-types.ts";
+/** One term as a predicate. Throws `SqlError` for an operator the field cannot take. */
+export declare function buildTerm(input: TermInput): FilterNode;
+//# sourceMappingURL=term.d.ts.map

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

@@ -0,0 +1,98 @@
+/*
+ * 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 { SqlError } from "../store-api.js";
+import { coerce } from "./coerce.js";
+import { isNumeric } from "./fields.js";
+import { likePattern } from "./like.js";
+import { isTerm, listTerm } from "./term-list.js";
+const BUILDERS = {
+    eq: eqTerm,
+    gt: rangeTerm,
+    gte: rangeTerm,
+    ilike: likeTerm,
+    in: listTerm,
+    is: isTerm,
+    like: likeTerm,
+    lt: rangeTerm,
+    lte: rangeTerm,
+    neq: neqTerm,
+    nin: listTerm,
+};
+/** One term as a predicate. Throws `SqlError` for an operator the field cannot take. */
+export function buildTerm(input) {
+    const { ctx, field, op, raw } = input;
+    /* 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: ctx.defects.has("CONTAINS_MATCHES_SUBSTRING"), value: raw };
+    }
+    const builder = Object.hasOwn(BUILDERS, op) ? BUILDERS[op] : undefined;
+    if (builder === undefined)
+        throw new SqlError("invalid_filter", `unhandled operator "${op}"`);
+    const asText = isNumeric(field) && ctx.defects.has("NUMERIC_COMPARED_AS_TEXT");
+    return builder({ ...input, asText, typed: typedReader(field, ctx.conventions) });
+}
+/* A value that is not of the field's type: lenient backends match nothing, strict ones say so. */
+function typedReader(field, conventions) {
+    return (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;
+    };
+}
+function eqTerm({ asText, ctx, field, raw, typed }) {
+    if (ctx.defects.has("FILTER_EQ_NOT_APPLIED"))
+        return { kind: "const", value: true };
+    const value = typed(raw);
+    return value === undefined
+        ? { kind: "const", value: false }
+        : { asText, field: field.name, kind: "cmp", nullsMatch: false, op: "eq", value };
+}
+function neqTerm({ asText, ctx, field, raw, typed }) {
+    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 = !ctx.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 { asText, field: field.name, kind: "cmp", nullsMatch, op: "neq", value };
+}
+function rangeTerm({ asText, ctx, field, op, raw, typed }) {
+    const value = typed(raw);
+    if (value === undefined)
+        return { kind: "const", value: false };
+    const effective = effectiveRange(op, ctx.defects);
+    return { asText, field: field.name, kind: "cmp", nullsMatch: false, op: effective, value };
+}
+/* The comparison a range operator is compiled as: a defect moves one bound across the boundary. */
+function effectiveRange(op, defects) {
+    if (op === "gte" && defects.has("FILTER_GTE_IS_GT"))
+        return "gt";
+    if (op === "lte" && defects.has("FILTER_LTE_IS_LT"))
+        return "lt";
+    if (op === "lt" && defects.has("FILTER_LT_IS_LTE"))
+        return "lte";
+    return op;
+}
+function likeTerm({ ctx, field, op, raw }) {
+    if (field.type !== "string")
+        throw new SqlError("invalid_filter", `${op} needs a text field`);
+    return {
+        field: field.name,
+        insensitive: op === "ilike" && !ctx.defects.has("FILTER_ILIKE_IS_LIKE"),
+        kind: "like",
+        pattern: likePattern(raw, ctx.defects.has("LIKE_UNESCAPED")),
+    };
+}
+//# sourceMappingURL=term.js.map

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

@@ -0,0 +1,6 @@
+import type { FilterNode } from "../query-types.ts";
+/** The conjunction of the predicates given, `null`s skipped: one alone is itself, none matches everything. */
+export declare function and(...nodes: Array<FilterNode | null>): FilterNode;
+/** Fields a filter expression names, for the tombstone rule (an explicit mention lifts it). */
+export declare function fieldsIn(node: FilterNode): string[];
+//# sourceMappingURL=tree.d.ts.map

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

@@ -0,0 +1,24 @@
+/** The conjunction of the predicates given, `null`s skipped: one alone is itself, none matches everything. */
+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];
+    }
+}
+//# sourceMappingURL=tree.js.map

package/dist/api/reference/query-types.d.ts

@@ -0,0 +1,76 @@
+export type Scalar = string | number | boolean | null;
+export type LikeSegment = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "any";
+} | {
+    kind: "one";
+};
+export type ComparisonOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte";
+export type FilterNode = {
+    kind: "const";
+    value: boolean;
+} | {
+    kind: "and" | "or";
+    children: FilterNode[];
+} | {
+    kind: "cmp";
+    field: string;
+    op: ComparisonOp;
+    value: Scalar;
+    /** Compare the textual form of both sides — the numeric-as-text defect. */
+    asText: boolean;
+    /** Whether a null value satisfies the predicate. True only for a correct `neq`. */
+    nullsMatch: boolean;
+} | {
+    kind: "in";
+    field: string;
+    values: Scalar[];
+    negate: boolean;
+    asText: boolean;
+} | {
+    kind: "isnull";
+    field: string;
+    negate: boolean;
+} | {
+    kind: "like";
+    field: string;
+    pattern: LikeSegment[];
+    insensitive: boolean;
+}
+/** Array membership. `substring` is the defect: the serialized array matched as text. */
+ | {
+    kind: "contains";
+    field: string;
+    value: string;
+    substring: boolean;
+} | {
+    kind: "search";
+    fields: string[];
+    token: string;
+    /** `prefix`: some field starts with the token; `contains`: some field contains it. */
+    mode: SearchMode;
+    caseSensitive: boolean;
+};
+export interface OrderTerm {
+    field: string;
+    descending: boolean;
+    nullsFirst: boolean;
+    asText: boolean;
+}
+export type Collation = "binary" | "insensitive";
+export type SearchMode = "contains" | "prefix";
+/** Everything a store needs to answer a listing: which rows, in what order. */
+export interface SelectPlan {
+    where: FilterNode;
+    order: OrderTerm[];
+    /** Text ordering. Filters always compare binary; only ordering follows the collation. */
+    collation: Collation;
+    /**
+     * Tied rows come back in an arbitrary, varying order — what a database does when the sort
+     * has no total order. Set only under UNSTABLE_SORT; otherwise the identity breaks every tie.
+     */
+    shuffleTies: boolean;
+}
+//# sourceMappingURL=query-types.d.ts.map

package/dist/api/reference/query-types.js

@@ -0,0 +1,4 @@
+/* The plan a store answers a listing from: which rows, in what order. Types only, so stores and the
+ * planner share them without importing each other. */
+export {};
+//# sourceMappingURL=query-types.js.map

package/dist/api/reference/shapes/catalog.d.ts

@@ -0,0 +1,4 @@
+import type { NamedShape } from "./types.ts";
+/** Every named shape the conformance suite serves the clean baseline behind. */
+export declare const SHAPES: readonly NamedShape[];
+//# sourceMappingURL=catalog.d.ts.map

package/dist/api/reference/shapes/catalog.js

@@ -0,0 +1,203 @@
+/** Every named shape the conformance suite serves the clean baseline behind. */
+export const SHAPES = [
+    {
+        cannotRun: {
+            "pagination.cursor-agrees-with-page": "there is no cursor",
+            "pagination.has-more-is-accurate": "there is no more-pages flag to judge",
+        },
+        cannotExhibit: ["CURSOR_DRIFT", "COLLATION_INCONSISTENT", "HASMORE_ALWAYS_FALSE"],
+        name: "page-total",
+        shape: { pagination: "page-total" },
+        why: "page numbers and a total, with no more-pages flag",
+    },
+    {
+        cannotRun: {
+            "pagination.cursor-agrees-with-page": "there is no page number or offset to agree with",
+            "pagination.has-more-is-accurate": "there is no more-pages flag to judge",
+        },
+        cannotExhibit: [
+            "OFF_BY_ONE_PAGE",
+            "HASMORE_ALWAYS_FALSE",
+            "COUNT_ALWAYS_ZERO",
+            "COUNT_IGNORES_FILTER",
+            /* Both are seen by comparing a cursor walk with a page walk, and there are no pages. */
+            "CURSOR_DRIFT",
+            "COLLATION_INCONSISTENT",
+            /* There is no page number to go past the end with. */
+            "PAGE_PAST_END_REPEATS",
+        ],
+        name: "cursor-only",
+        shape: { pagination: "cursor-only" },
+        why: "a forward cursor and nothing else to page by",
+    },
+    {
+        cannotRun: {
+            "pagination.cursor-agrees-with-page": "there is no cursor",
+            "pagination.has-more-is-accurate": "there is no more-pages flag to judge",
+        },
+        cannotExhibit: [
+            "CURSOR_DRIFT",
+            "COLLATION_INCONSISTENT",
+            "HASMORE_ALWAYS_FALSE",
+            /* There is no page number to go past the end with. */
+            "PAGE_PAST_END_REPEATS",
+        ],
+        name: "offset-total",
+        shape: { pagination: "offset-total", prepopulate: 12 },
+        why: "rows skipped and taken (skip / take) under a bounded page size, with only a total in a { data, totalCount } envelope",
+    },
+    {
+        cannotRun: {
+            "pagination.cursor-agrees-with-page": "there is no cursor",
+            "pagination.has-more-is-accurate": "there is no more-pages flag to judge",
+            "sort.nulls-first-last": "the sort template has no token that places nulls",
+            "spec.declared-sortable-nulls-accepted": "the sort template has no token that places nulls",
+        },
+        cannotExhibit: [
+            "CURSOR_DRIFT",
+            "COLLATION_INCONSISTENT",
+            "HASMORE_ALWAYS_FALSE",
+            "PAGE_PAST_END_REPEATS",
+            /* No nulls token to ignore. */
+            "SORT_NULLS_MODIFIER_IGNORED",
+        ],
+        name: "wrapped-records",
+        shape: {
+            identityField: "ID",
+            ids: "integer",
+            pagination: "offset-total",
+            prepopulate: 6,
+            recordEnvelope: true,
+            relatedRecord: true,
+            repeatedSort: true,
+            bareIdParams: true,
+        },
+        why: "an upper-case integer ID, records wrapped on create and read, writes answered without the record, rows beside a fields sidecar, a related record nested in each, and several sort keys as the parameter repeated",
+    },
+    {
+        name: "wrapped-rows",
+        shape: { wrappedRows: true },
+        why: "each listed row wraps its record under document beside its highlights, as a search engine answers",
+    },
+    {
+        /* It clamps a page size rather than refusing it, and its document says so. */
+        cannotRun: {
+            "pagination.limit-bounds-enforced": "the page size is clamped, as the document declares, not refused",
+        },
+        cannotExhibit: ["LIMIT_OUT_OF_RANGE_SERVED"],
+        name: "clamped-limit",
+        shape: { clampLimit: 3 },
+        why: "the server serves at most 3 per page whatever is asked, and does not document it",
+    },
+    {
+        name: "prepopulated",
+        shape: { prepopulate: 230 },
+        why: "the collection already holds more records than one page and than the API tester's walk cap",
+    },
+    { name: "uuid-ids", shape: { ids: "uuid" }, why: "UUID identifiers; a malformed one in a path is a 400" },
+    { name: "integer-ids", shape: { ids: "integer" }, why: "integer identifiers; a malformed one in a path is a 400" },
+    {
+        /* CREATE_DROPS_FIELD: the lost field fails the read-back that would confirm the record, so
+         * the seed stops before its check reads the record back. */
+        /* READ_DROPS_FIELD: an acknowledged create is confirmed by the read that drops the field, so
+         * no record is ever confirmed and the seed stops before anything can be judged. */
+        cannotExhibit: ["CREATE_DROPS_FIELD", "READ_DROPS_FIELD"],
+        exhibits: ["CLIENT_ID_IGNORED", "CLIENT_ID_OVERWRITES"],
+        name: "client-ids",
+        shape: { ackCreate: true, clientIds: { max: 999, min: 1 }, ids: "integer", prepopulate: 5 },
+        why: "the client picks a table's integer id and the create only acknowledges, with tables already present",
+    },
+    {
+        name: "ack-create",
+        shape: { createAnswer: "id-message" },
+        why: 'a create answers only an acknowledgment, { "id": ..., "message": "created" }, never the record',
+    },
+    {
+        name: "location-create",
+        shape: { createAnswer: "location" },
+        why: "a create answers 201 with an empty body, naming the new record only in its Location header",
+    },
+    {
+        cannotRun: {
+            "create.unique-conflict-rejected": "the document declares nothing unique",
+            "update.unique-conflict-rejected": "the document declares nothing unique",
+        },
+        /* Nothing is declared unique, so there is no declared uniqueness to stop enforcing. */
+        cannotExhibit: ["UNIQUE_NOT_ENFORCED"],
+        name: "tenant-slugs",
+        shape: { tableKey: "slug" },
+        why: "a table is named by a slug derived from its name, unique only within its project",
+    },
+    {
+        name: "strict-filter-types",
+        shape: { conventions: { strictTypes: true } },
+        why: "a filter value that is not of the field's type is rejected with 400",
+    },
+    { name: "nulls-last", shape: { conventions: { nulls: "last" } }, why: "nulls sort last in ascending order" },
+    {
+        name: "ci-collation",
+        shape: { conventions: { collation: "insensitive" }, prepopulate: 6 },
+        why: "text sorts case-insensitively, over mixed-case data",
+    },
+    { name: "path-prefix", shape: { basePath: "/api" }, why: "the whole API is mounted under /api" },
+    {
+        /* PUT replaces by contract, so "a partial update that replaces" has no partial update to break. */
+        /* Both are partial-write faults; under PUT the checks that see them stand down. */
+        cannotExhibit: ["PATCH_REPLACES", "CONCURRENT_WRITE_LOST"],
+        cannotRun: {
+            "concurrency.no-lost-update": "two concurrent PUTs each replace the whole record; only partial writes can be lost",
+            "patch.minimality": "a PUT replaces the record by contract; there is no partial update to keep minimal",
+        },
+        name: "put-update",
+        shape: { updateMethod: "PUT" },
+        why: "update is PUT, replacing the record; there is no PATCH",
+    },
+    {
+        exhibits: ["KEY_DELETE_CROSS_TENANT"],
+        name: "key-lifecycle",
+        shape: { keyLifecycle: true },
+        why: "the API keys a recipe mints are listed, named and renamed, each its own tenant's",
+    },
+    {
+        exhibits: ["STALE_PAST_BOUND", "BYPASS_IGNORED"],
+        name: "cached-reads",
+        shape: { cachedReads: true },
+        why: "item and list reads come from a 400 ms cache past which a declared bypass header reads fresh",
+    },
+    {
+        exhibits: ["WRITE_ONLY_LEAKED"],
+        name: "write-only-field",
+        shape: { writeOnlyField: true },
+        why: "create accepts a writeOnly field it never returns",
+    },
+    { name: "form-create", shape: { formCreate: true }, why: "create takes a form-encoded body, not JSON" },
+    {
+        name: "string-guard",
+        shape: { stringGuard: true },
+        why: "every written string carries a guard pattern, beside its own pattern in an allOf where it has one",
+    },
+    {
+        name: "totp-setup",
+        shape: { totpSetup: true },
+        why: "the caller enrolls TOTP and is answered its secret, the otpauth URI and a QR image of it",
+    },
+    {
+        name: "rich-schema",
+        shape: { richSchema: true },
+        why: "required date-time, a bounded number, a const, and one schema used twice in a body",
+    },
+    { name: "large-pages", shape: { largeRecords: true }, why: "one list page is larger than 256 KiB" },
+    {
+        /* 2XX documents 200 and 201 alike: answering one where the other was meant is permitted. */
+        cannotExhibit: ["CREATED_201_AS_200", "RESPONSE_STATUS_UNDECLARED"],
+        name: "range-statuses",
+        shape: { rangeStatuses: true },
+        why: "responses documented as 2XX and default",
+    },
+    {
+        name: "spec-layout",
+        shape: { specLayout: true },
+        why: "components before paths, path-level parameters, and a recursive schema",
+    },
+];
+//# sourceMappingURL=catalog.js.map

package/dist/api/reference/shapes/dialect.d.ts

@@ -0,0 +1,5 @@
+import type { Dialect } from "../dialect/types.ts";
+import type { ReferenceShape } from "./types.ts";
+/** The dialect as this shape serves it: its pagination model and sort spelling replace the dialect's own. */
+export declare function shapedDialect(dialect: Dialect, shape: ReferenceShape): Dialect;
+//# sourceMappingURL=dialect.d.ts.map

package/dist/api/reference/shapes/dialect.js

@@ -0,0 +1,61 @@
+/** The dialect as this shape serves it: its pagination model and sort spelling replace the dialect's own. */
+export function shapedDialect(dialect, shape) {
+    const paged = pagedDialect(dialect, shape);
+    if (shape.repeatedSort !== true)
+        return paged;
+    return {
+        ...paged,
+        params: { ...paged.params, order: "sort" },
+        sortGrammar: "template",
+        sortTemplate: { asc: "ascending", desc: "descending", join: "repeat", term: "{field}_{direction}" },
+    };
+}
+function pagedDialect(dialect, shape) {
+    if (shape.pagination === undefined)
+        return dialect;
+    if (shape.pagination === "page-total")
+        return pageTotal(dialect);
+    if (shape.pagination === "offset-total")
+        return offsetTotal(dialect);
+    return cursorOnly(dialect);
+}
+/* Page numbers and a total: no cursor, no offset, no more-pages flag. */
+function pageTotal(dialect) {
+    const params = { ...dialect.params };
+    const envelope = dialect.envelope === null ? null : { ...dialect.envelope };
+    delete params.cursor;
+    delete params.offset;
+    params.page = params.page ?? "page";
+    if (envelope !== null) {
+        delete envelope.hasMore;
+        delete envelope.nextCursor;
+        envelope.page = envelope.page ?? "page";
+        envelope.total = envelope.total ?? "total";
+    }
+    return { ...dialect, envelope, params };
+}
+/* Rows skipped and taken. The rows and how many there are in all: nothing says whether more pages follow. */
+function offsetTotal(dialect) {
+    const params = { ...dialect.params };
+    delete params.cursor;
+    delete params.page;
+    params.offset = "skip";
+    params.limit = "take";
+    return { ...dialect, envelope: { collection: "data", total: "totalCount" }, params };
+}
+/* A forward cursor and nothing else to page by. */
+function cursorOnly(dialect) {
+    const params = { ...dialect.params };
+    const envelope = dialect.envelope === null ? null : { ...dialect.envelope };
+    delete params.page;
+    delete params.offset;
+    params.cursor = params.cursor ?? "cursor";
+    if (envelope !== null) {
+        delete envelope.hasMore;
+        delete envelope.page;
+        delete envelope.total;
+        envelope.nextCursor = envelope.nextCursor ?? "next_cursor";
+    }
+    return { ...dialect, envelope, params };
+}
+//# sourceMappingURL=dialect.js.map

package/dist/api/reference/shapes/named.d.ts

@@ -0,0 +1,4 @@
+import type { NamedShape } from "./types.ts";
+/** The shape called `name`. Throws on a name no shape has, listing the ones there are. */
+export declare function shapeNamed(name: string): NamedShape;
+//# sourceMappingURL=named.d.ts.map

package/dist/api/reference/shapes/named.js

@@ -0,0 +1,10 @@
+import { SHAPES } from "./catalog.js";
+/** The shape called `name`. Throws on a name no shape has, listing the ones there are. */
+export function shapeNamed(name) {
+    const found = SHAPES.find((candidate) => candidate.name === name);
+    if (found === undefined) {
+        throw new Error(`unknown shape "${name}" — expected one of ${SHAPES.map((s) => s.name).join(", ")}`);
+    }
+    return found;
+}
+//# sourceMappingURL=named.js.map