@nxgt/typespec 0.1.0

package/docs/guide/pagination.md

@@ -0,0 +1,138 @@
+# Pagination
+
+Two ways to list a collection a page at a time, with the query and the page
+[`@nxgt/drizzle`](https://www.npmjs.com/package/@nxgt/drizzle) and
+[`@nxgt/mongo`](https://www.npmjs.com/package/@nxgt/mongo) use:
+
+| | Query | Page | Use it when |
+| --- | --- | --- | --- |
+| Offset | `...PageParameters` | `Page<Item>` | a client jumps to a page, and shows a total |
+| Cursor | `...CursorPageParameters` | `CursorPage<Item>` | a client scrolls on, and the collection is large or changes under it |
+
+## Offset
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+namespace Blog;
+
+@route("/posts")
+interface Posts {
+  @get list(@query status?: PostStatus, ...PageParameters): Page<Post>;
+}
+```
+
+`...PageParameters` adds two query parameters:
+
+- `page`: 1-based, 1 when absent;
+- `pageSize`: 20 when absent.
+
+Both must be integers of at least 1, or `@nxgt/openapi-hono` answers its
+400. `Page<Post>` is the schema `PostPage`:
+
+```json
+{ "items": [], "total": 42, "page": 3, "pageSize": 20, "pageCount": 3 }
+```
+
+`pageCount` is `ceil(total / pageSize)`, 0 when nothing matches. A page past
+the last one has no items and the same `total`.
+
+## Cursor
+
+```tsp
+@route("/posts/{postId}/comments")
+interface Comments {
+  @get list(
+    @path postId: string,
+    ...CursorPageParameters,
+  ): CursorPage<Comment> | BadRequest | NotFound;
+}
+```
+
+`...CursorPageParameters` adds:
+
+- `after`: the previous page's `nextCursor`, absent for the first page;
+- `limit`: 20 when absent, an integer of at least 1.
+
+`CursorPage<Comment>` is the schema `CommentCursorPage`, with no total:
+
+```json
+{ "items": [], "nextCursor": "eyJpZCI6NDJ9" }
+```
+
+`nextCursor` is `null` on the last page. It is opaque: a client sends it
+back as it is.
+
+## Serving it
+
+The generated query arrives checked, with its defaults filled in, so it
+goes to `@nxgt/drizzle` as it is. The page it returns is the generated type,
+when the table's rows are what the spec's `Post` describes:
+
+```ts
+import { Hono } from 'hono';
+import { createRoutes } from './generated/hono';
+import type { PostPage } from './generated/types';
+
+const app = new Hono();
+createRoutes(app).get('/posts', async (c) => {
+	const { page, pageSize } = c.req.valid('query');
+	const body: PostPage = await posts.paginate({ page, pageSize });
+	return c.json(body, 200);
+});
+```
+
+A cursor that was not written by the server, or for another ordering, makes
+`@nxgt/drizzle` throw `InvalidCursorError`. That is the client's input:
+declare `BadRequest` on the operation, as above, and answer it:
+
+```ts
+import { InvalidCursorError } from '@nxgt/drizzle';
+import type { BadRequestBody, CommentCursorPage } from './generated/types';
+
+createRoutes(app).get('/posts/{postId}/comments', async (c) => {
+	const { after, limit } = c.req.valid('query');
+	try {
+		const body: CommentCursorPage = await comments.paginateByCursor({ after, limit });
+		return c.json(body, 200);
+	} catch (error) {
+		if (!(error instanceof InvalidCursorError)) throw error;
+		const body: BadRequestBody = {
+			status: 400,
+			message: 'errors.invalid-cursor',
+			timestamp: new Date().toISOString(),
+		};
+		return c.json(body, 400);
+	}
+});
+```
+
+## The largest page
+
+Neither `pageSize` nor `limit` has a maximum in the spec. A server lowers one
+above its own maximum to it, as `@nxgt/drizzle` does with 100 by default,
+rather than refusing the request. A client reads the `pageSize` the page
+reports, not the one it asked for.
+
+## Names
+
+`Page<Item>` is named `<Item>Page`, and `CursorPage<Item>` `<Item>CursorPage`,
+after the item's model: `PostPage`, `CommentCursorPage`. Those names are
+global, as the library's other schemas are: a model named `PostPage` in the
+spec collides with `Page<Post>`
+([troubleshooting](../troubleshooting.md)).
+
+Give the item a name: a page of an anonymous type is named after what
+TypeSpec calls it, `Page<Post[]>` gives `ArrayPage` and
+`CursorPage<Cat | Dog>` gives `undefinedCursorPage`. Name the union, and the
+page follows:
+
+```tsp
+union Pet { cat: Cat, dog: Dog }
+
+@get list(...PageParameters): Page<Pet>; // PetPage
+```

package/docs/guide/resources.md

@@ -0,0 +1,112 @@
+# Resources
+
+`Resource` gives a resource its five operations in one line: list, read,
+create, update and delete, with the replies each one can send.
+
+## One resource
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+namespace Blog;
+
+model Author {
+  @visibility(Lifecycle.Read) id: uuid;
+  name: string;
+  email: email;
+  ...Timestamps;
+}
+
+model AuthorFilters {
+  /** Authors of this name. */
+  @query name?: string;
+}
+
+@route("/authors")
+interface Authors extends Resource<Author, AuthorFilters, SortField = "name" | "createdAt"> {}
+```
+
+| Operation | Route | Body | Answers |
+| --- | --- | --- | --- |
+| `listAuthors` | `GET /authors` | | `Page<Author>` |
+| `readAuthors` | `GET /authors/{id}` | | `Author`, `NotFound` |
+| `createAuthors` | `POST /authors` | `Create<Author>` | 201 `Author`, `BadRequest`, `Conflict` |
+| `updateAuthors` | `PATCH /authors/{id}` | `MergePatchUpdate<Author>` | `Author`, `BadRequest`, `NotFound`, `Conflict` |
+| `deleteAuthors` | `DELETE /authors/{id}` | | 204, `NotFound` |
+
+The template carries `@operationIds`, so each operation is named after the
+interface that extends it. The generator's own 400 is on every operation
+that takes a parameter or a body, as always.
+
+## The template's arguments
+
+`Resource<Item, Filters = {}, SortField = "id", Id = uuid>`. Name the ones
+after `Filters`, as above, to skip those you keep:
+
+- `Item`: the resource's model. `Create<Item>` and `MergePatchUpdate<Item>`
+  leave its read-only properties out, such as `id` and the `Timestamps`.
+- `Filters`: a model of `@query` properties, spread into `list`. Each is
+  typed and checked, as any query parameter.
+- `SortField`: the fields `list` may sort by, as a union of strings.
+- `Id`: the type of `{id}`. `Id = integer` for a table whose id is
+  `@nxgt/drizzle`'s `id('identity')`.
+
+## Filters and sort
+
+`list` takes the filters, the offset page's `page` and `pageSize`, and
+`SortParameters<SortField>`:
+
+| Query | Default | Checked |
+| --- | --- | --- |
+| `orderBy` | none: the server's order, the primary key with `@nxgt/drizzle` | one of the `SortField`s |
+| `direction` | `asc` | `asc` or `desc` |
+
+`?orderBy=email` on `Authors` is a 400: `email` is not a `SortField`. The
+handler passes them to `@nxgt/drizzle`:
+
+```ts
+import { Hono } from 'hono';
+import { createRoutes } from './generated/hono';
+
+const app = new Hono();
+createRoutes(app).get('/authors', async (c) => {
+	const { name, page, pageSize, orderBy, direction } = c.req.valid('query');
+	const found = await authors.paginate({
+		where: name === undefined ? {} : { name },
+		page,
+		pageSize,
+		// paginate takes the sort as an object of directions by field
+		...(orderBy === undefined ? {} : { orderBy: { [orderBy]: direction } }),
+	});
+	return c.json(found, 200);
+});
+```
+
+`paginateByCursor` takes them apart instead, `{ orderBy, direction }`, as
+the query has them.
+
+`SortParameters<Field>` works on its own too, in any list:
+
+```tsp
+@get list(...PageParameters, ...SortParameters<"createdAt" | "title">): Page<Post>;
+```
+
+## Changing an operation
+
+An interface that extends `Resource` can declare one of its operations
+again, and its own replaces the template's. A list paged by cursor:
+
+```tsp
+@route("/comments")
+interface Comments extends Resource<Comment> {
+  @get list(...CursorPageParameters): CursorPage<Comment>;
+}
+```
+
+Add `@useAuth(JanusAuth)` on the interface to protect all five, and name the
+guards' replies in the operations you declare again
+([Authentication](auth.md)).

package/docs/roadmap.md

@@ -0,0 +1,38 @@
+# Roadmap
+
+What `@nxgt/typespec` gives a spec, and what is coming. Each convention is the
+shape the `@nxgt/*` packages already send, compiled to OpenAPI 3.1 and 3.2 and
+generated by `@nxgt/openapi-codegen` in CI before it ships.
+
+## Now
+
+- **Error replies.** The envelope `@nxgt/openapi-hono` sends, and the
+  400, 401, 403, 404, 409, 422, 429 and 500 responses, with any other status
+  through `ErrorResponse<Status>`.
+- **Pagination.** `PageParameters` and `Page<Item>` for an offset page,
+  `CursorPageParameters` and `CursorPage<Item>` for a cursor page, as
+  `@nxgt/drizzle` and `@nxgt/mongo` page.
+- **Authentication.** `JanusAuth`, the bearer, header and cookie schemes
+  `@nxgt/janus` reads, and its guards' 401, 403 and 404 without a body.
+- **Scalars and columns.** `uuid` and `email`, and `Timestamps`,
+  `SoftDelete`, `Versioned` and `Actors`, the columns `@nxgt/drizzle`
+  stamps a row with.
+- **Headers.** `Idempotency-Key`, `Idempotent-Replayed`, the `RateLimit-*`
+  headers and `Retry-After`, and the idempotent write's 409 and 422.
+- **Resources.** `Resource<Item, Filters, SortField, Id>`: list, read,
+  create, update and delete in one template, with typed filters and a sort
+  by `orderBy` and `direction`.
+- **Operation ids.** `@operationIds` names an interface's operations
+  `listPosts`, `createPosts`, instead of `Posts_list`.
+
+## Next
+
+- **One reply per status.** An error when an operation declares two replies
+  of one status, such as `AuthenticationRequired` and `Unauthorized`, which
+  the emitter merges without a warning today.
+
+## Later
+
+- **`ETag` and conditional requests.** `ETag`, with `If-None-Match` and
+  `If-Match`, once the `@nxgt/*` packages send one the same way. The
+  optimistic lock is the body's `version` today (`Versioned`).

package/docs/troubleshooting.md

@@ -0,0 +1,109 @@
+# Troubleshooting
+
+## `schema ValidationErrorBody and schema ValidationErrorBody would both generate ValidationErrorBody`
+
+**When:** the spec declares a schema named `ValidationErrorBody`, for
+instance to describe the 400 with its `issues`.
+
+**Why:** `@nxgt/openapi-codegen` declares `ValidationErrorBody` itself, on
+every operation that takes a parameter or a body, and refuses two schemas of
+one name with `name_collision`.
+
+**Fix:** answer `BadRequest`. Its `BadRequestBody` carries the `issues`,
+optional, and the generator adds its own 400 beside it.
+
+```tsp
+@patch update(@path postId: string, @body post: MergePatchUpdate<Post>): Post | BadRequest;
+```
+
+## `Couldn't resolve import "@nxgt/typespec"`
+
+**When:** `tsp compile` runs on a spec that imports the library.
+
+**Why:** the library is not installed where the spec is, or the project has
+no `package.json` to resolve it from.
+
+**Fix:** install it and its peers next to the spec's project, as
+devDependencies, with the command in the
+[README's Install section](../README.md#install).
+
+## `Duplicate type name: 'NotFoundBody'`
+
+**When:** `tsp compile` runs on a spec that declares its own model named like
+one of the library's: `BadRequestBody` … `InternalServerErrorBody`,
+`ValidationIssue`, `ValidationTarget`, `Uuid` or `Email` when the spec uses
+`uuid` or `email`, or the page of one of its models,
+such as `PostPage` beside `Page<Post>`, or `CommentCursorPage` beside
+`CursorPage<Comment>`.
+
+```text
+error @typespec/openapi/duplicate-type-name: Duplicate type name: 'NotFoundBody'. Check @friendlyName decorators and overlap with types in TypeSpec or service namespace.
+```
+
+**Why:** the library names its schemas with `@friendlyName`, without a
+namespace, so they share the spec's schema names.
+
+**Fix:** reuse the library's model, or rename yours:
+
+```tsp
+@get read(@path postId: string): Post | NotFound;
+```
+
+## `Two operations are named listPets: an OpenAPI operation id must be unique`
+
+**When:** an operation of an `@operationIds` interface has the id of another
+operation:
+
+- two interfaces of one name, in two namespaces, share an operation name:
+  `Store.Pets` and `Shelter.Pets` both give `listPets`;
+- an interface `extends` another, whose operation has an `@operationId`:
+  `extends` copies it as is;
+- an `@operationId` written elsewhere takes the id `@operationIds` gives;
+- an operation declared in the service namespace is named after itself:
+  `op listPets()` takes the id of `Pets.list`.
+
+```text
+error @nxgt/typespec/duplicate-operation-id: Two operations are named listPets: an OpenAPI operation id must be unique.
+```
+
+**Why:** `@operationIds` names each operation `<operation><Interface>`, without
+the namespace. `@typespec/openapi3` would emit both ids without a word, and
+the generator would then refuse the spec.
+
+**Fix:** give one of them its own `@operationId`. An inherited operation takes
+one by being declared again in the interface that extends:
+
+```tsp
+import "@typespec/openapi";
+
+using OpenAPI;
+
+@route("/drafts")
+interface Drafts extends Posts {
+  @get @operationId("getDraft") read(@path postId: string): Post | NotFound;
+}
+```
+
+## `Unknown decorator @operationId`
+
+**When:** a spec writes `@operationId` next to `@operationIds`.
+
+**Why:** `@operationIds` comes from `@nxgt/typespec`, but `@operationId`
+comes from `@typespec/openapi`, which the file does not import.
+
+**Fix:** import it in that file:
+
+```tsp
+import "@typespec/openapi";
+
+using OpenAPI;
+```
+
+## `unsupported_version` from the generator
+
+**When:** you generate from what `tsp compile` emitted.
+
+**Why:** `@typespec/openapi3` emits OpenAPI 3.0 by default.
+
+**Fix:** in `tspconfig.yaml`, set `openapi-versions: ['3.1.0']` or
+`['3.2.0']` under the `@typespec/openapi3` options.

package/lib/auth.tsp

@@ -0,0 +1,43 @@
+import "@typespec/http";
+
+using Http;
+
+namespace Nxgt;
+
+/**
+ * A session token in the `X-Session-Token` header, as `@nxgt/janus` reads it
+ * after `Authorization: Bearer`.
+ */
+model SessionTokenAuth is ApiKeyAuth<ApiKeyLocation.header, "X-Session-Token">;
+
+/**
+ * A session token in the `janus-session` cookie, as `@nxgt/janus` sets it for
+ * a browser.
+ */
+model SessionCookieAuth is ApiKeyAuth<ApiKeyLocation.cookie, "janus-session">;
+
+/**
+ * Every way `@nxgt/janus` reads a session token, in its order:
+ * `Authorization: Bearer`, then `X-Session-Token`, then the `janus-session`
+ * cookie. Any one of them is enough. Use it with `@useAuth(JanusAuth)`.
+ */
+alias JanusAuth = BearerAuth | SessionTokenAuth | SessionCookieAuth;
+
+// An error reply without a body, as the @nxgt/janus guards send one:
+// session(auth, { required: true }) and permission() answer 401, 403 or 404
+// with no body.
+/** The request was refused; the reply has no body. */
+@error
+model ErrorWithoutBody<Status extends integer> {
+  @statusCode _: Status;
+}
+
+// A handler's own 401, with the envelope, is Unauthorized.
+/** The request carries no session, or one the server does not know. */
+@error
+model AuthenticationRequired is ErrorWithoutBody<401>;
+
+// A handler's own 403, with the envelope, is Forbidden.
+/** The session's user may not do this. */
+@error
+model AccessDenied is ErrorWithoutBody<403>;

package/lib/columns.tsp

@@ -0,0 +1,50 @@
+namespace Nxgt;
+
+/**
+ * `createdAt` and `updatedAt`, as `@nxgt/drizzle`'s `timestamps()` columns
+ * hold them. Set by the server: read-only. Spread it into a model.
+ */
+model Timestamps {
+  @visibility(Lifecycle.Read)
+  createdAt: utcDateTime;
+
+  @visibility(Lifecycle.Read)
+  updatedAt: utcDateTime;
+}
+
+/**
+ * `deletedAt`, as `@nxgt/drizzle`'s `softDelete()` column holds it: `null`
+ * until the row is deleted. Set by the server: read-only.
+ */
+model SoftDelete {
+  @visibility(Lifecycle.Read)
+  deletedAt: utcDateTime | null;
+}
+
+/**
+ * `version`, as `@nxgt/drizzle`'s `version()` column holds it: the optimistic
+ * lock. Read with the row, and sent back in an update, which the server
+ * refuses with a 409 once the row has moved on.
+ */
+model Versioned {
+  @visibility(Lifecycle.Read, Lifecycle.Update)
+  @minValue(0)
+  version: integer;
+}
+
+/**
+ * `createdBy`, `updatedBy` and `deletedBy`, as `@nxgt/drizzle`'s `actors()`
+ * columns hold them: the id of who wrote the row, `null` when nobody is
+ * known. Set by the server: read-only. `Id` is `uuid` by default; `string`
+ * or `integer` for `actors('text')` or `actors('integer')`.
+ */
+model Actors<Id = uuid> {
+  @visibility(Lifecycle.Read)
+  createdBy: Id | null;
+
+  @visibility(Lifecycle.Read)
+  updatedBy: Id | null;
+
+  @visibility(Lifecycle.Read)
+  deletedBy: Id | null;
+}

package/lib/errors.tsp

@@ -0,0 +1,148 @@
+import "@typespec/http";
+
+using Http;
+
+/**
+ * nxgt's HTTP conventions, as the `@nxgt/*` packages serve them.
+ */
+namespace Nxgt;
+
+/**
+ * Where `@nxgt/openapi-hono` found a request value wrong: a request location,
+ * or `response` for a reply the spec does not declare.
+ */
+@friendlyName("ValidationTarget")
+union ValidationTarget {
+  "param",
+  "query",
+  "header",
+  "json",
+  "form",
+  "body",
+  "response",
+}
+
+/** One value `@nxgt/openapi-hono` refused, and why. */
+@friendlyName("ValidationIssue")
+model ValidationIssue {
+  target: ValidationTarget;
+
+  /** Inside the target: `["items", 0, "name"]`, or `[]` for the whole of it. */
+  path: (string | integer)[];
+
+  /**
+   * Zod's issue code, or one of the engine's own: `invalid_json`,
+   * `invalid_form`, `invalid_content_type`, `missing_body`,
+   * `repeated_parameter`, `undeclared_status`.
+   */
+  code: string;
+
+  message: string;
+}
+
+/** The body of an error reply, as `@nxgt/openapi-hono` sends it. */
+model ErrorBody<Status extends integer> {
+  /** The reply's status, repeated in the body. */
+  status: Status;
+
+  /** An i18n key, such as `errors.not-found`, not a sentence. */
+  message: string;
+
+  /** When the error was answered. */
+  timestamp: utcDateTime;
+}
+
+/**
+ * The 400. `@nxgt/openapi-hono` sends it with the `issues` when its
+ * validators refuse a request; a handler sends it without them.
+ */
+@friendlyName("BadRequestBody")
+model BadRequestBody {
+  ...ErrorBody<400>;
+
+  /** Every value the validators refused, from every target at once. */
+  issues?: ValidationIssue[];
+}
+
+@friendlyName("UnauthorizedBody")
+model UnauthorizedBody is ErrorBody<401>;
+@friendlyName("ForbiddenBody")
+model ForbiddenBody is ErrorBody<403>;
+@friendlyName("NotFoundBody")
+model NotFoundBody is ErrorBody<404>;
+@friendlyName("ConflictBody")
+model ConflictBody is ErrorBody<409>;
+@friendlyName("UnprocessableEntityBody")
+model UnprocessableEntityBody is ErrorBody<422>;
+@friendlyName("TooManyRequestsBody")
+model TooManyRequestsBody is ErrorBody<429>;
+@friendlyName("InternalServerErrorBody")
+model InternalServerErrorBody is ErrorBody<500>;
+
+/** The request is refused, by the validators or by a handler. */
+@error
+model BadRequest {
+  @statusCode _: 400;
+  @body body: BadRequestBody;
+}
+
+/** No credentials, or credentials that are not valid. */
+@error
+model Unauthorized {
+  @statusCode _: 401;
+  @body body: UnauthorizedBody;
+}
+
+/** Authenticated, but not allowed. */
+@error
+model Forbidden {
+  @statusCode _: 403;
+  @body body: ForbiddenBody;
+}
+
+/** Nothing is there. */
+@error
+model NotFound {
+  @statusCode _: 404;
+  @body body: NotFoundBody;
+}
+
+/** The request conflicts with the resource's state, such as a version that moved on. */
+@error
+model Conflict {
+  @statusCode _: 409;
+  @body body: ConflictBody;
+}
+
+/** Well-formed, but not something the server can act on. */
+@error
+model UnprocessableEntity {
+  @statusCode _: 422;
+  @body body: UnprocessableEntityBody;
+}
+
+/** Too many requests. Retry after `Retry-After`. */
+@error
+model TooManyRequests {
+  @statusCode _: 429;
+  ...RateLimitHeaders;
+  ...RetryAfterHeader;
+  @body body: TooManyRequestsBody;
+}
+
+/**
+ * The server failed. With `validateResponses`, `@nxgt/openapi-hono` answers
+ * it too when a reply breaks the spec, with `errors.response-validation-failed`.
+ */
+@error
+model InternalServerError {
+  @statusCode _: 500;
+  @body body: InternalServerErrorBody;
+}
+
+/** Any other status, with the same body. */
+@error
+model ErrorResponse<Status extends integer> {
+  @statusCode _: Status;
+  @body body: ErrorBody<Status>;
+}