typespec-http-zod 0.25.1 → 0.26.0

package/dist/src/lib.d.ts

@@ -92,24 +92,6 @@ export interface EmitterOptions {
      * indistinguishable from one that is empty.
      */
     "key-vocabularies"?: string[];
-    /**
-     * The specifier the generated files import their runtime contract from. Defaults to
-     * `typespec-http-zod/runtime`.
-     *
-     * **This is here because the emitted response arms are annotated, and the annotation earns its
-     * keep.** `schemas.gen.ts` declares what each operation may answer with as
-     * `... satisfies readonly ResponseArm[]`. Measured against the alternative: `as const` needs no
-     * import at all, and catches a wrong `status` - but it is **blind** to a misspelled or omitted
-     * `schema`, because `schema: undefined` is legitimate for a bodyless response. The typo then
-     * produces a valid-looking arm that validates nothing, which is the failure this package exists to
-     * prevent. `satisfies` reports both, at the declaration, naming the key.
-     *
-     * An emitter built on this library points the default at its own runtime, which re-exports these
-     * names; an application that substitutes its own result or context types points it at its own
-     * module and re-declares them. That is also what makes the emitted output loadable from this
-     * package's own tests, where the package name does not resolve.
-     */
-    "runtime-module"?: string;
     /**
      * The command that regenerates these files, written into every banner.
      *
@@ -134,7 +116,6 @@ export interface EmitterOptions {
         "seal-object-schemas"?: boolean;
         "compile-schemas"?: boolean;
         "key-vocabularies"?: string[];
-        "runtime-module"?: string;
         "regenerate-hint"?: string;
     }>;
 }

package/dist/src/lib.js

@@ -14,7 +14,6 @@ export const EmitterOptionsSchema = {
         "seal-object-schemas": { type: "boolean", nullable: true },
         "compile-schemas": { type: "boolean", nullable: true },
         "key-vocabularies": { type: "array", items: { type: "string" }, nullable: true },
-        "runtime-module": { type: "string", nullable: true },
         "regenerate-hint": { type: "string", nullable: true },
         services: {
             type: "object",
@@ -29,7 +28,6 @@ export const EmitterOptionsSchema = {
                     "seal-object-schemas": { type: "boolean", nullable: true },
                     "compile-schemas": { type: "boolean", nullable: true },
                     "key-vocabularies": { type: "array", items: { type: "string" }, nullable: true },
-                    "runtime-module": { type: "string", nullable: true },
                     "regenerate-hint": { type: "string", nullable: true },
                 },
                 required: [],

package/dist/src/registry.js

@@ -1,7 +1,7 @@
 import { getVisibilitySuffix, Visibility } from "@typespec/http";
 import { reportDiagnostic } from "./lib.js";
-import { propertyToTs, typeToTsBody, withTsRefResolver } from "./types.js";
-import { captureBackEdges, currentVisibility, isTransformedBy, noteBackEdge, propertyToZod, typeToZodBody, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
+import { propertyToTs, propertyTypeToTs, typeToTsBody, withTsRefResolver } from "./types.js";
+import { captureBackEdges, currentVisibility, isOptionalAt, isTransformedBy, noteBackEdge, propertyToZod, typeToZodBody, withDeferredAnnotator, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
 /**
  * The name an ANONYMOUS payload model inherits from the single model it spreads.
  *
@@ -441,7 +441,30 @@ export class SchemaRegistry {
             if (declaredNameOf(candidate) === undefined)
                 return undefined;
             return this.expressionFor(candidate);
-        }, () => withSyntheticDeclarations((name, build) => this.#declareSynthetic(name, build), () => typeToZodBody(this.#program, type)));
+        }, () => withDeferredAnnotator((property) => this.#deferredAnnotationOf(property), () => withSyntheticDeclarations((name, build) => this.#declareSynthetic(name, build), () => typeToZodBody(this.#program, type))));
+    }
+    /**
+     * The Zod type a property emitted as a getter is annotated with, or `undefined` for none.
+     *
+     * **Written here because naming a type is this class's job.** The walk in `zod.ts` produces the
+     * getter; only the registry resolves a named type to the declaration that carries it, so only it
+     * can write `Record<string, InnerModel>` rather than inlining the model and recursing forever.
+     * `types.ts` is the same walk `propertyToTs` uses, so the annotation cannot drift from the type
+     * the wire contract compares against.
+     *
+     * **A DEFAULTED property is left unannotated.** `propertyToZod` emits `.default(...)` only where
+     * `defaultOf` could render the value and reports a diagnostic where it could not, so an annotation
+     * written here would have to predict that decision; predicting it wrongly would put a type on the
+     * getter that its own value does not satisfy. A recursive property carrying a default is the one
+     * shape this leaves as it was.
+     */
+    #deferredAnnotationOf(property) {
+        if (property.defaultValue !== undefined)
+            return undefined;
+        const declared = withTsRefResolver((candidate) => declaredNameOf(candidate), () => propertyTypeToTs(this.#program, property));
+        const core = `z.ZodType<${declared}, ${declared}>`;
+        const optional = property.optional || isOptionalAt(this.#program, property);
+        return `: ${optional ? `z.ZodExactOptional<${core}>` : core}`;
     }
     /** Every declaration, dependencies first. */
     declarations() {

package/dist/src/runtime.d.ts

@@ -9,16 +9,12 @@ import type { ZodType } from "zod";
  * the sake of two declarations. `test/packaging.test.ts` asserts the separation rather than trusting
  * it.
  *
- * A consumer may substitute this entirely: the `runtime-module` option decides the specifier the
- * generated files import from, so an application that wants its own declarations points at its own
- * module and re-declares these names.
+ * The emitted `schemas.gen.ts` does not import it: the arm lists there are annotated with a copy of
+ * {@link ResponseArm} declared in that file, so the output depends on no runtime at all. This module
+ * is what an application reading those arms imports, and `armFor` is the rule it reads them by.
  */
 /**
- * One status an operation may answer with, and the schema the document publishes for it.
- *
- * `when` is present only where an operation declares two success arms discriminated by a property of
- * the result - the application reads that property, because only it knows how to see inside its own
- * result envelope. Everything else about the choice is decided at generation time.
+ * One status an operation may answer with, and what the document publishes for it.
  *
  * **Failure arms are here too, and for a while they were not.** The document declares what an
  * error response looks like, and the generated server passed on only the success statuses - so an
@@ -32,6 +28,11 @@ import type { ZodType } from "zod";
  * status not otherwise listed. Sorting once at generation time is what keeps every application from
  * re-deriving the rule - and from getting it silently wrong when a `404` and a `4XX` both apply.
  *
+ * **Nothing here says how to choose an arm from a value.** An application names the status it is
+ * answering with, and {@link armFor} says which arm governs it. A `when` field used to name a
+ * property of the result to read the choice from; that made the choice depend on a TypeSpec property
+ * name the document never states, and it is gone.
+ *
  * **`schema: undefined` is a statement, not an absence.** A response the document says carries no
  * body has no validator, and that is the truthful answer. It is also why the generated arms are
  * annotated with `satisfies readonly ResponseArm[]` rather than `as const`: measured, `as const`
@@ -40,34 +41,31 @@ import type { ZodType } from "zod";
  */
 export interface ResponseArm {
     /**
-     * The media types this response offers, where the document names more than one.
+     * Every media type this response offers, including a single one.
      *
-     * Absent where it names one, which is what an application already assumes. Present, it is the set
-     * to negotiate against: `selectContentType` takes the caller's `Accept` and these.
+     * **A single type is carried too.** Omitting it assumed the one type is JSON, and a generic
+     * responder could then not tell a `text/plain` arm from a JSON one: the document knew and the
+     * runtime did not. Absent only where the response carries no body.
      */
     readonly contentTypes?: readonly string[];
     /**
-     * The headers this response declares, as the document publishes them.
-     *
-     * **Two names, because two different things need them.** `name` is the WIRE name, which is what
-     * the response sets; `property` is the name on the value the handler returned, which is where the
-     * value is read from. `@header("x-correlation-id") correlationId: string` is `x-correlation-id`
-     * on the wire and `correlationId` in the result.
+     * The headers this response declares, by the WIRE name the response sets.
      *
-     * Absent where the response declares none, so "none declared" and "none carried" are the same
-     * thing rather than two states an application has to tell apart.
+     * `optional` is the document's `required: false`. Absent where the response declares none, so
+     * "none declared" and "none carried" are the same thing rather than two states an application has
+     * to tell apart.
      */
     readonly headers?: readonly {
         readonly name: string;
-        readonly property: string;
+        readonly optional: boolean;
     }[];
     /**
      * The status this arm answers with: an exact code, a `4XX`-style range, or the catch-all.
      *
      * **`"default"` is carried as itself, not resolved to a number.** OpenAPI's `default` response
      * means "any status not listed", and an emitter picking one would be answering a question the
-     * contract deliberately left to the application. The application maps its own failure to a status;
-     * this says which schema the body must match once it has.
+     * contract deliberately left to the application. The application names its own status; this says
+     * which schema the body must match once it has.
      *
      * **A range is carried as itself for the same reason, and it used to be dropped entirely.**
      * `@minValue(400) @maxValue(499) @statusCode _: int32` is a `4XX` entry in the document; the
@@ -78,18 +76,6 @@ export interface ResponseArm {
      */
     readonly status: number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
     readonly schema: ZodType | undefined;
-    /**
-     * How a handler said WHICH arm it meant, where an operation declares more than one success.
-     *
-     * **`number` too, because a `@statusCode` union selects by the status itself.**
-     * `model Created { @statusCode statusCode: 200 | 201 }` names the property that chooses and its
-     * values are the statuses; the discriminator case carries a boolean or string literal off the body
-     * instead. Both answer the same question, so both use this one field.
-     */
-    readonly when?: {
-        readonly property: string;
-        readonly value: boolean | number | string;
-    };
 }
 /**
  * The arm that governs a status - **the rule the OpenAPI specification states, applied once here.**

package/dist/src/types.d.ts

@@ -9,6 +9,13 @@ import { type ModelProperty, type Program, type Type } from "@typespec/compiler"
  * types then failed to typecheck against a server that was correct: `z.object({ "x-thing": ... })`
  * on one side and `{ thing: string }` on the other.
  */
+/**
+ * The TypeScript type of a property's VALUE, without its key or its optionality.
+ *
+ * Shared with the annotation the registry writes on a deferred (getter) property, so the type that
+ * annotation claims is by construction the type this walk renders for the same property.
+ */
+export declare function propertyTypeToTs(program: Program, property: ModelProperty): string;
 export declare function propertyToTs(program: Program, property: ModelProperty, wireName?: string): string;
 export declare function withTsRefResolver<T>(resolver: (type: Type) => string | undefined, run: () => T): T;
 export declare function typeToTs(program: Program, type: Type): string;

package/dist/src/types.js

@@ -254,14 +254,23 @@ function modelToTs(program, model) {
  * types then failed to typecheck against a server that was correct: `z.object({ "x-thing": ... })`
  * on one side and `{ thing: string }` on the other.
  */
+/**
+ * The TypeScript type of a property's VALUE, without its key or its optionality.
+ *
+ * Shared with the annotation the registry writes on a deferred (getter) property, so the type that
+ * annotation claims is by construction the type this walk renders for the same property.
+ */
+export function propertyTypeToTs(program, property) {
+    // `@encode` changes the wire TYPE, resolved exactly as `zod.ts` resolves it - a property encoded as
+    // a string on one side and an array on the other fails the emitted assertion, and deserves to.
+    const encoded = getEncode(program, property)?.type;
+    return typeToTs(program, encoded ?? property.type);
+}
 export function propertyToTs(program, property, wireName) {
     // The WIRE name, resolved exactly as `zod.ts` resolves it - `wire-contract.gen.ts` asserts the
     // emitted Zod infers this type, so the two must name every property identically or it fails.
     const key = objectKey(wireName ?? resolveEncodedName(program, property, "application/json"));
-    // `@encode` changes the wire TYPE, resolved exactly as `zod.ts` resolves it - a property encoded as
-    // a string on one side and an array on the other fails the emitted assertion, and deserves to.
-    const encoded = getEncode(program, property)?.type;
-    const value = typeToTs(program, encoded ?? property.type);
+    const value = propertyTypeToTs(program, property);
     /**
      * **A defaulted property used to be REQUIRED here, and that was the OUTPUT type's answer to a
      * question this file does not ask.**

package/dist/src/uri-template.d.ts

@@ -0,0 +1,106 @@
+/**
+ * RFC 6570 URI templates, read for what a server has to mount and what it has to decode.
+ *
+ * **`HttpOperation.uriTemplate`, never `HttpOperation.path`.** `path` drops every operator, so
+ * `array{.param*}`, `array{;param}` and `array{/param}` all become `array{param}`, and a route mounted
+ * from it answers 404 to the URL its own contract declares. Measured on `@typespec/http-specs`
+ * `routes`: 30 of its mock server's URIs, plus the query-continuation six.
+ *
+ * `parseUriTemplate` is copied from `@typespec/http` 1.16.0 (`dist/src/uri-template.js`, MIT), which
+ * implements it but does not export it, so the template is split exactly as the library that built
+ * it splits it.
+ */
+/**
+ * One `/`-delimited segment of a route, as a server has to mount it.
+ *
+ * - `literal`: fixed text.
+ * - `expression`: exactly one parameter, with the literal text written before and after it inside
+ *   the same segment, its RFC 6570 operator (`""` for simple expansion) and whether it explodes. A
+ *   `/` expression opens a segment of its own, and one that explodes spans every segment after it.
+ * - `unsupported`: a segment holding more than one expression, which no segment router can split.
+ */
+export type EmittedPathSegment = {
+    readonly kind: "literal";
+    readonly text: string;
+} | {
+    readonly kind: "expression";
+    /** The parameter's WIRE name, the one `pathSchema` keys on. */
+    readonly parameter: string;
+    readonly prefix: string;
+    readonly suffix: string;
+    readonly operator: "" | "+" | "#" | "." | "/" | ";";
+    readonly explode: boolean;
+    readonly optional: boolean;
+    readonly reserved: boolean;
+} | {
+    readonly kind: "unsupported";
+    readonly text: string;
+};
+/** What the path segments need to know about each path parameter the operation resolves. */
+export interface PathParameterFacts {
+    readonly name: string;
+    readonly optional: boolean;
+    readonly reserved: boolean;
+}
+/** A route template as the segments a server mounts, and the literal query pairs it carries. */
+export declare function routeTemplateOf(uriTemplate: string, parameters: readonly PathParameterFacts[]): {
+    readonly segments: readonly EmittedPathSegment[];
+    readonly literalQuery: readonly (readonly [string, string])[];
+};
+/** What a value decodes into: one value, a list, or name/value pairs (a record or a model). */
+export type ExpansionShape = "scalar" | "list" | "record";
+/**
+ * Whether a path value needs decoding at all. **An ordinary whole-segment parameter does not**, and
+ * leaving its validator untouched keeps every spec without an RFC 6570 form byte-identical.
+ */
+export declare function needsExpansionDecoding(segment: Extract<EmittedPathSegment, {
+    kind: "expression";
+}>, shape: ExpansionShape): boolean;
+/**
+ * The call that decodes one expansion, as a `z.preprocess` argument. The decoder itself is
+ * {@link URI_EXPANSION_SOURCE}, declared once in `schemas.gen.ts` when something calls it.
+ */
+export declare function uriExpansionCall(spec: {
+    readonly prefix: string;
+    readonly suffix: string;
+    readonly operator: string;
+    readonly name: string;
+    readonly explode: boolean;
+    readonly shape: ExpansionShape;
+    readonly values: "number" | "boolean" | "";
+}): string;
+/**
+ * **RFC 6570 section 3.2, run backwards.** A router hands over the text of the segment an expression
+ * sits in (or, for an exploding `/` expression, every segment after its literal), and this undoes
+ * the expansion: the literal around it, the operator's leading character, a matrix parameter's
+ * `name=`, then the joiner the operator and explode modifier chose.
+ *
+ * Text that is not the expansion the route declares is REFUSED with an issue of its own, not passed
+ * on: a string parameter's schema would accept `primitive;other=a` as the string it is, so leaving
+ * the refusal to the schema admitted a request the route does not match. A list's element values
+ * are decoded by the element decoder inside, as a query list's are; a record's values are decoded
+ * here, because no schema expression reaches them one by one.
+ */
+export declare const URI_EXPANSION_SOURCE = "\n/** RFC 6570 section 3.2 in reverse: one expression's expansion, decoded into the value it expanded. */\nfunction uriExpansion(\n\traw: unknown,\n\tctx: { addIssue(issue: { code: \"custom\"; message: string }): void },\n\tspec: {\n\t\treadonly prefix: string;\n\t\treadonly suffix: string;\n\t\treadonly operator: string;\n\t\treadonly name: string;\n\t\treadonly explode: boolean;\n\t\treadonly shape: \"scalar\" | \"list\" | \"record\";\n\t\treadonly values: \"number\" | \"boolean\" | \"\";\n\t},\n): unknown {\n\tif (typeof raw !== \"string\") return raw;\n\tconst refuse = (): unknown => {\n\t\tctx.addIssue({ code: \"custom\", message: `Not the expansion of {${spec.operator}${spec.name}${spec.explode ? \"*\" : \"\"}} this route declares` });\n\t\treturn z.NEVER;\n\t};\n\tif (raw.length < spec.prefix.length + spec.suffix.length) return refuse();\n\tif (!raw.startsWith(spec.prefix) || !raw.endsWith(spec.suffix)) return refuse();\n\tlet text = raw.slice(spec.prefix.length, raw.length - spec.suffix.length);\n\tif (spec.operator === \".\" || spec.operator === \";\") {\n\t\tif (!text.startsWith(spec.operator)) return refuse();\n\t\ttext = text.slice(1);\n\t}\n\tif (spec.operator === \";\" && !(spec.shape === \"record\" && spec.explode)) {\n\t\tconst named = text\n\t\t\t.split(\";\")\n\t\t\t.map((part) => (part === spec.name ? \"\" : part.startsWith(`${spec.name}=`) ? part.slice(spec.name.length + 1) : undefined));\n\t\tif (named.some((part) => part === undefined)) return refuse();\n\t\tif (spec.shape === \"list\" && spec.explode) return named;\n\t\tif (named.length !== 1) return refuse();\n\t\ttext = named[0] ?? \"\";\n\t}\n\tif (spec.shape === \"scalar\") return text;\n\tconst joiner = spec.explode && (spec.operator === \".\" || spec.operator === \"/\" || spec.operator === \";\") ? spec.operator : \",\";\n\tif (spec.shape === \"list\") return text === \"\" ? [] : text.split(joiner);\n\tconst value = (item: string): unknown =>\n\t\tspec.values === \"number\" && item.trim() !== \"\" && Number.isFinite(Number(item))\n\t\t\t? Number(item)\n\t\t\t: spec.values === \"boolean\" && (item === \"true\" || item === \"false\")\n\t\t\t\t? item === \"true\"\n\t\t\t\t: item;\n\tconst entries: [string, unknown][] = [];\n\tif (spec.explode) {\n\t\tfor (const pair of text === \"\" ? [] : text.split(joiner)) {\n\t\t\tconst at = pair.indexOf(\"=\");\n\t\t\tif (at === -1) return refuse();\n\t\t\tentries.push([pair.slice(0, at), value(pair.slice(at + 1))]);\n\t\t}\n\t} else {\n\t\tconst items = text === \"\" ? [] : text.split(\",\");\n\t\tif (items.length % 2 !== 0) return refuse();\n\t\tfor (let index = 0; index < items.length; index += 2) {\n\t\t\tentries.push([items[index] ?? \"\", value(items[index + 1] ?? \"\")]);\n\t\t}\n\t}\n\treturn Object.fromEntries(entries);\n}\n";
+/**
+ * The call that gathers a form-exploded record or model back under its parameter name. The
+ * gatherer itself is {@link EXPLODED_QUERY_SOURCE}.
+ */
+export declare function explodedQueryCall(spec: {
+    readonly name: string;
+    /** For a record, every OTHER query parameter's wire name; its own keys are whatever is left. */
+    readonly others: readonly string[];
+    /** For a model, its own properties' wire names; `undefined` for a record. */
+    readonly keys: readonly string[] | undefined;
+    readonly numbers: readonly string[];
+    readonly booleans: readonly string[];
+    /** For a record, how every value decodes. */
+    readonly values: "number" | "boolean" | "";
+}): string;
+/**
+ * **`{?param*}` over a record or a model expands to the object's own keys**, `?a=1&b=2` and
+ * `?field=status&value=active`, so there is no `param` key for a query validator to find. This
+ * gathers those keys back under the parameter's name before the query object is validated: a model
+ * takes exactly its declared properties, a record every key no other query parameter claims.
+ */
+export declare const EXPLODED_QUERY_SOURCE = "\n/** RFC 6570 form expansion of an exploded record or model, gathered back under its parameter. */\nfunction explodedQuery(\n\traw: unknown,\n\tspec: {\n\t\treadonly name: string;\n\t\treadonly others: readonly string[];\n\t\treadonly keys: readonly string[] | null;\n\t\treadonly numbers: readonly string[];\n\t\treadonly booleans: readonly string[];\n\t\treadonly values: \"number\" | \"boolean\" | \"\";\n\t},\n): unknown {\n\tif (raw === null || typeof raw !== \"object\" || Array.isArray(raw) || spec.name in raw) return raw;\n\tconst gathered: Record<string, unknown> = {};\n\tconst rest: Record<string, unknown> = {};\n\tfor (const [key, value] of Object.entries(raw)) {\n\t\tconst own = spec.keys === null ? !spec.others.includes(key) : spec.keys.includes(key);\n\t\tif (!own) {\n\t\t\trest[key] = value;\n\t\t\tcontinue;\n\t\t}\n\t\tconst kind = spec.values !== \"\" ? spec.values : spec.numbers.includes(key) ? \"number\" : spec.booleans.includes(key) ? \"boolean\" : \"\";\n\t\tgathered[key] =\n\t\t\ttypeof value !== \"string\"\n\t\t\t\t? value\n\t\t\t\t: kind === \"number\" && value.trim() !== \"\" && Number.isFinite(Number(value))\n\t\t\t\t\t? Number(value)\n\t\t\t\t\t: kind === \"boolean\" && (value === \"true\" || value === \"false\")\n\t\t\t\t\t\t? value === \"true\"\n\t\t\t\t\t\t: value;\n\t}\n\treturn Object.keys(gathered).length === 0 ? raw : { ...rest, [spec.name]: gathered };\n}\n";

package/dist/src/uri-template.js

@@ -0,0 +1,254 @@
+/**
+ * RFC 6570 URI templates, read for what a server has to mount and what it has to decode.
+ *
+ * **`HttpOperation.uriTemplate`, never `HttpOperation.path`.** `path` drops every operator, so
+ * `array{.param*}`, `array{;param}` and `array{/param}` all become `array{param}`, and a route mounted
+ * from it answers 404 to the URL its own contract declares. Measured on `@typespec/http-specs`
+ * `routes`: 30 of its mock server's URIs, plus the query-continuation six.
+ *
+ * `parseUriTemplate` is copied from `@typespec/http` 1.16.0 (`dist/src/uri-template.js`, MIT), which
+ * implements it but does not export it, so the template is split exactly as the library that built
+ * it splits it.
+ */
+const OPERATORS = ["+", "#", ".", "/", ";", "?", "&"];
+function parseUriTemplate(template) {
+    const parts = [];
+    for (const [, rawExpression, literal] of template.matchAll(/\{([^{}]+)\}|([^{}]+)/g)) {
+        if (rawExpression === undefined) {
+            parts.push(literal ?? "");
+            continue;
+        }
+        let expression = rawExpression;
+        let operator;
+        const first = expression[0];
+        if (first !== undefined && OPERATORS.includes(first)) {
+            operator = first;
+            expression = expression.slice(1);
+        }
+        for (const item of expression.split(",")) {
+            const match = /([^:*]*)(?::(\d+)|(\*))?/.exec(item);
+            parts.push({ name: match?.[1] ?? item, operator, explode: match?.[3] !== undefined });
+        }
+    }
+    return parts;
+}
+/** A route template as the segments a server mounts, and the literal query pairs it carries. */
+export function routeTemplateOf(uriTemplate, parameters) {
+    const facts = new Map(parameters.map((parameter) => [parameter.name, parameter]));
+    const raw = [];
+    const literalQuery = [];
+    let current;
+    let inQuery = false;
+    const open = () => {
+        current = [];
+        raw.push(current);
+        return current;
+    };
+    for (const part of parseUriTemplate(uriTemplate)) {
+        if (typeof part === "string") {
+            let text = part;
+            if (inQuery) {
+                literalQuery.push(...pairsOf(text));
+                continue;
+            }
+            if (text.includes("?")) {
+                inQuery = true;
+                literalQuery.push(...pairsOf(text.slice(text.indexOf("?") + 1)));
+                text = text.slice(0, text.indexOf("?"));
+            }
+            text.split("/").forEach((piece, index) => {
+                const target = index === 0 ? (current ?? (piece === "" ? undefined : open())) : open();
+                if (piece !== "" && target !== undefined)
+                    target.push(piece);
+            });
+            continue;
+        }
+        // `{?x}` and `{&x}` are query parameters, which a query validator reads; they are not path.
+        if (part.operator === "?" || part.operator === "&")
+            continue;
+        if (part.operator === "/")
+            open().push(part);
+        else
+            (current ?? open()).push(part);
+    }
+    const segments = raw
+        .filter((parts) => parts.length > 0)
+        .map((parts) => {
+        const expressions = parts.filter((part) => typeof part !== "string");
+        const text = (from) => from.filter((part) => typeof part === "string").join("");
+        const [only] = expressions;
+        if (only === undefined)
+            return { kind: "literal", text: text(parts) };
+        if (expressions.length > 1) {
+            return {
+                kind: "unsupported",
+                text: parts
+                    .map((part) => typeof part === "string" ? part : `{${part.operator ?? ""}${part.name}}`)
+                    .join(""),
+            };
+        }
+        const at = parts.indexOf(only);
+        const fact = facts.get(only.name);
+        return {
+            kind: "expression",
+            parameter: only.name,
+            prefix: text(parts.slice(0, at)),
+            suffix: text(parts.slice(at + 1)),
+            operator: only.operator === "?" || only.operator === "&" ? "" : (only.operator ?? ""),
+            explode: only.explode,
+            optional: fact?.optional ?? false,
+            reserved: only.operator === "+" || only.operator === "#" || fact?.reserved === true,
+        };
+    });
+    return { segments, literalQuery };
+}
+/** `a=1&b=2` -> the pairs it spells; a piece with no `=` is a name with an empty value. */
+function pairsOf(text) {
+    return text
+        .split("&")
+        .filter((piece) => piece !== "")
+        .map((piece) => {
+        const at = piece.indexOf("=");
+        return at === -1 ? [piece, ""] : [piece.slice(0, at), piece.slice(at + 1)];
+    });
+}
+/**
+ * Whether a path value needs decoding at all. **An ordinary whole-segment parameter does not**, and
+ * leaving its validator untouched keeps every spec without an RFC 6570 form byte-identical.
+ */
+export function needsExpansionDecoding(segment, shape) {
+    return (segment.prefix !== "" ||
+        segment.suffix !== "" ||
+        segment.operator === "." ||
+        segment.operator === ";" ||
+        shape !== "scalar");
+}
+/**
+ * The call that decodes one expansion, as a `z.preprocess` argument. The decoder itself is
+ * {@link URI_EXPANSION_SOURCE}, declared once in `schemas.gen.ts` when something calls it.
+ */
+export function uriExpansionCall(spec) {
+    return `(raw, ctx) => uriExpansion(raw, ctx, { prefix: ${JSON.stringify(spec.prefix)}, suffix: ${JSON.stringify(spec.suffix)}, operator: ${JSON.stringify(spec.operator)}, name: ${JSON.stringify(spec.name)}, explode: ${spec.explode}, shape: ${JSON.stringify(spec.shape)}, values: ${JSON.stringify(spec.values)} })`;
+}
+/**
+ * **RFC 6570 section 3.2, run backwards.** A router hands over the text of the segment an expression
+ * sits in (or, for an exploding `/` expression, every segment after its literal), and this undoes
+ * the expansion: the literal around it, the operator's leading character, a matrix parameter's
+ * `name=`, then the joiner the operator and explode modifier chose.
+ *
+ * Text that is not the expansion the route declares is REFUSED with an issue of its own, not passed
+ * on: a string parameter's schema would accept `primitive;other=a` as the string it is, so leaving
+ * the refusal to the schema admitted a request the route does not match. A list's element values
+ * are decoded by the element decoder inside, as a query list's are; a record's values are decoded
+ * here, because no schema expression reaches them one by one.
+ */
+export const URI_EXPANSION_SOURCE = `
+/** RFC 6570 section 3.2 in reverse: one expression's expansion, decoded into the value it expanded. */
+function uriExpansion(
+	raw: unknown,
+	ctx: { addIssue(issue: { code: "custom"; message: string }): void },
+	spec: {
+		readonly prefix: string;
+		readonly suffix: string;
+		readonly operator: string;
+		readonly name: string;
+		readonly explode: boolean;
+		readonly shape: "scalar" | "list" | "record";
+		readonly values: "number" | "boolean" | "";
+	},
+): unknown {
+	if (typeof raw !== "string") return raw;
+	const refuse = (): unknown => {
+		ctx.addIssue({ code: "custom", message: \`Not the expansion of {\${spec.operator}\${spec.name}\${spec.explode ? "*" : ""}} this route declares\` });
+		return z.NEVER;
+	};
+	if (raw.length < spec.prefix.length + spec.suffix.length) return refuse();
+	if (!raw.startsWith(spec.prefix) || !raw.endsWith(spec.suffix)) return refuse();
+	let text = raw.slice(spec.prefix.length, raw.length - spec.suffix.length);
+	if (spec.operator === "." || spec.operator === ";") {
+		if (!text.startsWith(spec.operator)) return refuse();
+		text = text.slice(1);
+	}
+	if (spec.operator === ";" && !(spec.shape === "record" && spec.explode)) {
+		const named = text
+			.split(";")
+			.map((part) => (part === spec.name ? "" : part.startsWith(\`\${spec.name}=\`) ? part.slice(spec.name.length + 1) : undefined));
+		if (named.some((part) => part === undefined)) return refuse();
+		if (spec.shape === "list" && spec.explode) return named;
+		if (named.length !== 1) return refuse();
+		text = named[0] ?? "";
+	}
+	if (spec.shape === "scalar") return text;
+	const joiner = spec.explode && (spec.operator === "." || spec.operator === "/" || spec.operator === ";") ? spec.operator : ",";
+	if (spec.shape === "list") return text === "" ? [] : text.split(joiner);
+	const value = (item: string): unknown =>
+		spec.values === "number" && item.trim() !== "" && Number.isFinite(Number(item))
+			? Number(item)
+			: spec.values === "boolean" && (item === "true" || item === "false")
+				? item === "true"
+				: item;
+	const entries: [string, unknown][] = [];
+	if (spec.explode) {
+		for (const pair of text === "" ? [] : text.split(joiner)) {
+			const at = pair.indexOf("=");
+			if (at === -1) return refuse();
+			entries.push([pair.slice(0, at), value(pair.slice(at + 1))]);
+		}
+	} else {
+		const items = text === "" ? [] : text.split(",");
+		if (items.length % 2 !== 0) return refuse();
+		for (let index = 0; index < items.length; index += 2) {
+			entries.push([items[index] ?? "", value(items[index + 1] ?? "")]);
+		}
+	}
+	return Object.fromEntries(entries);
+}
+`;
+/**
+ * The call that gathers a form-exploded record or model back under its parameter name. The
+ * gatherer itself is {@link EXPLODED_QUERY_SOURCE}.
+ */
+export function explodedQueryCall(spec) {
+    return `(raw) => explodedQuery(raw, { name: ${JSON.stringify(spec.name)}, others: ${JSON.stringify(spec.others)}, keys: ${JSON.stringify(spec.keys ?? null)}, numbers: ${JSON.stringify(spec.numbers)}, booleans: ${JSON.stringify(spec.booleans)}, values: ${JSON.stringify(spec.values)} })`;
+}
+/**
+ * **`{?param*}` over a record or a model expands to the object's own keys**, `?a=1&b=2` and
+ * `?field=status&value=active`, so there is no `param` key for a query validator to find. This
+ * gathers those keys back under the parameter's name before the query object is validated: a model
+ * takes exactly its declared properties, a record every key no other query parameter claims.
+ */
+export const EXPLODED_QUERY_SOURCE = `
+/** RFC 6570 form expansion of an exploded record or model, gathered back under its parameter. */
+function explodedQuery(
+	raw: unknown,
+	spec: {
+		readonly name: string;
+		readonly others: readonly string[];
+		readonly keys: readonly string[] | null;
+		readonly numbers: readonly string[];
+		readonly booleans: readonly string[];
+		readonly values: "number" | "boolean" | "";
+	},
+): unknown {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw) || spec.name in raw) return raw;
+	const gathered: Record<string, unknown> = {};
+	const rest: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(raw)) {
+		const own = spec.keys === null ? !spec.others.includes(key) : spec.keys.includes(key);
+		if (!own) {
+			rest[key] = value;
+			continue;
+		}
+		const kind = spec.values !== "" ? spec.values : spec.numbers.includes(key) ? "number" : spec.booleans.includes(key) ? "boolean" : "";
+		gathered[key] =
+			typeof value !== "string"
+				? value
+				: kind === "number" && value.trim() !== "" && Number.isFinite(Number(value))
+					? Number(value)
+					: kind === "boolean" && (value === "true" || value === "false")
+						? value === "true"
+						: value;
+	}
+	return Object.keys(gathered).length === 0 ? raw : { ...rest, [spec.name]: gathered };
+}
+`;

package/dist/src/zod.d.ts

@@ -1,5 +1,6 @@
 import { type Enum, type Model, type ModelProperty, type Program, type Type } from "@typespec/compiler";
 import { Visibility } from "@typespec/http";
+export declare function withDeferredAnnotator<T>(annotator: (property: ModelProperty) => string | undefined, run: () => T): T;
 export declare function withSealedObjects<T>(sealed: boolean, run: () => T): T;
 export declare function withVisibility<T>(program: Program, next: Visibility, run: () => T): T;
 /** Whether a property is optional AT THE CURRENT POSITION - PATCH makes update fields optional. */