typespec-http-zod 0.25.0 → 0.26.0

package/dist/src/api.d.ts

@@ -1,6 +1,8 @@
 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 EmittedPathSegment } from "./uri-template.js";
+export type { EmittedPathSegment } from "./uri-template.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.
@@ -69,6 +71,70 @@ export declare function successStatusesOf(operation: HttpOperation): number[];
  * 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.
+ *
+ * **The WIRE name only.** A result a handler returns is keyed by what the response sets, which is
+ * what the document publishes under `responses.<status>.headers`. The TypeSpec property behind it
+ * used to be carried beside the name so a runtime could read the value off a flattened result; that
+ * made the handler contract depend on a property name the document never states.
+ */
+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 document's `required: false`. */
+    readonly optional: boolean;
+}
+/**
+ * One response the document declares for an operation, keyed the way the document keys it.
+ *
+ * **Complete on its own, because a server emitter types a handler's return one member per arm.**
+ * The route used to carry these facts in five separate projections - a primary status and body, a
+ * list of failure arms, headers for numeric statuses only, media types for numeric statuses only,
+ * and a selector for choosing between successes - and each projection had a hole the others did not:
+ *
+ * - a range or `default` arm never carried its headers or media types;
+ * - a second success status carried the FIRST status's body, because the selector assumed one model;
+ * - a failure's inline body was an expression nothing outside the arm list could name;
+ * - an operation whose only success was a `2XX` range was dropped without a diagnostic.
+ *
+ * One record per status, built in one pass over `@typespec/http`'s own resolution, has no such gaps
+ * to keep in step.
+ */
+export interface EmittedResponse {
+    readonly status: StatusKey;
+    /** This status's body, as an emitted Zod expression, or `undefined` where it declares none. */
+    readonly schema: string | undefined;
+    /**
+     * Every media type the document names for this status, in declaration order.
+     *
+     * Empty exactly when the response carries no body. **A single type is still carried**, because
+     * assuming the one type is JSON is how a `text/plain` arm became indistinguishable from a JSON one.
+     */
+    readonly contentTypes: readonly string[];
+    readonly headers: readonly EmittedResponseHeader[];
+    /**
+     * The body is raw binary, so `schema` is `z.unknown()` - see {@link isRawBinaryMediaType}. A server
+     * serves such a body as bytes or a stream rather than serialising it.
+     */
+    readonly binary: boolean;
+    /**
+     * The body is a stream of events or lines (`@typespec/streams`). The schema describes the stream as
+     * the document does, a string, which is not something a server validates a stream against.
+     */
+    readonly streamed: boolean;
+    /**
+     * The body's type is a string, so under a media type that is not JSON it IS the text served.
+     *
+     * **The fact a server needs to serve a non-JSON body at all.** A `string` declared as `text/plain`
+     * is validated and written as is; a MODEL declared as `application/xml` has no serialisation an
+     * emitter can derive from the document, so the text has to come from the application. Forty arms in
+     * the conformance corpus are the second kind and three are the first, and a server that could not
+     * tell them apart would either refuse the text or validate XML against a JSON schema.
+     */
+    readonly textual: boolean;
+}
 /**
  * Whether the operation declares `@useAuth(NoAuth)` - no caller is established for it.
  *
@@ -153,9 +219,36 @@ export interface EmittedRoute {
      * carries one of each.
      */
     readonly reservedPathParameters: readonly string[];
-    readonly statusCode: number;
-    readonly statusCodes: readonly number[];
-    /** Media types the success body can be served as - the basis for `Accept` negotiation. */
+    /**
+     * **The route as a server has to mount it: one entry per `/` segment, read from the operation's
+     * RFC 6570 `uriTemplate`.** `path` cannot say this, because `@typespec/http` strips every operator
+     * from it: `array{.param*}` (`array.a.b`), `array{;param}` (`array;param=a,b`) and
+     * `array{/param}` (`array/a,b`) all reach `path` as `array{param}`. A router mounted from `path`
+     * answered 404 to 31 of the requests `@typespec/http-specs` declares conformant.
+     *
+     * An expression segment names its parameter's wire name, the literal text around it in the same
+     * segment, its operator and explode modifier, and whether it is optional or reserved. A server
+     * hands `pathSchema` the TEXT of that segment (for an exploding `/` expression, of every segment
+     * after it), and `pathSchema` undoes the expansion. A segment holding more than one expression is
+     * `unsupported`: no segment router can split it.
+     */
+    readonly pathSegments: readonly EmittedPathSegment[];
+    /**
+     * A query string written into the route itself, as the pairs it spells:
+     * `/items?fixed=true{&param}` carries `[["fixed", "true"]]`. It identifies the route as much as
+     * the path does, and it is never part of `pathSegments`. Empty when there is none.
+     */
+    readonly literalQuery: readonly (readonly [string, string])[];
+    /**
+     * Every response the document declares, one per status key, in OpenAPI's precedence order. See
+     * {@link EmittedResponse}.
+     */
+    readonly responses: readonly EmittedResponse[];
+    /**
+     * Media types the lowest exact success status can be served as - the basis for `Accept`
+     * negotiation between several operations sharing one route. Empty where that status carries no
+     * body, or where the operation declares no exact success status at all.
+     */
     readonly responseContentTypes: readonly string[];
     /**
      * Media types the request body may be SENT as.
@@ -177,6 +270,20 @@ export interface EmittedRoute {
      * writes the server, exactly as `responseContentTypes` leaves negotiation to it.
      */
     readonly requestContentTypes: readonly string[];
+    /**
+     * Whether the request body IS the text a caller sends, rather than a structure parsed out of it.
+     *
+     * **A server cannot answer this from the media type alone**, and `typespec-hono` had no way to ask:
+     * `@body body: string` under `text/plain` has no JSON, form or multipart reader, so the body was
+     * never read and the handler was handed nothing. The same media type carrying a MODEL has no
+     * serialisation this emitter can derive, and must still be refused - so the question is about the
+     * TYPE, which only this package resolves.
+     *
+     * True where the body's type is a string (a scalar based on `string`, a literal, a template, or a
+     * union of those - the same rule {@link EmittedResponse.textual} applies to a response) and the
+     * document declares no JSON media type for it.
+     */
+    readonly requestTextual: boolean;
     readonly summary: string | undefined;
     readonly requestSchema: string | undefined;
     /**
@@ -192,6 +299,13 @@ export interface EmittedRoute {
      */
     readonly pathSchema: string | undefined;
     readonly querySchema: string | undefined;
+    /**
+     * The query OBJECT itself, which differs from `querySchema` only where a form-exploded record or
+     * model is gathered into it: `querySchema` is then `z.preprocess(gather, <this>)`, the validator a
+     * request's raw query goes through, and this is the object with a `.shape` a consumer building
+     * arguments from already-structured JSON can spread. Equal to `querySchema` otherwise.
+     */
+    readonly queryFieldsSchema: string | undefined;
     readonly headerSchema: string | undefined;
     /** The header schema minus `accept`, used when this route's operations negotiate. */
     readonly negotiatedHeaderSchema: string | undefined;
@@ -200,21 +314,6 @@ export interface EmittedRoute {
         readonly name: string;
         readonly value: string;
     } | undefined;
-    /**
-     * `undefined` when the operation's success response carries no body - a `204`, or any `@delete`
-     * returning `void`.
-     *
-     * **This used to be required, and requiring it silently deleted routes.** `collectRoutes`
-     * skipped any operation `successBodyOf` could not answer for, with no diagnostic: measured across
-     * `@typespec/http-specs`, the document declared 540 operations and this emitter mounted 256, with
-     * 282 of the 284 missing ones bodyless. `payload/multipart` produced `GENERATED_ROUTES = []`
-     * against seventeen declared operations and compiled clean. Even `parameters/path` lost both of
-     * its operations, because they answer `NoContentResponse`.
-     *
-     * A bodyless success is ordinary HTTP, not an edge case. The route is emitted; a server
-     * answers the declared status with no body.
-     */
-    readonly responseSchema: string | undefined;
     /**
      * The input property that receives the UNPARSED body, when the operation declares one.
      *
@@ -254,56 +353,19 @@ export interface EmittedRoute {
      * permits, in a shape that contract forbids.
      */
     readonly optionalBody: boolean;
-    /** Declared failures, each with the schema for its OWN body, in OpenAPI's precedence order. */
-    readonly errorArms: readonly {
-        readonly status: StatusKey;
-        readonly schema: string | undefined;
-    }[];
-    /**
-     * The headers each response status declares, as the document publishes them.
-     *
-     * **`deps.respond` could not set a header the contract promises.** A spec may declare `@header` on
-     * a response model - a `Location` on a 302, a `Link`, a correlation echo - and the document
-     * publishes it under `responses.<code>.headers`, but the arm carried a status and a body schema and
-     * nothing else. So the server could not answer faithfully, and a redirect could not be served at
-     * all. Reported as blocking by a consumer, and it is a fact the document already states.
-     *
-     * **Both names are carried, because two different things need them.** `name` is the WIRE name,
-     * which is what the response sets; `property` is the name on the returned value, which is where the
-     * value is read from. `@header("x-correlation-id") correlationId: string` is `x-correlation-id` on
-     * the wire and `correlationId` in the handler's result, and an emitter given only one of them would
-     * have to guess the other.
-     */
-    readonly responseHeaders: readonly {
-        readonly status: StatusKey;
-        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;
-        }[];
-    }[];
     /**
-     * The media types each response status offers.
+     * **Whether the operation needs a caller, in the three states its `security` can say.**
      *
-     * **`responseContentTypes` above carries this for the PRIMARY status only, and an arm carried
-     * none at all.** An operation whose one status offers `application/json` and `text/event-stream`
-     * emitted a single arm holding the JSON schema, and the alternative was dropped from the list
-     * entirely, so `deps.respond` could not tell what it was answering with and a non-JSON operation
-     * could not be served faithfully. Reported by two consumers independently.
-     */
-    readonly responseMediaTypes: readonly {
-        readonly status: StatusKey;
-        readonly contentTypes: readonly string[];
-    }[];
-    /**
-     * No caller is established, so the operation receives no `ServiceContext`.
+     * - `none`: no requirement asks for anything (`@useAuth(NoAuth)`, or no authentication at all).
+     * - `optional`: an anonymous alternative sits beside a real one (`NoAuth | BearerAuth`). A caller
+     *   who presents a credential is authenticated; one who presents none is still admitted.
+     * - `required`: every alternative asks for something.
      *
-     * Whether a tenant exists follows from whether the request was authenticated - there is no user,
-     * account or membership to build one from otherwise. Reading it here is what lets a server
-     * derive an operation's call shape rather than a hand-written table restating it per row.
+     * **This replaced `noAuth`, which could not tell the first two apart**, so a server passing it
+     * through treated `NoAuth | BearerAuth` as "no caller", and a caller with a valid token was never
+     * seen as one.
      */
-    readonly noAuth: boolean;
+    readonly authentication: "none" | "optional" | "required";
     /**
      * The OAuth scopes the operation requires, from `@useAuth`.
      *
@@ -317,7 +379,7 @@ export interface EmittedRoute {
     /**
      * What the DOCUMENT says a caller must satisfy, in the shape the document says it.
      *
-     * **`scopes` and `noAuth` are lossy projections of this, and publishing only those was a defect
+     * **`scopes` is a lossy projection of this (and a boolean `noAuth` was another), and publishing only those was a defect
      * both server emitters had to work around.** A flat scope union cannot say WHICH scheme demanded
      * what, so `@useAuth(BearerAuth)` -- which reaches OpenAPI as `security: [{ "BearerAuth": [] }]`
      * -- arrived here as an empty scope list indistinguishable from no authentication at all. An
@@ -325,30 +387,12 @@ export interface EmittedRoute {
      * again and rebuild this itself, and two of them did.
      *
      * Satisfying **any one** requirement authorises; every scheme within a requirement must be
-     * satisfied together. Empty where the operation declares `@useAuth(NoAuth)` or nothing, which is
-     * a fact rather than an absence.
+     * satisfied together. An anonymous alternative is the empty requirement `{}`, exactly as the
+     * document publishes it: `NoAuth | BearerAuth` is `[{}, { "BearerAuth": [] }]` and
+     * `@useAuth(NoAuth)` is `[{}]`. Empty where the operation declares no authentication at all.
+     * Whether a caller is needed is {@link EmittedRoute.authentication}.
      */
     readonly security: readonly SecurityRequirement[];
-    /** Which of two success statuses to answer, and the literal property that decides it. */
-    readonly statusBy: {
-        property: string;
-        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;
 }
 export declare function collectRoutes(program: Program, registry: SchemaRegistry, service: HttpService): EmittedRoute[];
 /** Whether emitted source references `name` as an identifier rather than as part of a longer one. */
@@ -365,10 +409,26 @@ export interface RouteSchemaNames {
     readonly operationId: string;
     readonly path: string | undefined;
     readonly query: string | undefined;
+    /**
+     * The query object's identifier, with a `.shape`. Equal to `query` except where a form-exploded
+     * record or model is gathered, when `query` is `z.preprocess(gather, <queryFields>)` and has no
+     * `.shape`. A consumer spreading request fields reads this; a validator of a raw request reads `query`.
+     */
+    readonly queryFields: string | undefined;
     readonly header: string | undefined;
     readonly body: string | undefined;
-    readonly response: string | undefined;
-    readonly alternateResponse: string | undefined;
+    /**
+     * The identifier each response's body is declared under, parallel to `EmittedRoute.responses` and
+     * in the same order. `schema` is `undefined` exactly where that response carries no body.
+     *
+     * **An identifier for every arm, failures included.** A success body used to be named and a
+     * failure's inline body stayed an expression inside the arm list, so a server emitter could not
+     * write `z.infer<typeof ...>` for the one response it most needs a handler to be able to return.
+     */
+    readonly arms: readonly {
+        readonly status: StatusKey;
+        readonly schema: string | undefined;
+    }[];
     /**
      * The `readonly ResponseArm[]` const - what the operation may answer with, and with which body.
      *
@@ -407,33 +467,7 @@ export interface ResolvedServiceOptions {
     /** Whether every emitted validator is wrapped in `z.compile()`. See the option's own docblock. */
     readonly compileSchemas: boolean;
     readonly keyVocabularies: readonly string[];
-    readonly runtimeModule: string;
     /** The command that regenerates, for the banner. `undefined` keeps the generic line. */
     readonly regenerateHint: string | undefined;
 }
-/** What the generated files import their runtime contract from when nothing says otherwise. */
-export declare const DEFAULT_RUNTIME_MODULE = "typespec-http-zod/runtime";
-/**
- * What a WRAPPING emitter may change about this one, without changing what a consumer may set.
- *
- * **`defaultRuntimeModule` is a default, not an override.** A consumer's `runtime-module` still
- * wins; this only decides what `schemas.gen.ts` and any file a wrapper emits beside it import from
- * when the consumer says nothing.
- *
- * **It exists because this package's own default is wrong for a wrapper, and shipped that way.**
- * `typespec-hono` emits `import type { AppEnv, Awaitable, Ctx, Result, RouteDeps }` and
- * `import { selectContentType }` from whatever this resolves to. None of those six is exported here -
- * this module exports `ResponseArm` and `armFor`, and nothing else. Worse, `typespec-http-zod` is a
- * TRANSITIVE dependency of a `typespec-hono` consumer, so under a strict `node_modules` the specifier
- * does not resolve at all whatever it exports. Measured in a fresh project installed from tarballs:
- * `tsp compile` succeeded with zero diagnostics and `tsc` then reported **two `TS2307`s**, one in each
- * generated file.
- *
- * Nothing in either suite saw it, because every compile in both harnesses sets `runtime-module`
- * explicitly. The default branch was ungraded across 240 tests.
- */
-export interface EmitHttpZodOptions {
-    /** The specifier generated files import their runtime contract from when the consumer sets none. */
-    readonly defaultRuntimeModule?: string;
-}
-export declare function emitHttpZod(context: EmitContext, wrapper?: EmitHttpZodOptions): Promise<readonly EmittedService[]>;
+export declare function emitHttpZod(context: EmitContext): Promise<readonly EmittedService[]>;