typespec-http-zod 0.29.0 → 0.31.0

package/README.md

@@ -193,6 +193,25 @@ break the build until the validator and the contract type diverge.
 Identifiers are named from the operation id the document publishes. An operation inside a namespace
 carries the whole id, so `op readWidget` in `namespace Widgets` becomes `Widgets_readWidgetPath`.
 
+Every component the document publishes is declared under its name - `widgetSchema` and `Widget` -
+including the types no operation reaches, which openapi3 publishes at `All`, and those no route
+names, such as a model a merge holds. A type used only by an operation the document leaves out -
+one whose path holds a query string, or an `@overload` on its base operation's endpoint - is
+declared too, as its validators are emitted. A component carries a visibility suffix,
+`WidgetCreate`, only where its type is used at more than one visibility, as openapi3 names it. Four
+names cannot be TypeScript's, and are not: a namespace is dropped, as one module has one, so two
+types of one name in two namespaces are `duplicate-declaration`; a character an identifier cannot
+hold is written `_`, `Hy-phen` as `Hy_phen`, and a name TypeScript refuses for a declaration - a
+reserved word, a predefined type such as `string`, a strict-mode word such as `public`, a type
+operator such as `keyof` - or a name the generated files declare or name for themselves takes a
+trailing `_` - `delete_`, `string_`, `WireReader_`, `ArrayBuffer_`; and
+a scalar is validated inline wherever it is used, since TypeScript cannot carry its constraints. A
+model named `Record`, `Promise`, `Readonly` or `Exclude` keeps its name - the copy a visibility
+template makes of a `Record<T>` instance, which openapi3 publishes as `Record`, included - and every
+generated file names the library's type as `globalThis.Record<...>`. A type published only as a
+reference to another document, by `@useRef`, is refused as `unsupported-type`: the document states
+no schema for it.
+
 ## Docs
 
 - [Guides](docs/guides.md): installing, validating a request, answering with the right body, content

package/dist/src/api.d.ts

@@ -242,6 +242,11 @@ export interface EmittedRoute {
      * 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.
+     *
+     * **For a `/` expression this is the only statement of the route there is.** openapi3 cannot
+     * publish the operator: `/lx{/v*}` is `/lx{v}` in the document, under `simple` style and its own
+     * `invalid-style` warning, which joins an exploded list `1,2` where the route joins it `1/2`. The
+     * validator undoes the route's, as `@typespec/http-specs` expects - see `docs/reference.md`.
      */
     readonly pathSegments: readonly EmittedPathSegment[];
     /**
@@ -257,6 +262,19 @@ export interface EmittedRoute {
      * a scalar. Empty when there is none, never `undefined`.
      */
     readonly decodedPathParameters: readonly string[];
+    /**
+     * Every pair of inputs a handler would be handed under ONE key - `@header("x")` beside
+     * `@query("x")`, two `@query("x")`, a `@path id` beside a `@header("id")`, a parameter named as
+     * the body is. Empty for almost every operation.
+     *
+     * **A server emitter spreads the parameter groups into one input, so the later group's value
+     * silently replaced the earlier one**, after each had been validated against its own schema.
+     * `@typespec/http` refuses only a path and a query parameter of one name. The handler input has
+     * one value per key and cannot carry both, so a server should not mount such an operation; this
+     * package reports it as `shared-input-key`, and states the key as both declarations at once. See
+     * {@link SharedInputKey}.
+     */
+    readonly sharedInputKeys: readonly SharedInputKey[];
     /**
      * 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
@@ -310,6 +328,26 @@ export interface EmittedRoute {
     readonly requestTextual: boolean;
     readonly summary: string | undefined;
     readonly requestSchema: string | undefined;
+    /**
+     * **The body as a URL-encoded form carries it**, where the route also takes it under another media
+     * type: each field read from the text a form holds - `n=5` is `5` where `n` is an `int32` - and a
+     * key sent more than once read as the list it stands for. A server validates a form body with this
+     * and any other with {@link requestSchema}. `undefined` where no form is declared, or where only a
+     * form is, when `requestSchema` reads it itself: validated as JSON, every numeric or boolean field
+     * of a form refused every conformant request.
+     */
+    readonly formRequestSchema?: string;
+    /**
+     * **The multipart parts whose value is read from text**, each with whether it is JSON alone: every
+     * part but a file and raw bytes. A client may send one with a filename all the same - `curl -F
+     * 'r=@data.json;type=application/json'` - and a form reader then hands it over as a file, which
+     * the part's schema, reading text, refuses. A server reads such a part's text first. Its media type
+     * says what the part is, not the filename. `undefined` where the body is not multipart.
+     */
+    readonly textParts?: readonly {
+        readonly name: string;
+        readonly json: boolean;
+    }[];
     /**
      * The parameters, split by WHERE they arrive - see `parameterSchemasOf`.
      *
@@ -439,6 +477,17 @@ export interface EmittedRoute {
      */
     readonly security: readonly SecurityRequirement[];
 }
+/** Where a value reaches a handler's input from. */
+export type InputLocation = "path" | "query" | "header" | "cookie" | "body";
+/** Two inputs a handler would be handed under one key. See {@link EmittedRoute.sharedInputKeys}. */
+export interface SharedInputKey {
+    /** The key both arrive under, as the input spells it. */
+    readonly key: string;
+    /** Where the input declared first comes from. */
+    readonly first: InputLocation;
+    /** Where the input declared second comes from. */
+    readonly second: InputLocation;
+}
 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. */
 export declare function referencedIn(source: string, name: string): boolean;
@@ -478,6 +527,12 @@ export interface RouteSchemaNames {
      */
     readonly cookie?: string | undefined;
     readonly body: string | undefined;
+    /**
+     * The validator of the body as a URL-encoded form carries it, where it differs from `body`'s - see
+     * {@link EmittedRoute.formRequestSchema}. Absent where a form, if one is declared, is validated by
+     * `body`.
+     */
+    readonly formBody?: string;
     /**
      * 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.