typespec-http-zod 0.25.1 → 0.27.0

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,16 @@
 import { type Enum, type Model, type ModelProperty, type Program, type Type } from "@typespec/compiler";
 import { Visibility } from "@typespec/http";
+/**
+ * What a walk returns after reporting a refusal.
+ *
+ * **Reporting does not unwind, which is the point.** A throw abandoned the compile at the first
+ * unrepresentable construct; reporting lets the walk carry on and name every one of them in a single
+ * run. The walk still has to return a `string`, and `z.never()` is the honest placeholder: valid
+ * Zod, rejects everything, and unreachable in practice because the error diagnostic has already
+ * failed the compile that would have written it.
+ */
+export declare const UNREPRESENTABLE = "z.never()";
+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. */
@@ -97,23 +108,6 @@ export declare function effectiveIndexer(model: Model): Model["indexer"];
  * for a real subtype - the same rule that decides whether a base may be sealed.
  */
 export declare function discriminatedSubtypes(program: Program, model: Model): readonly Model[];
-/**
- * **What JSON kind a value of this type arrives as, for a parameter carried in text.**
- *
- * A path, query or header value is always a string on the wire, so a numeric or boolean parameter has
- * to be decoded before the document's schema runs. Deciding WHICH decoder applies used to be done by
- * inspecting the emitted Zod - `declared.startsWith("z.number()")` - which is a string about a string
- * and fails silently the moment the expression is spelled any other way.
- *
- * It did. `@query size: 10 | 25 | 50` emits `z.union([z.literal(10), ...])`, which starts with
- * neither, so no decoder was wrapped around it and the validator required the NUMBER 25 from a wire
- * that can only deliver `"25"`. Measured: `?size=25` rejected, `size: 25` accepted. Every conformant
- * caller got a 400, and no document comparison could see it, because both sides agree the parameter
- * is a number - the disagreement is with the wire.
- *
- * Reading the TYPE answers the question the emitted text was standing in for. `SCALARS` remains the
- * single list of what becomes a number, so this cannot drift from what `scalarToZod` emits.
- */
 export declare function wireKindOf(program: Program, type: Type): "number" | "boolean" | undefined;
 /**
  * A name as an object key - quoted when it is not a legal JavaScript identifier.

package/dist/src/zod.js

@@ -11,7 +11,26 @@ import { reportDiagnostic } from "./lib.js";
  * Zod, rejects everything, and unreachable in practice because the error diagnostic has already
  * failed the compile that would have written it.
  */
-const UNREPRESENTABLE = "z.never()";
+export const UNREPRESENTABLE = "z.never()";
+/**
+ * **Installed by the registry, which is the only place that knows what a declared type is CALLED.**
+ *
+ * A property emitted as a getter needs its Zod type written out - see the getter docblock in
+ * `modelToZod`. Naming the type is the registry's job (it resolves a named type to its declaration,
+ * versioned name included), and `types.ts` already imports this module, so the annotation is handed
+ * in rather than computed here.
+ */
+let annotateDeferred = () => undefined;
+export function withDeferredAnnotator(annotator, run) {
+    const previous = annotateDeferred;
+    annotateDeferred = annotator;
+    try {
+        return run();
+    }
+    finally {
+        annotateDeferred = previous;
+    }
+}
 /**
  * TypeSpec type -> Zod source text.
  *
@@ -320,16 +339,36 @@ const SCALARS = {
     string: "z.string()",
     boolean: "z.boolean()",
     bytes: "z.string()",
-    int8: "z.number().int()",
-    int16: "z.number().int()",
-    int32: "z.number().int()",
-    int64: "z.number().int()",
-    safeint: "z.number().int()",
-    uint8: "z.number().int()",
-    uint16: "z.number().int()",
-    uint32: "z.number().int()",
-    uint64: "z.number().int()",
-    integer: "z.number().int()",
+    /**
+     * **A declared WIDTH is a claim about the value too, and ten of them used to share one check.**
+     *
+     * Every integer scalar emitted `z.number().int()`, which is "an integer within the safe range" and
+     * nothing more. Measured at the wire on `workerd`, against a document publishing the widths below:
+     * a `uint8` accepted `-5` and `100000`, an `int32` accepted `3000000000` and `-3000000000`.
+     *
+     * The differential oracle cannot see it. JSON Schema 2020-12 treats `format` as an annotation, so
+     * Ajv on the published document answers VALID for all of those and agrees with the server while
+     * both are wrong. Ajv says so out loud: `unknown format "uint8" ignored`.
+     *
+     * Zod 4 has the named formats for the two widths that have them, and they emit better JSON Schema
+     * than a bare bound would. The rest take explicit bounds.
+     *
+     * **`int64` and `uint64` keep the safe-integer ceiling, and that is a limit rather than a
+     * choice.** `JSON.parse` has already lost a value above 2^53 before any validator runs, so the
+     * alternatives are to refuse it or to accept a number that is not the one the caller sent.
+     * Refusing is the honest one. `z.int64()` exists but is a `bigint`, which a JSON body cannot
+     * carry. What changes here is only that `uint64` stops accepting negatives.
+     */
+    int8: "z.int().min(-128).max(127)",
+    int16: "z.int().min(-32768).max(32767)",
+    int32: "z.int32()",
+    int64: "z.int()",
+    safeint: "z.int()",
+    uint8: "z.int().min(0).max(255)",
+    uint16: "z.int().min(0).max(65535)",
+    uint32: "z.uint32()",
+    uint64: "z.int().min(0)",
+    integer: "z.int()",
     float: "z.number()",
     float32: "z.number()",
     float64: "z.number()",
@@ -762,9 +801,26 @@ function modelToZod(program, model) {
         .map((property) => {
         const key = propertyKey(program, property);
         const { value, deferred } = captureBackEdges(() => withDeclarationSite(property, () => propertyToZod(program, property)));
+        /**
+         * **A getter without a return type infers `unknown`, and the collapse is SILENT.**
+         *
+         * The docblock above claims the getter keeps `z.infer` inferring the recursive type. It does
+         * for the declaration itself, and not for a schema that WRAPS it: measured on the conformance
+         * corpus, `z.record(z.string(), innerModelSchema)` - what `@body body: Record<InnerModel>`
+         * emits - infers `children?: unknown`, and `.parse()` on it returns `unknown` outright. The
+         * generated server then failed to compile with `TS2322`, in `type/dictionary`, which is how
+         * this was found; nothing said the emitted TYPE was weaker than the document.
+         *
+         * Annotating the GETTER rather than the declaration is what keeps `.shape` and `.extend`,
+         * which inheritance and every group spread depend on. `: z.ZodType<T, T>` names both of Zod's
+         * parameters for the reason `renderSchemas` names both: one leaves the input side `unknown`.
+         */
+        const annotation = deferred ? (annotateDeferred(property) ?? "") : "";
         return {
             deferred,
-            text: deferred ? `\tget ${key}() {\n\t\treturn ${value};\n\t},` : `\t${key}: ${value},`,
+            text: deferred
+                ? `\tget ${key}()${annotation} {\n\t\treturn ${value};\n\t},`
+                : `\t${key}: ${value},`,
         };
     });
     const entries = members.map((member) => member.text);
@@ -823,8 +879,25 @@ function modelToZod(program, model) {
  * is a number - the disagreement is with the wire.
  *
  * Reading the TYPE answers the question the emitted text was standing in for. `SCALARS` remains the
- * single list of what becomes a number, so this cannot drift from what `scalarToZod` emits.
+ * single list of what becomes a number.
+ *
+ * **It still inspects the emitted expression to decide WHICH kind, and that did drift once more.**
+ * The test was `startsWith("z.number()")`, and giving each integer width its declared bounds spelled
+ * nine of them `z.int(`, `z.int32(` and `z.uint32(` instead. Every one silently lost its wire
+ * decoder: 22 arms went red at once, which is the only reason it was not shipped. The prefixes live
+ * in one named constant now.
+ *
+ * **That claim named a `scalars.test.ts` which did not exist, and nothing graded the list.**
+ * Measured: dropping `z.uint32(` from it, and separately `z.int(`, left all 468 arms in this
+ * package green, because no fixture had ever declared an integer width as a PARAMETER - the only
+ * place the decoder is attached. `test/widths/` now declares all ten as query parameters and sends
+ * each as text, so a spelling this list forgets fails here rather than at a consumer.
+ */
+/**
+ * Every emitted expression that denotes a JSON number. Named once, because `SCALARS` and this list
+ * have to agree and nothing about the two being in the same file makes them.
  */
+const NUMERIC_EXPRESSIONS = ["z.number()", "z.int(", "z.int32(", "z.uint32("];
 export function wireKindOf(program, type) {
     if (type.kind === "Scalar") {
         const encoded = encodedTypeOf(program, type);
@@ -834,7 +907,7 @@ export function wireKindOf(program, type) {
             const mapped = SCALARS[current.name];
             if (mapped === undefined)
                 continue;
-            if (mapped.startsWith("z.number()"))
+            if (NUMERIC_EXPRESSIONS.some((prefix) => mapped.startsWith(prefix)))
                 return "number";
             if (mapped === "z.boolean()")
                 return "boolean";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.25.1",
+  "version": "0.27.0",
   "description": "TypeSpec emitter and library: turn an HTTP service definition into Zod validators and framework-free contract types that agree, keyword for keyword, with the OpenAPI document @typespec/openapi3 publishes from the same source.",
   "keywords": [
     "codegen",
@@ -42,6 +42,9 @@
     "access": "public",
     "provenance": true
   },
+  "dependencies": {
+    "redos-detector": "^6.1.4"
+  },
   "devDependencies": {
     "@types/node": "^26.5.1",
     "@typespec/compiler": "1.16.0",
@@ -62,7 +65,7 @@
     "typespec-http-zod": "link:.",
     "vitest": "^5.0.0",
     "yaml": "^2.9.1",
-    "zod": "^4.5.2"
+    "zod": "^4.6.5"
   },
   "peerDependencies": {
     "@typespec/compiler": "^1.15.0",
@@ -85,7 +88,7 @@
   },
   "tspMain": "lib/main.tsp",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
     "test": "tsc -p tsconfig.build.json && vitest run",
     "typecheck": "tsc -p tsconfig.json",
     "lint": "oxlint src/ test/",