typespec-http-zod 0.17.0 → 0.19.0

package/dist/src/api.js

@@ -1,4 +1,4 @@
-import { emitFile, getDoc, getEncode, getSummary, isErrorModel, isNeverType, isVoidType, resolvePath, } from "@typespec/compiler";
+import { emitFile, getDoc, getEncode, getSummary, isErrorModel, isNeverType, isVoidType, NoTarget, resolvePath, } from "@typespec/compiler";
 import { getAuthenticationForOperation, resolveRequestVisibility, Visibility, } from "@typespec/http";
 import { getOperationId, resolveOperationId } from "@typespec/openapi";
 import { reportDiagnostic } from "./lib.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},`;
@@ -643,26 +655,60 @@ function multipartSchemaOf(body, registry) {
     return name === undefined ? shape : registry.declareNamed(name, () => shape);
 }
 /**
- * `bytes`, or a model built on `File` - the parts openapi3 publishes as an empty schema.
- *
- * **A narrowed type for a `File` part was tried in `0.17.0` and reverted; do not try it again
- * without reading this.** The ask was reasonable - `input.file.name` needs a cast today - and every
- * way of granting it breaks something load-bearing:
- *
- * - `z.custom<FileLike>()` throws in `z.toJSONSchema` ("Custom types cannot be represented"),
- *   which silently removes those schemas from the differential that compares this emitter's
- *   validators against the document. Measured: four corpus schemas dropped out.
- * - `z.unknown().refine(guard)` serialises fine and narrows correctly, but REJECTS a value the
- *   published contract permits, and `test/vocabulary.test.ts` refuses it by class for that reason.
- * - Narrowing the type without a check makes the two artefacts disagree and asserts a shape nothing
- *   established.
- *
- * The root cause is upstream and visible in this package's own fixtures: `@typespec/openapi3`
- * publishes a bare `{}` for a File part even in 3.1, where `contentMediaType` could express it, and
- * even when the part declares a specific content type. **The day the document says what the part is,
- * the validator may say it too and the type follows for free.** Until then `unknown` is the only
- * honest answer, and a consumer narrows at the boundary.
+ * 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") {
         for (let scalar = type; scalar !== undefined; scalar = scalar.baseScalar) {
@@ -1214,8 +1260,20 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
      *
      * `z.infer` of `.optional()` gives `p?: T | undefined`, which under `exactOptionalPropertyTypes`
      * admits an explicitly-undefined property. **JSON has no `undefined`**, and the document says the
-     * same thing by leaving the property out of `required`, so the inferred type was wider than both
-     * the contract and the wire and a consumer had to strip it at the boundary.
+     * same thing by leaving the property out of `required`, so the inferred type is wider than the
+     * wire and a consumer reading a payload had to strip it at the boundary.
+     *
+     * **It does NOT match the contract type, and this docblock used to claim it did.** The
+     * contract types in `requests.gen.ts` keep `?: T | undefined` on purpose: they are the floor a
+     * PRODUCER supplies, and `{ p: undefined }` serialises identically to omitting `p`, so refusing
+     * it would cost every producer a conditional spread and buy the wire nothing. Measured when this
+     * was "fixed" to agree: `(ctx, input) => ok(input)` - return what you were given - stopped
+     * compiling.
+     *
+     * So the two surfaces differ on this axis deliberately, exactly as they differ on openness: this
+     * one is the narrow view of what ARRIVES, the contract type is the permissive floor for what you
+     * may SEND. A reader comparing them will find them unequal and should - the emitted assertion
+     * pairs the contract against raw `z.infer`, not against this.
      *
      * Derived from the same schema rather than hand-written beside it, so there is still one source of
      * truth: a mapped type cannot drift from the thing it maps.
@@ -1617,8 +1675,14 @@ type Simplify<T> = { [K in keyof T]: T[K] } & {};
  * 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.
+ *
+ * **Exported, because a consumer needs it for a NAMED type and could not reach it.** It was applied
+ * to \`WireOutputs\` and declared locally, so a codebase whose layers hand back \`readonly T[]\` had
+ * the producer view sitting in the file it was already importing and no way to name it. Measured on
+ * one service: 2 contract methods returning \`readonly T[]\` and 35 readonly array properties, none
+ * of them expressible against the published shape.
  */
-type Produced<T> = T extends readonly (infer Element)[]
+export type Produced<T> = T extends readonly (infer Element)[]
 	? readonly Produced<Element>[]
 	: T extends object
 		? { readonly [K in keyof T]: Produced<T[K]> }
@@ -1826,6 +1890,36 @@ export async function emitHttpZod(context, wrapper = {}) {
      * there means a server emitter follows without knowing this rule exists.
      */
     const distinctServices = new Set(snapshots.map((snapshot) => snapshot.service.namespace.name));
+    /**
+     * **Every service must seal the same way, because `@typespec/openapi3` has no per-service
+     * options.**
+     *
+     * This option exists only so that two emitters answering the same question about the same models
+     * give the same answer - it is stated twice on purpose, and its own docblock says to set it to
+     * whatever openapi3 is set to. openapi3 applies ONE value to the whole program. So services that
+     * seal differently cannot both be mirrored: whichever way openapi3 is configured, at least one
+     * service publishes a document that disagrees with the validator generated beside it. Sealed here
+     * and silent there refuses a payload the document permits; the reverse publishes a strictness the
+     * runtime does not enforce.
+     *
+     * Reported once for the program rather than once per service, because the fault is the
+     * DISAGREEMENT and no single service is the wrong one.
+     */
+    const sealings = new Map();
+    for (const snapshot of snapshots) {
+        const name = snapshot.service.namespace.name;
+        const perService = options.services?.[name];
+        sealings.set(name, perService?.["seal-object-schemas"] ?? options["seal-object-schemas"] ?? false);
+    }
+    if (new Set(sealings.values()).size > 1) {
+        const sealed = [...sealings.entries()].filter(([, seals]) => seals).map(([name]) => name);
+        const open = [...sealings.entries()].filter(([, seals]) => !seals).map(([name]) => name);
+        reportDiagnostic(context.program, {
+            code: "unmirrorable-seal",
+            target: NoTarget,
+            format: { sealed: sealed.join(", "), open: open.join(", ") },
+        });
+    }
     for (const snapshot of snapshots) {
         beginOperationIds();
         const service = snapshot.service;

package/dist/src/lib.d.ts

@@ -125,6 +125,9 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "empty-union": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
+    "unmirrorable-seal": {
+        readonly default: import("@typespec/compiler").CallableMessage<["sealed", "open"]>;
+    };
     "unknown-key-vocabulary": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "service"]>;
     };
@@ -138,7 +141,7 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
 }, EmitterOptions, never>;
-export declare const reportDiagnostic: <C extends "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
+export declare const reportDiagnostic: <C extends "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
@@ -151,6 +154,9 @@ export declare const reportDiagnostic: <C extends "duplicate-declaration" | "dup
     "empty-union": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
+    "unmirrorable-seal": {
+        readonly default: import("@typespec/compiler").CallableMessage<["sealed", "open"]>;
+    };
     "unknown-key-vocabulary": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "service"]>;
     };
@@ -176,6 +182,9 @@ export declare const reportDiagnostic: <C extends "duplicate-declaration" | "dup
     "empty-union": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
+    "unmirrorable-seal": {
+        readonly default: import("@typespec/compiler").CallableMessage<["sealed", "open"]>;
+    };
     "unknown-key-vocabulary": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "service"]>;
     };

package/dist/src/lib.js

@@ -127,6 +127,19 @@ const diagnostics = {
      * consumer can iterate a closed key set at run time; a typo would emit no tuple at all, and "the
      * vocabulary is missing" looks exactly like "the vocabulary is empty" at the point it is used.
      */
+    /**
+     * Two services sealing differently, which `@typespec/openapi3` cannot mirror.
+     *
+     * An error rather than a warning, on the same footing as every other divergence here: the output
+     * is a document and a validator that contradict each other about whether a property may exist,
+     * and shipping that is worse than failing the build.
+     */
+    "unmirrorable-seal": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'seal-object-schemas' resolves to true for ${"sealed"} and false for ${"open"}, and '@typespec/openapi3' has no per-service options - it applies one value to the whole program. So one of these services would publish a document that disagrees with the validator emitted beside it. Give every service the same value, or split the surfaces into separate compiles.`,
+        },
+    },
     "unknown-key-vocabulary": {
         severity: "error",
         messages: {

package/dist/src/types.js

@@ -256,7 +256,23 @@ export function propertyToTs(program, property, wireName) {
      */
     if (property.defaultValue !== undefined)
         return `${key}: ${value};`;
-    // `exactOptionalPropertyTypes` is on, and Zod's `.optional()` infers `T | undefined`.
+    /**
+     * **`?: T | undefined`, and dropping the `| undefined` was tried in `0.19.0` and reverted.**
+     *
+     * It looks wrong - JSON has no `undefined`, so a wire type saying `?: T` reads more honest, and
+     * it would make this walk agree with `Exact<z.infer<...>>` on the schemas side. **Measured, it
+     * breaks the most ordinary handler there is.** `createWidget: (ctx, input) => ok(input)` - return
+     * what you were given - stopped compiling, because what a handler RECEIVES carries
+     * `?: T | undefined` and what it would then have to SUPPLY did not.
+     *
+     * That is the difference from the index signature and from `readonly`, which look like the same
+     * class and are not: removing those two makes MORE values assignable, and removing this one makes
+     * fewer. `{ retiredOn: undefined }` serialises to `{}`, identical to omitting the key, so
+     * permitting it costs the wire nothing and refusing it costs every producer a conditional spread.
+     *
+     * The two emitted surfaces differ here on purpose, exactly as they do on openness:
+     * `schemas.gen.ts` exports the narrow received view, this walk emits the permissive floor.
+     */
     return property.optional ? `${key}?: ${value} | undefined;` : `${key}: ${value};`;
 }
 /** Installed by the registry so a named model is declared once and referenced everywhere else. */

package/package.json

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