typespec-http-zod 0.30.0 → 0.32.0

package/README.md

@@ -50,6 +50,9 @@ And the OpenAPI that [`@typespec/openapi3`](https://typespec.io) generates from
 
 - **Documentation and validation cannot drift** - both come from one definition, so there is no
   second source to keep in step
+- **Agrees with the OpenAPI version you publish** - 3.0, `@typespec/openapi3`'s default, and 3.1 read
+  some schemas differently; the validators follow the `openapi-versions` you give openapi3, and refuse
+  at compile what a 3.0 document cannot say. See [OpenAPI versions](docs/guides.md#openapi-versions)
 - **One runtime dependency** - `zod`, and nothing else
 - **No framework** - use the validators in a server, a client, or a test
 - **Types with zero imports** - a contracts module anything can depend on
@@ -193,6 +196,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[];
     /**
@@ -323,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`.
      *
@@ -502,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.