@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/async.js

@@ -0,0 +1,206 @@
+/**
+ * Async operation support.
+ *
+ * `x-async` means the HTTP response is a receipt, then the API tester polls. A `text/event-stream` body is
+ * the result itself — parse events, do not `JSON.parse` the raw string. Poll only when the
+ * stream ends without a terminal frame and `idFrom` resolved.
+ */
+import { readPath } from "../client/read-path.js";
+import { sseEvents } from "./sse.js";
+import { fillPath } from "./fill-path.js";
+import { leastPolls } from "./wait.js";
+/**
+ * A single PostgREST-style predicate, reused here so `until`/`successWhen` speak the same
+ * language as the filter grammar rather than inventing a second one.
+ */
+export function matchesPredicate(record, expression) {
+    const segments = expression.split(".");
+    if (segments.length < 3)
+        return false;
+    const [field, op] = segments;
+    const raw = segments.slice(2).join(".");
+    const actual = record[field];
+    switch (op) {
+        case "eq":
+            return String(actual) === raw;
+        case "neq":
+            return String(actual) !== raw;
+        case "in":
+            return raw
+                .replace(/^\(|\)$/g, "")
+                .split(",")
+                .map((s) => s.trim())
+                .includes(String(actual));
+        case "is":
+            if (raw === "null")
+                return actual === null || actual === undefined;
+            if (raw === "true")
+                return actual === true;
+            if (raw === "false")
+                return actual === false;
+            return false;
+        default:
+            return false;
+    }
+}
+function recordOf(data) {
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        return null;
+    return data;
+}
+/**
+ * Resolve `idFrom` against a JSON receipt, or against each SSE event's JSON `data` (first hit).
+ */
+export function resolveAsyncId(receipt, idFrom) {
+    const events = sseEvents(receipt);
+    if (events !== null) {
+        for (const ev of events) {
+            const record = recordOf(ev.data);
+            if (record === null)
+                continue;
+            const found = readPath(record, idFrom);
+            if (found !== undefined && found !== null)
+                return found;
+        }
+        return undefined;
+    }
+    return readPath(receipt, idFrom);
+}
+/** Read job id and terminal state from SSE frames. `null` when the body is not a stream. */
+export function inspectStreamAsync(receipt, spec) {
+    const events = sseEvents(receipt);
+    if (events === null)
+        return null;
+    let id;
+    let idRecord = null;
+    let terminal = null;
+    for (const ev of events) {
+        const record = recordOf(ev.data);
+        if (record === null)
+            continue;
+        if (id === undefined && spec.idFrom !== undefined) {
+            const found = readPath(record, spec.idFrom);
+            if (found !== undefined && found !== null) {
+                id = found;
+                idRecord = record;
+            }
+        }
+        const named = ev.event === "complete" || ev.event === "error";
+        const untilHit = spec.until !== undefined && matchesPredicate(record, spec.until);
+        if (named || untilHit)
+            terminal = record;
+    }
+    return { events, id, idRecord, terminal };
+}
+/** The caller's scope, plus the job id the receipt names bound to whichever poll-path parameter is unresolved. */
+function pollScopeOf(spec, receipt, scope) {
+    const pollScope = { ...scope };
+    if (spec.idFrom === undefined)
+        return pollScope;
+    const id = resolveAsyncId(receipt, spec.idFrom);
+    if (id === undefined || id === null)
+        return pollScope;
+    const parameters = (spec.poll.match(/\{[^}]+\}/g) ?? []).map((parameter) => parameter.slice(1, -1));
+    const unbound = parameters.find((name) => pollScope[name] === undefined);
+    pollScope[unbound ?? spec.idFrom.replace(/^\$\./, "")] = String(id);
+    return pollScope;
+}
+/** The poll's method and path template: spelled `"GET /path"`, or the operation `poll` names. */
+function pollRoute(input) {
+    const { spec } = input;
+    const named = spec.poll.includes("/") ? undefined : input.operation?.(spec.poll);
+    if (named !== undefined)
+        return { method: named.method.toUpperCase(), template: named.path };
+    const [method, template = spec.poll] = spec.poll.split(" ");
+    return { method, template };
+}
+async function pollOnce(input, method, path) {
+    return input.client.request(method, path, { as: { principal: input.principal, via: input.start } });
+}
+function terminalOutcome(spec, record, run) {
+    const polled = {
+        elapsedMs: performance.now() - run.began,
+        exchanges: run.exchanges,
+        polls: run.polls,
+        terminal: record,
+        timedOut: false,
+    };
+    return spec.successWhen === undefined || matchesPredicate(record, spec.successWhen)
+        ? { ...polled, state: "terminal", succeeded: true }
+        : { ...polled, state: "terminal", succeeded: false, unmet: spec.successWhen };
+}
+function unfinished(run, state) {
+    return {
+        elapsedMs: performance.now() - run.began,
+        exchanges: run.exchanges,
+        polls: run.polls,
+        state,
+        succeeded: false,
+        terminal: null,
+        timedOut: state === "timed-out",
+    };
+}
+/** How one answer ends polling, or `undefined` while the job is still running. */
+function settledBy(spec, exchange, run) {
+    if (exchange.status < 300) {
+        const body = exchange.responseBody;
+        if (body === null || typeof body !== "object")
+            return undefined;
+        const record = body;
+        const done = spec.until === undefined || matchesPredicate(record, spec.until);
+        return done ? terminalOutcome(spec, record, run) : undefined;
+    }
+    /* The job was served and then was not — a vanished job, and reporting it as a timeout
+     * would name the wrong problem. */
+    return exchange.status === 404 && run.exchanges.some((prior) => prior.status < 300)
+        ? unfinished(run, "vanished")
+        : undefined;
+}
+/**
+ * Polls until `until` matches, the timeout expires, or the poll route stops responding.
+ *
+ * Polling is capped by wall-clock rather than attempt count so a slow backend and a fast one
+ * behave the same way, and the interval is fixed rather than exponential — the point is to
+ * observe when the state changes, not to be gentle with an API the API tester is already hammering.
+ */
+export async function driveAsync(input) {
+    const run = { began: performance.now(), exchanges: [], polls: 0 };
+    const pollScope = pollScopeOf(input.spec, input.receipt, input.scope);
+    const { method, template } = pollRoute(input);
+    let path;
+    try {
+        path = fillPath(template, pollScope);
+    }
+    catch (error) {
+        /* `fillPath` throws only a `SeedError`, naming the parameter it had no value for. */
+        return {
+            elapsedMs: performance.now() - run.began,
+            exchanges: run.exchanges,
+            polls: 0,
+            state: "unfillable",
+            succeeded: false,
+            terminal: null,
+            timedOut: false,
+            unfillable: error.message,
+        };
+    }
+    /* Never "timed out" on one late poll: a slow host can spend the whole budget on it. */
+    const minimum = leastPolls(input.spec.timeoutMs);
+    while (performance.now() - run.began < input.spec.timeoutMs || run.polls < minimum) {
+        const exchange = await pollOnce(input, method, path);
+        run.exchanges.push(exchange);
+        run.polls += 1;
+        const outcome = settledBy(input.spec, exchange, run);
+        if (outcome !== undefined)
+            return outcome;
+        if (performance.now() - run.began >= input.spec.timeoutMs && run.polls >= minimum)
+            break;
+        await sleep(input.spec.pollIntervalMs);
+    }
+    return unfinished(run, "timed-out");
+}
+function sleep(ms) {
+    return new Promise((done) => setTimeout(done, ms));
+}
+export { readPath };
+//# sourceMappingURL=async.js.map

package/dist/api/runtime/baseline.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Findings a team already knows about.
+ *
+ * A backend with open defects fails every run, so a gate built on the exit code cannot tell the
+ * old failures from a new one. A baseline names the known ones: a finding an entry matches is
+ * reported as known and leaves the verdict alone; every other root cause still fails the run; and
+ * an entry that matched nothing is reported as fixed, never as a failure.
+ */
+import { type Finding } from "./finding.ts";
+export interface BaselineEntry {
+    check: string;
+    /** Matches only this entity's findings; absent, every entity's. */
+    entity?: string;
+    /** Matches only findings that judge this operation; absent, the check's findings on any operation. */
+    operationId?: string;
+    /** Why it is known — a ticket, a release note. Shown beside the finding. */
+    reason: string;
+}
+export interface BaselineFile {
+    version: 1;
+    entries: BaselineEntry[];
+}
+/** A baseline file, validated; `where` names it in the error. */
+export declare function parseBaseline(raw: unknown, where: string): BaselineFile;
+/**
+ * Marks every root-cause finding an entry matches as known, in place, and returns the entries that
+ * matched nothing — the defects that are gone.
+ */
+export declare function applyBaseline(findings: readonly Finding[], baseline: BaselineFile): {
+    fixed: BaselineEntry[];
+};
+/** One entry per root-cause finding of a run, deduplicated and sorted, each naming its summary. */
+export declare function baselineFrom(findings: ReadonlyArray<Pick<Finding, "check" | "entity" | "verdict" | "summary" | "operations">>): BaselineFile;
+//# sourceMappingURL=baseline.d.ts.map

package/dist/api/runtime/baseline.js

@@ -0,0 +1,103 @@
+/**
+ * Findings a team already knows about.
+ *
+ * A backend with open defects fails every run, so a gate built on the exit code cannot tell the
+ * old failures from a new one. A baseline names the known ones: a finding an entry matches is
+ * reported as known and leaves the verdict alone; every other root cause still fails the run; and
+ * an entry that matched nothing is reported as fixed, never as a failure.
+ */
+import { didYouMean } from "../errors/suggest.js";
+import { UsageError } from "../errors/usage-error.js";
+import { CHECK_IDS, RUN_FINDING_IDS } from "./check-ids.js";
+import { isRootCause } from "./finding.js";
+const ENTRY_KEYS = /* @__PURE__ */ new Set(["check", "entity", "operationId", "reason"]);
+/** A plain object, read as `T` before any of its values is checked. */
+const isRaw = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/* Every id a finding can name: a registered check's, or the run's own. */
+const FINDING_IDS = /* @__PURE__ */ new Set([...CHECK_IDS, ...RUN_FINDING_IDS]);
+/** A baseline file, validated; `where` names it in the error. */
+export function parseBaseline(raw, where) {
+    if (!isRaw(raw))
+        throw new UsageError(`${where}: a baseline is { "version": 1, "entries": [...] }`);
+    if (raw.version !== 1)
+        throw new UsageError(`${where}: version must be 1`);
+    if (!Array.isArray(raw.entries))
+        throw new UsageError(`${where}: entries must be an array`);
+    const entries = raw.entries.map((entry, index) => {
+        const at = `${where}: entries[${index}]`;
+        if (!isRaw(entry))
+            throw new UsageError(`${at} must be an object`);
+        for (const key of Object.keys(entry)) {
+            if (!ENTRY_KEYS.has(key))
+                throw new UsageError(`${at}.${key} is not a baseline key`);
+        }
+        if (typeof entry.check !== "string" || entry.check === "")
+            throw new UsageError(`${at}.check must name a check`);
+        if (typeof entry.reason !== "string" || entry.reason === "") {
+            throw new UsageError(`${at}.reason must say why the finding is known`);
+        }
+        for (const key of ["entity", "operationId"]) {
+            if (entry[key] !== undefined && typeof entry[key] !== "string") {
+                throw new UsageError(`${at}.${key} must be a string`);
+            }
+        }
+        /* An id no run raises would match nothing and read as fixed: a renamed check, or a typo. */
+        if (!FINDING_IDS.has(entry.check)) {
+            throw new UsageError(`${at}.check "${entry.check}" is no check the API tester runs.${didYouMean(entry.check, FINDING_IDS)}`);
+        }
+        return {
+            check: entry.check,
+            reason: entry.reason,
+            ...(typeof entry.entity === "string" ? { entity: entry.entity } : {}),
+            ...(typeof entry.operationId === "string" ? { operationId: entry.operationId } : {}),
+        };
+    });
+    return { entries, version: 1 };
+}
+function matches(entry, finding) {
+    if (entry.check !== finding.check)
+        return false;
+    if (entry.entity !== undefined && entry.entity !== finding.entity)
+        return false;
+    return entry.operationId === undefined || (finding.operations ?? []).includes(entry.operationId);
+}
+/**
+ * Marks every root-cause finding an entry matches as known, in place, and returns the entries that
+ * matched nothing — the defects that are gone.
+ */
+export function applyBaseline(findings, baseline) {
+    const used = new Set();
+    for (const finding of findings) {
+        if (!isRootCause(finding))
+            continue;
+        const entry = baseline.entries.find((candidate) => matches(candidate, finding));
+        if (entry === undefined)
+            continue;
+        finding.known = { reason: entry.reason };
+        used.add(entry);
+    }
+    return { fixed: baseline.entries.filter((entry) => !used.has(entry)) };
+}
+/** One entry per root-cause finding of a run, deduplicated and sorted, each naming its summary. */
+export function baselineFrom(findings) {
+    const entries = new Map();
+    for (const finding of findings) {
+        if (!isRootCause(finding))
+            continue;
+        const operationId = finding.operations?.[0];
+        const entry = {
+            check: finding.check,
+            entity: finding.entity,
+            reason: finding.summary,
+            ...(operationId === undefined ? {} : { operationId }),
+        };
+        entries.set(`${entry.check}|${entry.entity}|${entry.operationId ?? ""}`, entry);
+    }
+    return {
+        entries: [...entries.values()].sort((a, b) => a.check.localeCompare(b.check) ||
+            a.entity.localeCompare(b.entity) ||
+            (a.operationId ?? "").localeCompare(b.operationId ?? "")),
+        version: 1,
+    };
+}
+//# sourceMappingURL=baseline.js.map

package/dist/api/runtime/blocked-check.d.ts

@@ -0,0 +1,14 @@
+/**
+ * How a run says a check could not complete because the credential it needed is BLOCKED: an
+ * `auth.blocked` finding whose summary names the check. One place writes the summary and one
+ * reads it back, so a reader of the report (the combination fuzz among them) can tell that check
+ * said why it stopped from a check that went quiet.
+ */
+/** The summary of the `auth.blocked` finding a check stopped on. */
+export declare function blockedCheckSummary(check: string): string;
+/** The check an `auth.blocked` finding stopped, or undefined for any other finding. */
+export declare function blockedCheckOf(finding: {
+    check: string;
+    summary: string;
+}): string | undefined;
+//# sourceMappingURL=blocked-check.d.ts.map

package/dist/api/runtime/blocked-check.js

@@ -0,0 +1,18 @@
+/**
+ * How a run says a check could not complete because the credential it needed is BLOCKED: an
+ * `auth.blocked` finding whose summary names the check. One place writes the summary and one
+ * reads it back, so a reader of the report (the combination fuzz among them) can tell that check
+ * said why it stopped from a check that went quiet.
+ */
+const SUFFIX = " needed a credential that is BLOCKED";
+/** The summary of the `auth.blocked` finding a check stopped on. */
+export function blockedCheckSummary(check) {
+    return `${check}${SUFFIX}`;
+}
+/** The check an `auth.blocked` finding stopped, or undefined for any other finding. */
+export function blockedCheckOf(finding) {
+    if (finding.check !== "auth.blocked" || !finding.summary.endsWith(SUFFIX))
+        return undefined;
+    return finding.summary.slice(0, -SUFFIX.length);
+}
+//# sourceMappingURL=blocked-check.js.map

package/dist/api/runtime/body/encode.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Turns a generated field map into the body the document asked for.
+ *
+ * JSON stays a plain object. urlencoded becomes URLSearchParams. Multipart becomes
+ * FormData — file parts are resolved (hook → pool → dummy), never JSON.stringified.
+ */
+import { requestContent } from "../../spec/collection/request.ts";
+import type { OperationModel, SpecModel } from "../../spec/graph/types.ts";
+import type { EncodedBody, EncodeOptions, EncodePlacement } from "./types.ts";
+/** The fields to encode as an operation's body, and where that body is placed. */
+export interface OperationFields extends EncodePlacement {
+    fields: Record<string, unknown>;
+    /** See `EncodeOptions.omit`. */
+    omit?: ReadonlySet<string> | undefined;
+}
+export declare function requestContentOf(op: OperationModel, model: SpecModel): ReturnType<typeof requestContent>;
+export declare function encodeRequest(options: EncodeOptions): Promise<EncodedBody>;
+/** The body `op` documents, built from `fields`; a body-less document leaves `fields` as they are. */
+export declare function encodeForOperation(op: OperationModel, model: SpecModel, { fields, uploads, variant, index, omit }: OperationFields): Promise<EncodedBody>;
+//# sourceMappingURL=encode.d.ts.map

package/dist/api/runtime/body/encode.js

@@ -0,0 +1,50 @@
+/**
+ * Turns a generated field map into the body the document asked for.
+ *
+ * JSON stays a plain object. urlencoded becomes URLSearchParams. Multipart becomes
+ * FormData — file parts are resolved (hook → pool → dummy), never JSON.stringified.
+ */
+import { requestContent } from "../../spec/collection/request.js";
+import { applyResolveInput } from "../input.js";
+import { encodeUrlencoded } from "./form-pairs.js";
+import { encodeMultipart } from "./multipart.js";
+export function requestContentOf(op, model) {
+    const raw = model.rawOperations.get(op.operationId);
+    return raw === undefined ? null : requestContent(raw);
+}
+export async function encodeRequest(options) {
+    const fields = await applyResolveInput(options.fields, options.uploads.resolveInput, options);
+    const next = { ...options, fields };
+    const media = options.mediaType.toLowerCase();
+    if (media.startsWith("multipart/")) {
+        return { body: await encodeMultipart(next), contentType: null };
+    }
+    if (media.includes("x-www-form-urlencoded")) {
+        return {
+            body: encodeUrlencoded(next.fields, next.encoding),
+            contentType: "application/x-www-form-urlencoded",
+        };
+    }
+    return { body: next.fields, contentType: undefined };
+}
+/** The body `op` documents, built from `fields`; a body-less document leaves `fields` as they are. */
+export async function encodeForOperation(op, model, { fields, uploads, variant = "baseline", index = 0, omit }) {
+    const content = requestContentOf(op, model);
+    if (content === null)
+        return { body: fields, contentType: undefined };
+    const options = {
+        fields,
+        index,
+        mediaType: content.mediaType,
+        operationId: op.operationId,
+        schema: content.schema,
+        uploads,
+        variant,
+    };
+    if (content.encoding !== undefined)
+        options.encoding = content.encoding;
+    if (omit !== undefined)
+        options.omit = omit;
+    return encodeRequest(options);
+}
+//# sourceMappingURL=encode.js.map

package/dist/api/runtime/body/form-data.d.ts

@@ -0,0 +1,16 @@
+/** Appending fields and files to a multipart body. */
+import type { UploadFile } from "../../config/types/hooks.ts";
+import type { FieldEncoding } from "./types.ts";
+export declare function appendFile(form: FormData, name: string, file: UploadFile): void;
+export declare function appendFields(form: FormData, fields: Record<string, string | UploadFile>): void;
+/** One field of a form: its name and the value generated for it. */
+export interface FormField {
+    name: string;
+    value: unknown;
+}
+/**
+ * One multipart field: a part per array item, and an object as one JSON part (the OpenAPI
+ * default content type for an object in multipart) unless the encoding says otherwise.
+ */
+export declare function appendValue(form: FormData, { name, value }: FormField, encoding: FieldEncoding | undefined): void;
+//# sourceMappingURL=form-data.d.ts.map

package/dist/api/runtime/body/form-data.js

@@ -0,0 +1,41 @@
+/** Appending fields and files to a multipart body. */
+export function appendFile(form, name, file) {
+    const blob = new File([file.bytes], file.filename, { type: file.mediaType });
+    form.append(name, blob, file.filename);
+}
+export function appendFields(form, fields) {
+    for (const [name, value] of Object.entries(fields)) {
+        if (typeof value === "string")
+            form.append(name, value);
+        else
+            appendFile(form, name, value);
+    }
+}
+function json(item) {
+    return new Blob([JSON.stringify(item)], { type: "application/json" });
+}
+/**
+ * One multipart field: a part per array item, and an object as one JSON part (the OpenAPI
+ * default content type for an object in multipart) unless the encoding says otherwise.
+ */
+export function appendValue(form, { name, value }, encoding) {
+    if (encoding?.contentType?.includes("json") === true) {
+        form.append(name, json(value));
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            if (item !== null && typeof item === "object")
+                form.append(name, json(item));
+            else
+                form.append(name, String(item));
+        }
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        form.append(name, json(value));
+        return;
+    }
+    form.append(name, String(value));
+}
+//# sourceMappingURL=form-data.js.map

package/dist/api/runtime/body/form-pairs.d.ts

@@ -0,0 +1,13 @@
+/** Form fields as the key/value pairs a urlencoded body sends. */
+import type { FieldEncoding } from "./types.ts";
+/**
+ * One form field as the key/value pairs the operation's `encoding` says it becomes.
+ *
+ * The OpenAPI default for a form is `style: form, explode: true`: an array repeats its key per
+ * item, an object spreads its properties as keys of their own. `deepObject` writes `name[key]`;
+ * `explode: false` joins with the style's delimiter; a JSON `contentType` sends the value as JSON.
+ * The parameter serializer writes them; the body's encoder encodes them.
+ */
+export declare function formPairs(name: string, value: unknown, encoding: FieldEncoding | undefined): Array<[string, string]>;
+export declare function encodeUrlencoded(fields: Record<string, unknown>, encoding?: Record<string, FieldEncoding>): URLSearchParams;
+//# sourceMappingURL=form-pairs.d.ts.map

package/dist/api/runtime/body/form-pairs.js

@@ -0,0 +1,26 @@
+/** Form fields as the key/value pairs a urlencoded body sends. */
+import { unencodedPairs } from "../../client/param-style.js";
+/**
+ * One form field as the key/value pairs the operation's `encoding` says it becomes.
+ *
+ * The OpenAPI default for a form is `style: form, explode: true`: an array repeats its key per
+ * item, an object spreads its properties as keys of their own. `deepObject` writes `name[key]`;
+ * `explode: false` joins with the style's delimiter; a JSON `contentType` sends the value as JSON.
+ * The parameter serializer writes them; the body's encoder encodes them.
+ */
+export function formPairs(name, value, encoding) {
+    if (value === undefined || value === null)
+        return [];
+    if (encoding?.contentType?.includes("json") === true)
+        return [[name, JSON.stringify(value)]];
+    return unencodedPairs({ ...encoding, name }, value);
+}
+export function encodeUrlencoded(fields, encoding) {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(fields)) {
+        for (const [key, item] of formPairs(name, value, encoding?.[name]))
+            params.append(key, item);
+    }
+    return params;
+}
+//# sourceMappingURL=form-pairs.js.map

package/dist/api/runtime/body/multipart.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A multipart body: file parts are resolved (hook → pool → dummy), never JSON.stringified, and
+ * every other field becomes the part its encoding names.
+ */
+import type { EncodeOptions } from "./types.ts";
+export declare function encodeMultipart(options: EncodeOptions): Promise<FormData>;
+//# sourceMappingURL=multipart.d.ts.map

package/dist/api/runtime/body/multipart.js

@@ -0,0 +1,78 @@
+/**
+ * A multipart body: file parts are resolved (hook → pool → dummy), never JSON.stringified, and
+ * every other field becomes the part its encoding names.
+ */
+import { isFieldOverride, isUploadFile, resolveUploadOverride } from "../upload.js";
+import { appendFields, appendFile, appendValue } from "./form-data.js";
+import { additionalSchema, isFilePart, propertiesOf, requiredOf } from "./schema.js";
+import { fileForPart, filePartNames, overrideIncludesFile, uploadRequest } from "./upload-parts.js";
+/**
+ * The file-typed `additionalProperties` part for the first required field no property sent,
+ * unless the form already holds a file. A required file property was sent as one by then. The
+ * hook was asked for this part with the others: its file is sent, and it is not asked again.
+ */
+async function appendAdditionalFile(form, options, parts) {
+    const additional = additionalSchema(options.schema);
+    if (additional === undefined || !isFilePart(additional, undefined))
+        return;
+    const already = [...form.keys()].some((name) => form.get(name) instanceof File);
+    if (already)
+        return;
+    const name = parts.required.find((item) => !parts.sent.has(item) && options.omit?.has(item) !== true);
+    if (name === undefined)
+        return;
+    const hit = parts.hookHits.get(name);
+    appendFile(form, name, isUploadFile(hit) ? hit : await fileForPart(name, additional, options));
+}
+/** A non-file property's value, when it has one. */
+function appendProperty(form, name, options) {
+    const value = options.fields[name];
+    if (value === undefined || value === null)
+        return;
+    appendValue(form, { name, value }, options.encoding?.[name]);
+}
+export async function encodeMultipart(options) {
+    const form = new FormData();
+    const properties = propertiesOf(options.schema);
+    const required = requiredOf(options.schema);
+    const names = filePartNames(properties, required, options).filter((name) => options.omit?.has(name) !== true);
+    const hookHits = new Map();
+    const overlays = [];
+    for (const name of names) {
+        /* A file the caller names itself (a scenario step's body) is that part; no hook overrides it. */
+        const given = options.fields[name];
+        if (isUploadFile(given)) {
+            hookHits.set(name, given);
+            continue;
+        }
+        /* A file part is a property, or the required field `additionalProperties` types as a file. */
+        const schema = properties[name] ?? additionalSchema(options.schema);
+        const resolved = await resolveUploadOverride(uploadRequest(name, schema, options), options.uploads);
+        hookHits.set(name, resolved);
+        if (isFieldOverride(resolved)) {
+            if (overrideIncludesFile(resolved.fields, names)) {
+                appendFields(form, resolved.fields);
+                return form;
+            }
+            overlays.push(resolved.fields);
+        }
+    }
+    const sent = new Set();
+    for (const [name, schema] of Object.entries(properties)) {
+        sent.add(name);
+        if (!isFilePart(schema, options.encoding?.[name])) {
+            appendProperty(form, name, options);
+            continue;
+        }
+        if (options.omit?.has(name) === true)
+            continue;
+        const hit = hookHits.get(name);
+        const file = isUploadFile(hit) ? hit : await fileForPart(name, schema, options);
+        appendFile(form, name, file);
+    }
+    await appendAdditionalFile(form, options, { hookHits, required, sent });
+    for (const overlay of overlays)
+        appendFields(form, overlay);
+    return form;
+}
+//# sourceMappingURL=multipart.js.map

package/dist/api/runtime/body/schema.d.ts

@@ -0,0 +1,12 @@
+/** What a request schema says about its parts: which are files, and what each file's type is. */
+import type { JsonSchema } from "../../spec/types.ts";
+export declare function isFilePart(schema: unknown, encoding?: {
+    contentType?: string;
+}): boolean;
+export declare function contentMediaTypeOf(schema: JsonSchema, encoding?: {
+    contentType?: string;
+}): string | undefined;
+export declare function propertiesOf(schema: JsonSchema): Record<string, JsonSchema>;
+export declare function requiredOf(schema: JsonSchema): string[];
+export declare function additionalSchema(schema: JsonSchema): JsonSchema | undefined;
+//# sourceMappingURL=schema.d.ts.map