typespec-http-zod 0.23.0 → 0.25.0

package/README.md

@@ -1,14 +1,60 @@
 # typespec-http-zod
 
-Generate Zod validators and framework-free TypeScript types from a TypeSpec HTTP service.
+Zod validators generated from the same API definition as your OpenAPI document.
 
-The emitted validators agree, keyword for keyword, with the OpenAPI document
-[`@typespec/openapi3`](https://typespec.io) publishes from the same source. Use them with Express,
-Fastify, Elysia, a Workers fetch handler, a typed client, or a test suite. No server framework is
-required.
+## What is it?
 
-It is also a library. [`typespec-hono`](https://github.com/bison-digital/typespec-hono) is an emitter
-built on its API.
+An emitter for [TypeSpec](https://typespec.io), Microsoft's language for describing APIs. Describe
+your API once, and this package generates the Zod schemas that validate every request and response,
+plus the TypeScript types to go with them.
+
+TypeSpec compiles to OpenAPI as well, so the same definition also gives you documentation that cannot
+drift from the validation.
+
+One model:
+
+```tsp
+model Widget {
+  id: string;
+
+  @minLength(1)
+  name: string;
+}
+```
+
+The validators and types this package generates:
+
+```ts
+export const widgetSchema = z.object({
+	id: z.string(),
+	name: z.string().min(1),
+});
+
+export type Widget = z.infer<typeof widgetSchema>;
+```
+
+And the OpenAPI that [`@typespec/openapi3`](https://typespec.io) generates from that same model:
+
+```jsonc
+"Widget": {
+  "type": "object",
+  "required": ["id", "name"],
+  "properties": {
+    "id": { "type": "string" },
+    "name": { "type": "string", "minLength": 1 }
+  }
+}
+```
+
+## Features
+
+- **Documentation and validation cannot drift** - both come from one definition, so there is no
+  second source to keep in step
+- **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
+- **Built on a public API** - [`typespec-hono`](https://github.com/bison-digital/typespec-hono)
+  generates a whole Hono server from it
 
 ## Install
 
@@ -138,6 +184,12 @@ then a range such as `4XX`, then `default`.
 | `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
+error. TypeScript reaches the file through `tsconfig`'s `include`, which has two consequences worth
+knowing before removing it: dependency scanners report the file as unused, and deleting it does not
+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`.
 
@@ -148,6 +200,8 @@ carries the whole id, so `op readWidget` in `namespace Widgets` becomes `Widgets
 - [Reference](docs/reference.md): every option, every diagnostic, and the known limits.
 - [Oracles](docs/oracles.md): every artefact this emitter produces, and what compares it to the
   thing it has to agree with.
+- [Releasing](docs/releasing.md): why this package publishes first, and how to rehearse a
+  two-package release against a local registry.
 
 ## Licence
 

package/dist/src/api.d.ts

@@ -42,7 +42,7 @@ export { EmitterOptionsSchema, type EmitterOptions } from "./lib.js";
  * emitted module stopped being loadable. This is not a style choice a second emitter may make
  * independently.
  */
-export { objectKey } from "./zod.js";
+export { jsDocComment, objectKey } from "./zod.js";
 export declare function beginBanner(hint: string | undefined): void;
 /**
  * The status a row registers: the first non-error status the operation declares.
@@ -69,6 +69,22 @@ 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`;
+/**
+ * Whether the operation declares `@useAuth(NoAuth)` - no caller is established for it.
+ *
+ * **`@useAuth(NoAuth)` reaches OpenAPI as `security: []`, which is why this is derivable at all.**
+ * Whether an operation needs a caller is a contract fact the document publishes. What KIND of caller
+ * - account-scoped, resource-scoped - is not: no OpenAPI keyword expresses it, and a server emitter
+ * that guesses is enforcing something no document states.
+ */
+/**
+ * One requirement the document publishes: scheme name to the scopes it demands.
+ *
+ * Satisfying **any one** requirement authorises a caller, and every scheme WITHIN a requirement must
+ * be satisfied together -- which is what an array of OpenAPI `security` objects means, and why this
+ * is published as a list of lists rather than a flat set of scopes.
+ */
+export type SecurityRequirement = Readonly<Record<string, readonly string[]>>;
 /**
  * The body every `@error` response in the service declares, when they all declare the same one.
  *
@@ -298,6 +314,21 @@ export interface EmittedRoute {
      * `requireScopes(...)` repeated per route that nothing checks against it.
      */
     readonly scopes: readonly string[];
+    /**
+     * 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
+     * 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
+     * emitter wanting the gate the document publishes had to call `getAuthenticationForOperation`
+     * 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.
+     */
+    readonly security: readonly SecurityRequirement[];
     /** Which of two success statuses to answer, and the literal property that decides it. */
     readonly statusBy: {
         property: string;
@@ -373,6 +404,8 @@ export interface ResolvedServiceOptions {
     readonly contractsOutputDir: string | undefined;
     readonly contractsPackage: string | undefined;
     readonly sealObjectSchemas: boolean;
+    /** 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. */
@@ -403,15 +436,4 @@ export interface EmitHttpZodOptions {
     /** The specifier generated files import their runtime contract from when the consumer sets none. */
     readonly defaultRuntimeModule?: string;
 }
-/**
- * Emit this library's artefacts for every `@service` in the program, and hand back what was emitted.
- *
- * **The whole orchestration lives here, once.** The nesting below is load-bearing - a walk that
- * runs outside `collectExternalImports` throws, vocabularies must be collected from what the service
- * DECLARES rather than from what the Zod walk happens to touch, and the error body has to be
- * registered inside the walk or its validator never reaches `schemas.gen.ts`. An emitter built on this
- * library calls this rather than restating it: two copies of a sequence that must agree are two
- * copies that will not, and the symptom would be a subtly different set of declarations in a file
- * whose name is the contract.
- */
 export declare function emitHttpZod(context: EmitContext, wrapper?: EmitHttpZodOptions): Promise<readonly EmittedService[]>;