@nxgt/typespec 0.13.1 → 0.14.0

package/README.md

@@ -339,7 +339,8 @@ model Place {
 Each is an OpenAPI component named as in GraphQL (`Latitude`, `URL`), with a
 `format`, a pattern or bounds approximating the rule, and `x-nxgt-scalar`
 naming it. The exact rules (checksums, ISO and IANA lists) are outside the
-pattern. TypeSpec's own `url` takes any scheme; `httpUrl` takes `http:` and
+pattern; [`@nxgt/openapi-codegen`](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-codegen/docs/guide/options.md#scalars)'s
+`scalars: 'exact'` checks them with the schemas of `@nxgt/zod`. TypeSpec's own `url` takes any scheme; `httpUrl` takes `http:` and
 `https:`. Every scalar by category, in
 [Scalars](docs/guide/scalars.md); the ids, the addresses and the columns, in
 [Scalars and columns](docs/guide/columns.md).
@@ -539,6 +540,28 @@ with a reason, or for one operation with
 `#suppress "@nxgt/typespec/<rule>" "<reason>"`. More, with a failing and a
 passing example of each rule, in [Linter](docs/guide/linter.md).
 
+### Shared responses, headers and path servers
+
+Three decorators, written by the emitter `@nxgt/typespec` (with
+`@typespec/openapi3` in `emit` each is `shared-needs-nxgt-emitter`):
+
+```tsp
+@sharedResponse @error
+model Unauthorized {
+  @sharedHeader("NoStore") @header("cache-control") cacheControl: "no-store";
+  @statusCode code: 401;
+  message: string;
+}
+
+@route("/users")
+@pathServer("https://users.example.com", "Users")
+@get op listUsers(): { @body users: string[] } | Unauthorized;
+```
+
+`Unauthorized` is emitted once under `components.responses`, its header once
+under `components.headers`, a `$ref` at each use, and `/users` alone gets
+`servers`. More, in [The emitter](docs/guide/emitter.md#shared-responses-shared-headers-and-path-servers).
+
 ## API
 
 ### Decorators
@@ -546,6 +569,9 @@ passing example of each rule, in [Linter](docs/guide/linter.md).
 | Decorator | On | What it does |
 | --- | --- | --- |
 | `@queryMethod` | an operation | marks a `@post` as a `QUERY`: needs the emitter `@nxgt/typespec` and OpenAPI 3.2, where the document gets a `query` operation, and is an error otherwise; `@operationIds` checks its verb as a `QUERY`'s |
+| `@sharedResponse(name?)` | a response model | emits the response once under `components.responses`, a `$ref` at each use; needs the emitter `@nxgt/typespec` |
+| `@sharedHeader(name?)` | a `@header` property of a response | emits the header once under `components.headers`, a `$ref` at each use; needs the emitter `@nxgt/typespec` |
+| `@pathServer(url, description?, parameters?)` | an operation | `servers` on its path item, with `@server`'s variables; the other paths keep the document's; needs the emitter `@nxgt/typespec` |
 | `@operationIds(options?: OperationIdsOptions)` | a namespace or an interface | makes each operation's id its name, as written, or a known verb with the interface's resource (`list` in `Users` is `listUsers`), in the namespace however deep or in the interface, unless it has an `@operationId` |
 
 `OperationIdsOptions` is `#{ singular?: string, plural?: string, verbs?: Record<"singular" | "plural"> }`:
@@ -572,6 +598,14 @@ overrides verbs, on a namespace or an interface.
 | `query-method-not-post` | error: an operation marked `@queryMethod` is not a `@post` |
 | `query-method-needs-openapi-3.2` | error: the emitter `@nxgt/typespec` is asked for a version below 3.2 (or none, which is 3.0) beside a `@queryMethod`; nothing is emitted |
 | `query-method-needs-nxgt-emitter` | error: `@typespec/openapi3` is in `emit` beside a `@queryMethod` |
+| `shared-component-conflict` | error: two `@sharedResponse` or two `@sharedHeader` of one name differ; the first is the component, the other stays inline |
+| `shared-response-merged` | error: operations sharing a route reply one status with different responses, one a `@sharedResponse` |
+| `path-server-missing-variable` | error: a `{name}` of a `@pathServer` URL has no property in its parameters |
+| `path-server-invalid-variable` | error: a `@pathServer` variable is not a string, a string enum or a union of strings |
+| `shared-header-misplaced` | error: `@sharedHeader` on a request header or a body property |
+| `invalid-component-name` | error: the name given to `@sharedResponse` or `@sharedHeader` has a character OpenAPI does not allow in a component name |
+| `path-server-conflict` | error: two `@pathServer` of one path give one URL a different description or variables |
+| `shared-needs-nxgt-emitter` | error: `@typespec/openapi3` is in `emit` beside a `@sharedResponse`, `@sharedHeader` or `@pathServer` |
 | `openapi3-missing` | error: the emitter `@nxgt/typespec` runs `@typespec/openapi3`, which is not installed |
 
 ### Linter rules
@@ -733,6 +767,7 @@ envelope and the rate limit's headers.
   template, the files it writes, and the steps from the spec to a Hono route;
 - [The emitter](docs/guide/emitter.md): `@nxgt/typespec` in `tspconfig.yaml`,
   a `@queryMethod` as a real `QUERY` in OpenAPI 3.2, and what that needs;
+  shared responses and headers under `components`, and `servers` on a path;
 - [Error replies](docs/guide/errors.md): the envelope, each response, the
   aliases by verb, and what the generator makes of them;
 - [Pagination](docs/guide/pagination.md): offset and cursor pages, and

package/dist/components.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@sharedResponse`, `@sharedHeader` and `@pathServer`: what the spec asks
+ * to be emitted once under `components`, or on one path item. A header and
+ * an operation carry their mark (`marks.ts`) until `shared-components.ts`
+ * rewrites the emitted document; a response is marked at emit time
+ * (`response-marks.ts`).
+ */
+import { type DecoratorContext, type Model, type ModelProperty, type Operation, type Program } from '@typespec/compiler';
+export declare function sharedResponse(context: DecoratorContext, target: Model, name?: string): void;
+export declare function sharedHeader(context: DecoratorContext, target: ModelProperty, name?: string): void;
+export declare function pathServer(context: DecoratorContext, target: Operation, url: string, description?: string, parameters?: Model): void;
+/**
+ * Each marked target must be emitted by `@nxgt/typespec`: `@typespec/openapi3`
+ * would write the copies, or drop the servers, without a word.
+ */
+export declare function validateComponents(program: Program): void;
+//# sourceMappingURL=components.d.ts.map

package/dist/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACN,KAAK,gBAAgB,EAErB,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,MAAM,oBAAoB,CAAC;AAuB5B,wBAAgB,cAAc,CAC7B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,KAAK,EACb,IAAI,CAAC,EAAE,MAAM,GACX,IAAI,CAKN;AAED,wBAAgB,YAAY,CAC3B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,MAAM,GACX,IAAI,CAMN;AAED,wBAAgB,UAAU,CACzB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,MAAM,EACX,WAAW,CAAC,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,KAAK,GAChB,IAAI,CA+BN;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqBzD"}

package/dist/document-text.d.ts

@@ -0,0 +1,7 @@
+export type Document = Record<string, unknown>;
+/**
+ * The text with `rewrite` applied to its document, and left as it was when
+ * `rewrite` says nothing changed.
+ */
+export declare function rewriteDocument(content: string, rewrite: (document: Document) => boolean): string;
+//# sourceMappingURL=document-text.d.ts.map

package/dist/document-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-text.d.ts","sourceRoot":"","sources":["../src/document-text.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,GACtC,MAAM,CAeR"}

package/dist/emitter.d.ts

@@ -2,7 +2,9 @@
  * The emitter `@nxgt/typespec`: `@typespec/openapi3`, with its options,
  * checked by its own schema, and its files, and each `POST` marked
  * `@queryMethod` a real `QUERY` in an OpenAPI 3.2 document
- * (`query-operations.ts`). Only 3.2 has a `QUERY`: a marked operation with
+ * (`query-operations.ts`), and what `@sharedResponse`, `@sharedHeader` and
+ * `@pathServer` ask: components emitted once, servers on a path item
+ * (`shared-components.ts`). Only 3.2 has a `QUERY`: a marked operation with
  * an older version asked for is an error, and nothing is emitted.
  * `@typespec/openapi3` is loaded only here, so a spec that only imports the
  * library does not need it.

package/dist/emitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAGN,KAAK,WAAW,EAEhB,MAAM,oBAAoB,CAAC;AAmE5B,wBAAsB,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BjE"}
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../src/emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAGN,KAAK,WAAW,EAGhB,MAAM,oBAAoB,CAAC;AAkG5B,wBAAsB,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCjE"}

package/dist/index.d.ts

@@ -7,6 +7,7 @@
  * export would declare it a second time, in the global namespace.
  */
 import type { Program } from '@typespec/compiler';
+import { pathServer, sharedHeader, sharedResponse } from './components.js';
 import { operationIds } from './operation-ids.js';
 import { queryMethod } from './query-method.js';
 export { $onEmit } from './emitter.js';
@@ -16,7 +17,10 @@ export declare function $onValidate(program: Program): void;
 export declare const $decorators: {
     Nxgt: {
         operationIds: typeof operationIds;
+        pathServer: typeof pathServer;
         queryMethod: typeof queryMethod;
+        sharedHeader: typeof sharedHeader;
+        sharedResponse: typeof sharedResponse;
     };
 };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,YAAY,EAAwB,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,WAAW,EAAwB,MAAM,gBAAgB,CAAC;AAGnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAOlD;AAED,eAAO,MAAM,WAAW;;;;;CAEvB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EACN,UAAU,EACV,YAAY,EACZ,cAAc,EAEd,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,YAAY,EAAwB,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,WAAW,EAAwB,MAAM,gBAAgB,CAAC;AAGnE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAQlD;AAED,eAAO,MAAM,WAAW;;;;;;;;CAQvB,CAAC"}