@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/spec/operation-name.js

@@ -0,0 +1,46 @@
+/**
+ * How the API tester names an operation, and how config names one back.
+ *
+ * An operation is named by its `operationId`, or, when the document gives it none, `METHOD /path`
+ * with the method uppercased. Config may write that method in any case, but the path must be one
+ * of the document's path templates exactly, and an operation with an `operationId` answers to that
+ * id alone. `ops`, `allow` and `overlay.operations` all resolve through here, so they cannot
+ * disagree about what a name means.
+ */
+import { isRaw, isRecord } from "../config/types/raw.js";
+import { PATH_ITEM_METHODS } from "./methods.js";
+const METHODS = /* @__PURE__ */ new Set(PATH_ITEM_METHODS);
+/** The name of the operation at `method` and `path`. */
+export function operationName(method, path, operationId) {
+    return operationId ?? `${method.toUpperCase()} ${path}`;
+}
+/** Each operation of a document's `paths`, by name. */
+export function operationSlots(paths) {
+    const slots = new Map();
+    for (const [path, item] of Object.entries(paths)) {
+        if (!isRecord(item))
+            continue;
+        for (const method of PATH_ITEM_METHODS) {
+            const op = item[method];
+            if (!isRaw(op))
+                continue;
+            const id = typeof op.operationId === "string" ? op.operationId : undefined;
+            slots.set(operationName(method, path, id), { item, method });
+        }
+    }
+    return slots;
+}
+/** The operation name in `names` that `ref` refers to, or `undefined` when it refers to none. */
+export function resolveOperationName(ref, names) {
+    if (names.has(ref))
+        return ref;
+    const space = ref.indexOf(" ");
+    if (space < 0)
+        return undefined;
+    const method = ref.slice(0, space).toLowerCase();
+    if (!METHODS.has(method))
+        return undefined;
+    const canonical = operationName(method, ref.slice(space + 1), undefined);
+    return names.has(canonical) ? canonical : undefined;
+}
+//# sourceMappingURL=operation-name.js.map

package/dist/api/spec/overlay.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Patches to a document the tester cannot change, applied from config before anything reads it.
+ *
+ * An operation is addressed as `ops` and `allow` address one: by its `operationId`, or as
+ * `METHOD /path` when the document gives it none. A schema is addressed by its name under
+ * `components.schemas`. Objects merge, arrays replace, and `null` deletes the key, so a patch can
+ * add a tag, fix a constraint or restate a parameter list without copying the rest. A patch that
+ * names nothing is a mistake in the config, and stops the run before it starts; so are two patches
+ * that name one operation (`GET /a` and `get /a`), since neither order is the obvious one.
+ *
+ * Security is the exception to naming: `securitySchemes` may add a scheme the document never
+ * declared, since declaring one is its purpose, and `security` replaces the root requirement.
+ */
+import type { SpecOverlay } from "../config/types/config.ts";
+import type { OpenApiDocument } from "./types.ts";
+export type { SpecOverlay } from "../config/types/config.ts";
+export declare function applyOverlay(doc: OpenApiDocument, overlay: SpecOverlay): OpenApiDocument;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/api/spec/overlay.js

@@ -0,0 +1,72 @@
+/**
+ * Patches to a document the tester cannot change, applied from config before anything reads it.
+ *
+ * An operation is addressed as `ops` and `allow` address one: by its `operationId`, or as
+ * `METHOD /path` when the document gives it none. A schema is addressed by its name under
+ * `components.schemas`. Objects merge, arrays replace, and `null` deletes the key, so a patch can
+ * add a tag, fix a constraint or restate a parameter list without copying the rest. A patch that
+ * names nothing is a mistake in the config, and stops the run before it starts; so are two patches
+ * that name one operation (`GET /a` and `get /a`), since neither order is the obvious one.
+ *
+ * Security is the exception to naming: `securitySchemes` may add a scheme the document never
+ * declared, since declaring one is its purpose, and `security` replaces the root requirement.
+ */
+import { didYouMean } from "../errors/suggest.js";
+import { UsageError } from "../errors/usage-error.js";
+import { operationSlots, resolveOperationName } from "./operation-name.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** `base` with `patch` laid over it: objects merge, arrays and scalars replace, `null` deletes. */
+function merge(base, patch) {
+    if (!isRecord(patch) || !isRecord(base))
+        return structuredClone(patch);
+    const out = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null)
+            delete out[key];
+        else
+            out[key] = merge(base[key], value);
+    }
+    return out;
+}
+export function applyOverlay(doc, overlay) {
+    const out = structuredClone(doc);
+    if (overlay.securitySchemes !== undefined) {
+        const securitySchemes = merge(out.components?.securitySchemes ?? {}, overlay.securitySchemes);
+        out.components = { ...out.components, securitySchemes: securitySchemes };
+    }
+    if (overlay.security !== undefined)
+        out.security = structuredClone(overlay.security);
+    patchOperations(operationSlots((out.paths ?? {})), overlay.operations ?? {});
+    patchSchemas((out.components?.schemas ?? {}), overlay.schemas ?? {});
+    return out;
+}
+/** Each patch merged into the operation its key names, as the document named it before any patch. */
+function patchOperations(slots, patches) {
+    const keyOf = new Map();
+    for (const [key, patch] of Object.entries(patches)) {
+        const name = resolveOperationName(key, slots);
+        if (name === undefined) {
+            throw new UsageError(`overlay.operations "${key}" matches no operation.${didYouMean(key, slots.keys())}`);
+        }
+        const earlier = keyOf.get(name);
+        if (earlier !== undefined) {
+            throw new UsageError(`overlay.operations "${earlier}" and "${key}" name the same operation`);
+        }
+        keyOf.set(name, key);
+        const renamed = patch["operationId"];
+        if (typeof renamed === "string" && renamed !== name && slots.has(renamed)) {
+            throw new UsageError(`overlay.operations "${key}" renames it to "${renamed}", which another operation has`);
+        }
+        const at = slots.get(name);
+        at.item[at.method] = merge(at.item[at.method], patch);
+    }
+}
+function patchSchemas(schemas, patches) {
+    for (const [name, patch] of Object.entries(patches)) {
+        if (!Object.hasOwn(schemas, name)) {
+            throw new UsageError(`overlay.schemas["${name}"] names no schema under components.schemas`);
+        }
+        schemas[name] = merge(schemas[name], patch);
+    }
+}
+//# sourceMappingURL=overlay.js.map

package/dist/api/spec/prepare.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The document as a run sees it: the config's overlay applied, then everything outside `allow`
+ * removed. One function, so `run`, `plan` and `doctor` cannot disagree about what the API tester may call.
+ */
+import type { PrincipalEntry, Recipe } from "../config/types/security.ts";
+import type { Scenario } from "../config/types/steps.ts";
+import { type SpecOverlay } from "./overlay.ts";
+import type { OpenApiDocument } from "./types.ts";
+export interface DocumentConfig {
+    overlay?: SpecOverlay;
+    allow?: readonly string[];
+    /** Recipes and principal overrides: the operations their steps, mints and revokes call must survive `allow`. */
+    security?: Readonly<Record<string, Partial<Recipe>>>;
+    principals?: Readonly<Record<string, PrincipalEntry>>;
+    scenarios?: readonly Scenario[];
+}
+export declare function prepareDocument(raw: OpenApiDocument, config: DocumentConfig, onRemoved?: (removed: string[]) => void): OpenApiDocument;
+//# sourceMappingURL=prepare.d.ts.map

package/dist/api/spec/prepare.js

@@ -0,0 +1,16 @@
+/**
+ * The document as a run sees it: the config's overlay applied, then everything outside `allow`
+ * removed. One function, so `run`, `plan` and `doctor` cannot disagree about what the API tester may call.
+ */
+import { assertAllowedReferences, pruneToAllow } from "./allow.js";
+import { applyOverlay } from "./overlay.js";
+export function prepareDocument(raw, config, onRemoved) {
+    const overlaid = config.overlay === undefined ? raw : applyOverlay(raw, config.overlay);
+    if (config.allow === undefined)
+        return overlaid;
+    const { doc, kept, removed } = pruneToAllow(overlaid, config.allow);
+    assertAllowedReferences(kept, config);
+    onRemoved?.(removed);
+    return doc;
+}
+//# sourceMappingURL=prepare.js.map

package/dist/api/spec/query/catalog-layers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Catalog layers stacked into one: the tag, then the global config, then the entity's. A later
+ * layer replaces a key; the keyed tables (`operatorsByType`, `aliases`, `sort`, `select`) merge.
+ */
+import type { QueryCapabilities } from "../../config/types/query.ts";
+import type { EffectiveQueryCapabilities, MergeTag } from "./effective.ts";
+export declare function overlayCatalog(tag: MergeTag | null, global: QueryCapabilities | undefined, entity: QueryCapabilities | undefined): QueryCapabilities;
+/** Copies every carried key `catalog` sets onto `target`. */
+export declare function assignOptional(target: EffectiveQueryCapabilities, catalog: Partial<QueryCapabilities>): void;
+//# sourceMappingURL=catalog-layers.d.ts.map

package/dist/api/spec/query/catalog-layers.js

@@ -0,0 +1,80 @@
+/**
+ * Catalog layers stacked into one: the tag, then the global config, then the entity's. A later
+ * layer replaces a key; the keyed tables (`operatorsByType`, `aliases`, `sort`, `select`) merge.
+ */
+/** The catalog keys an effective capability map carries over as they are, in their order. */
+const CARRIED = [
+    "operators",
+    "operatorsByType",
+    "identityFilter",
+    "emptyIn",
+    "limitOutOfRange",
+    "maxInValues",
+    "maxFilterConditions",
+    "searchModes",
+    "searchEmpty",
+    "searchCase",
+    "sort",
+    "select",
+    "filterableFrom",
+    "sortableFrom",
+    "searchableFrom",
+    "selectableFrom",
+];
+/** The keys a layer sets, in the order a stacked catalog lists them. */
+const LAYERED = [
+    "operators",
+    "operatorsByType",
+    "aliases",
+    "identityFilter",
+    "emptyIn",
+    "limitOutOfRange",
+    "maxInValues",
+    "maxFilterConditions",
+    "searchModes",
+    "searchEmpty",
+    "searchCase",
+    "sort",
+    "select",
+    "filterableFrom",
+    "sortableFrom",
+    "searchableFrom",
+    "selectableFrom",
+];
+const MERGED = /* @__PURE__ */ new Set(["operatorsByType", "aliases", "sort", "select"]);
+/** The tag's catalog with its flat `defaultOrder` / `stableTiebreak` lifted into `sort`, in place. */
+function tagLayer(tag) {
+    const fromTag = tag?.catalog ?? {};
+    if (tag?.defaultOrder !== undefined || tag?.stableTiebreak !== undefined) {
+        fromTag.sort = {
+            ...fromTag.sort,
+            ...(tag.defaultOrder === undefined ? {} : { defaultOrder: tag.defaultOrder }),
+            ...(tag.stableTiebreak === undefined ? {} : { stableTiebreak: tag.stableTiebreak }),
+        };
+    }
+    return fromTag;
+}
+function stack(out, layer) {
+    for (const key of LAYERED) {
+        const value = layer[key];
+        if (value === undefined)
+            continue;
+        out[key] = MERGED.has(key) ? { ...out[key], ...value } : value;
+    }
+}
+export function overlayCatalog(tag, global, entity) {
+    const out = {};
+    for (const layer of [tagLayer(tag), global, entity])
+        if (layer !== undefined)
+            stack(out, layer);
+    return out;
+}
+/** Copies every carried key `catalog` sets onto `target`. */
+export function assignOptional(target, catalog) {
+    for (const key of CARRIED) {
+        const value = catalog[key];
+        if (value !== undefined)
+            Object.assign(target, { [key]: value });
+    }
+}
+//# sourceMappingURL=catalog-layers.js.map

package/dist/api/spec/query/effective.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Declared query capabilities — the catalog every list check consults.
+ *
+ * The API tester does not own which fields, operators, search modes, or nulls policies an API supports.
+ * Those are declared on `x-query`, in `config.query` / `config.entities`, or harvested.
+ * Missing capability → the check does not apply. New surface is never inferred.
+ */
+import type { FieldType, FilterableField, FilterableFrom, FilterOp, Nulls, QueryCapabilities, SearchMode, SortableField } from "../../config/types/query.ts";
+import type { JsonSchema } from "../types.ts";
+export interface EffectiveFilterField {
+    field: string;
+    type?: FieldType;
+    ops?: FilterOp[];
+}
+export interface EffectiveSortableField {
+    field: string;
+    type?: FieldType;
+    nulls?: Nulls[];
+}
+export interface EffectiveQueryCapabilities {
+    filterable: EffectiveFilterField[];
+    sortable: EffectiveSortableField[];
+    searchable: string[];
+    selectable: string[];
+    operators?: FilterOp[];
+    operatorsByType?: Partial<Record<FieldType, FilterOp[]>>;
+    aliases: Partial<Record<FilterOp, FilterOp>>;
+    identityFilter?: string;
+    emptyIn?: "reject" | "match-none";
+    /** What a page size of 0 or past the maximum gets: refused, or served clamped. Undeclared, either. */
+    limitOutOfRange?: "reject" | "clamp";
+    maxInValues?: number;
+    maxFilterConditions?: number;
+    searchModes?: SearchMode[];
+    searchEmpty?: "ignore" | "match-all" | "reject";
+    searchCase?: "sensitive" | "insensitive";
+    sort?: QueryCapabilities["sort"];
+    select?: QueryCapabilities["select"];
+    filterableFrom?: FilterableFrom;
+    sortableFrom?: FilterableFrom;
+    searchableFrom?: FilterableFrom;
+    selectableFrom?: FilterableFrom;
+    source: "tag" | "config" | "heuristic" | "mixed";
+    hook: boolean;
+}
+export interface MergeTag {
+    filterable: string[];
+    sortable: string[];
+    searchable: string[];
+    selectable: string[];
+    source: "tag" | "heuristic";
+    filterableDeclared?: boolean;
+    sortableDeclared?: boolean;
+    searchableDeclared?: boolean;
+    selectableDeclared?: boolean;
+    filterFields?: FilterableField[];
+    sortableFields?: SortableField[];
+    catalog?: QueryCapabilities;
+    defaultOrder?: string;
+    stableTiebreak?: string;
+}
+export interface MergeInput {
+    tag: MergeTag | null;
+    global?: QueryCapabilities;
+    entity?: QueryCapabilities;
+    itemSchema?: JsonSchema | null;
+}
+//# sourceMappingURL=effective.d.ts.map

package/dist/api/spec/query/effective.js

@@ -0,0 +1,9 @@
+/**
+ * Declared query capabilities — the catalog every list check consults.
+ *
+ * The API tester does not own which fields, operators, search modes, or nulls policies an API supports.
+ * Those are declared on `x-query`, in `config.query` / `config.entities`, or harvested.
+ * Missing capability → the check does not apply. New surface is never inferred.
+ */
+export {};
+//# sourceMappingURL=effective.js.map

package/dist/api/spec/query/field-ops.d.ts

@@ -0,0 +1,10 @@
+/** What one declared field allows: its operators, closed or implicit, its aliases, and its nulls placements. */
+import type { FilterOp, Nulls } from "../../config/types/query.ts";
+import type { EffectiveFilterField, EffectiveQueryCapabilities, EffectiveSortableField } from "./effective.ts";
+export declare function opsForField(field: EffectiveFilterField, caps: EffectiveQueryCapabilities): FilterOp[];
+export declare function opsAreClosed(field: EffectiveFilterField, caps: EffectiveQueryCapabilities): boolean;
+/** The field allows `op` itself, or an alias the capabilities map onto `op`. */
+export declare function fieldAllows(field: EffectiveFilterField, op: FilterOp, caps: EffectiveQueryCapabilities): boolean;
+export declare function anyFieldAllows(caps: EffectiveQueryCapabilities, op: FilterOp): EffectiveFilterField | undefined;
+export declare function fieldAllowsNulls(field: EffectiveSortableField, caps: EffectiveQueryCapabilities, token: Nulls): boolean;
+//# sourceMappingURL=field-ops.d.ts.map

package/dist/api/spec/query/field-ops.js

@@ -0,0 +1,39 @@
+/** What one declared field allows: its operators, closed or implicit, its aliases, and its nulls placements. */
+import { IMPLICIT_OPS, isFilterOp } from "./ops.js";
+export function opsForField(field, caps) {
+    if (field.ops !== undefined)
+        return field.ops;
+    if (field.type !== undefined) {
+        const byType = caps.operatorsByType?.[field.type];
+        if (byType !== undefined)
+            return byType;
+    }
+    if (caps.operators !== undefined)
+        return caps.operators;
+    return [...IMPLICIT_OPS];
+}
+export function opsAreClosed(field, caps) {
+    return (field.ops !== undefined ||
+        (field.type !== undefined && caps.operatorsByType?.[field.type] !== undefined) ||
+        caps.operators !== undefined);
+}
+/** The field allows `op` itself, or an alias the capabilities map onto `op`. */
+export function fieldAllows(field, op, caps) {
+    const ops = opsForField(field, caps);
+    if (ops.includes(op))
+        return true;
+    for (const alias of Object.keys(caps.aliases)) {
+        if (caps.aliases[alias] === op && isFilterOp(alias) && ops.includes(alias))
+            return true;
+    }
+    return false;
+}
+export function anyFieldAllows(caps, op) {
+    return caps.filterable.find((field) => fieldAllows(field, op, caps));
+}
+export function fieldAllowsNulls(field, caps, token) {
+    if (field.nulls?.includes(token) === true)
+        return true;
+    return caps.sort?.nulls?.includes(token) === true;
+}
+//# sourceMappingURL=field-ops.js.map

package/dist/api/spec/query/harvest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Field names a `*From` source read off a live response, added to one axis of the capabilities.
+ * A harvested type is mapped through the source's `typeMap`, or kept when it is already a type.
+ */
+import type { EffectiveQueryCapabilities } from "./effective.ts";
+export type HarvestAxis = "filterable" | "sortable" | "searchable" | "selectable";
+/** What a `*From` source read: field names, their raw types by position, and the axis they extend. */
+export interface Harvest {
+    names: string[];
+    types?: Array<string | undefined>;
+    axis?: HarvestAxis;
+}
+export declare function applyHarvest(caps: EffectiveQueryCapabilities, { names, types, axis }: Harvest): EffectiveQueryCapabilities;
+//# sourceMappingURL=harvest.d.ts.map

package/dist/api/spec/query/harvest.js

@@ -0,0 +1,29 @@
+/**
+ * Field names a `*From` source read off a live response, added to one axis of the capabilities.
+ * A harvested type is mapped through the source's `typeMap`, or kept when it is already a type.
+ */
+import { isFieldType } from "./ops.js";
+import { unionNamed, unionStrings } from "./union.js";
+function mapHarvestType(from, rawType) {
+    if (rawType === undefined)
+        return undefined;
+    return from?.typeMap?.[rawType] ?? (isFieldType(rawType) ? rawType : undefined);
+}
+function typedRow(field, type) {
+    return type === undefined ? { field } : { field, type };
+}
+export function applyHarvest(caps, { names, types = [], axis = "filterable" }) {
+    const extraNames = names.filter((name) => name !== "");
+    if (axis === "searchable")
+        return { ...caps, searchable: unionStrings(caps.searchable, extraNames) };
+    if (axis === "selectable")
+        return { ...caps, selectable: unionStrings(caps.selectable, extraNames) };
+    if (axis === "sortable") {
+        /* A sortable row takes the type at its name's first place among the names. */
+        const extra = extraNames.map((field) => typedRow(field, mapHarvestType(caps.sortableFrom, types[extraNames.indexOf(field)])));
+        return { ...caps, sortable: unionNamed(caps.sortable, extra) };
+    }
+    const extra = extraNames.map((name, index) => typedRow(name, mapHarvestType(caps.filterableFrom, types[index])));
+    return { ...caps, filterable: unionNamed(caps.filterable, extra) };
+}
+//# sourceMappingURL=harvest.js.map

package/dist/api/spec/query/hook.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What a config's capabilities hook returned, laid over the merged capabilities: `null` keeps
+ * them, a list replaces the filterable fields, an object replaces each axis or key it sets.
+ */
+import type { FilterableField, QueryCapabilities } from "../../config/types/query.ts";
+import type { EffectiveQueryCapabilities } from "./effective.ts";
+export declare function applyHook(caps: EffectiveQueryCapabilities, result: FilterableField[] | Partial<QueryCapabilities> | null): EffectiveQueryCapabilities;
+//# sourceMappingURL=hook.d.ts.map

package/dist/api/spec/query/hook.js

@@ -0,0 +1,46 @@
+/**
+ * What a config's capabilities hook returned, laid over the merged capabilities: `null` keeps
+ * them, a list replaces the filterable fields, an object replaces each axis or key it sets.
+ */
+import { assignOptional } from "./catalog-layers.js";
+function toEffectiveFilter(field) {
+    const row = { field: field.field };
+    if (field.type !== undefined)
+        row.type = field.type;
+    if (field.ops !== undefined)
+        row.ops = field.ops;
+    return row;
+}
+function toEffectiveSort(field) {
+    const row = { field: field.field };
+    if (field.type !== undefined)
+        row.type = field.type;
+    if (field.nulls !== undefined)
+        row.nulls = field.nulls;
+    return row;
+}
+function axes(next, result) {
+    if (result.filterable !== undefined)
+        next.filterable = result.filterable.map(toEffectiveFilter);
+    if (result.sortable !== undefined)
+        next.sortable = result.sortable.map(toEffectiveSort);
+    if (result.searchable !== undefined)
+        next.searchable = result.searchable === null ? [] : [...result.searchable];
+    if (result.selectable !== undefined)
+        next.selectable = [...result.selectable];
+}
+export function applyHook(caps, result) {
+    if (result === null)
+        return { ...caps, hook: true };
+    if (Array.isArray(result))
+        return { ...caps, filterable: result.map(toEffectiveFilter), hook: true };
+    const next = { ...caps, hook: true };
+    axes(next, result);
+    assignOptional(next, result);
+    if (result.aliases !== undefined)
+        next.aliases = { ...caps.aliases, ...result.aliases };
+    if (caps.source === "heuristic")
+        next.source = "config";
+    return next;
+}
+//# sourceMappingURL=hook.js.map

package/dist/api/spec/query/infer-type.d.ts

@@ -0,0 +1,6 @@
+/** A field's query type read off its schema, for a declared field that does not state one. */
+import type { FieldType } from "../../config/types/query.ts";
+import type { JsonSchema } from "../types.ts";
+export declare function inferFieldType(schema: JsonSchema | undefined): FieldType | undefined;
+export declare function inferTypesFromSchema(schema: JsonSchema | null | undefined): Map<string, FieldType>;
+//# sourceMappingURL=infer-type.d.ts.map

package/dist/api/spec/query/infer-type.js

@@ -0,0 +1,34 @@
+/** A field's query type read off its schema, for a declared field that does not state one. */
+import { scalarKinds } from "../schema.js";
+export function inferFieldType(schema) {
+    if (schema === undefined)
+        return undefined;
+    if (Array.isArray(schema.enum) && schema.enum.length > 0)
+        return "enum";
+    const format = typeof schema.format === "string" ? schema.format : "";
+    if (format === "date" || format === "date-time")
+        return "date";
+    if (schema.type === "array")
+        return "array";
+    const kinds = scalarKinds(schema);
+    if (kinds === undefined)
+        return undefined;
+    /* An integer filters as a number; a field that admits two kinds has no one type to filter as. */
+    const types = new Set(kinds.map((kind) => (kind === "integer" ? "number" : kind)));
+    return types.size === 1 ? [...types][0] : undefined;
+}
+export function inferTypesFromSchema(schema) {
+    const out = new Map();
+    const props = schema?.properties;
+    if (props === null || props === undefined || typeof props !== "object")
+        return out;
+    for (const [name, raw] of Object.entries(props)) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        const type = inferFieldType(raw);
+        if (type !== undefined)
+            out.set(name, type);
+    }
+    return out;
+}
+//# sourceMappingURL=infer-type.js.map

package/dist/api/spec/query/json-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `$`, dots, `[n]`, `[*]`, and `[?(@.key==value)]`.
+ * Used by `*From` harvest. Not a full JSONPath implementation.
+ */
+export declare function readJsonPathList(body: unknown, path: string): unknown[];
+//# sourceMappingURL=json-path.d.ts.map

package/dist/api/spec/query/json-path.js

@@ -0,0 +1,87 @@
+/**
+ * `$`, dots, `[n]`, `[*]`, and `[?(@.key==value)]`.
+ * Used by `*From` harvest. Not a full JSONPath implementation.
+ */
+const FILTER = /^\?\(@\.([A-Za-z_][\w]*)==(true|false|null|"[^"]*"|'[^']*'|[^\s)]+)\)$/;
+function parseJsonPathLiteral(raw) {
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    if (raw === "null")
+        return null;
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+        return raw.slice(1, -1);
+    }
+    /* The pattern never captures an empty literal, so a numeric one is never `""` read as 0. */
+    if (!Number.isNaN(Number(raw)))
+        return Number(raw);
+    return raw;
+}
+function applyJsonPathFilter(node, token) {
+    const match = FILTER.exec(token);
+    if (match === null || !Array.isArray(node))
+        return undefined;
+    /* Both groups are required by the pattern. */
+    const key = match[1];
+    const expected = parseJsonPathLiteral(match[2]);
+    return node.filter((item) => {
+        if (item === null || typeof item !== "object")
+            return false;
+        return item[key] === expected;
+    });
+}
+function tokenizeJsonPath(path) {
+    const out = [];
+    let buf = "";
+    for (let i = 0; i < path.length; i++) {
+        const ch = path[i];
+        if (ch === ".") {
+            if (buf !== "")
+                out.push(buf);
+            buf = "";
+            continue;
+        }
+        if (ch === "[") {
+            if (buf !== "")
+                out.push(buf);
+            buf = "";
+            const end = path.indexOf("]", i);
+            if (end === -1) {
+                out.push(path.slice(i));
+                return out;
+            }
+            out.push(path.slice(i + 1, end));
+            i = end;
+            continue;
+        }
+        buf += ch;
+    }
+    if (buf !== "")
+        out.push(buf);
+    return out;
+}
+/** The values one token reaches from one node, `undefined` among them where a key is absent. */
+function step(node, token) {
+    if (token === "*")
+        return Array.isArray(node) ? node : [];
+    const filtered = applyJsonPathFilter(node, token);
+    if (filtered !== undefined)
+        return filtered;
+    if (node === null || typeof node !== "object")
+        return [];
+    if (Array.isArray(node))
+        return /^\d+$/.test(token) ? [node[Number(token)]] : [];
+    return [node[token]];
+}
+export function readJsonPathList(body, path) {
+    const trimmed = path.replace(/^\$\.?/, "");
+    if (trimmed === "")
+        return body === undefined ? [] : [body];
+    let nodes = [body];
+    for (const token of tokenizeJsonPath(trimmed)) {
+        nodes = nodes.flatMap((node) => step(node, token)).filter((value) => value !== undefined);
+    }
+    return nodes;
+}
+//# sourceMappingURL=json-path.js.map

package/dist/api/spec/query/merge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * One list endpoint's effective capabilities: the `x-query` tag, the global config and the
+ * entity's config merged per axis. A declared axis is never widened by a guess; an axis nobody
+ * declared falls back to the heuristic reading of the tag.
+ */
+import type { EffectiveQueryCapabilities, MergeInput } from "./effective.ts";
+export declare function emptyCapabilities(): EffectiveQueryCapabilities;
+export declare function mergeQueryCapabilities(input: MergeInput): EffectiveQueryCapabilities;
+//# sourceMappingURL=merge.d.ts.map