@nxgt/typespec 0.1.0

package/docs/guide/auth.md

@@ -0,0 +1,103 @@
+# Authentication
+
+How an operation says it needs a session, and what it answers without one,
+as [`@nxgt/janus`](https://www.npmjs.com/package/@nxgt/janus) serves it.
+
+## Declaring it
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+namespace Blog;
+
+@route("/posts/{postId}/comments")
+interface Comments {
+  @get list(@path postId: string): Comment[];
+
+  @useAuth(JanusAuth)
+  @delete delete(@path postId: string, @path commentId: string):
+    NoContentResponse | AuthenticationRequired | AccessDenied | ErrorWithoutBody<404>;
+}
+```
+
+`@useAuth` is TypeSpec's own, from `@typespec/http`. On an interface or a
+namespace, it covers every operation inside; `@useAuth(NoAuth)` opens one
+of them again.
+
+## The schemes
+
+`@nxgt/janus` reads a session token from three places, in this order, and
+takes the first it finds:
+
+| Scheme | Where the token is | Emitted as |
+| --- | --- | --- |
+| `BearerAuth` | `Authorization: Bearer <token>` | `type: http`, `scheme: Bearer` |
+| `SessionTokenAuth` | the `X-Session-Token` header | `type: apiKey`, `in: header` |
+| `SessionCookieAuth` | the `janus-session` cookie | `type: apiKey`, `in: cookie` |
+
+`JanusAuth` is the three, as alternatives: any one of them is enough. Each
+is also usable alone, `@useAuth(BearerAuth)` for an API that only takes
+the header. A janus app that renames its cookie declares its own:
+
+```tsp
+model AdminCookieAuth is ApiKeyAuth<ApiKeyLocation.cookie, "admin-session">;
+```
+
+The spec lists them under `securitySchemes`, for its readers and for the
+clients generated from it. `@nxgt/openapi-codegen` does not read them:
+checking the session is the guard's work, not the validators'.
+
+## The refusals, without a body
+
+The guards of [`@nxgt/janus-hono`](https://www.npmjs.com/package/@nxgt/janus-hono)
+refuse a request with a status and nothing else:
+
+| Guard | Refuses with | Declare |
+| --- | --- | --- |
+| `session(auth, { required: true })` | 401: no session, or one the server does not know | `AuthenticationRequired` |
+| `fresh()` | 401: no session | `AuthenticationRequired` |
+| `permission()` | 401: no session | `AuthenticationRequired` |
+| `permission()` | 404: the object does not exist | `ErrorWithoutBody<404>` |
+| `permission()` | 403: its user may not do this | `AccessDenied` |
+
+The generated `hono.ts` types those replies without a body, so the route
+answers them as the guard does:
+
+```ts
+createRoutes(app).delete('/posts/{postId}/comments/{commentId}', async (c) => {
+	// … permission() has let the request through
+	return c.body(null, 204);
+});
+```
+
+A handler that sends one of the guards' replies with a body does not
+type-check. With
+`validateResponses`, `@nxgt/openapi-hono` checks a reply's body only where
+the spec declares one, so it lets a body through on these at run time.
+
+The errors `janusErrors()` answers are another shape: `fresh()`'s step-up
+403 and janus's own errors carry its `{ code }` body, which this library does
+not declare.
+
+## Beside a handler's refusal
+
+A handler that refuses on its own, after the guard, answers with the
+envelope: `Unauthorized` or `Forbidden` ([Error replies](errors.md)). An
+operation can declare the guard's 401 and the handler's 403:
+
+```tsp
+@useAuth(JanusAuth)
+@post create(@body post: Create<Post>): {
+  @statusCode _: 201;
+  @body post: Post;
+} | BadRequest | AuthenticationRequired | Forbidden;
+```
+
+Not both replies of one status, though: an operation that declares
+`AuthenticationRequired` and `Unauthorized` gets a single 401, with the
+envelope, and the reply without a body is lost without a warning. Declare
+the one the route sends.

package/docs/guide/columns.md

@@ -0,0 +1,117 @@
+# Scalars and columns
+
+Two scalars for the strings every API has, and the columns
+[`@nxgt/drizzle`](https://www.npmjs.com/package/@nxgt/drizzle) stamps a row
+with, as models to spread.
+
+## Scalars
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+namespace Blog;
+
+model Author {
+  @visibility(Lifecycle.Read) id: uuid;
+  email: email;
+  site?: url;
+}
+
+@route("/authors/{authorId}")
+@get op readAuthor(@path authorId: uuid): Author;
+```
+
+| Scalar | Emitted as | Generated | Refused |
+| --- | --- | --- | --- |
+| `uuid` | `$ref` to the schema `Uuid`: `type: string`, `format: uuid` | `type Uuid = string`, `zUuid = z.guid()` | `42`, in a path, a query or a body |
+| `email` | `$ref` to the schema `Email`: `format: email` | `type Email = string`, `zEmail = z.email()` | `not an address` |
+| `url` | TypeSpec's own: `format: uri`, inline | `z.url()` | `not a url` |
+
+`z.guid()` checks the shape of a UUID, as JSON Schema's `uuid` does, not
+the version and variant bits `z.uuid()` also checks.
+
+## Columns
+
+`@nxgt/drizzle/pg` declares a table's stamps with its column helpers. The
+models here are the same columns, as the API sends them:
+
+```ts
+pgTable('posts', {
+	id: id(),
+	title: text('title').notNull(),
+	...timestamps(),
+	...version(),
+	...actors(),
+});
+```
+
+```tsp
+model Post {
+  @visibility(Lifecycle.Read) id: uuid;
+  title: string;
+  ...Timestamps;
+  ...Versioned;
+  ...Actors;
+}
+```
+
+| Model | Properties | Visibility | drizzle |
+| --- | --- | --- | --- |
+| `Timestamps` | `createdAt`, `updatedAt: utcDateTime` | read | `timestamps()` |
+| `SoftDelete` | `deletedAt: utcDateTime \| null` | read | `softDelete()` |
+| `Versioned` | `version: integer`, at least 0 | read, update | `version()` |
+| `Actors<Id = uuid>` | `createdBy`, `updatedBy`, `deletedBy: Id \| null` | read | `actors()` |
+
+The server sets every read-only column, so `Create<Post>` and
+`MergePatchUpdate<Post>` leave them out, and the generated `CreatePost` and
+`PostMergePatchUpdate` have no `createdAt` a client could send.
+`Actors<string>` or `Actors<integer>` match `actors('text')` or
+`actors('integer')`.
+
+## The version in an update
+
+`version` is read with the row and sent back in an update. `@nxgt/drizzle`
+takes it as a condition: it writes the update only while the row is still at
+that version, and throws `OptimisticLockError` otherwise. Declare the
+`Conflict` it becomes:
+
+```tsp
+@patch update(@path postId: uuid, @body post: MergePatchUpdate<Post>):
+  Post | BadRequest | NotFound | Conflict;
+```
+
+```ts
+import { OptimisticLockError } from '@nxgt/drizzle';
+import { Hono } from 'hono';
+import { createRoutes } from './generated/hono';
+import type { ConflictBody } from './generated/types';
+
+const app = new Hono();
+createRoutes(app).patch('/posts/{postId}', async (c) => {
+	try {
+		const post = await posts.update(c.req.valid('param').postId, c.req.valid('json'));
+		return c.json(post, 200);
+	} catch (error) {
+		if (!(error instanceof OptimisticLockError)) throw error;
+		const body: ConflictBody = {
+			status: 409,
+			message: 'errors.version-conflict',
+			timestamp: new Date().toISOString(),
+		};
+		return c.json(body, 409);
+	}
+});
+```
+
+In a merge patch, every property is optional, `version` too: an update
+without it is not checked against the version.
+
+## Names
+
+`Uuid` and `Email` are schemas of their own, and their names are global: a
+model named `Email` in a spec that also uses `email` collides with it
+([troubleshooting](../troubleshooting.md)).

package/docs/guide/errors.md

@@ -0,0 +1,190 @@
+# Error replies
+
+`@nxgt/typespec` declares the error replies the `@nxgt/*` packages send, so a
+spec names them instead of describing them again.
+
+## A whole spec
+
+```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
+```
+
+The spec is split by role, as it grows: `main.tsp` assembles, `models/`
+holds the shapes and `routes/` the operations and their errors.
+
+```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;
+}
+```
+
+```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;
+}
+```
+
+```ts
+// openapi-codegen.config.ts
+import { defineConfig } from '@nxgt/openapi-codegen';
+
+export default defineConfig({
+	input: 'openapi/openapi.yaml',
+	output: 'src/generated',
+	hono: true,
+});
+```
+
+```sh
+bunx --no-install tsp compile api && bunx nxgt-openapi generate
+```
+
+A Hono handler then answers the 404 with the generated type. The generated
+`hono.ts` imports
+[`@nxgt/openapi-hono`](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-hono/README.md),
+and its validators `zod`: install them with `hono`.
+
+```sh
+bun add @nxgt/openapi-hono hono zod
+```
+
+
+```ts
+import { Hono } from 'hono';
+import { createRoutes } from './generated/hono';
+import type { NotFoundBody } from './generated/types';
+
+const app = new Hono();
+createRoutes(app).get('/posts/{postId}', (c) => {
+	const body: NotFoundBody = {
+		status: 404,
+		message: 'errors.not-found',
+		timestamp: new Date().toISOString(),
+	};
+	return c.json(body, 404);
+});
+```
+
+## The envelope
+
+Every error body is `ErrorBody<Status>`, the envelope of
+`@nxgt/openapi-hono`'s own replies, which a handler answers with too:
+
+```tsp
+model ErrorBody<Status extends integer> {
+  status: Status;        // the reply's status, repeated
+  message: string;       // an i18n key: errors.not-found
+  timestamp: utcDateTime;
+}
+```
+
+`message` is a key for the client to translate, never a sentence. `status`
+is a literal, so the generated type narrows on it:
+
+```ts
+export interface NotFoundBody {
+	status: 404;
+	message: string;
+	timestamp: string;
+}
+```
+
+## The 400
+
+`@nxgt/openapi-hono` refuses a request its validators reject with a 400 that
+lists every value refused:
+
+```json
+{
+	"status": 400,
+	"message": "errors.validation-failed",
+	"timestamp": "2026-09-29T08:00:00.000Z",
+	"issues": [
+		{ "target": "json", "path": ["title"], "code": "too_small", "message": "Too small" }
+	]
+}
+```
+
+A handler may send a 400 of its own, without `issues`. `BadRequestBody`
+describes both, with `issues` optional:
+
+```tsp
+@patch update(@path postId: string, @body post: MergePatchUpdate<Post>): Post | BadRequest;
+```
+
+The generator declares the validators' 400 itself, as `ValidationErrorBody`,
+on every operation that takes a parameter or a body, whether the spec says
+so or not. Beside `BadRequest`, the 400 is typed
+`BadRequestBody | ValidationErrorBody`. An app that answers a refused request
+its own way, through `onValidationError`, turns that off with the generator's
+[`validationErrors: false`](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-codegen/docs/guide/options.md#validationerrors).
+
+## Each response
+
+| Response | Status | Body | Sent when |
+| --- | --- | --- | --- |
+| `BadRequest` | 400 | `BadRequestBody` | the validators or a handler refuse the request |
+| `Unauthorized` | 401 | `UnauthorizedBody` | no credentials, or invalid ones; a `@nxgt/janus-hono` guard sends `AuthenticationRequired` instead ([Authentication](auth.md)) |
+| `Forbidden` | 403 | `ForbiddenBody` | authenticated, but not allowed; a `@nxgt/janus-hono` guard sends `AccessDenied` instead, and `janusErrors()` its own `{ code }` body ([Authentication](auth.md)) |
+| `NotFound` | 404 | `NotFoundBody` | nothing is there |
+| `Conflict` | 409 | `ConflictBody` | the request conflicts with the resource's state, such as a stale `version` |
+| `UnprocessableEntity` | 422 | `UnprocessableEntityBody` | well-formed, but not something the server can act on |
+| `TooManyRequests` | 429 | `TooManyRequestsBody` | too many requests; with the `RateLimit-*` headers and `Retry-After` ([Headers](headers.md)) |
+| `InternalServerError` | 500 | `InternalServerErrorBody` | the server failed; with `validateResponses`, `@nxgt/openapi-hono` sends it with `errors.response-validation-failed` when a reply breaks the spec |
+| `ErrorResponse<Status>` | any | `ErrorBody<Status>` | any other status |
+
+Name them in an operation's return type, beside the success:
+
+```tsp
+@get read(@path postId: string): Post | NotFound | Unauthorized | Forbidden;
+```
+
+## Another status, named
+
+`ErrorResponse<503>` works, but its body is emitted inline and generated as
+`<Operation>503Response`. For a named schema, declare the body and the
+response once:
+
+```tsp
+model ServiceUnavailableBody is ErrorBody<503>;
+
+@error
+model ServiceUnavailable {
+  @statusCode _: 503;
+  @body body: ServiceUnavailableBody;
+}
+```

package/docs/guide/headers.md

@@ -0,0 +1,96 @@
+# Headers
+
+The headers of an idempotent write and of a rate limit, with the replies
+that go with them.
+
+## An idempotent write
+
+A client that may retry a write sends an `Idempotency-Key` with it: the
+server writes once, and answers a retry with the first answer.
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+namespace Blog;
+
+@route("/posts")
+interface Posts {
+  @post create(...IdempotencyKeyHeader, @body post: Create<Post>): {
+    @statusCode _: 201;
+    ...IdempotentReplayedHeader;
+    @body post: Post;
+  } | BadRequest | IdempotencyInProgress | IdempotencyKeyReused;
+}
+```
+
+- `...IdempotencyKeyHeader` adds the optional `Idempotency-Key` header, 1 to
+  255 characters. The generated validators check it: an empty key, or a
+  longer one, is a 400. A handler reads it as
+  `c.req.valid('header')['idempotency-key']`.
+- `...IdempotentReplayedHeader` declares `Idempotent-Replayed: true` on the
+  reply that replays an earlier one.
+- `IdempotencyInProgress` is the 409 of a key whose first request still
+  runs, with `Retry-After` and the `ConflictBody` envelope. The client
+  retries as it is.
+- `IdempotencyKeyReused` is the 422 of a key sent again with another body,
+  with the `UnprocessableEntityBody` envelope. The client takes a new key.
+
+Both carry the `RateLimit-*` headers, as a route that also has a rate limit
+answers them. An operation that declares `Conflict` too, for its optimistic
+lock, gets one 409 with the description of the first: declare one of the
+two, and tell them apart by the `message` key.
+
+## A rate limit
+
+```tsp
+@post create(@body post: Create<Post>): {
+  @statusCode _: 201;
+  ...RateLimitHeaders;
+  @body post: Post;
+} | BadRequest | TooManyRequests;
+```
+
+| Header | Value |
+| --- | --- |
+| `RateLimit-Limit` | how many requests a full window allows |
+| `RateLimit-Remaining` | how many more are allowed now, after this one |
+| `RateLimit-Reset` | seconds until the window is full again, rounded up |
+| `Retry-After` | seconds to wait before trying again: a delay, never a date |
+
+`TooManyRequests`, `IdempotencyInProgress` and `IdempotencyKeyReused`
+carry the three `RateLimit-*` headers already. `...RateLimitHeaders` adds
+them to a reply the spec declares inline, such as the 201 above.
+
+## What is checked
+
+The generator checks a request's headers, as it checks its query: the
+`Idempotency-Key` arrives valid, or the request is a 400. It does not check
+a reply's headers: they are in the spec for a client to read, and the
+handler sets them:
+
+```ts
+import { Hono } from 'hono';
+import { createRoutes } from './generated/hono';
+
+const app = new Hono();
+createRoutes(app).post('/posts', async (c) => {
+	const key = c.req.valid('header')['idempotency-key'];
+	// … look the key up; on a replay, answer the post it wrote:
+	const post = await replayed(key);
+	c.header('Idempotent-Replayed', 'true');
+	return c.json(post, 201);
+});
+```
+
+Every header here is optional, in the spec as on the wire: a route without
+an idempotency store or a rate limiter declares none of them.
+
+## Not yet
+
+`ETag`, `If-None-Match` and `If-Match` are not declared here: the
+`@nxgt/*` packages do not send an `ETag` the same way yet. The optimistic
+lock is the body's `version` ([Scalars and columns](columns.md)).

package/docs/guide/operation-ids.md

@@ -0,0 +1,113 @@
+# Operation ids
+
+An OpenAPI operation id is what `@nxgt/openapi-codegen` names everything
+after: the client's method, the `operations` entry, and the prefix of the
+operation's types (`ListPostsQuery`, `zGetPostParam`).
+
+## What TypeSpec does alone
+
+Without an `@operationId`, `@typespec/openapi3` names an operation after its
+interface and its method, joined by `_`:
+
+```tsp
+@route("/posts")
+interface Posts {
+  @get list(@query status?: PostStatus): Post[]; // Posts_list
+  @post create(@body post: Create<Post>): Post;  // Posts_create
+}
+```
+
+The client then calls `Posts_list`, and its types are `PostsListQuery`.
+Writing an `@operationId` on each operation fixes that, one line per
+operation.
+
+## `@operationIds`
+
+Put it on the interface, once:
+
+```tsp
+import "@typespec/http";
+import "@typespec/openapi";
+import "@nxgt/typespec";
+
+using Http;
+using OpenAPI;
+using Nxgt;
+
+namespace Blog;
+
+@route("/posts")
+@operationIds
+interface Posts {
+  @get list(@query status?: PostStatus): Post[];                  // listPosts
+  @get @operationId("getPost") read(@path postId: string): Post | NotFound; // getPost
+  @post create(@body post: Create<Post>): Post | BadRequest;      // createPosts
+  @patch update(@path postId: string, @body post: MergePatchUpdate<Post>): Post | NotFound; // updatePosts
+  @delete delete(@path postId: string): NoContentResponse | NotFound; // deletePosts
+}
+```
+
+- Each operation is named `<operation><Interface>`: the method's name, then
+  the interface's, as written.
+- An operation with its own `@operationId` keeps it, whether it is written
+  before or after `@operationIds`. `import "@typespec/openapi"` and
+  `using OpenAPI` are only needed for that `@operationId`.
+- An interface that `extends` a marked one is marked too, and names the
+  operations it inherits after itself: `interface Drafts extends Posts {}`
+  gives `listDrafts`. An inherited `@operationId` is copied as is, though,
+  so `Drafts` would name its `read` `getPost` too: see below.
+
+The generated `operations` then has one entry per id:
+
+```ts
+import { operations } from './generated/operations';
+
+Object.keys(operations);
+// ['listPosts', 'createPosts', 'getPost', 'updatePosts', 'deletePosts']
+```
+
+## On a template
+
+On an interface template, `@operationIds` names the operations of each
+interface that extends an instance, after that interface:
+
+```tsp
+@operationIds
+interface Resource<Item> {
+  @get list(): Item[];
+}
+
+@route("/pets")
+interface Pets extends Resource<Pet> {}     // listPets
+
+@route("/orders")
+interface Orders extends Resource<Order> {} // listOrders
+```
+
+## Two operations named alike
+
+An id must be unique, and four cases break that:
+
+- the namespace is not part of the id, so `Store.Pets` and `Shelter.Pets`
+  would both name their `list` `listPets`;
+- an `@operationId` is copied by `extends`, so `Drafts extends Posts` would
+  have a second `getPost`;
+- an `@operationId` written on another operation, in any interface, takes
+  the id `@operationIds` gives;
+- an operation declared in the service namespace is named after itself, so
+  `op listPets()` takes the id of `Pets.list`.
+
+`@operationIds` refuses each with `duplicate-operation-id`, where
+`@typespec/openapi3` would emit both without a word. Give one of them its own
+`@operationId`; an inherited operation takes one by being declared again in
+the interface that extends ([troubleshooting](../troubleshooting.md)).
+
+## Without the library
+
+The emitter's own option, `operation-id-strategy`, only chooses between
+`parent-container` (`Posts_list`, the default), `fqn` (with the namespace)
+and `explicit-only`. None of them gives `listPosts`.
+
+`@operationIds` only names the operations of the interfaces it marks: the
+strategy still names every other one. The check for two operations named
+alike reads their ids as the default strategy gives them.