@nxgt/typespec 0.13.1 → 0.14.0

package/docs/guide/emitter.md

@@ -2,7 +2,9 @@
 
 `@nxgt/typespec` is a TypeSpec emitter as well as a library: it compiles a
 spec to OpenAPI with `@typespec/openapi3`, and writes each `@queryMethod` as a
-real `QUERY` when the document is OpenAPI 3.2.
+real `QUERY` when the document is OpenAPI 3.2. It also emits a shared
+response or header once under `components`, and `servers` on one path
+([below](#shared-responses-shared-headers-and-path-servers)).
 
 ## The smallest setup
 
@@ -98,6 +100,150 @@ where `@typespec/openapi3` wrote `tsp-output/@typespec/openapi3`. Set
 `@typespec/openapi3` is loaded only when emitting, so a spec that only
 imports the library, `tsp compile --no-emit`, does not need it installed.
 
+## Shared responses, shared headers and path servers
+
+`@typespec/openapi3` writes every response and header in full at each
+operation, and `@server` only reaches the document's `servers`. Three
+decorators ask the emitter for the rest, with no post-processing of the JSON.
+They need this emitter: with `@typespec/openapi3` in `emit` each is the error
+`shared-needs-nxgt-emitter`, since it would write the copies or drop the
+servers without a word.
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+@service(#{ title: "Example" })
+@server("https://api.example.com", "Main")
+namespace Example;
+
+model NoStore {
+  @sharedHeader("NoStore")
+  @header("cache-control")
+  cacheControl: "no-store";
+}
+
+@sharedResponse
+@error
+model Unauthorized {
+  ...NoStore;
+  @statusCode code: 401;
+  message: string;
+}
+
+@route("/items") @get op listItems(): { @body items: string[] } | Unauthorized;
+
+@route("/users")
+@pathServer("https://users.example.com", "Users")
+@get op listUsers(): { @body users: string[] } | Unauthorized;
+```
+
+```yaml
+# openapi.yaml (extract)
+paths:
+  /items:
+    get:
+      responses:
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /users:
+    servers:
+      - url: https://users.example.com
+        description: Users
+    get:
+      responses:
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+components:
+  headers:
+    NoStore:
+      required: true
+      schema: { type: string, enum: [no-store] }
+  responses:
+    Unauthorized:
+      description: Access is unauthorized.
+      headers:
+        cache-control:
+          $ref: '#/components/headers/NoStore'
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Unauthorized'
+servers:
+  - url: https://api.example.com
+    description: Main
+```
+
+| Decorator | On | Result |
+| --- | --- | --- |
+| `@sharedResponse(name?)` | a response model | each reply of that model, whatever the operation, is one entry of `components.responses` (named after the model unless `name` is given) and a `$ref` at each use |
+| `@sharedHeader(name?)` | a model property that is a `@header` | the header is one entry of `components.headers` (named after the property unless `name` is given) and a `$ref` at each response that carries it |
+| `@pathServer(url, description?, parameters?)` | an operation | `servers` on the operation's path item; the other paths keep the document's. Repeated on the operations of one path, the servers add up |
+
+What to know:
+
+- **A response header only.** `components.headers` holds response headers.
+  `@sharedHeader` on a request `@header` or on a body property is the error
+  `shared-header-misplaced`; the mark never stays in the document.
+- **A shared response is the whole reply**: description, headers and content.
+  A model with several statuses (`@statusCode code: 400 | 404`) is one
+  component per status, `Name400` and `Name404`, since their descriptions
+  differ.
+  Two shared responses, or two shared headers, of one name that differ are the
+  error `shared-component-conflict`: the first is the component, the other
+  stays inline. A name is letters,
+  digits, `.`, `_` and `-` (`invalid-component-name` otherwise).
+- **A `@pathServer` is for a path item, not an operation**: `get` and `post`
+  of one route share it. The same server on several operations of one path is
+  written once; one URL with a different description or variables on another
+  is the error `path-server-conflict`, and the first is the one emitted.
+- **Server variables** are `@server`'s third parameter: each property is a
+  variable, its default the variable's `default` (`""` without one), its
+  `@doc` the `description`, and a literal, enum or union of literals type its
+  `enum`. As with `@server`, a variable is a string (a string, a string enum
+  or a union of strings: `path-server-invalid-variable` otherwise), and each
+  `{name}` of the URL needs its property (`path-server-missing-variable`).
+
+  ```tsp
+  @route("/jmap")
+  @pathServer("{origin}{basePath}", "Mail", {
+    @doc("The mail origin") origin: string = "https://mail.example.com",
+    @doc("Where it is mounted") basePath: string = "/jmap",
+  })
+  @get op session(): string;
+  ```
+
+  ```yaml
+  /jmap:
+    servers:
+      - url: '{origin}{basePath}'
+        description: Mail
+        variables:
+          origin:
+            default: https://mail.example.com
+            description: The mail origin
+          basePath:
+            default: /jmap
+            description: Where it is mounted
+  ```
+- **Several services** keep their own: each decorator marks the object the
+  emitter writes for its own operation or header, and the emitter reads and
+  takes off those marks per document, so the same path in two services, a
+  dotted service name or a nested service never mixes them.
+- **Operations of a `@sharedRoute`** merge into one in the document; their
+  servers add up, and each one's shared responses are hoisted.
+- **`@typespec/versioning` is not verified.** A shared response is marked on
+  the operation at emit time, and nothing here tests a versioned service,
+  whose operations the versioning library clones: shared responses on a
+  versioned service may stay inline, and a `@pathServer`'s servers may be missing.
+- **Nothing changes without them.** A spec that uses none of the three emits
+  byte-identical output, and the hoisting is the same in 3.1 and 3.2.
+- `@nxgt/openapi-codegen` generates a document with `$ref` responses and
+  headers as it does the inline copies.
+
 ## What follows downstream
 
 | Step | What it does with the `query` operation |

package/docs/guide/scalars.md

@@ -67,9 +67,12 @@ components:
 | `description` | The rule in words, and what the pattern leaves out. |
 
 A generator that knows nothing of `x-nxgt-scalar` still validates the pattern
-and the bounds. A later `@nxgt/openapi-codegen` release will map it to the exact
-Zod schema from `@nxgt/zod` ([roadmap](../roadmap.md)); until then, what a
-scalar leaves out is not checked.
+and the bounds. `@nxgt/openapi-codegen` with
+[`scalars: 'exact'`](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-codegen/docs/guide/options.md#scalars) maps it to the exact Zod
+schema from `@nxgt/zod`, the checksum, the list or the `Intl` rule included;
+with the default `'pattern'`, what a scalar leaves out is not checked. The
+codecs (`dateTime`, `timestamp`, `bigInt`, `long`) keep their pattern under
+`'exact'` too.
 
 ## Names
 

package/docs/roadmap.md

@@ -10,9 +10,7 @@ Nothing in progress.
 
 ## Next
 
-- **Exact scalar rules in the generated code.** `@nxgt/openapi-codegen` maps
-  `x-nxgt-scalar` to the exact Zod schema from `@nxgt/zod`: the checksums,
-  the ISO and IANA lists and the `Intl` rules the patterns leave out.
+Nothing planned beyond what is under Later.
 
 ## Later
 
@@ -27,6 +25,23 @@ Nothing in progress.
 
 ## Shipped
 
+### 0.14.0
+
+- **Shared responses, shared headers and path servers.** `@sharedResponse`
+  and `@sharedHeader` emit a response and a header once under
+  `components.responses` and `components.headers`, a `$ref` at each use, and
+  `@pathServer` puts `servers` on one path item, from the spec alone with no
+  post-processing, with `@server`'s variables.
+
+### 0.13.2
+
+- **Exact scalar rules in the generated code.** `@nxgt/openapi-codegen`
+  with `scalars: 'exact'` maps `x-nxgt-scalar` to the exact Zod schema from
+  `@nxgt/zod`: the checksums, the ISO and IANA lists, the `Intl` rules and the
+  refusal of `-0` the patterns leave out. The codecs keep their pattern until
+  `@nxgt/zod` offers their wire schemas. The guides and the troubleshooting
+  entries say so.
+
 ### 0.13.0
 
 - **The emitter `@nxgt/typespec`.** `emit: ["@nxgt/typespec"]` runs

package/docs/troubleshooting.md

@@ -361,6 +361,98 @@ options:
     openapi-versions: ['3.2.0']
 ```
 
+## `The server URL https://{tenant}.example.com of listUsers has {tenant}, which is not a property of its parameters. Add the variable, or take the braces out.`
+
+**When:** `tsp compile`; the error `path-server-missing-variable` on a
+`@pathServer` whose URL has a `{name}` its third parameter lacks.
+
+**Fix:** add the variable, as `@server` asks:
+
+```tsp
+@pathServer("https://{tenant}.example.com", "Tenant", { tenant: string = "main" })
+```
+
+## `The variable port of the @pathServer of listUsers is not a string, a string enum or a union of strings: an OpenAPI server variable is a string.`
+
+**When:** `tsp compile`; the error `path-server-invalid-variable`, for a
+variable typed `int32`, `boolean`… The default of a server variable is a string.
+
+**Fix:** type it as a string: `port: string = "443"`, or `"443" | "8443"`.
+
+## `Trace is marked @sharedHeader outside a response header: it applies to a @header of a reply only, not to a request header or a body property.`
+
+**When:** `tsp compile`; the error `shared-header-misplaced`, for a
+`@sharedHeader` property that ends up in a request (a `@header` parameter) or
+in a body schema.
+
+**Why:** `components.headers` holds response headers; a request header is a
+parameter and a body property is a schema.
+
+**Fix:** take `@sharedHeader` off, or keep it on a `@header` of a reply model.
+
+## `Operations sharing the route GET /m reply 400 with different responses, one of them a @sharedResponse: @sharedRoute merges them into one reply, which cannot be a component. Give them the same shared response, or none.`
+
+**When:** `tsp compile`; the error `shared-response-merged`, for operations
+with `@sharedRoute` that answer one status with different responses (two shared
+ones of different names, or a shared one and a plain one).
+
+**Why:** the operations are one in the document, with one reply per status,
+which cannot be a component and something else.
+
+**Fix:** answer that status with the same `@sharedResponse` in each, or with
+none:
+
+```tsp
+@route("/m") @sharedRoute @get op one(): string | Gone;
+@route("/m") @sharedRoute @get op two(): string | Gone;
+```
+
+## `Two shared responses named Failure differ: a component is emitted once. Give each its own name, or make them the same.`
+
+**When:** `tsp compile`; the error `shared-component-conflict`, for two
+`@sharedResponse` models (or two `@sharedHeader` properties, as `headers`) that
+take one name and do not emit the same response or header.
+
+**Why:** a component has one definition, and the emitter will not pick one.
+The first is the component; the other stays inline in the document.
+
+**Fix:** give each its own name, or make them one model:
+
+```tsp
+@sharedResponse("BadInput") @error model A { @statusCode code: 400; a: string; }
+@sharedResponse("Refused") @error model B { @statusCode code: 400; b: string; }
+```
+
+## `Two @pathServer of /users give the server https://a.example.com a description or variables that differ. Give the path one definition of it.`
+
+**When:** `tsp compile`; the error `path-server-conflict`. The first definition is emitted.
+
+**Why:** operations of one path share its `servers`; the same URL cannot be
+described two ways. The first definition is the one emitted.
+
+**Fix:** give every `@pathServer` of that URL on the path the same
+description and variables, or put it on one operation.
+
+## `"not ok" is not a name OpenAPI allows for a component: use letters, digits, '.', '_' and '-'.`
+
+**When:** `tsp compile`; the error `invalid-component-name`, on a name given to
+`@sharedResponse` or `@sharedHeader` (or a model or property name used as one).
+
+**Fix:** pass a name of letters, digits, `.`, `_` and `-`:
+`@sharedResponse("NotOk")`.
+
+## `Unauthorized is marked @sharedResponse: emit with @nxgt/typespec, which writes it; @typespec/openapi3 would write it inline or drop it.`
+
+**When:** `tsp compile` with `@typespec/openapi3` in `emit`; the error
+`shared-needs-nxgt-emitter` for each `@sharedResponse`, `@sharedHeader` and
+`@pathServer`.
+
+**Why:** only the emitter `@nxgt/typespec` reads them: `@typespec/openapi3`
+would write the copies, leak `x-nxgt-component` on a header, or leave out the
+path's `servers`.
+
+**Fix:** emit with `@nxgt/typespec` ([The emitter](guide/emitter.md)).
+
 ## `The emitter @nxgt/typespec runs @typespec/openapi3, which is not installed: add it beside @nxgt/typespec.`
 
 **When:** `tsp compile` with `@nxgt/typespec` in `emit`; the error
@@ -628,12 +720,17 @@ one.
 
 **Why:** the scalar's pattern checks the shape. A list (`countryCode`,
 `currency`, `timeZone`, `locale`) or a checksum (`iban`, ISBN) does not fit in
-a pattern. `x-nxgt-scalar` names the exact rule, but `@nxgt/openapi-codegen`
-does not map it to the `@nxgt/zod` schema yet ([roadmap](roadmap.md)).
-
-**Fix:** until it does, check the value in the handler against the exact
-rule, the list or the checksum, from `@nxgt/zod` or your own table, and answer
-`400` as the generated validator does:
+a pattern. `x-nxgt-scalar` names the exact rule, and `@nxgt/openapi-codegen`
+maps it to the `@nxgt/zod` schema only with `scalars: 'exact'`; the default is
+`'pattern'`.
+
+**Fix:** generate with
+[`scalars: 'exact'`](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-codegen/docs/guide/options.md#scalars)
+(`bun add @nxgt/zod`, then `generate({ …, scalars: 'exact' })`): `iban` is
+checked by `ibanSchema`, `countryCode` by its list of assigned codes. If you
+cannot, check the value in the handler against the exact rule, the list or the
+checksum, from `@nxgt/zod` or your own table, and answer `400` as the generated
+validator does:
 
 ```ts
 if (!knownCountries.has(body.country)) {
@@ -651,7 +748,8 @@ where `@nxgt/graphql-scalars` refuses it.
 tell from `0`. For `nonNegativeInt`, `nonPositiveInt`, `port`, the bound holds,
 so the value passes (`positiveInt` and `negativeInt` refuse it by their bound).
 
-**Fix:** normalise in the handler when the sign matters:
+**Fix:** generate with [`scalars: 'exact'`](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-codegen/docs/guide/options.md#scalars), whose schemas refuse `-0` for
+an integer scalar. Otherwise normalise in the handler when the sign matters:
 
 ```ts
 const quantity = Object.is(body.quantity, -0) ? 0 : body.quantity;

package/lib/components.tsp

@@ -0,0 +1,65 @@
+import "../dist/index.js";
+
+using TypeSpec.Reflection;
+
+namespace Nxgt;
+
+/**
+ * Emits a response model once, under `components.responses`, with a `$ref`
+ * at each operation that returns it, instead of a full copy at each. The
+ * name is the model's unless one is given. Two shared responses of one name
+ * that differ are the error `shared-component-conflict`. Only
+ * `@nxgt/typespec` writes it: `@typespec/openapi3` would write the copies.
+ *
+ * @example
+ * ```typespec
+ * @sharedResponse
+ * @error model Unauthorized { @statusCode code: 401; message: string; }
+ * ```
+ */
+extern dec sharedResponse(target: Model, name?: valueof string);
+
+/**
+ * Emits a response header once, under `components.headers`, with a `$ref`
+ * at each response that carries it. The name is the property's unless one is
+ * given. For a response header only; a request header is a parameter.
+ *
+ * @example
+ * ```typespec
+ * model NoStore {
+ *   @sharedHeader("NoStore") @header("cache-control") cacheControl: "no-store";
+ * }
+ * ```
+ */
+extern dec sharedHeader(target: ModelProperty, name?: valueof string);
+
+/**
+ * Puts `servers` on the path item of the operation: the other paths keep the
+ * document's. Repeated on the operations of one path, the servers add up; the
+ * same server twice is one, and one URL with two different definitions is the
+ * error `path-server-conflict`. The third parameter is `@server`'s: each
+ * property is a variable of the URL, its default the variable's `default`
+ * and its doc comment the `description`.
+ *
+ * @param url The server's URL, with `{variable}` placeholders if any.
+ * @param description What the server is.
+ * @param parameters The URL's variables.
+ *
+ * @example
+ * ```typespec
+ * @route("/files")
+ * @pathServer("{origin}{basePath}", "Files", {
+ *   @doc("The server's origin")
+ *   origin: string = "https://files.example.com",
+ *   @doc("Where the API is mounted")
+ *   basePath: string = "/files",
+ * })
+ * @get op listFiles(): string[];
+ * ```
+ */
+extern dec pathServer(
+  target: Operation,
+  url: valueof string,
+  description?: valueof string,
+  parameters?: Record<unknown>
+);

package/lib/main.tsp

@@ -11,3 +11,4 @@ import "./headers.tsp";
 import "./sorting.tsp";
 import "./requests.tsp";
 import "./query-method.tsp";
+import "./components.tsp";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/typespec",
-	"version": "0.13.1",
+	"version": "0.14.0",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -61,8 +61,9 @@
 		}
 	},
 	"devDependencies": {
-		"@nxgt/openapi-codegen": "^0.9.2",
+		"@nxgt/openapi-codegen": "^0.11.0",
 		"@nxgt/openapi-hono": "^0.3.3",
+		"@nxgt/zod": "^0.1.3",
 		"@types/bun": "^1.4.0",
 		"@typespec/compiler": "1.17.0",
 		"@typespec/http": "1.17.0",