typespec-http-zod 0.16.0 → 0.18.0

package/dist/src/api.js

@@ -617,7 +617,13 @@ function alternateSchemaFor(operation, status, registry) {
 function multipartTsOf(body, registry) {
     const entries = body.parts.map((part) => {
         const type = part.body?.type;
-        const inner = type === undefined || isBinaryPart(type) ? "unknown" : registry.expressionFor(type);
+        const inner = type === undefined
+            ? "unknown"
+            : isFilePart(type)
+                ? MULTIPART_FILE
+                : isBinaryPart(type)
+                    ? "unknown"
+                    : registry.expressionFor(type);
         const value = part.multi === true ? `(${inner})[]` : inner;
         const optional = part.optional === true ? "?" : "";
         return `\t${objectKey(part.name ?? "")}${optional}: ${value};`;
@@ -627,7 +633,13 @@ function multipartTsOf(body, registry) {
 function multipartSchemaOf(body, registry) {
     const entries = body.parts.map((part) => {
         const type = part.body?.type;
-        const inner = type === undefined || isBinaryPart(type) ? "z.unknown()" : registry.expressionFor(type);
+        const inner = type === undefined
+            ? "z.unknown()"
+            : isFilePart(type)
+                ? `z.unknown().refine(${MULTIPART_FILE_REFINEMENT})`
+                : isBinaryPart(type)
+                    ? "z.unknown()"
+                    : registry.expressionFor(type);
         // `multi` is `HttpPart<T>[]` - the same part repeated, which arrives as an array.
         const value = part.multi === true ? `z.array(${inner})` : inner;
         return `\t${objectKey(part.name ?? "")}: ${part.optional === true ? `${value}.optional()` : value},`;
@@ -642,6 +654,60 @@ function multipartSchemaOf(body, registry) {
     const name = named !== undefined && named.kind === "Model" && named.name !== "" ? named.name : undefined;
     return name === undefined ? shape : registry.declareNamed(name, () => shape);
 }
+/**
+ * The shape a multipart file part actually arrives as, spelled structurally.
+ *
+ * **Structural rather than `File`, because emitted output must depend on no ambient library.**
+ * `File` is reachable only through `lib.dom` or `@types/node`, and this package's own
+ * emitted-output typecheck runs with `types: []` precisely so a dependency like that cannot creep
+ * in. The three members are the ones a handler needs and the ones {@link MULTIPART_FILE_REFINEMENT}
+ * actually verifies - claiming more would be asserting what nothing established.
+ *
+ * `arrayBuffer` is a property rather than a method on purpose: `Declared<>` maps the inferred side
+ * of the wire assertion, and a mapped type turns a method into a function-typed property, so
+ * spelling it this way on both sides is what keeps the two identical.
+ */
+const MULTIPART_FILE = "{ name: string; type: string; arrayBuffer: () => Promise<ArrayBuffer> }";
+/**
+ * The check that makes {@link MULTIPART_FILE} established rather than asserted.
+ *
+ * **Why this is derivable from the contract, which is the rule `test/vocabulary.test.ts` enforces.**
+ * `@typespec/openapi3` publishes a bare `{}` for a `HttpPart<File>`, in 3.1 and even where the part
+ * declares a content type. That is OpenAPI's IDIOM for binary content in a multipart body rather
+ * than a statement that any value is acceptable, and the transport says the same: Hono types a
+ * multipart part as `string | File` and nothing else. So this refuses exactly one thing - a text
+ * field where the spec declared a file - which is malformed against the spec that produced the
+ * document. A spec meaning "either" writes `HttpPart<File | string>`, so nothing becomes
+ * inexpressible; the declaration simply means what it says.
+ *
+ * **`z.unknown().refine()` rather than `z.custom<T>()`, and the difference is not stylistic.**
+ * Measured on zod 4.4.3: `z.toJSONSchema(z.custom(...))` throws `Custom types cannot be represented
+ * in JSON Schema`, which silently took four corpus schemas out of the differential comparing these
+ * validators against the document. Refined `z.unknown()` serialises to `{}` - exactly what openapi3
+ * publishes - so that comparison keeps working. Zod 4 narrows on a type predicate, so the inferred
+ * type is the same either way.
+ *
+ * Every member the type claims is verified, so the narrowing is sound.
+ */
+const MULTIPART_FILE_REFINEMENT = `(value): value is ${MULTIPART_FILE} => typeof value === "object" && value !== null && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string" && "arrayBuffer" in value && typeof value.arrayBuffer === "function"`;
+/**
+ * A part declared as a `File`, as opposed to raw `bytes`.
+ *
+ * **Narrower than {@link isBinaryPart} deliberately.** A `File` part is declared to be a file and
+ * `c.req.parseBody()` produces one, so the contract supports saying so. `bytes` says only that the
+ * payload is binary; a client may legitimately send it as an ordinary form field, which arrives as a
+ * string. Widening this to cover `bytes` would refuse payloads that pass today, on an inference the
+ * spec never made.
+ */
+function isFilePart(type) {
+    if (type.kind !== "Model")
+        return false;
+    for (let model = type; model !== undefined; model = model.baseModel) {
+        if (model.name === "File")
+            return true;
+    }
+    return false;
+}
 /** `bytes`, or a model built on `File` - the parts openapi3 publishes as an empty schema. */
 function isBinaryPart(type) {
     if (type.kind === "Scalar") {
@@ -1593,6 +1659,10 @@ type Simplify<T> = { [K in keyof T]: T[K] } & {};
  * mutable one. Mutability is not a fact about a wire shape: it says nothing about what a caller
  * receives. Making the TARGET readonly accepts both, which is the permissive direction; the reverse
  * would reject every view a producer actually returns.
+ *
+ * No branch for functions, deliberately: the wire vocabulary is primitives, objects and arrays, so
+ * a call signature cannot appear here. Mapping one would yield \`{}\`, so the day something does
+ * carry a method - a narrowed multipart file part is the near miss - this needs one.
  */
 type Produced<T> = T extends readonly (infer Element)[]
 	? readonly Produced<Element>[]
@@ -1655,7 +1725,7 @@ function renderWireAssertions(schemas, types, entries, contractsPackage) {
     }
     if (paired.length === 0)
         return undefined;
-    const assertions = paired.map((pair) => `export type Assert${pair.name} = MustHold<Identical<z.infer<typeof ${pair.identifier}>, Contracts.${pair.name}>>;`);
+    const assertions = paired.map((pair) => `export type Assert${pair.name} = MustHold<Identical<Declared<z.infer<typeof ${pair.identifier}>>, Contracts.${pair.name}>>;`);
     return `${generatedBanner()}
 import type { z } from "zod";
 import type * as Contracts from "${contractsPackage}";
@@ -1672,6 +1742,45 @@ type Identical<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends
 	? true
 	: ["the emitted validator and the shared wire type describe different shapes"];
 
+/**
+ * A shape with its index signatures removed, at every depth.
+ *
+ * **The two sides of this contract differ on exactly one axis, deliberately.** For an open model the
+ * validator's output carries \`[key: string]: unknown\`, because a loose parse really does pass
+ * unknown keys through. The shared wire type does not, because it is a FLOOR - the properties a
+ * producer must supply - and an index signature there is an obligation on the producer rather than a
+ * description of the payload. TypeScript gives an interface no implicit index signature, so carrying
+ * it made the published shape unsatisfiable by most domain types.
+ *
+ * So this comparison is over DECLARED PROPERTIES, the only claim both sides make. **That the
+ * validator is open wherever the document is open has not stopped being checked** - it is asserted
+ * directly by the emitter's own suite now, instead of falling out of this comparison as a side
+ * effect. Every other kind of drift still fails here exactly as before.
+ *
+ * Applied to the INFERRED side only. If the shared type ever grew an index signature of its own that
+ * is a real disagreement, and this still catches it.
+ *
+ * Deep, because openness recurs: a nested open model puts one at every level, which is why a single
+ * spread never repaired the shape it was supposed to repair.
+ */
+type Declared<T> = T extends (...args: never[]) => unknown
+	? T
+	: T extends readonly (infer Element)[]
+		? T extends Element[]
+			? Declared<Element>[]
+			: readonly Declared<Element>[]
+		: T extends object
+			? {
+					[K in keyof T as string extends K
+						? never
+						: number extends K
+							? never
+							: symbol extends K
+								? never
+								: K]: Declared<T[K]>;
+				}
+			: T;
+
 /**
  * \u26a0\ufe0f **The constraint is what fails the build.** \`Identical<A, B> & true\` merely produces an odd
  * type when the two disagree, and a type alias to an odd type compiles fine \u2014 66 assertions that

package/dist/src/types.js

@@ -208,27 +208,25 @@ function modelToTs(program, model) {
      * producer must contain. The contract type is the floor: these fields, at least.
      */
     /**
-     * **An open model carries its catchall here too, or the two walks disagree.**
+     * **`0.16.0` added the catchall here and `0.17.0` reverted it. Do not add it again.**
      *
-     * `modelToZod` emits `.loose()` for a `...Record<unknown>` indexer and `.catchall(T)` for a typed
-     * one, so `z.infer` gains an index signature. This walk emitted the declared properties alone, and
-     * the emitter's OWN assertion caught it:
-     * `TS2344: the emitted validator and the shared wire type describe different shapes`. Any spec with
-     * `...Record<unknown>` on a request model shipped a `wire-contract.gen.ts` that does not compile.
+     * The argument for it was that the document says `additionalProperties` and the validator says
+     * `.loose()`, so the type should say it too. Both of those state what is TOLERATED ON ARRIVAL. On
+     * the type it reads as an obligation on whoever PRODUCES the value, and TypeScript gives an
+     * interface no implicit index signature (microsoft/TypeScript#15300) - only a type alias gets one
+     * - so whether a consumer could satisfy our published shape came to depend on which keyword their
+     * own domain type happened to use, in files this emitter does not own.
      *
-     * **Emitted rather than compared away.** The document says `additionalProperties`, the validator
-     * says `.loose()`, so the type saying it too is what makes all three agree. Relaxing the comparison
-     * instead would hide the disagreement rather than remove it, and a looser comparison stops catching
-     * the drift it exists for.
+     * Measured on one consumer's document: **58 of 101 components open, 26 of those nesting another
+     * open component**, so the obligation cost a structural deep copy of the response tree per
+     * response. One spread satisfies one level and does not reach the next, which is the whole shape
+     * of the failure - see `test/contractshape/`.
      *
-     * The dictionary case above returns before this: a model with an indexer and NO declared properties
-     * is a `Record<...>` outright rather than an object with a catchall.
+     * What arrives is still described honestly, on the surface derived from the validator:
+     * `schemas.gen.ts` exports `Exact<z.infer<typeof x>>`, which carries the index signature because
+     * a `.loose()` parse really does. Two surfaces, two directions, neither lying.
      */
-    const catchall = indexerKey === "string" && indexer !== undefined && !isNeverType(indexer.value)
-        ? [`\t[key: string]: ${typeToTs(program, indexer.value)};`]
-        : [];
-    const all = [...entries, ...catchall];
-    return all.length === 0 ? "{}" : `{\n${all.join("\n")}\n}`;
+    return entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
 }
 /**
  * A property line, including its optionality marker.

package/dist/src/zod.js

@@ -783,8 +783,13 @@ function modelToZod(program, model) {
      * Measured on Zod 4.4.3: `.strict()`, `.loose()` and `.catchall()` all read `shape` eagerly, so
      * each one fires the getter during module initialisation and throws `Cannot access 'X' before
      * initialization` - the very thing the getter exists to avoid. `z.strictObject` and
-     * `z.looseObject` take the same shape without reading it. The suffix form stays everywhere else,
-     * so a model that does not recurse emits exactly the text it emitted before.
+     * `z.looseObject` take the same shape without reading it.
+     *
+     * **So the constructor form is used wherever it exists, not only where a cycle forces it.** It is
+     * also what Zod 4 asks for: its own types say "Consider `z.looseObject(A.shape)` instead" on
+     * `.loose()` and `.strict()`, and `.passthrough()` is deprecated outright. Emitting one spelling
+     * means a model that gains a back edge later does not silently change form, and the eager-`shape`
+     * hazard above stops being something this walk has to keep reasoning about.
      *
      * **A TYPED catchall has no constructor form, and that used to be a refusal.** There is nowhere
      * safe to put the getter - `.catchall()` reads `shape` eagerly - so the cycle was reported as
@@ -796,11 +801,11 @@ function modelToZod(program, model) {
     const lazily = members.some((member) => member.deferred);
     const constructible = suffix === "" || suffix === ".loose()";
     const shape = entries.length === 0 ? "{}" : `{\n${entries.join("\n")}\n}`;
-    const body = lazily
-        ? constructible
-            ? `${suffix === ".loose()" ? "z.looseObject" : strict === ".strict()" ? "z.strictObject" : "z.object"}(${shape})`
-            : `z.lazy(() => z.object(${shape})${suffix}${strict})`
-        : `z.object(${shape})${suffix}${strict}`;
+    const body = constructible
+        ? `${suffix === ".loose()" ? "z.looseObject" : strict === ".strict()" ? "z.strictObject" : "z.object"}(${shape})`
+        : lazily
+            ? `z.lazy(() => z.object(${shape})${suffix}${strict})`
+            : `z.object(${shape})${suffix}${strict}`;
     return applyConstraints(program, body, model);
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.16.0",
+  "version": "0.18.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",