@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/spec/collection/request.js

@@ -0,0 +1,67 @@
+/** The request body an operation takes: which media type the API tester sends, and its schema. */
+import { asSchema, effective } from "./effective.js";
+/* An object, or a reference the API tester cannot see into: either has properties of its own. */
+function objectLike(schema) {
+    return schema !== null && (schema.type === "object" || schema.properties !== undefined || schema.$ref !== undefined);
+}
+/**
+ * Whether a urlencoded form can carry the body. Under the default `style: form, explode: true` an
+ * object property spreads its keys among its siblings', and an array of objects has no form at all:
+ * either one is lost unless its `encoding` writes it as JSON, or the object as a `deepObject`.
+ */
+function formCarries(media) {
+    const properties = asSchema(effective(asSchema(media?.schema))?.properties) ?? {};
+    return Object.entries(properties).every(([name, raw]) => {
+        const encoding = media?.encoding?.[name];
+        if (encoding?.contentType?.includes("json") === true)
+            return true;
+        const property = effective(asSchema(raw));
+        if (property?.type === "array")
+            return !objectLike(effective(asSchema(property.items)));
+        return !objectLike(property) || encoding?.style === "deepObject";
+    });
+}
+function mediaRank(mediaType, media, hasJson) {
+    if (mediaType.startsWith("multipart/"))
+        return 0;
+    if (mediaType.includes("x-www-form-urlencoded"))
+        return hasJson && !formCarries(media) ? 3 : 1;
+    if (mediaType.includes("json"))
+        return 2;
+    return 4;
+}
+/**
+ * The request body the API tester sends: `preferred` when the operation documents it, else the best-ranked
+ * one. Prefers multipart, then urlencoded, then JSON, then the first listed type: file ops often
+ * document both JSON and a form, and the form is the real contract. A form that cannot carry the
+ * body (`formCarries`) gives way to JSON documented beside it.
+ */
+export function requestContent(op, preferred) {
+    const content = op.requestBody?.content;
+    if (content === undefined)
+        return null;
+    const keys = Object.keys(content);
+    if (keys.length === 0)
+        return null;
+    const hasJson = keys.some((key) => key.includes("json"));
+    const rank = (key) => mediaRank(key, content[key], hasJson);
+    /* `keys` is not empty, so a media type is always picked. */
+    const mediaType = preferred !== undefined && keys.includes(preferred)
+        ? preferred
+        : [...keys].sort((a, b) => rank(a) - rank(b) || keys.indexOf(a) - keys.indexOf(b))[0];
+    /* A media type written with no body (`application/json:` in YAML) is null. */
+    const media = content[mediaType];
+    const picked = { mediaType, schema: media?.schema ?? {} };
+    if (media?.encoding !== undefined)
+        picked.encoding = media.encoding;
+    return picked;
+}
+export function hasRequestBody(op) {
+    const content = op.requestBody?.content;
+    return content !== undefined && Object.keys(content).length > 0;
+}
+export function requestSchema(op) {
+    const picked = requestContent(op);
+    return picked === null ? null : picked.schema;
+}
+//# sourceMappingURL=request.js.map

package/dist/api/spec/collection/responses.d.ts

@@ -0,0 +1,6 @@
+/** What an operation's documented success responses say: the JSON schema it answers with, and whether it streams. */
+import type { OperationObject, JsonSchema } from "../types.ts";
+export declare function successSchema(op: OperationObject): JsonSchema | null;
+/** True when a success response lists `text/event-stream`. That media type is the stream tag. */
+export declare function documentsEventStream(op: OperationObject): boolean;
+//# sourceMappingURL=responses.d.ts.map

package/dist/api/spec/collection/responses.js

@@ -0,0 +1,32 @@
+/** What an operation's documented success responses say: the JSON schema it answers with, and whether it streams. */
+export function successSchema(op) {
+    const responses = op.responses ?? {};
+    for (const code of ["200", "201", "202", "2XX", "default"]) {
+        const content = responses[code]?.content;
+        if (content === undefined)
+            continue;
+        for (const [mediaType, media] of Object.entries(content)) {
+            if (!mediaType.includes("json"))
+                continue;
+            if (media.schema !== undefined)
+                return media.schema;
+        }
+    }
+    return null;
+}
+const isSuccess = (code) => code === "2XX" || code === "default" || /^2\d\d$/.test(code);
+/** True when a success response lists `text/event-stream`. That media type is the stream tag. */
+export function documentsEventStream(op) {
+    const responses = op.responses ?? {};
+    for (const [code, response] of Object.entries(responses)) {
+        if (!isSuccess(code))
+            continue;
+        const content = response?.content;
+        if (content === undefined)
+            continue;
+        if (Object.keys(content).some((mediaType) => mediaType.includes("text/event-stream")))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=responses.js.map

package/dist/api/spec/collection/shape.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Derives collection shape from the response schema rather than guessing at wrapper key names.
+ *
+ * Hardcoding `["data","items","results","records"]` — as prior art does — returns null on any
+ * API whose envelopes are named after the resource (`{ tables: [...] }`), which silently
+ * disables every list-based assertion. The schema already states the answer; read it.
+ */
+import type { JsonSchema } from "../types.ts";
+export interface CollectionShape {
+    /** Property holding the array, or null when the response *is* the array. */
+    key: string | null;
+    itemSchema: JsonSchema | null;
+    /** Sibling properties of the collection — `count`, `hasMore`, `nextCursor`, `page`. */
+    envelopeKeys: string[];
+    /**
+     * Where each row keeps its record, one property name per step: `["document"]` for
+     * `$.hits[*].document`. Empty when the row is the record.
+     */
+    within: string[];
+    pagination: {
+        countKey?: string;
+        hasMoreKey?: string;
+        cursorKey?: string;
+        pageKey?: string;
+        limitKey?: string;
+    };
+}
+/**
+ * The list a response holds, read from its schema. A declared `recordPath` names the rows and
+ * where each keeps its record; without one the rows are inferred, and a body with substantive
+ * siblings beside its array is read as a document that holds a list, not a list. A declaration
+ * is the author saying otherwise: Typesense answers `request_params` beside its `hits`.
+ */
+export declare function deriveCollectionShape(raw: JsonSchema | null, recordPath?: string | null): CollectionShape | null;
+/**
+ * The arrays of objects a list response could hold its rows in, when there is more than one: a
+ * document that leaves this open needs `x-entity.recordPath` on the list. Empty otherwise.
+ */
+export declare function ambiguousRows(raw: JsonSchema | null): string[];
+/** Where a list's `recordPath` says its records are: the rows' top-level key, and each record within a row. */
+export interface Rows {
+    key: string;
+    within: string[];
+}
+/** The rows a list's `recordPath` names (`$.data`, `$.data[*]`, `$.hits[*].document`), or null. */
+export declare function rowsOf(recordPath: string | null): Rows | null;
+//# sourceMappingURL=shape.d.ts.map

package/dist/api/spec/collection/shape.js

@@ -0,0 +1,123 @@
+/**
+ * Derives collection shape from the response schema rather than guessing at wrapper key names.
+ *
+ * Hardcoding `["data","items","results","records"]` — as prior art does — returns null on any
+ * API whose envelopes are named after the resource (`{ tables: [...] }`), which silently
+ * disables every list-based assertion. The schema already states the answer; read it.
+ */
+import { asSchema, effective } from "./effective.js";
+/** The sibling names each pagination key is read from, in the order the shape lists them. */
+const PAGINATION_KEYS = [
+    ["countKey", ["count", "total", "totalCount", "total_count", "totalItems"]],
+    ["hasMoreKey", ["hasMore", "has_more", "hasNextPage", "more"]],
+    ["cursorKey", ["nextCursor", "next_cursor", "cursor", "next", "endCursor"]],
+    ["pageKey", ["page", "pageNumber", "page_number", "offset"]],
+    ["limitKey", ["limit", "perPage", "per_page", "pageSize", "page_size"]],
+];
+/** Array properties that are an obvious sidecar, never the rows. */
+const SIDECAR = /^(errors?|warnings?|messages?|meta|links)$/i;
+/** Object properties an envelope may carry beside its rows. */
+const PAGE_SIDECAR = /^(errors?|warnings?|messages?|meta|links|filters?|facets)$/i;
+const holdsObjects = (item) => item?.type === "object" || item?.properties !== undefined;
+/** The schema's properties, each read as the instance sees it; `null` when it has none. */
+function propertyEntries(schema) {
+    const props = schema.properties;
+    if (props === null || typeof props !== "object")
+        return null;
+    return Object.entries(props).map(([name, value]) => [name, effective(asSchema(value))]);
+}
+/**
+ * With several array properties, the collection is the one whose items are objects and whose
+ * name is not an obvious sidecar (`errors`, `warnings`, `meta`). Two arrays of objects (rows
+ * beside a `fields` sidecar) leave the rows unnamed: taking the first compares the wrong records,
+ * so the list's `x-entity.recordPath` names them.
+ */
+function chooseRows(entries, rowsKey) {
+    const candidates = entries
+        .filter(([name, value]) => value?.type === "array" && !SIDECAR.test(name))
+        .map(([name, value]) => ({ item: effective(asSchema(value.items)), name }))
+        .filter((c) => c.item !== null);
+    if (rowsKey !== undefined)
+        return candidates.find((c) => c.name === rowsKey);
+    const objectRows = candidates.filter((c) => holdsObjects(c.item));
+    return objectRows.length > 1 ? undefined : (objectRows[0] ?? candidates[0]);
+}
+function paginationOf(siblingNames) {
+    const pagination = {};
+    for (const [key, names] of PAGINATION_KEYS) {
+        const found = siblingNames.find((name) => names.includes(name));
+        if (found !== undefined)
+            pagination[key] = found;
+    }
+    return pagination;
+}
+/**
+ * An envelope's other fields describe the page — counts, cursors, a meta or links sidecar. A body
+ * with its own nested objects beside the array (an OpenAPI document's `info` and `paths` beside
+ * `servers`) is a document that happens to hold a list, not a list.
+ */
+function hasSubstantiveSibling(entries, chosen) {
+    return entries.some(([name, value]) => name !== chosen && !PAGE_SIDECAR.test(name) && (holdsObjects(value) || value?.additionalProperties !== undefined));
+}
+/* The schema `within` names inside a row's, or null where the row's schema does not say. */
+function schemaWithin(row, within) {
+    let schema = row;
+    for (const name of within)
+        schema = effective(asSchema(asSchema(schema?.properties)?.[name]));
+    return schema;
+}
+/**
+ * The list a response holds, read from its schema. A declared `recordPath` names the rows and
+ * where each keeps its record; without one the rows are inferred, and a body with substantive
+ * siblings beside its array is read as a document that holds a list, not a list. A declaration
+ * is the author saying otherwise: Typesense answers `request_params` beside its `hits`.
+ */
+export function deriveCollectionShape(raw, recordPath = null) {
+    const schema = effective(raw);
+    if (schema === null)
+        return null;
+    if (schema.type === "array") {
+        return { envelopeKeys: [], itemSchema: effective(asSchema(schema.items)), key: null, pagination: {}, within: [] };
+    }
+    const entries = propertyEntries(schema);
+    if (entries === null)
+        return null;
+    const declared = rowsOf(recordPath);
+    const chosen = chooseRows(entries, declared?.key);
+    if (chosen === undefined || (declared === null && hasSubstantiveSibling(entries, chosen.name)))
+        return null;
+    const siblingNames = entries.map(([name]) => name).filter((name) => name !== chosen.name);
+    const within = declared?.within ?? [];
+    return {
+        envelopeKeys: siblingNames,
+        itemSchema: schemaWithin(chosen.item, within),
+        key: chosen.name,
+        pagination: paginationOf(siblingNames),
+        within,
+    };
+}
+/**
+ * The arrays of objects a list response could hold its rows in, when there is more than one: a
+ * document that leaves this open needs `x-entity.recordPath` on the list. Empty otherwise.
+ */
+export function ambiguousRows(raw) {
+    const schema = effective(raw);
+    if (schema === null || schema.type === "array")
+        return [];
+    const entries = propertyEntries(schema) ?? [];
+    const rows = entries
+        .filter(([name, value]) => value?.type === "array" && !SIDECAR.test(name) && holdsObjects(effective(asSchema(value.items))))
+        .map(([name]) => name);
+    return rows.length > 1 ? rows : [];
+}
+/* `$.data`, `$.data[*]`, or `$.hits[*].document` and deeper: rows under one top-level key. A
+ * name is anything but a separator, a bracket or a space. */
+const ROWS_PATH = /^\$\.([^.[\]\s]+)(?:\[\*\]((?:\.[^.[\]\s]+)*))?$/;
+/** The rows a list's `recordPath` names (`$.data`, `$.data[*]`, `$.hits[*].document`), or null. */
+export function rowsOf(recordPath) {
+    const match = recordPath === null ? null : ROWS_PATH.exec(recordPath);
+    if (match === null)
+        return null;
+    return { key: match[1], within: (match[2] ?? "").split(".").filter(Boolean) };
+}
+//# sourceMappingURL=shape.js.map

package/dist/api/spec/configured-model.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The model a run plans against: the document read with config's parameter and envelope names, then
+ * config's grammars laid over it. Config is the operator's own statement, so a name it cannot use stops the
+ * run instead of testing something they did not ask for.
+ */
+import type { QueryEnvelopeNames, QueryParamNames } from "../config/types/query.ts";
+import { type GrammarConfig } from "./grammar-overrides.ts";
+import type { SpecModel } from "./graph/types.ts";
+import type { OpenApiDocument } from "./types.ts";
+export type ModelConfig = GrammarConfig & {
+    query?: {
+        params?: QueryParamNames;
+        envelope?: QueryEnvelopeNames;
+    };
+};
+export declare function buildConfiguredModel(doc: OpenApiDocument, config: ModelConfig): SpecModel;
+/**
+ * Stops on a config name no model of the run declares. Config is run-wide, read against the primary
+ * document and each origin's, so a name only an origin declares is not a typo.
+ */
+export declare function assertQueryNamesDeclared(config: ModelConfig, models: readonly SpecModel[]): void;
+//# sourceMappingURL=configured-model.d.ts.map

package/dist/api/spec/configured-model.js

@@ -0,0 +1,58 @@
+/**
+ * The model a run plans against: the document read with config's parameter and envelope names, then
+ * config's grammars laid over it. Config is the operator's own statement, so a name it cannot use stops the
+ * run instead of testing something they did not ask for.
+ */
+import { UsageError } from "../errors/usage-error.js";
+import { isQueryEnvelopeRole, QUERY_ENVELOPE_ROLES } from "./conventions/envelope-names.js";
+import { isQueryParamRole, QUERY_PARAM_ROLES } from "./conventions/query-params.js";
+import { applyGrammarOverrides } from "./grammar-overrides.js";
+import { buildModel } from "./graph/build.js";
+export function buildConfiguredModel(doc, config) {
+    const params = readNames(config.query?.params, PARAMS);
+    const envelope = readNames(config.query?.envelope, ENVELOPE);
+    const model = buildModel(doc, { queryEnvelope: envelope, queryParams: params });
+    applyGrammarOverrides(model, config);
+    return model;
+}
+/**
+ * Stops on a config name no model of the run declares. Config is run-wide, read against the primary
+ * document and each origin's, so a name only an origin declares is not a typo.
+ */
+export function assertQueryNamesDeclared(config, models) {
+    const operations = models.flatMap((model) => model.operations);
+    for (const [role, name] of Object.entries(config.query?.params ?? {})) {
+        if (!operations.some((op) => op.queryParamNames.includes(name))) {
+            throw new UsageError(`query.params.${role} names "${name}", which no operation declares`);
+        }
+    }
+    for (const [role, name] of Object.entries(config.query?.envelope ?? {})) {
+        if (!operations.some((op) => op.collection?.envelopeKeys.includes(name) === true)) {
+            throw new UsageError(`query.envelope.${role} names "${name}", which no list response declares`);
+        }
+    }
+}
+const PARAMS = { isRole: isQueryParamRole, key: "params", names: "a parameter name", roles: QUERY_PARAM_ROLES };
+const ENVELOPE = {
+    isRole: isQueryEnvelopeRole,
+    key: "envelope",
+    names: "a field name",
+    roles: QUERY_ENVELOPE_ROLES,
+};
+/* A config file is untyped until read: every key a role, every value a name. */
+function readNames(raw, { isRole, key, names, roles }) {
+    if (raw === undefined)
+        return undefined;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new UsageError(`query.${key} must be an object of role names`);
+    }
+    for (const [role, name] of Object.entries(raw)) {
+        if (!isRole(role)) {
+            throw new UsageError(`query.${key} names an unknown role "${role}"; the roles are ${roles.join(", ")}`);
+        }
+        if (typeof name !== "string" || name === "")
+            throw new UsageError(`query.${key}.${role} must be ${names}`);
+    }
+    return raw;
+}
+//# sourceMappingURL=configured-model.js.map

package/dist/api/spec/conventions/derive.d.ts

@@ -0,0 +1,26 @@
+import type { CollectionShape } from "../collection/shape.ts";
+import type { ParameterObject } from "../types.ts";
+import type { QueryEnvelopeNames, QueryParamNames } from "../../config/types/query.ts";
+import type { QueryConventions } from "./types.ts";
+/**
+ * What the document and config say beside the parameters: the `x-query` grammars, the parameter
+ * each role is sent in, the field each paging fact is read from, and the response headers.
+ */
+export interface ConventionSources {
+    declared?: {
+        grammar?: unknown;
+        sortGrammar?: unknown;
+    } | undefined;
+    /** The parameter each role is sent in, where a name outranks the aliases. */
+    params?: QueryParamNames | undefined;
+    /** The response field each paging fact is read from, where a name outranks the aliases. */
+    envelope?: QueryEnvelopeNames | undefined;
+    /** Told when a named parameter or envelope field is not one the operation declares. */
+    onUnmatched?: (message: string) => void;
+    /** Told when the filter grammar could not be recognized and nothing declared it. */
+    onGuess?: (message: string) => void;
+    /** Response headers the success response declares, by name. */
+    responseHeaders?: readonly string[];
+}
+export declare function deriveQueryConventions(parameters: readonly ParameterObject[], collection: CollectionShape | null, sources?: ConventionSources): QueryConventions;
+//# sourceMappingURL=derive.d.ts.map

package/dist/api/spec/conventions/derive.js

@@ -0,0 +1,125 @@
+import { parseFilterGrammar } from "../render/filter-parse.js";
+import { parseSortGrammar } from "../render/sort-parse.js";
+import { SORT_PRESETS } from "../render/sort.js";
+import { inferGrammar, inferSelectGrammar, inferSortGrammar } from "./infer.js";
+import { publicRole, toNamedRoles } from "./query-params.js";
+import { parameterNamed, resolveRoles } from "./roles.js";
+/* Where each envelope role is read from the collection's pagination. */
+const ENVELOPE = [
+    ["total", "countKey"],
+    ["hasMore", "hasMoreKey"],
+    ["nextCursor", "cursorKey"],
+    ["page", "pageKey"],
+    ["limit", "limitKey"],
+];
+export function deriveQueryConventions(parameters, collection, sources = {}) {
+    const query = parameters.filter((p) => p.in === "query");
+    const resolved = resolveRoles(query, toNamedRoles(sources.params ?? {}));
+    reportUnmatched(resolved.unmatched, sources.onUnmatched);
+    const found = resolved.roles;
+    const conventions = {
+        envelope: envelopeOf(collection, sources),
+        ...filterConventions(parameterNamed(query, found.filter), sources),
+        selectGrammar: inferSelectGrammar(parameterNamed(query, found.select)),
+        ...declaredSort(sources.declared?.sortGrammar, parameterNamed(query, found.order)),
+    };
+    const link = (sources.responseHeaders ?? []).find((name) => name.toLowerCase() === "link");
+    if (link !== undefined)
+        conventions.linkHeader = link;
+    return Object.assign(conventions, roles(found));
+}
+function reportUnmatched(unmatched, tell) {
+    for (const { name, role } of unmatched) {
+        const named = publicRole(role);
+        tell?.(`params.${named} names "${name}", which the operation does not declare; ` +
+            `the API tester finds the ${named} parameter by its aliases`);
+    }
+}
+function filterConventions(filterParam, sources) {
+    const declared = sources.declared?.grammar;
+    const stated = statedGrammar(declared);
+    if (stated !== undefined)
+        return stated;
+    const inferred = inferGrammar(filterParam);
+    /* A single free-text `filter` parameter almost never means equality-per-field; it means a grammar
+     * The API tester could not recognize. Writing `?name=value` anyway would send parameters the document never
+     * declared and read the shrug that comes back as a defect, so no filter term is written at all. */
+    const unrecognized = inferred === "equality" && filterParam?.schema?.type === "string";
+    if (unrecognized && declared === undefined)
+        sources.onGuess?.(unrecognizedMessage(filterParam.name));
+    return { grammar: unrecognized ? "unrecognized" : inferred };
+}
+/** The filter grammar `x-query` names or describes as a template, when it does so readably. */
+function statedGrammar(declared) {
+    if (declared === "postgrest" || declared === "colon" || declared === "equality") {
+        return { grammar: declared, grammarDeclared: true };
+    }
+    /* An object that cannot be read is a gap `x-query`'s validation records; the API tester infers instead. */
+    const template = typeof declared === "object" ? parseFilterGrammar(declared) : null;
+    return template?.ok === true
+        ? { grammar: "template", filterGrammar: template.spec, grammarDeclared: true }
+        : undefined;
+}
+function unrecognizedMessage(name) {
+    return (`parameter "${name}" takes a filter expression whose grammar could not be ` +
+        "recognized from its description or examples, so the API tester writes no filter terms for it. " +
+        'Declare it with x-query: { grammar: "postgrest" | "colon" | "equality" }, or describe it as a ' +
+        'template: { grammar: { term: "{conj}_{field}_{op}_{value}", ops: { eq: "eq" }, … } }');
+}
+/** A declared sort grammar, or the inferred one when none was declared or it cannot be read. */
+function declaredSort(declared, order) {
+    if (typeof declared === "string" && Object.hasOwn(SORT_PRESETS, declared)) {
+        return { sortDeclared: true, sortGrammar: declared };
+    }
+    /* An object that cannot be read is a gap `x-query`'s validation records; the API tester infers instead. */
+    const parsed = typeof declared === "object" ? parseSortGrammar(declared) : null;
+    if (parsed?.ok === true)
+        return { sortDeclared: true, sortGrammar: "template", sortSpec: parsed.spec };
+    return { sortGrammar: inferSortGrammar(order) };
+}
+/** The parameter playing each role, for the roles the endpoint has, in a fixed order. */
+function roles(found) {
+    const ordered = {
+        filter: found.filter,
+        order: found.order,
+        select: found.select,
+        search: found.search,
+        searchMode: found.searchMode,
+        cursor: found.cursor,
+        limit: found.limit,
+        page: found.page,
+        offset: found.offset,
+    };
+    return Object.fromEntries(Object.entries(ordered).filter(([, name]) => name !== undefined));
+}
+/*
+ * The envelope is already derived from the 200 schema when the shape was resolved — reuse it
+ * rather than matching on literal key names a second time. A named field the envelope holds wins,
+ * and no alias keeps a field a name claimed for another fact.
+ */
+function envelopeOf(collection, sources) {
+    const named = namedEnvelope(collection, sources);
+    const claimed = new Set(Object.values(named));
+    const envelope = {};
+    for (const [role, key] of ENVELOPE) {
+        const alias = collection?.pagination[key];
+        const name = named[role] ?? (alias !== undefined && !claimed.has(alias) ? alias : undefined);
+        if (name !== undefined)
+            envelope[role] = name;
+    }
+    return envelope;
+}
+/* The names the envelope holds; each other name is told and its fact read by its aliases. */
+function namedEnvelope(collection, sources) {
+    const held = {};
+    for (const [role, name] of Object.entries(sources.envelope ?? {})) {
+        if (collection?.envelopeKeys.includes(name) === true)
+            held[role] = name;
+        else {
+            sources.onUnmatched?.(`envelope.${role} names "${name}", which the response envelope does not declare; ` +
+                `the API tester finds the ${role} field by its aliases`);
+        }
+    }
+    return held;
+}
+//# sourceMappingURL=derive.js.map

package/dist/api/spec/conventions/envelope-names.d.ts

@@ -0,0 +1,21 @@
+/** The response fields `x-query.envelope` or config `query.envelope` read each paging fact from. */
+import type { QueryEnvelopeNames, QueryEnvelopeRole } from "../../config/types/query.ts";
+/** The role names an `envelope` object may hold, in the order a message lists them. */
+export declare const QUERY_ENVELOPE_ROLES: readonly QueryEnvelopeRole[];
+export declare function isQueryEnvelopeRole(key: string): key is QueryEnvelopeRole;
+/**
+ * The known roles of a raw `envelope` object that name a field. `x-query`'s validation records a gap
+ * for everything else; this keeps what can be used.
+ */
+export declare function readEnvelopeNames(raw: unknown): QueryEnvelopeNames | undefined;
+/**
+ * The names a list response uses: its `x-query.envelope`, with config's laid over them. A config name
+ * the response's envelope does not hold is not applied to it; config is run-wide, and the response
+ * it was written for holds it.
+ */
+export declare function mergeEnvelopeNames(sources: {
+    tag: unknown;
+    config?: QueryEnvelopeNames | undefined;
+    declared: readonly string[];
+}): QueryEnvelopeNames;
+//# sourceMappingURL=envelope-names.d.ts.map

package/dist/api/spec/conventions/envelope-names.js

@@ -0,0 +1,25 @@
+/** The response fields `x-query.envelope` or config `query.envelope` read each paging fact from. */
+/** The role names an `envelope` object may hold, in the order a message lists them. */
+export const QUERY_ENVELOPE_ROLES = ["total", "hasMore", "nextCursor"];
+export function isQueryEnvelopeRole(key) {
+    return QUERY_ENVELOPE_ROLES.includes(key);
+}
+/**
+ * The known roles of a raw `envelope` object that name a field. `x-query`'s validation records a gap
+ * for everything else; this keeps what can be used.
+ */
+export function readEnvelopeNames(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    return Object.fromEntries(Object.entries(raw).filter(([role, name]) => isQueryEnvelopeRole(role) && typeof name === "string" && name !== ""));
+}
+/**
+ * The names a list response uses: its `x-query.envelope`, with config's laid over them. A config name
+ * the response's envelope does not hold is not applied to it; config is run-wide, and the response
+ * it was written for holds it.
+ */
+export function mergeEnvelopeNames(sources) {
+    const applied = Object.entries(sources.config ?? {}).filter(([, name]) => sources.declared.includes(name));
+    return { ...readEnvelopeNames(sources.tag), ...Object.fromEntries(applied) };
+}
+//# sourceMappingURL=envelope-names.js.map

package/dist/api/spec/conventions/filter.d.ts

@@ -0,0 +1,31 @@
+/** Filter terms, written in whichever grammar the endpoint speaks. */
+import type { FilterGrammarSpec, FilterPredicate, FilterQuery } from "../render/filter-types.ts";
+import type { FilterOp } from "../../config/types/query.ts";
+import type { QueryConventions } from "./types.ts";
+/** One equality predicate: `field` equals `value`. */
+export interface Equality {
+    field: string;
+    value: string;
+}
+/** How this endpoint's filter terms are spelled: its declared template, or its named grammar's preset. */
+export declare function filterSpec(conventions: QueryConventions): FilterGrammarSpec;
+/** Whether this grammar can emit `op`. */
+export declare function canWriteFilterOp(conventions: QueryConventions, op: FilterOp): boolean;
+/** Renders one filter term in whichever grammar the endpoint speaks. */
+export declare function filterTerm(conventions: QueryConventions, predicate: FilterPredicate): Record<string, string> | null;
+/** The equality term `filterTerm` wraps in its parameter, as bare text. */
+export declare function filterFragment(conventions: QueryConventions, field: string, value: string): string | null;
+/**
+ * A conjunction of two equality predicates, in whatever grammar the endpoint speaks.
+ *
+ * Per-field equality ANDs implicitly — two query parameters together already mean "both must
+ * hold". A raw filter expression has no such shortcut: postgrest groups with `and(...)`, the colon
+ * grammar joins with a comma, and a template says which of those, or a repeated parameter, it uses.
+ */
+export declare function andTerm(conventions: QueryConventions, a: Equality, b: Equality): FilterQuery | null;
+/**
+ * A disjunction of two equality predicates; `null` for a grammar that has no way to ask for
+ * "either" rather than "both".
+ */
+export declare function orTerm(conventions: QueryConventions, a: Equality, b: Equality): FilterQuery | null;
+//# sourceMappingURL=filter.d.ts.map

package/dist/api/spec/conventions/filter.js

@@ -0,0 +1,51 @@
+/** Filter terms, written in whichever grammar the endpoint speaks. */
+import { canWriteOp, renderTerm } from "../render/filter-term.js";
+import { FILTER_PRESETS } from "../render/filter-presets.js";
+import { renderAnd, renderOr } from "../render/filter-combine.js";
+/** How this endpoint's filter terms are spelled: its declared template, or its named grammar's preset. */
+export function filterSpec(conventions) {
+    if (conventions.grammar === "template") {
+        if (conventions.filterGrammar === undefined)
+            throw new Error("a template grammar without its template");
+        return conventions.filterGrammar;
+    }
+    return FILTER_PRESETS[conventions.grammar];
+}
+/** Whether this grammar can emit `op`. */
+export function canWriteFilterOp(conventions, op) {
+    return canWriteOp(filterSpec(conventions), op);
+}
+/** Renders one filter term in whichever grammar the endpoint speaks. */
+export function filterTerm(conventions, predicate) {
+    return renderTerm(filterSpec(conventions), conventions.filter, predicate);
+}
+/** The equality term `filterTerm` wraps in its parameter, as bare text. */
+export function filterFragment(conventions, field, value) {
+    const term = filterTerm(conventions, { field, op: "eq", value });
+    /* A rendered term is exactly one parameter and its text. */
+    return term === null ? null : Object.values(term)[0];
+}
+/**
+ * A conjunction of two equality predicates, in whatever grammar the endpoint speaks.
+ *
+ * Per-field equality ANDs implicitly — two query parameters together already mean "both must
+ * hold". A raw filter expression has no such shortcut: postgrest groups with `and(...)`, the colon
+ * grammar joins with a comma, and a template says which of those, or a repeated parameter, it uses.
+ */
+export function andTerm(conventions, a, b) {
+    return renderAnd(filterSpec(conventions), conventions.filter, [
+        { field: a.field, op: "eq", value: a.value },
+        { field: b.field, op: "eq", value: b.value },
+    ]);
+}
+/**
+ * A disjunction of two equality predicates; `null` for a grammar that has no way to ask for
+ * "either" rather than "both".
+ */
+export function orTerm(conventions, a, b) {
+    return renderOr(filterSpec(conventions), conventions.filter, [
+        { field: a.field, op: "eq", value: a.value },
+        { field: b.field, op: "eq", value: b.value },
+    ]);
+}
+//# sourceMappingURL=filter.js.map