typespec-http-zod 0.26.0 → 0.28.0

package/README.md

@@ -177,12 +177,12 @@ then a range such as `4XX`, then `default`.
 
 ## What it emits
 
-| file                   | contents                                                                                                  | emitted when                  |
-| ---------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| `schemas.gen.ts`       | component schemas, per-operation path, query, header, body and response validators, and the response arms | always                        |
-| `requests.gen.ts`      | framework-free TypeScript types, with no imports                                                          | `contracts-output-dir` is set |
-| `vocabularies.gen.ts`  | each enum's members as a runtime tuple                                                                    | `contracts-output-dir` is set |
-| `wire-contract.gen.ts` | assertions pairing the emitted Zod against those types                                                    | that and `contracts-package`  |
+| file                   | contents                                                                                                                                                          | emitted when                  |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `schemas.gen.ts`       | component schemas, per-operation path, query, header, body and response validators, and the response arms                                                         | always                        |
+| `requests.gen.ts`      | framework-free TypeScript types, with no imports: the models, and every operation's input, success bodies and result (`WireInputs`, `WireOutputs`, `WireResults`) | `contracts-output-dir` is set |
+| `vocabularies.gen.ts`  | each enum's members as a runtime tuple                                                                                                                            | `contracts-output-dir` is set |
+| `wire-contract.gen.ts` | assertions pairing the emitted Zod against those types                                                                                                            | that and `contracts-package`  |
 
 `wire-contract.gen.ts` is not imported by any other file. The file contains type-level assertions
 pairing each generated validator with its contract type, so a mismatch between the two is a compile

package/dist/src/api.d.ts

@@ -1,8 +1,11 @@
 import { type EmitContext, type Program, type Type } from "@typespec/compiler";
 import { type HttpOperation, type HttpService } from "@typespec/http";
 import { SchemaRegistry } from "./registry.js";
+import { type StatusKey } from "./results.js";
 import { type EmittedPathSegment } from "./uri-template.js";
 export type { EmittedPathSegment } from "./uri-template.js";
+export { CONTENTLESS_STATUS_CODES, STATUS_CODES } from "./statuses.js";
+export { type BodyServing, isJsonMediaType, isMediaRange, isTextualMediaType, mediaTypeEssenceOf, mediaTypeTypeOf, type ResponseFacts, type ResultMember, resultMembersOf, type StatusKey, statusCodesOf, } from "./results.js";
 /**
  * `typespec-http-zod` - Zod validators and framework-free contract types from a TypeSpec HTTP
  * service, agreeing with the OpenAPI document `@typespec/openapi3` publishes from the same source.
@@ -64,13 +67,6 @@ export declare function successStatusOf(operation: HttpOperation): number | unde
  * asserts the two stay in step.
  */
 export declare function successStatusesOf(operation: HttpOperation): number[];
-/**
- * A status as the DOCUMENT keys it: an exact code, a `4XX` bucket, or the catch-all.
- *
- * `"default"` is kept as itself rather than mapped to a number. The document means "any status not
- * listed above", and inventing one would be answering a question the contract left open.
- */
-export type StatusKey = number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
 /**
  * A header one response declares, as a handler has to supply it.
  *
@@ -83,6 +79,15 @@ export interface EmittedResponseHeader {
     readonly name: string;
     /** The TypeScript type of the value, so a server emitter can put it in a signature. */
     readonly type: string;
+    /**
+     * The Zod expression for the value, so a server can check what it is about to send.
+     *
+     * The TYPE above constrains what a handler may return at compile time; this constrains what
+     * actually goes on the wire, which is the same split `schema` and the contract types already make
+     * for a body. A value that crossed a boundary the type system cannot see into - a service binding,
+     * a cast - is exactly what it catches.
+     */
+    readonly schema: string;
     /** The document's `required: false`. */
     readonly optional: boolean;
 }
@@ -298,6 +303,8 @@ export interface EmittedRoute {
      * request. It read as "the parameters" and was the field an adopter reached for first.
      */
     readonly pathSchema: string | undefined;
+    /** Cookie parameters, as one object schema, or `undefined` where the operation declares none. */
+    readonly cookieSchema: string | undefined;
     readonly querySchema: string | undefined;
     /**
      * The query OBJECT itself, which differs from `querySchema` only where a form-exploded record or
@@ -317,10 +324,29 @@ export interface EmittedRoute {
     /**
      * The input property that receives the UNPARSED body, when the operation declares one.
      *
-     * A `bytes` body means the bytes themselves are the contract: where a signature covers exactly
-     * what arrived, parsing and re-serialising would verify a different string than the sender signed.
+     * Three bodies are handed over unparsed. A `bytes` body, because the bytes themselves are the
+     * contract: where a signature covers exactly what arrived, parsing and re-serialising would verify
+     * a different string than the sender signed. An `Http.File` body, whose contents are the body. And
+     * a body declared only under media types nothing can parse into it, such as a model as
+     * `application/xml`, which is the text that arrived, or as `application/octet-stream`, which is
+     * the bytes. {@link rawBodyBinary} says which are bytes.
      */
     readonly rawBodyProperty: string | undefined;
+    /**
+     * Whether the raw body is BYTES - handed over as the unread stream - rather than the text a
+     * signature covers. A `bytes` body is bytes under a binary media type and text under a JSON one;
+     * an `Http.File` body is bytes whatever its media type, which is why a server cannot read this off
+     * {@link requestContentTypes}: a file declared `application/json` looks like a JSON body there.
+     * `false` where there is no raw body.
+     */
+    readonly rawBodyBinary: boolean;
+    /**
+     * **The raw body is declared with a schema nothing checks it against**: it is declared only under
+     * media types nothing can parse into it, such as a model as `application/xml`. A `bytes` or
+     * `Http.File` body declares nothing to check, so it is not this. The request-side twin of
+     * {@link ResultMember.unvalidated}.
+     */
+    readonly rawBodyUnvalidated: boolean;
     /**
      * The input property a PARSED body arrives under, where it must not be spread into the parameters.
      *
@@ -416,6 +442,22 @@ export interface RouteSchemaNames {
      */
     readonly queryFields: string | undefined;
     readonly header: string | undefined;
+    /**
+     * **The `accept` the negotiation selects this operation by**, on a route several operations
+     * share. `header` leaves it out there, because it chooses the operation rather than constraining
+     * one, and the operation's input still declares it: the one value that reaches this operation is
+     * its own literal, so a handler receives exactly that. `undefined` wherever `header` validates
+     * `accept` itself, or the operation declares no literal one.
+     */
+    readonly selectedAccept: {
+        readonly name: string;
+        readonly value: string;
+    } | undefined;
+    /**
+     * Cookie parameters. **Optional on the interface, so a server emitter that does not read it yet
+     * still compiles** - this arrived after the other four and two emitters consume this type.
+     */
+    readonly cookie?: string | undefined;
     readonly body: string | undefined;
     /**
      * The identifier each response's body is declared under, parallel to `EmittedRoute.responses` and
@@ -428,6 +470,11 @@ export interface RouteSchemaNames {
     readonly arms: readonly {
         readonly status: StatusKey;
         readonly schema: string | undefined;
+        /**
+         * The identifier holding this status's declared response headers, where it declares any.
+         * **Optional on the interface**, so a server emitter that does not check them yet still builds.
+         */
+        readonly headers?: string | undefined;
     }[];
     /**
      * The `readonly ResponseArm[]` const - what the operation may answer with, and with which body.
@@ -454,6 +501,13 @@ export interface EmittedService {
     readonly routes: readonly EmittedRoute[];
     /** The identifiers every per-operation validator was declared under, keyed by operation id. */
     readonly schemaNames: ReadonlyMap<string, RouteSchemaNames>;
+    /**
+     * **The operation each route was collected from, keyed by operation id**, so a wrapping emitter
+     * reading its doc comment, tags or diagnostic target reads the right one. Verb and path do not
+     * identify an operation: `@sharedRoute` puts several on one, and a lookup by them answers the
+     * same operation for each - its description became every member's, and its tags selected them.
+     */
+    readonly operations: ReadonlyMap<string, HttpOperation>;
     /** Where this service's artefacts were written - a server emitter writes its own beside them. */
     readonly outputDir: string;
     /** Already resolved through the per-service overrides, so a caller re-reads nothing. */