typespec-http-zod 0.20.0 → 0.22.0

package/dist/src/api.d.ts

@@ -263,6 +263,8 @@ export interface EmittedRoute {
         readonly headers: readonly {
             readonly name: string;
             readonly property: string;
+            /** The TypeScript type of the value, so a server emitter can put it in a signature. */
+            readonly type: string;
         }[];
     }[];
     /**
@@ -302,6 +304,18 @@ export interface EmittedRoute {
         value: boolean | string;
         status: number;
     } | undefined;
+    /**
+     * The property a handler sets to choose between several declared success statuses, and the
+     * statuses it may carry - read from a `@statusCode` typed as a union of literals.
+     *
+     * **Published because the handler has to be able to SAY it.** The property is HTTP metadata, so it
+     * is stripped from the body schema (correctly - it is not body), which means a server emitter has
+     * to add it back to the type a handler returns or the arms name something unsatisfiable.
+     */
+    readonly statusSelector: {
+        property: string;
+        statuses: readonly number[];
+    } | undefined;
     /** The schema for the SECOND success status, when the operation declares two distinct arms. */
     readonly alternateResponseSchema: string | undefined;
 }

package/dist/src/api.js

@@ -1,8 +1,9 @@
 import { emitFile, getDoc, getEncode, getSummary, isErrorModel, isNeverType, isVoidType, NoTarget, resolvePath, } from "@typespec/compiler";
-import { getAuthenticationForOperation, resolveRequestVisibility, Visibility, } from "@typespec/http";
+import { getAuthenticationForOperation, isStatusCode, resolveRequestVisibility, Visibility, } from "@typespec/http";
 import { getOperationId, resolveOperationId } from "@typespec/openapi";
 import { reportDiagnostic } from "./lib.js";
 import { SchemaRegistry, TypeRegistry } from "./registry.js";
+import { typeToTs } from "./types.js";
 import { resolveStreamModule, streamedTypeOf, withStreamModule } from "./streams.js";
 import { resolveVersioningModule, serviceSnapshots } from "./versioning.js";
 import { collectExternalImports, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, wireKindOf, withContractsPackage, withSealedObjects, withVisibility, } from "./zod.js";
@@ -306,7 +307,7 @@ function isSuccessKey(status) {
  * body and gives each one under its WIRE name with the declaring property behind it. Deriving either
  * name any other way would be a second spelling of a fact the compiler already resolved.
  */
-function responseHeadersOf(operation) {
+function responseHeadersOf(program, operation) {
     const byStatus = new Map();
     for (const response of operation.responses) {
         const status = response.statusCodes;
@@ -316,7 +317,14 @@ function responseHeadersOf(operation) {
         for (const content of response.responses) {
             for (const [name, property] of Object.entries(content.headers ?? {})) {
                 if (!headers.some((existing) => existing.name === name)) {
-                    headers.push({ name, property: property.name });
+                    /**
+                     * **The TYPE too, because a handler has to be able to SET this.** A `@header`
+                     * property is stripped from the body schema - correctly, it is not body - so a server
+                     * emitter has to put it back into the type a handler returns, and it cannot do that
+                     * from a name alone. Measured before this existed: an arm naming `contentType` and
+                     * `metadata` against a handler declared `Awaitable<Result<void>>`.
+                     */
+                    headers.push({ name, property: property.name, type: typeToTs(program, property.type) });
                 }
             }
         }
@@ -579,6 +587,36 @@ function statusDiscriminatorOf(operation, statuses) {
     }
     return undefined;
 }
+/**
+ * How a handler says WHICH success status it means, when the spec declares more than one.
+ *
+ * **The `@statusCode` property is the selector, and it is the one the spec already wrote.**
+ * `model Created { @statusCode statusCode: 200 | 201; @body body: Item }` declares both statuses and
+ * names the property that chooses between them, so nothing has to be inferred from the body's shape.
+ *
+ * That inference is what {@link statusDiscriminatorOf} does, and it needs a required literal property
+ * on one of the bodies. Measured across the whole conformance corpus: it fires ZERO times, so before
+ * this the second arm had never been emitted by any spec at all - `armFor` could not select a status
+ * that was never written. Both remain: a discriminator still serves two DIFFERENT response models,
+ * this serves one model declaring a union of statuses.
+ *
+ * All statuses of such a model share one body by construction - it is one model - so every arm
+ * carries the same schema and only the status and the selector value differ.
+ */
+function statusSelectorOf(program, operation, statuses) {
+    if (statuses.length < 2)
+        return undefined;
+    for (const response of operation.responses) {
+        const type = response.type;
+        if (type === undefined || type.kind !== "Model")
+            continue;
+        for (const [name, property] of type.properties) {
+            if (isStatusCode(program, property))
+                return { property: name, statuses };
+        }
+    }
+    return undefined;
+}
 /** The emitted schema for a specific success status, used for the second arm of a dual-status op. */
 function alternateSchemaFor(operation, status, registry) {
     const body = successBodyOf(operation, status);
@@ -1039,6 +1077,7 @@ export function collectRoutes(program, registry, service) {
             const requestVisibility = resolveRequestVisibility(program, operation.operation, operation.verb);
             const statusCodes = successStatusesOf(operation);
             const discriminator = statusDiscriminatorOf(operation, statusCodes);
+            const statusSelector = statusSelectorOf(program, operation, statusCodes);
             /**
              * A `bytes` body means the BYTES are the contract.
              *
@@ -1145,7 +1184,7 @@ export function collectRoutes(program, registry, service) {
                 // them under the ambient request visibility declared six components under the wrong
                 // suffix - measured: type/model/visibility gained six divergences.
                 errorArms: withVisibility(program, Visibility.Read, () => errorArmsOf(program, operation, registry)),
-                responseHeaders: responseHeadersOf(operation),
+                responseHeaders: responseHeadersOf(program, operation),
                 responseMediaTypes: responseMediaTypesOf(operation),
                 scopes: [
                     ...new Set((getAuthenticationForOperation(program, operation.operation)?.options ?? []).flatMap((option) => option.schemes.flatMap((scheme) => scheme.type === "oauth2"
@@ -1154,6 +1193,7 @@ export function collectRoutes(program, registry, service) {
                 ],
                 noAuth: noAuthFor(program, operation),
                 statusBy: discriminator,
+                statusSelector,
                 /**
                  * **Each arm is validated against its OWN shape.**
                  *
@@ -1461,7 +1501,22 @@ function responseArmsOf(route, response, alternate) {
             .join(", ");
         return `, headers: [${rendered}]`;
     };
-    if (route.statusBy === undefined) {
+    if (route.statusSelector !== undefined) {
+        /**
+         * **One arm per declared status, keyed on the property the spec already named.**
+         *
+         * The selector arms come first and the default last, the same order the discriminator below
+         * uses: anything scanning for a match wants the specific ones before the fallback. Every arm
+         * carries the same schema because a `@statusCode` union is ONE model - the statuses differ,
+         * the body does not.
+         */
+        const { property, statuses } = route.statusSelector;
+        for (const status of statuses.filter((candidate) => candidate !== route.statusCode)) {
+            arms.push(`{ status: ${status}, schema: ${primary}${mediaTypesFor(status)}${headersFor(status)}, when: { property: ${JSON.stringify(property)}, value: ${status} } }`);
+        }
+        arms.push(`{ status: ${route.statusCode}, schema: ${primary}${mediaTypesFor(route.statusCode)}${headersFor(route.statusCode)} }`);
+    }
+    else if (route.statusBy === undefined) {
         arms.push(`{ status: ${route.statusCode}, schema: ${primary}${mediaTypesFor(route.statusCode)}${headersFor(route.statusCode)} }`);
     }
     else {
@@ -1659,8 +1714,21 @@ function renderRequestTypes(entries, responses, registry) {
     const lookup = entries
         .map((entry) => `\t${entry.operationId}: ${upperFirst(entry.operationId)}Input;`)
         .join("\n");
-    return `${generatedBanner()}
-/**
+    /**
+     * **Emitted only where an operation has something to flatten.**
+     *
+     * A generated file has to pass the lint of whatever project it lands in, and `noUnusedLocals`
+     * makes an unused type declaration an error. A service whose operations take no input at all -
+     * two parameterless `GET`s, which is where a health check starts and therefore where every new
+     * consumer starts - got this declaration and no use of it, so `requests.gen.ts` did not compile.
+     * `TS6196: 'Simplify' is declared but never used.` Third of its kind, after the unconditional
+     * `zValidator` and `z` imports.
+     *
+     * Decided from the aliases actually rendered rather than by searching the output for the name.
+     */
+    const simplifyHelper = inputs.length === 0
+        ? ""
+        : `/**
  * Flattens an intersection into a single object type.
  *
  * Without it, \`Body & { filingId: string }\` and the equivalent flat object are structurally the
@@ -1668,7 +1736,8 @@ function renderRequestTypes(entries, responses, registry) {
  * this file with the emitted Zod would fail on correct code.
  */
 type Simplify<T> = { [K in keyof T]: T[K] } & {};
-
+`;
+    return `${generatedBanner()}${simplifyHelper}
 /**
  * The same shape, tolerant of \`readonly\`.
  *

package/dist/src/runtime.d.ts

@@ -78,9 +78,17 @@ 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 | string;
+        readonly value: boolean | number | string;
     };
 }
 /**

package/package.json

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