@nxgt/typespec 0.7.0 → 0.9.0

package/docs/guide/getting-started.md

@@ -0,0 +1,277 @@
+# Getting started
+
+This page starts a new API project from the package's `tsp init` template,
+then takes it from the spec to a running Hono route.
+
+## Start a project
+
+You need Node.js for `tsp`, and [Bun](https://bun.sh) on the PATH for the
+generator, `nxgt-openapi`, which runs on Bun
+([Compile and generate](#compile-and-generate)).
+
+Run `tsp init` with the template, in an empty directory:
+
+```sh
+mkdir petstore && cd petstore
+npx --package=@typespec/compiler tsp init https://unpkg.com/@nxgt/typespec/templates/scaffolding.json
+```
+
+`tsp init` asks for the template, the project's name and the emitters. To
+answer them on the command line instead:
+
+```sh
+npx --package=@typespec/compiler tsp init https://unpkg.com/@nxgt/typespec/templates/scaffolding.json \
+  --template nxgt -y --project-name petstore
+```
+
+`--package=@typespec/compiler` matters: in a directory without the compiler,
+a bare `npx tsp` runs `tsp`, an unrelated npm package. `bunx
+--package=@typespec/compiler tsp init …` works too.
+
+`tsp init` writes into the current directory, then runs `npm install`, so it
+needs the network. The template ships from 0.9.0 on; an older version, or no
+network, fails before anything is written
+([troubleshooting](../troubleshooting.md#init-template-invalid-json-unable-to-parse-scaffoldingjson-unexpected-token--is-not-valid-json)).
+
+## What it writes
+
+| File | What it holds |
+| --- | --- |
+| `package.json` | the compiler, `@typespec/http`, `@typespec/openapi`, `@typespec/openapi3`, `@nxgt/typespec` and `@nxgt/openapi-codegen`, at their latest versions |
+| `tspconfig.yaml` | the linter's recommended rules, and OpenAPI 3.1 written to `openapi/openapi.yaml` |
+| `main.tsp` | the service, marked with `@operationIds`, and a `Users` resource |
+| `openapi-codegen.config.ts` | the generator's input and output, with the Hono routes on |
+| `README.md` | the commands below, and the scripts to add |
+| `.gitignore` | `node_modules/`, and TypeSpec's default output |
+
+`tspconfig.yaml` turns the linter on and emits OpenAPI 3.1, which
+`@nxgt/openapi-codegen` reads (it refuses 3.0, the emitter's default):
+
+```yaml
+# tspconfig.yaml
+linter:
+  extends:
+    - "@nxgt/typespec/recommended"
+emit:
+  - "@typespec/openapi3"
+options:
+  "@typespec/openapi3":
+    emitter-output-dir: "{project-root}/openapi"
+    openapi-versions:
+      - 3.1.0
+    output-file: openapi.yaml
+```
+
+`main.tsp` declares the service in the namespace `Api`, titled after the
+project, and one resource with each convention in place: a paged, filtered and sorted
+list, and the error aliases of each verb.
+
+```tsp
+// main.tsp (excerpt)
+@service(#{ title: "petstore" })
+@operationIds
+namespace Api;
+
+model User {
+  @visibility(Lifecycle.Read)
+  id: uuid;
+
+  @minLength(1)
+  @maxLength(80)
+  name: string;
+
+  email: email;
+
+  ...Timestamps;
+}
+
+@route("/users")
+@tag("Users")
+interface Users {
+  @get
+  list(
+    ...UserFilters,
+    ...PageParameters,
+    ...SortParameters<"name" | "createdAt">,
+  ): Page<User> | ListErrors;
+
+  @get
+  get(@path id: uuid): User | GetErrors;
+
+  @post
+  create(@body user: Create<User>): {
+    @statusCode _: 201;
+    @body user: User;
+  } | CreateErrors;
+
+  @patch
+  update(@path id: uuid, @body user: MergePatchUpdate<User>): User | UpdateErrors;
+
+  @delete
+  delete(@path id: uuid): NoContentResponse | DeleteErrors;
+}
+```
+
+`@operationIds` names the operations `listUsers`, `getUser`, `createUser`,
+`updateUser` and `deleteUser` ([Operation ids](operation-ids.md)).
+
+```ts
+// openapi-codegen.config.ts
+import { defineConfig } from '@nxgt/openapi-codegen';
+
+export default defineConfig({
+	input: 'openapi/openapi.yaml',
+	output: 'src/generated',
+	hono: true,
+});
+```
+
+## Compile and generate
+
+Compile the spec to `openapi/openapi.yaml`, then generate the code from it.
+`nxgt-openapi` runs on Bun: it needs `bun` on the PATH, even through `npx` or
+an npm script, and fails with `env: 'bun': No such file or directory`
+without it ([troubleshooting](../troubleshooting.md#env-bun-no-such-file-or-directory)).
+`bunx nxgt-openapi generate` does the same as the `npx` line.
+
+```sh
+npx tsp compile .
+npx nxgt-openapi generate
+```
+
+```text
+openapi/openapi.yaml → src/generated: 5 written, 0 unchanged
+```
+
+`src/generated` then holds `types.ts`, `zod.ts`, `operations.ts`, `paths.ts`
+and `hono.ts`. The linter runs in `tsp compile`; the template's spec passes
+it.
+
+## Add the scripts
+
+`tsp init` writes its own `package.json`, so the template cannot add
+scripts. Add these two, so the code never lags the spec:
+
+```json
+{
+  "scripts": {
+    "api": "tsp compile . && nxgt-openapi generate",
+    "api:check": "tsp compile . && nxgt-openapi generate --check"
+  }
+}
+```
+
+`api:check` exits with 1 and lists the files when the generated code is out
+of date: run it in CI.
+
+## Serve it
+
+The generated `hono.ts` binds the routes to the spec through
+[`@nxgt/openapi-hono`](https://www.npmjs.com/package/@nxgt/openapi-hono).
+Install it, Hono, and zod, which the generated validators import, with the
+package manager `tsp init` used:
+
+```sh
+npm install @nxgt/openapi-hono hono zod
+```
+
+Then register a handler per operation. Each one reads its validated input,
+and may only answer the replies the spec declares:
+
+```ts
+// src/app.ts
+import { Hono } from 'hono';
+import { createRoutes } from './generated/hono';
+import type { NotFoundBody } from './generated/types';
+
+const app = new Hono();
+const routes = createRoutes(app);
+
+routes.operation('getUser', async (c) => {
+	const { id } = c.req.valid('param');
+	const user = await users.find(id);
+	if (!user) {
+		const body: NotFoundBody = {
+			status: 404,
+			message: 'errors.not-found',
+			timestamp: new Date().toISOString(),
+		};
+		return c.json(body, 404);
+	}
+	return c.json(user, 200);
+});
+
+routes.operation('listUsers', async (c) => {
+	const { name, page = 1, pageSize = 20, orderBy, direction } = c.req.valid('query');
+	return c.json(await users.page({ name, page, pageSize, orderBy, direction }), 200);
+});
+
+export default app;
+```
+
+`users` stands for your data layer. Annotate an error body with its generated
+type, as `NotFoundBody` above: an object literal passed straight to
+`c.json(…, 404)` is inferred beside the handler's other returns, its fields
+turn optional, and the handler fails with `TS2769: No overload matches this
+call`. A `418`,
+or a 404 without `timestamp`, does not compile either. More on the routes in the
+[`@nxgt/openapi-hono` README](https://www.npmjs.com/package/@nxgt/openapi-hono),
+and on serving a page in [Pagination](pagination.md#serving-it).
+
+## Rename the resource
+
+`Users` is an example. To make it your own resource, rename the model, its
+filters, the interface, the route and the tag in `main.tsp`, and the body
+parameters with them:
+
+```tsp
+model Pet {
+  @visibility(Lifecycle.Read)
+  id: uuid;
+
+  @minLength(1)
+  name: string;
+
+  ...Timestamps;
+}
+
+model PetFilters {
+  @query
+  name?: string;
+}
+
+@route("/pets")
+@tag("Pets")
+interface Pets {
+  @get
+  list(...PetFilters, ...PageParameters, ...SortParameters<"name" | "createdAt">): Page<Pet> | ListErrors;
+
+  @get
+  get(@path id: uuid): Pet | GetErrors;
+
+  @post
+  create(@body pet: Create<Pet>): {
+    @statusCode _: 201;
+    @body pet: Pet;
+  } | CreateErrors;
+
+  @patch
+  update(@path id: uuid, @body pet: MergePatchUpdate<Pet>): Pet | UpdateErrors;
+
+  @delete
+  delete(@path id: uuid): NoContentResponse | DeleteErrors;
+}
+```
+
+The operation names stay; `@operationIds` takes the resource from the
+interface, so the ids become `listPets`, `getPet`, `createPet`, `updatePet`
+and `deletePet`. Run `tsp compile .` and `nxgt-openapi generate` again, and
+the generated types, `Pet` and `PetPage`, follow. A name the singular rule
+does not know takes `@operationIds(#{ singular: "…" })` on the interface
+([Operation ids](operation-ids.md)).
+
+A second resource is a second model and interface, in the same namespace or
+in files of their own ([README](../README.md#a-spec-split-across-files)).
+
+Next: what each error alias holds, in [Error replies](errors.md), and the
+rules the linter checks, in [Linter](linter.md).

package/docs/guide/linter.md

@@ -0,0 +1,257 @@
+# Linter
+
+The linter warns when a spec strays from the conventions the library gives
+it: a list that returns an array, a service without `@operationIds`, an error
+reply without the envelope.
+
+## Turn it on
+
+Extend the ruleset in `tspconfig.yaml`, beside the emitter:
+
+```yaml
+# api/tspconfig.yaml
+emit:
+  - '@typespec/openapi3'
+linter:
+  extends:
+    - '@nxgt/typespec/recommended'
+options:
+  '@typespec/openapi3':
+    openapi-versions: ['3.1.0']
+```
+
+Nothing runs without it: importing `@nxgt/typespec` does not lint the spec.
+Each rule is a warning, so `tsp compile` still emits:
+
+```text
+warning @nxgt/typespec/list-returns-page: listAll returns an array: return Page<Item> or CursorPage<Item>, which can carry a total or a next cursor.
+```
+
+`tsp compile api --warn-as-error` fails on any of them, for CI.
+
+| Rule | Warns when |
+| --- | --- |
+| [`list-returns-page`](#list-returns-page) | a `list`, `search` or `query` returns an array |
+| [`service-operation-ids`](#service-operation-ids) | a `@service` namespace has no `@operationIds` |
+| [`error-body-shape`](#error-body-shape) | an error reply's body is not `status`, `message` and `timestamp` |
+
+The library's own checks, such as `verb-method-mismatch` and
+`duplicate-operation-id`, run whether or not the linter is on
+([Operation ids](operation-ids.md)).
+
+## `list-returns-page`
+
+**Checks:** an operation whose name is `list`, `search` or `query`, alone or
+followed by a capital letter (`listUsers`, `searchPosts`), with a success
+reply whose body is an array. `listing` and `queryable` are not lists, and
+are not checked. The name is checked as written, in an interface or not.
+
+Only the operations the emitter writes are checked, by this rule and
+`error-body-shape`: a template's declaration, its instance (`Read<Pet>`) and
+the operations of an interface template are not, while an interface that
+extends a template, `interface Users extends Crud<User> {}`, has its copied
+operations checked.
+
+**Why:** an array cannot grow a `total` or a `nextCursor` later without
+breaking every client. `Page<Item>` and `CursorPage<Item>` can, and they are
+the pages `@nxgt/drizzle` and `@nxgt/mongo` return.
+
+Fails:
+
+```tsp
+@route("/users")
+interface Users {
+  @get list(): User[];
+}
+```
+
+```text
+warning @nxgt/typespec/list-returns-page: list returns an array: return Page<Item> or CursorPage<Item>, which can carry a total or a next cursor.
+```
+
+Passes:
+
+```tsp
+@route("/users")
+interface Users {
+  @get list(...PageParameters): Page<User>;
+  @get @route("/search") search(...CursorPageParameters): CursorPage<User>;
+}
+```
+
+More on both pages in [Pagination](pagination.md).
+
+## `service-operation-ids`
+
+**Checks:** a `@service` namespace that is not marked with `@operationIds`,
+neither itself nor a namespace around it.
+
+**Why:** without it, the emitter names each operation after its interface,
+`Users_list`, and the generated client's methods and types take that name.
+`@operationIds` gives `listUsers` ([Operation ids](operation-ids.md)).
+
+Fails:
+
+```tsp
+@service
+namespace Shop {
+  @route("/health") @get op health(): void;
+}
+```
+
+```text
+warning @nxgt/typespec/service-operation-ids: The service Shop has no @operationIds: its ids are the emitter's, such as Users_list. Mark the namespace with @operationIds.
+```
+
+Passes, marked on the service or on a namespace around it:
+
+```tsp
+@service
+@operationIds
+namespace Shop {
+  @route("/health") @get op health(): void;
+}
+
+@operationIds
+namespace Admin {
+  @service
+  namespace Billing {
+    @route("/invoices") @get op invoices(): void;
+  }
+}
+```
+
+`@operationIds` on an interface alone does not count: the rule asks for the
+namespace.
+
+## `error-body-shape`
+
+**Checks:** each reply of status 400 or above, of a range that starts at 400
+or above (`5XX`), or of no status (`default`, an `@error` model without
+`@statusCode`), that has a body. The body must be a model with a `status`, a
+`message` and a `timestamp` property. A reply without a body passes, such as
+`AuthenticationRequired`, `AccessDenied` or `ErrorWithoutBody<404>`.
+
+**Why:** `@nxgt/openapi-hono` answers its own 400 and 500 with that envelope,
+and a client written against it reads `message` from every error. A body of
+another shape is one more case each client must handle.
+
+Fails:
+
+```tsp
+model Teapot {
+  @statusCode _: 418;
+  @body body: { reason: string };
+}
+
+@route("/users")
+interface Users {
+  @post create(@body user: User): User | Teapot;
+}
+```
+
+```text
+warning @nxgt/typespec/error-body-shape: create answers 418 with a body that is not the nxgt envelope: declare BadRequest, NotFound or another of the library's errors, or a body that spreads or extends ErrorBody<Status>.
+```
+
+A range is named by its bounds, `500-599`, and a reply without a status as
+`*`.
+
+Passes: one of the library's errors, `ErrorResponse<Status>`, or a body that
+spreads or extends `ErrorBody<Status>` and adds its own fields
+(`model TeapotBody extends ErrorBody<418> { reason: string; }` passes too):
+
+```tsp
+model TeapotBody {
+  ...ErrorBody<418>;
+  reason: string;
+}
+
+@error
+model Teapot {
+  @statusCode _: 418;
+  @body body: TeapotBody;
+}
+
+@route("/users")
+interface Users {
+  @get @route("/{id}") get(@path id: uuid): User | NotFound | AuthenticationRequired;
+  @post create(@body user: User): User | BadRequest | Teapot | ErrorResponse<503>;
+}
+```
+
+The rule checks the property names, not their types. Each error is in
+[Error replies](errors.md).
+
+## Turn a rule off
+
+For the whole spec, in `tspconfig.yaml`, with the reason:
+
+```yaml
+linter:
+  extends:
+    - '@nxgt/typespec/recommended'
+  disable:
+    '@nxgt/typespec/error-body-shape': 'the legacy routes answer their own errors'
+```
+
+For one operation or one namespace, a `#suppress` line above it:
+
+```tsp
+@route("/users")
+interface Users {
+  #suppress "@nxgt/typespec/list-returns-page" "a fixed set of ten"
+  @get @route("/top") listTop(): User[];
+}
+
+#suppress "@nxgt/typespec/service-operation-ids" "its clients already call Health_check"
+@service
+namespace Health {
+  @route("/health") @get op check(): void;
+}
+```
+
+Or turn on only the rules you want, without the set:
+
+```yaml
+linter:
+  enable:
+    '@nxgt/typespec/list-returns-page': true
+```
+
+## A whole spec
+
+The rules pass on a spec that uses the library throughout:
+
+```tsp
+// api/main.tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+@service(#{ title: "Shop" })
+@operationIds
+namespace Shop;
+
+model User {
+  @visibility(Lifecycle.Read) id: uuid;
+  name: string;
+}
+
+@route("/users")
+interface Users {
+  @get list(...PageParameters): Page<User> | BadRequest;                            // listUsers
+  @get @route("/search") search(...CursorPageParameters): CursorPage<User>;          // searchUsers
+  @get @route("/{id}") get(@path id: uuid): User | NotFound | AuthenticationRequired; // getUser
+  @post create(@body user: User): User | BadRequest | Conflict;                      // createUser
+}
+```
+
+```sh
+bunx --no-install tsp compile api --warn-as-error
+```
+
+The messages, with their fixes, are also in
+[troubleshooting](../troubleshooting.md).

package/docs/roadmap.md

@@ -6,10 +6,7 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
 
 ## Now
 
-- **Error aliases by verb.** `ListErrors`, `GetErrors`, `CreateErrors`,
-  `UpdateErrors`, `DeleteErrors` and `AuthErrors` name the errors each verb
-  usually answers, so an operation writes `User | GetErrors` instead of the
-  union. Each is exactly its union, and they combine.
+Nothing in progress.
 
 ## Later
 
@@ -23,6 +20,29 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
 
 ## Shipped
 
+### 0.9.0
+
+- **A `tsp init` template.** `tsp init` with the package's template
+  starts a project with the conventions in place: `@operationIds`, a paged
+  resource with its error aliases, the linter on, and the OpenAPI that
+  `@nxgt/openapi-codegen` generates from.
+
+### 0.8.0
+
+- **A linter.** The ruleset `@nxgt/typespec/recommended`, which a spec
+  extends in `tspconfig.yaml`, warns of a list that returns an array
+  (`list-returns-page`), a service without `@operationIds`
+  (`service-operation-ids`), and an error reply without the envelope
+  (`error-body-shape`). Each rule can be turned off, for the spec or for one
+  operation.
+
+### 0.7.0
+
+- **Error aliases by verb.** `ListErrors`, `GetErrors`, `CreateErrors`,
+  `UpdateErrors`, `DeleteErrors` and `AuthErrors` name the errors each verb
+  usually answers, so an operation writes `User | GetErrors` instead of the
+  union. Each is exactly its union, and they combine.
+
 ### 0.6.0
 
 - **Verbs name their methods.** An operation named after one of the