@nxgt/typespec 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,458 @@
+# @nxgt/typespec
+
+nxgt's HTTP conventions as a [TypeSpec](https://typespec.io) library, so an
+API spec states them in one word instead of rewriting them. Compile the spec to
+OpenAPI 3.1 or 3.2 with `@typespec/openapi3`, then generate the code with
+[`@nxgt/openapi-codegen`](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-codegen/README.md).
+Each shape here is one the `@nxgt/*` packages already send on the wire.
+
+## Install
+
+```sh
+bun add -d @nxgt/typespec @typespec/compiler @typespec/http @typespec/openapi @typespec/openapi3 @nxgt/openapi-codegen
+```
+
+`@typespec/compiler`, `@typespec/http` and `@typespec/openapi` 1.16 or later
+are peer dependencies,
+and `typescript` 6 too, as for every `@nxgt` package. `@typespec/openapi3`
+compiles the spec, and `@nxgt/openapi-codegen` generates the code from it.
+Emit OpenAPI 3.1 or 3.2 in `tspconfig.yaml`: `@typespec/openapi3` emits 3.0
+by default, and the generator refuses it. Every convention here is compiled
+to both in CI, and generates the same code from either.
+
+```yaml
+# api/tspconfig.yaml
+emit:
+  - '@typespec/openapi3'
+options:
+  '@typespec/openapi3':
+    openapi-versions: ['3.1.0']
+    emitter-output-dir: '{project-root}/../openapi'
+    output-file: openapi.yaml
+```
+
+## Usage
+
+### A spec split across files
+
+A spec that grows is split by role: one file per resource's models, one per
+resource's routes, and a `main.tsp` that only assembles them. Each file opens
+the service's namespace again:
+
+```text
+api/
+  main.tsp            imports every file below, and declares the service
+  tspconfig.yaml
+  models/
+    author.tsp  post.tsp  comment.tsp
+  routes/
+    authors.tsp  posts.tsp  comments.tsp
+```
+
+```tsp
+// api/main.tsp
+import "@typespec/http";
+import "./models/post.tsp";
+import "./routes/posts.tsp";
+
+using Http;
+
+@service(#{ title: "Blog" })
+namespace Blog;
+```
+
+```tsp
+// api/models/post.tsp
+namespace Blog;
+
+model Post {
+  @visibility(Lifecycle.Read) id: string;
+  @minLength(1) title: string;
+  body: string;
+}
+```
+
+### Error replies
+
+Import the library where the routes are, and name the errors each operation
+can answer:
+
+```tsp
+// api/routes/posts.tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+namespace Blog;
+
+@route("/posts")
+interface Posts {
+  @get read(@path postId: string): Post | NotFound | Unauthorized;
+  @post create(@body post: Create<Post>): {
+    @statusCode _: 201;
+    @body post: Post;
+  } | BadRequest | Conflict | ErrorResponse<503>;
+}
+```
+
+```sh
+bunx --no-install tsp compile api && bunx nxgt-openapi generate -i openapi/openapi.yaml -o src/generated
+```
+
+Every error body has the envelope of `@nxgt/openapi-hono`'s own replies, its
+400 and its 500, and a handler answers with the same envelope: `status`,
+`message`, an i18n key rather than a sentence, and `timestamp`. The generated
+types require all three:
+
+```ts
+// src/generated/types.ts (excerpt)
+export interface NotFoundBody {
+	status: 404;
+	message: string;
+	timestamp: string;
+}
+```
+
+| Response | Status | Body |
+| --- | --- | --- |
+| `BadRequest` | 400 | `BadRequestBody`: the envelope, and `issues` when the validators refused the request |
+| `Unauthorized` | 401 | `UnauthorizedBody` |
+| `Forbidden` | 403 | `ForbiddenBody` |
+| `NotFound` | 404 | `NotFoundBody` |
+| `Conflict` | 409 | `ConflictBody` |
+| `UnprocessableEntity` | 422 | `UnprocessableEntityBody` |
+| `TooManyRequests` | 429 | `TooManyRequestsBody`, with the `RateLimit-*` headers and `Retry-After` |
+| `InternalServerError` | 500 | `InternalServerErrorBody` |
+| `ErrorResponse<Status>` | any | `ErrorBody<Status>` |
+
+The generator also declares the validators' own 400, `ValidationErrorBody`,
+on every operation that takes a parameter or a body. With `BadRequest`, a
+400 reply is typed `BadRequestBody | ValidationErrorBody`.
+
+### Pagination
+
+Spread the query of a page into the operation's parameters, and answer the
+page:
+
+```tsp
+@route("/posts")
+interface Posts {
+  @get list(@query status?: PostStatus, ...PageParameters): Page<Post>;
+}
+
+@route("/posts/{postId}/comments")
+interface Comments {
+  @get list(@path postId: string, ...CursorPageParameters): CursorPage<Comment> | BadRequest | NotFound;
+}
+```
+
+The shapes are the ones
+[`@nxgt/drizzle`](https://www.npmjs.com/package/@nxgt/drizzle) and
+[`@nxgt/mongo`](https://www.npmjs.com/package/@nxgt/mongo) return, so a
+handler answers their page as it is:
+
+```ts
+// src/generated/types.ts (excerpt)
+export interface PostPage {
+	items: Post[];
+	total: number;
+	page: number;
+	pageSize: number;
+	pageCount: number;
+}
+
+export interface CommentCursorPage {
+	items: Comment[];
+	nextCursor: string | null;
+}
+```
+
+| Query | Default | Checked |
+| --- | --- | --- |
+| `page` | 1 | an integer, at least 1 |
+| `pageSize` | 20 | an integer, at least 1 |
+| `after` | none: the first page | a string, the previous page's `nextCursor` |
+| `limit` | 20 | an integer, at least 1 |
+
+A `pageSize` or `limit` above the server's maximum is not refused: the
+server lowers it, as `@nxgt/drizzle` does. A cursor the server did not write
+makes `@nxgt/drizzle` throw `InvalidCursorError`: answer it with the
+`BadRequest` declared above
+([Serving it](docs/guide/pagination.md#serving-it)).
+
+### Authentication
+
+Name how a request authenticates with `@useAuth`, and the guards' refusals
+beside the success:
+
+```tsp
+@route("/posts/{postId}/comments/{commentId}")
+interface Comments {
+  @useAuth(JanusAuth)
+  @delete delete(@path postId: string, @path commentId: string):
+    NoContentResponse | AuthenticationRequired | AccessDenied | ErrorWithoutBody<404>;
+}
+```
+
+`JanusAuth` is every way [`@nxgt/janus`](https://www.npmjs.com/package/@nxgt/janus)
+reads a session token, and any one of them is enough:
+
+| Scheme | Where the token is |
+| --- | --- |
+| `BearerAuth` | `Authorization: Bearer <token>` |
+| `SessionTokenAuth` | the `X-Session-Token` header |
+| `SessionCookieAuth` | the `janus-session` cookie |
+
+The guards of [`@nxgt/janus-hono`](https://www.npmjs.com/package/@nxgt/janus-hono),
+`session(auth, { required: true })` and `permission()`, refuse without a body:
+`AuthenticationRequired` is their 401 and `AccessDenied` their 403, and
+`ErrorWithoutBody<404>` the 404 of `permission()`. A handler's own refusal,
+with the envelope, stays `Unauthorized` or `Forbidden`. The generated
+`hono.ts` types the guards' replies as `c.body(null, 401)`. More in
+[Authentication](docs/guide/auth.md).
+
+### Scalars and columns
+
+Type an id or an address with a scalar, and spread the columns
+[`@nxgt/drizzle`](https://www.npmjs.com/package/@nxgt/drizzle) stamps a row
+with:
+
+```tsp
+import "@nxgt/typespec";
+
+using Nxgt;
+
+namespace Blog;
+
+model Post {
+  @visibility(Lifecycle.Read) id: uuid;
+  title: string;
+  contact?: email;
+  ...Timestamps;   // createdAt, updatedAt: read-only
+  ...Versioned;    // version: read, and sent back in an update
+  ...Actors;       // createdBy, updatedBy, deletedBy: read-only
+}
+```
+
+| Name | Emitted as | Generated | drizzle |
+| --- | --- | --- | --- |
+| `uuid` | the schema `Uuid`, `format: uuid` | `Uuid`, `z.guid()` | `id()` |
+| `email` | the schema `Email`, `format: email` | `Email`, `z.email()` | |
+| `...Timestamps` | `createdAt`, `updatedAt`, read-only | left out of `Create<T>` and updates | `timestamps()` |
+| `...SoftDelete` | `deletedAt: utcDateTime \| null`, read-only | | `softDelete()` |
+| `...Versioned` | `version: integer`, read and update | kept in `MergePatchUpdate<T>` | `version()` |
+| `...Actors<Id = uuid>` | `createdBy`, `updatedBy`, `deletedBy`, `Id \| null`, read-only | | `actors()` |
+
+TypeSpec's own `url` is the address of a page, `format: uri`, generated as
+`z.url()`. More in [Scalars and columns](docs/guide/columns.md).
+
+### Headers
+
+Spread the headers of an idempotent write and of a rate limit into an
+operation and its replies:
+
+```tsp
+@post create(...IdempotencyKeyHeader, @body post: Create<Post>): {
+  @statusCode _: 201;
+  ...IdempotentReplayedHeader;
+  ...RateLimitHeaders;
+  @body post: Post;
+} | BadRequest | IdempotencyInProgress | IdempotencyKeyReused | TooManyRequests;
+```
+
+| Name | Header | Where |
+| --- | --- | --- |
+| `IdempotencyKeyHeader` | `Idempotency-Key`, 1 to 255 characters, optional | the request: checked |
+| `IdempotentReplayedHeader` | `Idempotent-Replayed: true` | a reply that replays an earlier one |
+| `RateLimitHeaders` | `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` | a rate-limited route's replies |
+| `RetryAfterHeader` | `Retry-After`, in seconds | a 409 or a 429 |
+| `IdempotencyInProgress` | 409, `ConflictBody`, `RateLimit-*`, `Retry-After` | the key's first request still runs |
+| `IdempotencyKeyReused` | 422, `UnprocessableEntityBody`, `RateLimit-*` | the key was used with another body |
+
+`TooManyRequests` carries the `RateLimit-*` headers and `Retry-After` too. The
+generator checks the request's `Idempotency-Key`; a reply's headers are
+documented, not checked. More in [Headers](docs/guide/headers.md).
+
+### Resources
+
+One line gives a resource its five operations, with `@operationIds` names:
+
+```tsp
+model PostFilters {
+  @query status?: PostStatus;
+  @query authorId?: uuid;
+}
+
+@route("/posts")
+interface Posts extends Resource<Post, PostFilters, SortField = "createdAt" | "title"> {}
+```
+
+| Operation | Route | Answers |
+| --- | --- | --- |
+| `listPosts` | `GET /posts`, with the filters, `page`, `pageSize`, `orderBy`, `direction` | `Page<Post>` |
+| `readPosts` | `GET /posts/{id}` | `Post \| NotFound` |
+| `createPosts` | `POST /posts`, `Create<Post>` | 201 `Post \| BadRequest \| Conflict` |
+| `updatePosts` | `PATCH /posts/{id}`, `MergePatchUpdate<Post>` | `Post \| BadRequest \| NotFound \| Conflict` |
+| `deletePosts` | `DELETE /posts/{id}` | 204, `NotFound` |
+
+`orderBy` takes one of the `SortField`s (`SortField` is `"id"` by default), and `direction`
+`asc` (the default) or `desc`, as `@nxgt/drizzle` sorts a page. `{id}`
+is a `uuid`, or the `Id` you name. More in
+[Resources](docs/guide/resources.md).
+
+### Operation ids
+
+TypeSpec names an operation after its interface, `Posts_list`, and the
+generator turns that id into the client's method and its types' prefix. Put
+`@operationIds` on the interface to name each operation after its method and
+the interface instead:
+
+```tsp
+import "@typespec/openapi"; // for @operationId
+
+using OpenAPI;
+
+@route("/posts")
+@operationIds
+interface Posts {
+  @get list(): Post[];                                     // listPosts
+  @get @operationId("getPost") read(@path postId: string): Post | NotFound; // getPost
+}
+```
+
+An operation's own `@operationId` wins. An interface that extends a marked
+one, or an instance of a marked template, is named after itself. An operation
+of a marked interface that has another operation's id is an error,
+`duplicate-operation-id`. More in
+[Operation ids](docs/guide/operation-ids.md).
+
+## API
+
+### Decorators
+
+| Decorator | On | What it does |
+| --- | --- | --- |
+| `@operationIds` | an interface | names each operation `<operation><Interface>`, unless it has an `@operationId` |
+
+### Models
+
+| Model | What it is |
+| --- | --- |
+| `ErrorBody<Status>` | `{ status: Status, message: string, timestamp: utcDateTime }` |
+| `BadRequestBody` | `ErrorBody<400>` and `issues?: ValidationIssue[]` |
+| `UnauthorizedBody` … `InternalServerErrorBody` | `ErrorBody<401>` … `ErrorBody<500>`, one per response above |
+| `PageParameters` | the query `page` and `pageSize`, to spread into an operation's parameters |
+| `Page<Item>` | `{ items: Item[], total, page, pageSize, pageCount }`, the schema `<Item>Page` |
+| `CursorPageParameters` | the query `after` and `limit` |
+| `CursorPage<Item>` | `{ items: Item[], nextCursor: string \| null }`, the schema `<Item>CursorPage` |
+| `ValidationIssue` | `{ target: ValidationTarget, path: (string \| integer)[], code: string, message: string }` |
+| `ValidationTarget` | `"param" \| "query" \| "header" \| "json" \| "form" \| "body" \| "response"` |
+
+### Authentication
+
+| Name | What it is |
+| --- | --- |
+| `JanusAuth` | `BearerAuth \| SessionTokenAuth \| SessionCookieAuth`, for `@useAuth` |
+| `SessionTokenAuth` | an API key in the `X-Session-Token` header |
+| `SessionCookieAuth` | an API key in the `janus-session` cookie |
+
+### Scalars and columns
+
+| Name | What it is |
+| --- | --- |
+| `uuid` | a string, `format: uuid`; the schema `Uuid` |
+| `email` | a string, `format: email`; the schema `Email` |
+| `Timestamps` | `createdAt`, `updatedAt: utcDateTime`, read-only |
+| `SoftDelete` | `deletedAt: utcDateTime \| null`, read-only |
+| `Versioned` | `version: integer`, read and update |
+| `Actors<Id = uuid>` | `createdBy`, `updatedBy`, `deletedBy: Id \| null`, read-only |
+
+### Headers
+
+| Model | What it is |
+| --- | --- |
+| `IdempotencyKeyHeader` | `Idempotency-Key`, 1 to 255 characters, optional: to spread into parameters |
+| `IdempotentReplayedHeader` | `Idempotent-Replayed: "true"`, optional: to spread into a reply |
+| `RateLimitHeaders` | `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, integers, optional |
+| `RetryAfterHeader` | `Retry-After`, seconds, optional |
+
+### Resources
+
+| Name | What it is |
+| --- | --- |
+| `Resource<Item, Filters = {}, SortField = "id", Id = uuid>` | an interface template: `list`, `read`, `create`, `update`, `delete` |
+| `SortParameters<Field>` | the query `orderBy?: Field` and `direction?: "asc" \| "desc" = "asc"` |
+
+### Responses
+
+`AuthenticationRequired` (401) and `AccessDenied` (403), without a body, and
+`ErrorWithoutBody<Status>` for any other status without a body.
+`IdempotencyInProgress` (409) and `IdempotencyKeyReused` (422), with the
+envelope and the rate limit's headers.
+
+`BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `Conflict`,
+`UnprocessableEntity`, `TooManyRequests`, `InternalServerError`, each an
+`@error` model with its `@statusCode` and body, and
+`ErrorResponse<Status>` for any other status.
+
+## Traps
+
+- **Do not declare a schema named `ValidationErrorBody`.** The generator
+  declares it itself, and two schemas of that name fail with
+  `name_collision`. `BadRequestBody` carries the `issues` instead.
+- **`ErrorResponse<503>`'s body is emitted inline**, and generated as
+  `<Operation>503Response`. For a named schema, name the body and the
+  response:
+
+  ```tsp
+  model ServiceUnavailableBody is ErrorBody<503>;
+
+  @error
+  model ServiceUnavailable {
+    @statusCode _: 503;
+    @body body: ServiceUnavailableBody;
+  }
+  ```
+- **One status, one reply.** An operation that declares both
+  `AuthenticationRequired` and `Unauthorized` gets a single 401, with the
+  envelope: the reply without a body is lost, without a warning. Declare the
+  one the route sends: the guard's, or the handler's. The same goes for
+  `Conflict` beside `IdempotencyInProgress`, and `UnprocessableEntity`
+  beside `IdempotencyKeyReused`: both keep one body, but the reply's
+  description is the first one's, and the body a union of the envelope with
+  itself. Declare one of each pair: the `message` key tells them apart.
+- **Both versions at once write two folders.** With
+  `openapi-versions: ['3.1.0', '3.2.0']`, the emitter writes
+  `3.1.0/openapi.yaml` and `3.2.0/openapi.yaml`: point the generator's input
+  at one of them.
+- **The library's schema names are global.** `BadRequestBody` …
+  `InternalServerErrorBody`, `ValidationIssue`, `ValidationTarget`, `Uuid`,
+  `Email`, and each `<Item>Page` and `<Item>CursorPage` are emitted under
+  those names, without a namespace, once the spec uses them. A model of the
+  same name in your spec then fails with `duplicate-type-name`
+  ([troubleshooting](docs/troubleshooting.md)).
+
+## Documentation
+
+- [Error replies](docs/guide/errors.md): the envelope, each response, and
+  what the generator makes of them;
+- [Pagination](docs/guide/pagination.md): offset and cursor pages, and
+  what a handler answers;
+- [Authentication](docs/guide/auth.md): `JanusAuth`, and the guards'
+  replies without a body;
+- [Scalars and columns](docs/guide/columns.md): `uuid`, `email`, and the
+  columns `@nxgt/drizzle` stamps;
+- [Headers](docs/guide/headers.md): `Idempotency-Key`, the rate limit and
+  `Retry-After`;
+- [Resources](docs/guide/resources.md): the five operations of a resource
+  in one line, with its filters and sort;
+- [Operation ids](docs/guide/operation-ids.md): `@operationIds`, and what
+  the generated client calls each operation;
+- [troubleshooting](docs/troubleshooting.md);
+- [the roadmap](docs/roadmap.md): what is coming.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The JavaScript side of the `@nxgt/typespec` library, which `lib/main.tsp`
+ * imports from `dist/`: its name and diagnostics, and the decorators a
+ * template cannot express. The conventions themselves are in `lib/`.
+ *
+ * A decorator is exported only through `$decorators`: a top-level `$name`
+ * export would declare it a second time, in the global namespace.
+ */
+import type { Program } from '@typespec/compiler';
+import { operationIds } from './operation-ids';
+export { $lib } from './lib';
+export declare function $onValidate(program: Program): void;
+export declare const $decorators: {
+    Nxgt: {
+        operationIds: typeof operationIds;
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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;AAClD,OAAO,EAAE,YAAY,EAAwB,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC;AAE7B,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAElD;AAED,eAAO,MAAM,WAAW;;;;CAEvB,CAAC"}

package/dist/index.js

@@ -0,0 +1,75 @@
+// src/operation-ids.ts
+import {
+  isTemplateInstance,
+  navigateProgram
+} from "@typespec/compiler";
+import {
+  getOperationId,
+  resolveOperationId,
+  setOperationId
+} from "@typespec/openapi";
+
+// src/lib.ts
+import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
+var $lib = createTypeSpecLibrary({
+  name: "@nxgt/typespec",
+  diagnostics: {
+    "duplicate-operation-id": {
+      severity: "error",
+      messages: {
+        default: paramMessage`Two operations are named ${"id"}: an OpenAPI operation id must be unique.`
+      }
+    }
+  },
+  state: {
+    operationIds: { description: "The interfaces marked with @operationIds" }
+  }
+});
+
+// src/operation-ids.ts
+function operationIds(context, target) {
+  context.program.stateSet($lib.stateKeys.operationIds).add(target);
+}
+function isMarked(program, target) {
+  return program.stateSet($lib.stateKeys.operationIds).has(target) || target.sourceInterfaces.some((source) => isMarked(program, source));
+}
+function isNamed(program, operation) {
+  const container = operation.interface;
+  return container !== undefined && !isTemplateInstance(container) && isMarked(program, container);
+}
+function validateOperationIds(program) {
+  const seen = new Map;
+  navigateProgram(program, {
+    operation(operation) {
+      const named = isNamed(program, operation);
+      const own = getOperationId(program, operation);
+      const id = own ?? (named ? `${operation.name}${operation.interface?.name}` : resolveOperationId(program, operation));
+      if (seen.has(id) && (named || seen.get(id))) {
+        $lib.reportDiagnostic(program, {
+          code: "duplicate-operation-id",
+          format: { id },
+          target: operation
+        });
+      }
+      seen.set(id, named || (seen.get(id) ?? false));
+      if (named && own === undefined)
+        setOperationId(program, operation, id);
+    }
+  });
+}
+
+// src/index.ts
+function $onValidate(program) {
+  validateOperationIds(program);
+}
+var $decorators = {
+  Nxgt: { operationIds }
+};
+export {
+  $decorators,
+  $lib,
+  $onValidate
+};
+
+//# debugId=2D92CF45DEECB16A64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/operation-ids.ts", "../src/lib.ts", "../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * `@operationIds`: names each operation of an interface after its method and\n * the interface, `<operation><Interface>`, such as `listPets`.\n */\nimport {\n\ttype DecoratorContext,\n\ttype Interface,\n\tisTemplateInstance,\n\tnavigateProgram,\n\ttype Operation,\n\ttype Program,\n} from '@typespec/compiler';\nimport {\n\tgetOperationId,\n\tresolveOperationId,\n\tsetOperationId,\n} from '@typespec/openapi';\nimport { $lib } from './lib';\n\n/**\n * Marks the interface; its ids are set once the program is checked. On a\n * template, TypeSpec runs it on each instance, which `isMarked` follows to\n * the interfaces extending it.\n */\nexport function operationIds(\n\tcontext: DecoratorContext,\n\ttarget: Interface,\n): void {\n\tcontext.program.stateSet($lib.stateKeys.operationIds).add(target);\n}\n\n/** Marked itself, or extending a marked interface: an instance of a marked template included. */\nfunction isMarked(program: Program, target: Interface): boolean {\n\treturn (\n\t\tprogram.stateSet($lib.stateKeys.operationIds).has(target) ||\n\t\ttarget.sourceInterfaces.some((source) => isMarked(program, source))\n\t);\n}\n\n/**\n * Whether `@operationIds` names the operation's id, or checks it: its\n * interface is marked, and is not a template instance, which is never\n * emitted; only the interfaces extending it are.\n */\nfunction isNamed(program: Program, operation: Operation): boolean {\n\tconst container = operation.interface;\n\treturn (\n\t\tcontainer !== undefined &&\n\t\t!isTemplateInstance(container) &&\n\t\tisMarked(program, container)\n\t);\n}\n\n/**\n * Sets the ids, after every decorator, so the order of `@operationId` and\n * `@operationIds` in the source does not matter. Two operations with one id,\n * one of them in a marked interface, are an error: two interfaces of one name\n * in two namespaces, an `@operationId` that `extends` copied, one written\n * elsewhere, or an operation in the service namespace, named after itself. `@typespec/openapi3` would emit both without a word.\n */\nexport function validateOperationIds(program: Program): void {\n\tconst seen = new Map<string, boolean>();\n\tnavigateProgram(program, {\n\t\toperation(operation) {\n\t\t\tconst named = isNamed(program, operation);\n\t\t\tconst own = getOperationId(program, operation);\n\t\t\t// Elsewhere, only checked: the id `@typespec/openapi3` gives under its\n\t\t\t// default strategy; an operation in the service namespace is named\n\t\t\t// after itself.\n\t\t\tconst id =\n\t\t\t\town ??\n\t\t\t\t(named\n\t\t\t\t\t? `${operation.name}${operation.interface?.name}`\n\t\t\t\t\t: resolveOperationId(program, operation));\n\t\t\tif (seen.has(id) && (named || seen.get(id))) {\n\t\t\t\t$lib.reportDiagnostic(program, {\n\t\t\t\t\tcode: 'duplicate-operation-id',\n\t\t\t\t\tformat: { id },\n\t\t\t\t\ttarget: operation,\n\t\t\t\t});\n\t\t\t}\n\t\t\tseen.set(id, named || (seen.get(id) ?? false));\n\t\t\t// Only the ids it gives: an explicit id on any other operation would\n\t\t\t// override the emitter's `operation-id-strategy`.\n\t\t\tif (named && own === undefined) setOperationId(program, operation, id);\n\t\t},\n\t});\n}\n",
+    "/** The library's definition: its name, diagnostics and state keys. */\nimport { createTypeSpecLibrary, paramMessage } from '@typespec/compiler';\n\nexport const $lib = createTypeSpecLibrary({\n\tname: '@nxgt/typespec',\n\tdiagnostics: {\n\t\t'duplicate-operation-id': {\n\t\t\tseverity: 'error',\n\t\t\tmessages: {\n\t\t\t\tdefault: paramMessage`Two operations are named ${'id'}: an OpenAPI operation id must be unique.`,\n\t\t\t},\n\t\t},\n\t},\n\tstate: {\n\t\toperationIds: { description: 'The interfaces marked with @operationIds' },\n\t},\n});\n",
+    "/**\n * The JavaScript side of the `@nxgt/typespec` library, which `lib/main.tsp`\n * imports from `dist/`: its name and diagnostics, and the decorators a\n * template cannot express. The conventions themselves are in `lib/`.\n *\n * A decorator is exported only through `$decorators`: a top-level `$name`\n * export would declare it a second time, in the global namespace.\n */\nimport type { Program } from '@typespec/compiler';\nimport { operationIds, validateOperationIds } from './operation-ids';\n\nexport { $lib } from './lib';\n\nexport function $onValidate(program: Program): void {\n\tvalidateOperationIds(program);\n}\n\nexport const $decorators = {\n\tNxgt: { operationIds },\n};\n"
+  ],
+  "mappings": ";AAIA;AAAA;AAAA;AAAA;AAQA;AAAA;AAAA;AAAA;AAAA;;;ACXA;AAEO,IAAM,OAAO,sBAAsB;AAAA,EACzC,MAAM;AAAA,EACN,aAAa;AAAA,IACZ,0BAA0B;AAAA,MACzB,UAAU;AAAA,MACV,UAAU;AAAA,QACT,SAAS,wCAAwC;AAAA,MAClD;AAAA,IACD;AAAA,EACD;AAAA,EACA,OAAO;AAAA,IACN,cAAc,EAAE,aAAa,2CAA2C;AAAA,EACzE;AACD,CAAC;;;ADQM,SAAS,YAAY,CAC3B,SACA,QACO;AAAA,EACP,QAAQ,QAAQ,SAAS,KAAK,UAAU,YAAY,EAAE,IAAI,MAAM;AAAA;AAIjE,SAAS,QAAQ,CAAC,SAAkB,QAA4B;AAAA,EAC/D,OACC,QAAQ,SAAS,KAAK,UAAU,YAAY,EAAE,IAAI,MAAM,KACxD,OAAO,iBAAiB,KAAK,CAAC,WAAW,SAAS,SAAS,MAAM,CAAC;AAAA;AASpE,SAAS,OAAO,CAAC,SAAkB,WAA+B;AAAA,EACjE,MAAM,YAAY,UAAU;AAAA,EAC5B,OACC,cAAc,aACd,CAAC,mBAAmB,SAAS,KAC7B,SAAS,SAAS,SAAS;AAAA;AAWtB,SAAS,oBAAoB,CAAC,SAAwB;AAAA,EAC5D,MAAM,OAAO,IAAI;AAAA,EACjB,gBAAgB,SAAS;AAAA,IACxB,SAAS,CAAC,WAAW;AAAA,MACpB,MAAM,QAAQ,QAAQ,SAAS,SAAS;AAAA,MACxC,MAAM,MAAM,eAAe,SAAS,SAAS;AAAA,MAI7C,MAAM,KACL,QACC,QACE,GAAG,UAAU,OAAO,UAAU,WAAW,SACzC,mBAAmB,SAAS,SAAS;AAAA,MACzC,IAAI,KAAK,IAAI,EAAE,MAAM,SAAS,KAAK,IAAI,EAAE,IAAI;AAAA,QAC5C,KAAK,iBAAiB,SAAS;AAAA,UAC9B,MAAM;AAAA,UACN,QAAQ,EAAE,GAAG;AAAA,UACb,QAAQ;AAAA,QACT,CAAC;AAAA,MACF;AAAA,MACA,KAAK,IAAI,IAAI,UAAU,KAAK,IAAI,EAAE,KAAK,MAAM;AAAA,MAG7C,IAAI,SAAS,QAAQ;AAAA,QAAW,eAAe,SAAS,WAAW,EAAE;AAAA;AAAA,EAEvE,CAAC;AAAA;;;AEzEK,SAAS,WAAW,CAAC,SAAwB;AAAA,EACnD,qBAAqB,OAAO;AAAA;AAGtB,IAAM,cAAc;AAAA,EAC1B,MAAM,EAAE,aAAa;AACtB;",
+  "debugId": "2D92CF45DEECB16A64756E2164756E21",
+  "names": []
+}

package/dist/lib.d.ts

@@ -0,0 +1,6 @@
+export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
+    'duplicate-operation-id': {
+        readonly default: import("@typespec/compiler").CallableMessage<["id"]>;
+    };
+}, Record<string, any>, "operationIds">;
+//# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,IAAI;;;;uCAaf,CAAC"}

package/dist/operation-ids.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@operationIds`: names each operation of an interface after its method and
+ * the interface, `<operation><Interface>`, such as `listPets`.
+ */
+import { type DecoratorContext, type Interface, type Program } from '@typespec/compiler';
+/**
+ * Marks the interface; its ids are set once the program is checked. On a
+ * template, TypeSpec runs it on each instance, which `isMarked` follows to
+ * the interfaces extending it.
+ */
+export declare function operationIds(context: DecoratorContext, target: Interface): void;
+/**
+ * Sets the ids, after every decorator, so the order of `@operationId` and
+ * `@operationIds` in the source does not matter. Two operations with one id,
+ * one of them in a marked interface, are an error: two interfaces of one name
+ * in two namespaces, an `@operationId` that `extends` copied, one written
+ * elsewhere, or an operation in the service namespace, named after itself. `@typespec/openapi3` would emit both without a word.
+ */
+export declare function validateOperationIds(program: Program): void;
+//# sourceMappingURL=operation-ids.d.ts.map

package/dist/operation-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-ids.d.ts","sourceRoot":"","sources":["../src/operation-ids.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,SAAS,EAId,KAAK,OAAO,EACZ,MAAM,oBAAoB,CAAC;AAQ5B;;;;GAIG;AACH,wBAAgB,YAAY,CAC3B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,SAAS,GACf,IAAI,CAEN;AAwBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2B3D"}

package/docs/README.md

@@ -0,0 +1,15 @@
+# @nxgt/typespec documentation
+
+The [package README](../README.md) is the short version.
+
+| Page | Read it when |
+| --- | --- |
+| [Error replies](guide/errors.md) | declaring what an operation answers when it fails |
+| [Pagination](guide/pagination.md) | listing a collection a page at a time |
+| [Authentication](guide/auth.md) | protecting an operation with a `@nxgt/janus` session |
+| [Scalars and columns](guide/columns.md) | typing ids and addresses, and the columns a row carries |
+| [Headers](guide/headers.md) | making a write idempotent, or declaring a rate limit |
+| [Resources](guide/resources.md) | declaring a resource's five operations at once |
+| [Operation ids](guide/operation-ids.md) | naming the generated client's methods after the spec's |
+| [Troubleshooting](troubleshooting.md) | the compiler or the generator refused the spec |
+| [Roadmap](roadmap.md) | wondering what is coming |