@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/reference/http/validation.js

@@ -0,0 +1,188 @@
+/** What a write body may carry, coerced to the types the schema declares. */
+import { writableFields } from "../model/fields.js";
+import { HttpError } from "./errors.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/i;
+const invalid = (message) => new HttpError(400, "invalid_input", message);
+export function validateBody(body, rules) {
+    const { entity, mode, defects } = rules;
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw invalid("request body must be a JSON object");
+    }
+    const input = body;
+    const allowed = new Map(writableFields(entity, mode === "create" ? "create" : "update").map((f) => [f.name, f]));
+    for (const key of Object.keys(input))
+        admit(key, allowed, rules);
+    /* A create, and a replacing update, must carry every required field. */
+    if (mode !== "update" && !defects.has("REQUIRED_NOT_VALIDATED") && rules.lenient !== true) {
+        const missing = [...allowed.values()].find((field) => field.required === true && input[field.name] === undefined);
+        if (missing !== undefined)
+            throw invalid(`field "${missing.name}" is required`);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        const field = allowed.get(key);
+        if (field === undefined)
+            continue;
+        const kept = rules.lenient === true ? parsed(field, value, defects) : { value: coerceField(field, value, defects) };
+        if (kept !== undefined)
+            out[key] = kept.value;
+    }
+    return out;
+}
+/* The value as the field takes it, or undefined when it refuses it: a lenient update drops that one. */
+function parsed(field, value, defects) {
+    try {
+        return { value: coerceField(field, value, defects) };
+    }
+    catch {
+        return undefined;
+    }
+}
+/* A key the body may carry: writable, or — under the defect — immutable or generated too. */
+function admit(key, allowed, { entity, defects }) {
+    if (allowed.has(key))
+        return;
+    const known = entity.fields.find((f) => f.name === key);
+    if (known === undefined)
+        throw invalid(`unknown field "${key}"`);
+    if (known.immutable !== true && known.generated !== true)
+        throw invalid(`unknown field "${key}"`);
+    if (!defects.has("IMMUTABLE_WRITABLE"))
+        throw invalid(`field "${key}" is not writable`);
+    allowed.set(key, known);
+}
+export function coerceField(field, value, defects) {
+    if (value === null) {
+        if (field.nullable !== true)
+            throw invalid(`field "${field.name}" is not nullable`);
+        return null;
+    }
+    switch (field.type) {
+        case "integer":
+        case "number":
+            return coerceNumber(field, value);
+        case "array":
+            return coerceArray(field, value);
+        case "object":
+            return coerceObject(field, value);
+        case "boolean":
+            if (typeof value !== "boolean")
+                throw invalid(`field "${field.name}" must be a boolean`);
+            return value;
+        default:
+            return coerceString(field, value, defects);
+    }
+}
+function coerceNumber(field, value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw invalid(`field "${field.name}" must be a number`);
+    if (field.type === "integer" && !Number.isInteger(value))
+        throw invalid(`field "${field.name}" must be an integer`);
+    if ((field.minimum !== undefined && value < field.minimum) ||
+        (field.maximum !== undefined && value > field.maximum) ||
+        (field.multipleOf !== undefined && !Number.isInteger(value / field.multipleOf))) {
+        throw invalid(`field "${field.name}" is out of range`);
+    }
+    return value;
+}
+function coerceArray(field, value) {
+    const allowed = field.items ?? [];
+    if (!Array.isArray(value) ||
+        value.length > 5 ||
+        value.some((element) => typeof element !== "string" || !allowed.includes(element))) {
+        throw invalid(`field "${field.name}" must be a list of ${allowed.join(", ")}`);
+    }
+    return [...value];
+}
+function coerceObject(field, value) {
+    if (field.ref !== "Point" || !isPoint(value))
+        throw invalid(`field "${field.name}" must be a ${field.ref ?? "object"}`);
+    return { x: value.x, y: value.y };
+}
+function coerceString(field, value, defects) {
+    if (typeof value !== "string")
+        throw invalid(`field "${field.name}" must be a string`);
+    if (field.maxLength !== undefined && value.length > field.maxLength && !defects.has("MAXLENGTH_NOT_VALIDATED")) {
+        throw invalid(`field "${field.name}" exceeds maxLength`);
+    }
+    if (field.enum !== undefined && !field.enum.includes(value) && !defects.has("ENUM_NOT_VALIDATED")) {
+        throw invalid(`field "${field.name}" must be one of ${field.enum.join(", ")}`);
+    }
+    if (field.const !== undefined && value !== field.const)
+        throw invalid(`field "${field.name}" must be "${field.const}"`);
+    assertFormat(field, value);
+    assertPatterns(field, value);
+    return defects.has("STRING_PAYLOAD_MANGLED") ? value.replace(/[^\x20-\x7E]/g, "").trim() : value;
+}
+/* The minimum, in code points, and every pattern the field declares. */
+function assertPatterns(field, value) {
+    if (field.minLength !== undefined && [...value].length < field.minLength) {
+        throw invalid(`field "${field.name}" is shorter than ${field.minLength}`);
+    }
+    for (const pattern of field.patterns ?? []) {
+        if (!new RegExp(pattern, "u").test(value))
+            throw invalid(`field "${field.name}" must match ${pattern}`);
+    }
+}
+function assertFormat(field, value) {
+    if (field.format === "date-time" && (!DATE_TIME.test(value) || Number.isNaN(Date.parse(value)))) {
+        throw invalid(`field "${field.name}" must be an RFC 3339 date-time`);
+    }
+    if (field.format === "uuid" && !UUID.test(value))
+        throw invalid(`field "${field.name}" must be a UUID`);
+}
+/** The value a field takes when nobody supplied one. */
+export function emptyValue(field) {
+    if (field.nullable === true)
+        return null;
+    if (field.type === "array")
+        return [];
+    if (field.type === "boolean")
+        return false;
+    if (field.type === "integer" || field.type === "number")
+        return 0;
+    return field.enum?.[0] ?? "";
+}
+function isPoint(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const { x, y } = value;
+    return Object.keys(value).length === 2 && Number.isInteger(x) && Number.isInteger(y);
+}
+/** A path identifier as the type its entity declares: a malformed one is a 400, as real frameworks answer before a handler runs. */
+export function pathId(entities, param, raw) {
+    const owner = entities.find((entity) => entity.itemParam === param);
+    const identity = owner?.fields.find((field) => field.name === owner.identity);
+    if (identity?.type === "integer") {
+        if (!/^[1-9]\d{0,14}$/.test(raw))
+            throw invalid(`"${raw}" is not a valid ${param}`);
+        return Number(raw);
+    }
+    if (identity?.format === "uuid" && !UUID.test(raw))
+        throw invalid(`"${raw}" is not a valid ${param}`);
+    return raw;
+}
+/**
+ * Reads a form-encoded body into the types the schema declares.
+ *
+ * A form carries only strings, so a correct backend coerces each field by its declared type —
+ * exactly what it would have to do in production.
+ */
+export function formFields(entity, text) {
+    const out = {};
+    for (const [key, raw] of new URLSearchParams(text)) {
+        const field = entity.fields.find((candidate) => candidate.name === key);
+        /* A form repeats the key once per element. */
+        out[key] = field?.type === "array" ? [...(out[key] ?? []), raw] : formValue(field, raw);
+    }
+    return out;
+}
+function formValue(field, raw) {
+    if (field?.type === "integer" || field?.type === "number")
+        return raw.trim() === "" ? raw : Number(raw);
+    if (field?.type === "boolean")
+        return raw === "true" ? true : raw === "false" ? false : raw;
+    return raw;
+}
+//# sourceMappingURL=validation.js.map

package/dist/api/reference/http/wire.d.ts

@@ -0,0 +1,28 @@
+/** A request and its answer as the reference sees them, whichever transport carried them. */
+export type Json = Record<string, unknown>;
+export interface ReferenceRequest {
+    /** Upper-cased. */
+    method: string;
+    /** Below the base path, when the shape mounts one. */
+    url: URL;
+    /** Lower-cased names. */
+    headers: Readonly<Record<string, string>>;
+    /** The body as text; read once, however often asked. */
+    text: () => Promise<string>;
+}
+export interface ReferenceResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export declare function respond(status: number, body: unknown, extraHeaders?: Record<string, string>): ReferenceResponse;
+/** A 204: nothing in the body, so no content type either. */
+export declare function noContent(): ReferenceResponse;
+/** What a request carries beside its method and URL: its headers, and how to read its body. */
+export interface ReferenceInit {
+    headers: Readonly<Record<string, string>>;
+    read: () => Promise<string>;
+}
+/** A request whose body is read at most once. */
+export declare function referenceRequest(method: string, url: URL, { headers, read }: ReferenceInit): ReferenceRequest;
+//# sourceMappingURL=wire.d.ts.map

package/dist/api/reference/http/wire.js

@@ -0,0 +1,23 @@
+/** A request and its answer as the reference sees them, whichever transport carried them. */
+export function respond(status, body, extraHeaders = {}) {
+    const payload = JSON.stringify(body);
+    return {
+        body: payload,
+        headers: {
+            "content-length": String(Buffer.byteLength(payload)),
+            "content-type": "application/json",
+            ...extraHeaders,
+        },
+        status,
+    };
+}
+/** A 204: nothing in the body, so no content type either. */
+export function noContent() {
+    return { body: "", headers: {}, status: 204 };
+}
+/** A request whose body is read at most once. */
+export function referenceRequest(method, url, { headers, read }) {
+    let body;
+    return { headers, method: method.toUpperCase(), text: () => (body ??= read()), url };
+}
+//# sourceMappingURL=wire.js.map

package/dist/api/reference/listing/axes.d.ts

@@ -0,0 +1,14 @@
+import type { DefectSet } from "../defects/defect-set.ts";
+import type { ListingRequest } from "./types.ts";
+/**
+ * Which axes a request combines. Each FILTER_DROPPED_WHEN_* defect keeps the filter while it is
+ * alone and drops it once its named combination is present — the combination is the bug.
+ */
+export interface Axes {
+    sorted: boolean;
+    selected: boolean;
+    searched: boolean;
+}
+export declare function axesOf(request: ListingRequest): Axes;
+export declare function filterDropped(defects: DefectSet, axes: Axes): boolean;
+//# sourceMappingURL=axes.d.ts.map

package/dist/api/reference/listing/axes.js

@@ -0,0 +1,21 @@
+/* Each defect and the axes that, all present, drop the filter. */
+const FILTER_DROPS = [
+    ["FILTER_DROPPED_WHEN_SORTED_SEARCHED_AND_SELECTED", ["sorted", "searched", "selected"]],
+    ["FILTER_DROPPED_WHEN_SORTED", ["sorted"]],
+    ["FILTER_DROPPED_WHEN_SELECTED", ["selected"]],
+    ["FILTER_DROPPED_WHEN_SEARCHED", ["searched"]],
+    ["FILTER_DROPPED_WHEN_SORTED_AND_SELECTED", ["sorted", "selected"]],
+    ["FILTER_DROPPED_WHEN_SORTED_AND_SEARCHED", ["sorted", "searched"]],
+    ["FILTER_DROPPED_WHEN_SEARCHED_AND_SELECTED", ["searched", "selected"]],
+];
+export function axesOf(request) {
+    return {
+        searched: request.q !== undefined && request.q.trim() !== "",
+        selected: request.select !== undefined && request.select !== "" && request.select !== "*",
+        sorted: request.order !== undefined && request.order !== "",
+    };
+}
+export function filterDropped(defects, axes) {
+    return FILTER_DROPS.some(([name, needs]) => defects.has(name) && needs.every((axis) => axes[axis]));
+}
+//# sourceMappingURL=axes.js.map

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

@@ -0,0 +1,16 @@
+import type { ParseContext } from "../query/conventions.ts";
+import type { FilterNode, OrderTerm } from "../query-types.ts";
+import type { Axes } from "./axes.ts";
+import type { ListingRequest } from "./types.ts";
+/** The order a listing's rows take, and what that order changes about which rows there are. */
+export interface ListingOrder {
+    /** The order with its tiebreaks: a total order, unless the sort is unstable. */
+    fullOrder: OrderTerm[];
+    /** Under SORT_DESC_DROPS_NULLS: a not-null test per descending key. */
+    dropNulls: FilterNode[];
+    /** Ties come back in an arbitrary order: UNSTABLE_SORT. */
+    unstable: boolean;
+}
+/** The listing's order. Throws `SqlError` for an order a correct backend refuses. */
+export declare function listingOrder(request: ListingRequest, ctx: ParseContext, axes: Axes): ListingOrder;
+//# sourceMappingURL=order.d.ts.map

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

@@ -0,0 +1,37 @@
+import { parseOrder } from "../query/order.js";
+/** The listing's order. Throws `SqlError` for an order a correct backend refuses. */
+export function listingOrder(request, ctx, axes) {
+    const { defects, entity } = ctx;
+    const order = chosenOrder(request, ctx, axes);
+    const dropNulls = defects.has("SORT_DESC_DROPS_NULLS")
+        ? order.filter((term) => term.descending).map((term) => ({ field: term.field, kind: "isnull", negate: true }))
+        : [];
+    /* A sort without a total order is not a sort: equal keys may come back in any order, and
+     * paging over it silently loses rows. The identity tiebreak is what makes paging sound. */
+    const unstable = defects.has("UNSTABLE_SORT");
+    return { dropNulls, fullOrder: unstable ? order : withTiebreaks(order, entity, defects), unstable };
+}
+/* The order asked for, or the documented default where none is asked for or the asked one is dropped. */
+function chosenOrder(request, ctx, axes) {
+    const { defects, entity } = ctx;
+    /* Without an order the documented default applies — unless the backend forgets it. */
+    const named = request.order === undefined || request.order === "" ? undefined : request.order;
+    const fallback = defects.has("DEFAULT_ORDER_IGNORED") ? undefined : entity.defaultOrder;
+    const implicit = parseOrder(fallback ?? "", ctx, true);
+    const requested = named === undefined ? implicit : parseOrder(named, ctx);
+    const orderDropped = defects.has("ORDER_DROPPED_WHEN_SELECTED") && axes.selected && named !== undefined;
+    return defects.has("ORDER_IGNORED") || orderDropped ? implicit : requested;
+}
+function withTiebreaks(order, entity, defects) {
+    /* Ties broken by a text field instead of the declared tiebreak: still a total order, so pages
+     * are sound, but not the one the document promises. */
+    const tiebreak = defects.has("TIEBREAK_NOT_APPLIED")
+        ? entity.fields.find((field) => field.searchable === true && field.name !== entity.identity)?.name
+        : undefined;
+    return [
+        ...order,
+        ...(tiebreak === undefined ? [] : [{ asText: true, descending: false, field: tiebreak, nullsFirst: false }]),
+        { asText: false, descending: false, field: entity.identity, nullsFirst: false },
+    ];
+}
+//# sourceMappingURL=order.js.map

package/dist/api/reference/listing/params.d.ts

@@ -0,0 +1,19 @@
+import type { ParseContext } from "../query/conventions.ts";
+import type { ListingOptions, ListingRequest } from "./types.ts";
+/** The paging parameters, validated against the ranges the document publishes. */
+export interface Paging {
+    /** The page size served: the request's, the default, or a ceiling's. */
+    servedLimit: number;
+    page: number | undefined;
+    offset: number | undefined;
+}
+/** The integers a paging parameter may take: from `min`, up to `max` when there is one. */
+export interface IntegerRange {
+    min: number;
+    max?: number | undefined;
+}
+export declare function integerParam(raw: string | undefined, name: string, { min, max }: IntegerRange): number | undefined;
+export declare function nearestLimit(raw: string | undefined, max: number | undefined): number | undefined;
+/** Reads the limit, then the page, then the offset; throws `SqlError` for the first out of range. */
+export declare function pagingOf(ctx: Pick<ParseContext, "defects" | "entity">, request: ListingRequest, options: ListingOptions): Paging;
+//# sourceMappingURL=params.d.ts.map

package/dist/api/reference/listing/params.js

@@ -0,0 +1,31 @@
+import { SqlError } from "../store-api.js";
+export function integerParam(raw, name, { min, max }) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (raw.trim() === "" || !Number.isInteger(value) || value < min || (max !== undefined && value > max)) {
+        const range = max === undefined ? `>= ${min}` : `between ${min} and ${max}`;
+        throw new SqlError("invalid_paging", `query parameter "${name}" must be an integer ${range}`);
+    }
+    return value;
+}
+/* LIMIT_OUT_OF_RANGE_SERVED: a page size outside the published range is quietly moved inside it. */
+export function nearestLimit(raw, max) {
+    const value = integerParam(raw, "limit", { min: Number.MIN_SAFE_INTEGER });
+    return value === undefined ? undefined : Math.min(Math.max(value, 1), max ?? Number.POSITIVE_INFINITY);
+}
+/** Reads the limit, then the page, then the offset; throws `SqlError` for the first out of range. */
+export function pagingOf(ctx, request, options) {
+    const { defects, entity } = ctx;
+    const ceiling = defects.has("LIMIT_EXCEEDS_MAX") || options.clampLimit !== undefined ? undefined : entity.maxLimit;
+    const requestedLimit = (defects.has("LIMIT_OUT_OF_RANGE_SERVED")
+        ? nearestLimit(request.limit, ceiling)
+        : integerParam(request.limit, "limit", { max: ceiling, min: 1 })) ?? entity.defaultLimit;
+    const servedLimit = defects.has("LIMIT_EXCEEDS_MAX")
+        ? requestedLimit
+        : Math.min(requestedLimit, options.clampLimit ?? entity.maxLimit);
+    const page = integerParam(request.page, "page", { min: 1 });
+    const offset = integerParam(request.offset, "offset", { min: 0 });
+    return { offset, page, servedLimit };
+}
+//# sourceMappingURL=params.js.map

package/dist/api/reference/listing/predicate.d.ts

@@ -0,0 +1,22 @@
+import type { ParseContext } from "../query/conventions.ts";
+import type { FilterNode } from "../query-types.ts";
+import { type Axes } from "./axes.ts";
+import type { ListingOptions, ListingRequest } from "./types.ts";
+/** Which rows a listing holds, as the parts its queries combine. */
+export interface ListingPredicate {
+    axes: Axes;
+    /** The tenant and parent constraints from the path. */
+    scope: FilterNode[];
+    /** The scope as the listing applies it: a defect drops it once a filter is present. */
+    scoped: FilterNode[];
+    filter: FilterNode | null;
+    search: FilterNode | null;
+    /** Hides soft-deleted rows; `null` when nothing hides them. */
+    tombstones: FilterNode | null;
+}
+/**
+ * The listing's predicate. Validates the select, then the filter, then the search, and throws
+ * `SqlError` for the first a correct backend refuses.
+ */
+export declare function listingPredicate(request: ListingRequest, options: ListingOptions, ctx: ParseContext): ListingPredicate;
+//# sourceMappingURL=predicate.d.ts.map

package/dist/api/reference/listing/predicate.js

@@ -0,0 +1,56 @@
+import { SEARCH_MODES } from "../query/conventions.js";
+import { parseFilter } from "../query/filter.js";
+import { parseSearch } from "../query/search.js";
+import { fieldsIn } from "../query/tree.js";
+import { SqlError } from "../store-api.js";
+import { axesOf, filterDropped } from "./axes.js";
+import { checkSelect } from "./select.js";
+/**
+ * The listing's predicate. Validates the select, then the filter, then the search, and throws
+ * `SqlError` for the first a correct backend refuses.
+ */
+export function listingPredicate(request, options, ctx) {
+    const { defects, entity } = ctx;
+    const scope = scopeTerms(entity, options.scope);
+    const axes = axesOf(request);
+    checkSelect(request.select, entity, defects);
+    const filter = request.filter === undefined || request.filter === "" || filterDropped(defects, axes)
+        ? null
+        : parseFilter(request.filter, ctx);
+    const search = searchOf(request, ctx, axes);
+    const soft = entity.softDeleteField;
+    /* Tombstones are hidden unless the caller asked about them by name. */
+    const tombstones = soft === undefined || defects.has("SOFT_DELETE_LEAK") || (filter !== null && fieldsIn(filter).includes(soft))
+        ? null
+        : { field: soft, kind: "isnull", negate: false };
+    /* The tenant predicate is applied to the plain listing but dropped once a filter is present,
+     * which is how a filter turns into an authorization bypass. */
+    const scoped = defects.has("TENANT_LEAK_VIA_FILTER") && filter !== null ? [] : scope;
+    return { axes, filter, scope, scoped, search, tombstones };
+}
+/* An equality per path constraint the entity has a field for. */
+function scopeTerms(entity, scope) {
+    return Object.entries(scope)
+        .filter(([name]) => entity.fields.some((field) => field.name === name))
+        .map(([field, value]) => ({ asText: false, field, kind: "cmp", nullsMatch: false, op: "eq", value }));
+}
+/* The free-text search, its mode validated first. */
+function searchOf(request, ctx, axes) {
+    const { defects } = ctx;
+    const mode = request.searchMode ?? "contains";
+    if (!SEARCH_MODES.includes(mode)) {
+        throw new SqlError("invalid_search", `search mode "${mode}" is not one of ${SEARCH_MODES.join(", ")}`);
+    }
+    if (mode === "prefix" && defects.has("SEARCH_MODE_REJECTED")) {
+        throw new SqlError("invalid_search", 'search mode "prefix" is not supported');
+    }
+    return request.q === undefined || defects.has("SEARCH_IGNORED") || searchDropped(defects, axes)
+        ? null
+        : parseSearch(request.q, mode, ctx);
+}
+/* Each of these keeps the search while it is alone and drops it once its axis joins. */
+function searchDropped(defects, axes) {
+    return ((defects.has("SEARCH_DROPPED_WHEN_SELECTED") && axes.selected) ||
+        (defects.has("SEARCH_DROPPED_WHEN_SORTED") && axes.sorted));
+}
+//# sourceMappingURL=predicate.js.map

package/dist/api/reference/listing/project.d.ts

@@ -0,0 +1,14 @@
+import type { DefectSet } from "../defects/defect-set.ts";
+import type { EntityDef } from "../model/types.ts";
+import type { Row } from "../store-api.ts";
+import type { ListingOptions } from "./types.ts";
+/** What a projection reads besides the row: the sparse fieldset, and how to load a relation. */
+export interface Projection {
+    select: string | undefined;
+    entity: EntityDef;
+    defects: DefectSet;
+    embed?: ListingOptions["embed"];
+}
+/** The row cut to its sparse fieldset, a nested entry embedding the related record's fields. */
+export declare function project(row: Row, { select, entity, defects, embed }: Projection): Promise<Row>;
+//# sourceMappingURL=project.d.ts.map

package/dist/api/reference/listing/project.js

@@ -0,0 +1,36 @@
+import { NESTED, nestedFields, selectEntries, wholeRow } from "./select.js";
+/** The row cut to its sparse fieldset, a nested entry embedding the related record's fields. */
+export async function project(row, { select, entity, defects, embed }) {
+    if (wholeRow(select))
+        return { ...row };
+    if (defects.has("SELECT_IGNORED"))
+        return { ...row };
+    const out = {};
+    for (const entry of selectEntries(select)) {
+        const nested = NESTED.exec(entry);
+        if (nested !== null) {
+            const name = nested[1];
+            const related = embed === undefined ? null : await embed(name, row);
+            if (related === null) {
+                out[name] = null;
+                continue;
+            }
+            /* The defect embeds the whole related record instead of the fields asked for. */
+            out[name] = defects.has("NESTED_SELECT_IGNORED") ? related : picked(related, nested[2]);
+            continue;
+        }
+        if (!Object.hasOwn(row, entry))
+            continue;
+        if (defects.has("SELECT_FIELD_MISSING") && entry !== entity.identity)
+            continue;
+        out[entry] = row[entry];
+    }
+    return out;
+}
+/* The fields of `related` a nested entry lists, those it holds, in the order listed. */
+function picked(related, list) {
+    return Object.fromEntries(nestedFields(list)
+        .filter((field) => Object.hasOwn(related, field))
+        .map((f) => [f, related[f]]));
+}
+//# sourceMappingURL=project.js.map

package/dist/api/reference/listing/run.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A collection read, end to end, above any store.
+ *
+ * The store answers one question — which rows match, in what order — and everything a listing
+ * adds on top is decided here once: validating the paging parameters, resolving a cursor, cutting
+ * the window, counting, projecting a sparse fieldset. Every defect that corrupts one of those
+ * steps is applied here too, so a broken count or an off-by-one page is the same bug on every
+ * engine rather than three bugs that happen to share a name.
+ */
+import type { DefectSet } from "../defects/defect-set.ts";
+import type { EntityDef } from "../model/types.ts";
+import { type Store } from "../store-api.ts";
+import type { ListingOptions, ListingRequest, ListingResult } from "./types.ts";
+/** One listing to run: the entity, the request in the canonical grammar, the options, the defects. */
+export interface Listing {
+    entity: EntityDef;
+    request: ListingRequest;
+    options: ListingOptions;
+    defects: DefectSet;
+}
+export declare function runListing(store: Store, { entity, request, options, defects }: Listing): Promise<ListingResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/api/reference/listing/run.js

@@ -0,0 +1,88 @@
+/**
+ * A collection read, end to end, above any store.
+ *
+ * The store answers one question — which rows match, in what order — and everything a listing
+ * adds on top is decided here once: validating the paging parameters, resolving a cursor, cutting
+ * the window, counting, projecting a sparse fieldset. Every defect that corrupts one of those
+ * steps is applied here too, so a broken count or an off-by-one page is the same bug on every
+ * engine rather than three bugs that happen to share a name.
+ */
+import { and } from "../query/tree.js";
+import { decodeCursor, encodeCursor } from "../store-api.js";
+import { listingOrder } from "./order.js";
+import { pagingOf } from "./params.js";
+import { listingPredicate } from "./predicate.js";
+import { project } from "./project.js";
+import { cursorOffset, cut, filteredWindow, invert, numberedStart } from "./window.js";
+/*
+ * Every await of a listing is here, in the order the stores are asked: the rows, the empty-result
+ * fallback, the count, the cursor's other collation, the post-paging filter, the projections.
+ * Everything between them is synchronous, so the await sequence is the listing's own.
+ */
+export async function runListing(store, { entity, request, options, defects }) {
+    const ctx = { conventions: options.conventions, defects, entity };
+    const paging = pagingOf(ctx, request, options);
+    const predicate = listingPredicate(request, options, ctx);
+    const { filter, scope, scoped, search, tombstones } = predicate;
+    const { dropNulls, fullOrder, unstable } = listingOrder(request, ctx, predicate.axes);
+    const plan = planner(fullOrder, unstable, options.conventions.collation);
+    /* Paging before filtering: the window is cut from the unfiltered set and the predicate is then
+     * applied to whatever that window held. */
+    const pageBeforeFilter = defects.has("FILTER_AFTER_PAGINATION") && filter !== null;
+    const listingWhere = and(...scoped, tombstones, pageBeforeFilter ? null : filter, search, ...dropNulls);
+    let rows = await store.select(entity, plan(listingWhere));
+    if (fallsBackToAll(defects, rows, predicate))
+        rows = await store.select(entity, plan(and(...scope, tombstones)));
+    const count = defects.has("COUNT_ALWAYS_ZERO")
+        ? 0
+        : defects.has("COUNT_IGNORES_FILTER")
+            ? (await store.select(entity, plan(and(...scope, tombstones)))).length
+            : rows.length;
+    let start;
+    if (request.cursor !== undefined && request.cursor !== "") {
+        const afterId = decodeCursor(request.cursor);
+        /* The boundary must be resolved under exactly the listing's ordering. Under the defect it
+         * is resolved under the other collation, and that position is then used as an offset into
+         * the listing — a boundary the listing never had, so rows are skipped or repeated. */
+        const ordered = defects.has("COLLATION_INCONSISTENT")
+            ? await store.select(entity, plan(listingWhere, invert(options.conventions.collation)))
+            : rows;
+        start = { offset: cursorOffset(ctx, ordered, afterId), page: null };
+    }
+    else
+        start = numberedStart(paging, rows.length, defects);
+    let window = cut(ctx, rows, start, paging.servedLimit);
+    if (pageBeforeFilter) {
+        const matching = await store.select(entity, plan(and(...scoped, tombstones, filter, search)));
+        window = filteredWindow(ctx, window, matching);
+    }
+    const projection = { defects, embed: options.embed, entity, select: request.select };
+    const items = await Promise.all(window
+        .map((row) => (options.transform === undefined ? row : options.transform(row)))
+        .map((row) => project(row, projection)));
+    return listingResult(ctx, { count, items, limit: paging.servedLimit, rows, start, window });
+}
+/* The select plan for a predicate: the listing's order, under its collation unless told another. */
+function planner(order, unstable, listing) {
+    return (where, collation = listing) => ({ collation, order, shuffleTies: unstable, where });
+}
+/* The "no results must mean the query was wrong" guard: an empty filtered set falls back to the
+ * unfiltered listing, which makes an empty result impossible to express. */
+function fallsBackToAll(defects, rows, { filter, search }) {
+    return defects.has("EMPTY_RESULT_RETURNS_ALL") && rows.length === 0 && (filter !== null || search !== null);
+}
+/* What the listing answers: the rows served, the count, and where the page sits among the rest. */
+function listingResult({ defects, entity }, { count, items, limit, rows, start, window }) {
+    const hasMore = defects.has("HASMORE_ALWAYS_FALSE") ? false : start.offset + window.length < rows.length;
+    const last = window.at(-1);
+    return {
+        count,
+        hasMore,
+        items,
+        limit,
+        nextCursor: hasMore && last !== undefined ? encodeCursor(String(last[entity.identity])) : null,
+        offset: start.offset,
+        page: start.page,
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/api/reference/listing/select.d.ts

@@ -0,0 +1,13 @@
+import type { DefectSet } from "../defects/defect-set.ts";
+import type { EntityDef } from "../model/types.ts";
+/** `relation(field,field)` inside a sparse fieldset. Both groups take part in every match. */
+export declare const NESTED: RegExp;
+/** No sparse fieldset at all: every field is served. */
+export declare function wholeRow(select: string | undefined): boolean;
+/** Splits a sparse fieldset on top-level commas, so `id,table(name,status)` is two entries. */
+export declare function selectEntries(select: string): string[];
+/** The fields a nested entry names: `name,status` of `table(name,status)`. */
+export declare function nestedFields(list: string): string[];
+/** Validates a sparse fieldset against the entity before any row is read. */
+export declare function checkSelect(select: string | undefined, entity: EntityDef, defects: DefectSet): void;
+//# sourceMappingURL=select.d.ts.map