@nxgt/typespec 0.2.0 → 0.4.0

package/docs/guide/operation-ids.md

@@ -1,113 +1,202 @@
 # 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`).
+`@operationIds` makes each operation's OpenAPI id its name, exactly as
+written, so the generated client's methods are the names in your spec.
 
-## What TypeSpec does alone
+An 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`).
 
-Without an `@operationId`, `@typespec/openapi3` names an operation after its
-interface and its method, joined by `_`:
+## On the service namespace
+
+Mark the namespace once, and every operation in it is named as written:
 
 ```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+@service(#{ title: "Blog" })
+@operationIds
+namespace Blog;
+
+model Post {
+  @visibility(Lifecycle.Read) id: uuid;
+  title: string;
+}
+
+model Comment {
+  @visibility(Lifecycle.Read) id: uuid;
+  body: string;
+}
+
 @route("/posts")
 interface Posts {
-  @get list(@query status?: PostStatus): Post[]; // Posts_list
-  @post create(@body post: Create<Post>): Post;  // Posts_create
+  @get listPosts(...PageParameters): Page<Post>;                       // listPosts
+  @get getPost(@path postId: uuid): Post | NotFound;                   // getPost
+  @delete deletePost(@path postId: uuid): NoContentResponse | NotFound; // deletePost
+}
+
+@route("/posts/{postId}/comments")
+interface Comments {
+  @get findPostComments(@path postId: uuid, ...CursorPageParameters): CursorPage<Comment>; // findPostComments
 }
 ```
 
-The client then calls `Posts_list`, and its types are `PostsListQuery`.
-Writing an `@operationId` on each operation fixes that, one line per
-operation.
+Alone, `@typespec/openapi3` would write `Posts_listPosts` and
+`Comments_findPostComments`. The generated `operations` has one entry per
+id:
+
+```ts
+import { operations } from './generated/operations';
+
+Object.keys(operations);
+// ['listPosts', 'getPost', 'deletePost', 'findPostComments']
+```
 
-## `@operationIds`
+Name each operation as the client should call it: `listPosts`, not `list`.
+An operation named `list` gets the id `list`, and a second `list` in another
+interface is an error ([below](#two-operations-named-alike)).
 
-Put it on the interface, once:
+## Where it goes
 
 ```tsp
-import "@typespec/http";
-import "@typespec/openapi";
-import "@nxgt/typespec";
+extern dec operationIds(target: Interface | Namespace);
+```
 
-using Http;
-using OpenAPI;
-using Nxgt;
+| Marked | Named as written |
+| --- | --- |
+| a namespace | every operation in it, however deep: in its interfaces, in the namespaces it contains, and declared in it with `op` |
+| an interface | its operations, and those of each interface that `extends` it |
+| neither | nothing: the emitter's `operation-id-strategy` names the operation |
+
+On one interface, the others keep the emitter's names:
 
+```tsp
+@service
 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
+  @get listPosts(): Post[]; // listPosts
+}
+
+@route("/drafts")
+interface Drafts {
+  @get listDrafts(): Post[]; // Drafts_listDrafts
 }
 ```
 
-- 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.
+A namespace beside the marked one is not marked: `@operationIds` on `Blog`
+does not reach a `namespace Legacy` declared next to it.
 
-The generated `operations` then has one entry per id:
+## An operation's own `@operationId`
 
-```ts
-import { operations } from './generated/operations';
+An operation with its own `@operationId` keeps it, whether it is written
+before or after `@operationIds`:
 
-Object.keys(operations);
-// ['listPosts', 'createPosts', 'getPost', 'updatePosts', 'deletePosts']
+```tsp
+import "@typespec/openapi";
+
+using OpenAPI;
+
+@route("/posts")
+interface Posts {
+  @get @operationId("fetchPost") getPost(@path postId: uuid): Post | NotFound; // fetchPost
+}
 ```
 
+`import "@typespec/openapi"` and `using OpenAPI` are only needed for
+`@operationId` ([troubleshooting](../troubleshooting.md#unknown-decorator-operationid)).
+
 ## On a template
 
-On an interface template, `@operationIds` names the operations of each
-interface that extends an instance, after that interface:
+An interface template is never emitted, only the interfaces that extend one
+of its instances. When the template is marked, or the interface that extends
+it is in a marked namespace, those are named as written:
 
 ```tsp
 @operationIds
-interface Resource<Item> {
-  @get list(): Item[];
+interface Listable<Item> {
+  @get listAll(): Item[];
 }
 
 @route("/pets")
-interface Pets extends Resource<Pet> {}     // listPets
+interface Pets extends Listable<Pet> {} // listAll
+```
+
+A second interface extending `Listable` would name its operation `listAll`
+too, which is an error: see below.
 
-@route("/orders")
-interface Orders extends Resource<Order> {} // listOrders
+An operation template is never emitted either, only the operations declared
+from it. In a marked namespace, each is named as written:
+
+```tsp
+op Read<Item>(): Item;
+
+@route("/pets/first") @get op readFirstPet is Read<Pet>; // readFirstPet
+@route("/toys/first") @get op readFirstToy is Read<Toy>; // readFirstToy
 ```
 
 ## Two operations named alike
 
-An id must be unique, and four cases break that:
+An id must be unique in its service's document. Two `@service` namespaces
+are two documents, and may each have a `health`. `@operationIds` refuses two
+operations of one id, one of them named by it, with `duplicate-operation-id`,
+where `@typespec/openapi3` would emit both without a word:
 
-- 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`.
+```text
+error @nxgt/typespec/duplicate-operation-id: Two operations are named listPets: an OpenAPI operation id must be unique.
+```
+
+It happens when:
+
+- one name is in two interfaces: neither the namespace nor the interface is
+  part of the id, so `Store.Pets` and `Shelter.Pets` both give `listPets`;
+- an interface `extends` another: it copies its operations and their
+  names, so `Drafts extends Posts` gives a second `getPost`, and two
+  interfaces extending one template share every operation;
+- an `@operationId` written on another operation is a name
+  `@operationIds` gives;
+- an unmarked operation declared in the service namespace, which the
+  emitter names after itself, has a marked operation's name: `op listPets()`
+  beside `Pets.listPets`.
+
+Declare distinct operations rather than extending:
+
+```tsp
+@route("/posts")
+interface Posts {
+  @get getPost(@path postId: uuid): Post | NotFound;
+}
+
+@route("/drafts")
+interface Drafts {
+  @get getDraft(@path draftId: uuid): Post | NotFound;
+}
+```
+
+Or keep `extends`, and declare each copied operation again with its own
+`@operationId`:
+
+```tsp
+@route("/drafts")
+interface Drafts extends Posts {
+  @get @operationId("getDraft") getPost(@path postId: uuid): Post | NotFound;
+}
+```
 
-`@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)).
+More in [troubleshooting](../troubleshooting.md#two-operations-are-named-listpets-an-openapi-operation-id-must-be-unique).
 
 ## 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`.
+`parent-container` (`Posts_listPosts`, 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.
+The operations `@operationIds` does not name keep that strategy. They are
+checked against the ones it names by the id the default strategy gives
+them.

package/docs/guide/pagination.md

@@ -22,7 +22,7 @@ namespace Blog;
 
 @route("/posts")
 interface Posts {
-  @get list(@query status?: PostStatus, ...PageParameters): Page<Post>;
+  @get listPosts(@query status?: PostStatus, ...PageParameters): Page<Post>;
 }
 ```
 
@@ -46,7 +46,7 @@ the last one has no items and the same `total`.
 ```tsp
 @route("/posts/{postId}/comments")
 interface Comments {
-  @get list(
+  @get findPostComments(
     @path postId: string,
     ...CursorPageParameters,
   ): CursorPage<Comment> | BadRequest | NotFound;
@@ -134,5 +134,5 @@ page follows:
 ```tsp
 union Pet { cat: Cat, dog: Dog }
 
-@get list(...PageParameters): Page<Pet>; // PetPage
+@get listPets(...PageParameters): Page<Pet>; // PetPage
 ```

package/docs/guide/sorting.md

@@ -0,0 +1,131 @@
+# Sorting
+
+`SortParameters<Field>` gives a list the query `orderBy` and `direction`,
+checked against the fields you name, as `@nxgt/drizzle` sorts a page.
+
+## A filtered, sorted list
+
+Write the filters as a model of `@query` properties, and spread it into the
+list with `PageParameters` and `SortParameters`:
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+@service(#{ title: "Blog" })
+@operationIds
+namespace Blog;
+
+model Author {
+  @visibility(Lifecycle.Read) id: uuid;
+  name: string;
+  email: email;
+  ...Timestamps;
+}
+
+/** What the author list filters on. */
+model AuthorFilters {
+  /** Authors of this name. */
+  @query name?: string;
+}
+
+@route("/authors")
+interface Authors {
+  @get listAuthors(
+    ...AuthorFilters,
+    ...PageParameters,
+    ...SortParameters<"name" | "createdAt">,
+  ): Page<Author>;
+
+  @get getAuthor(@path id: uuid): Author | NotFound;
+}
+```
+
+`GET /authors?name=Ada&orderBy=name&direction=desc` is one page of the
+authors named Ada, by name, descending. The list is an operation like any
+other, and `@operationIds` gives it the id `listAuthors`
+([Operation ids](operation-ids.md)).
+
+## The query
+
+```tsp
+model SortParameters<Field extends string> {
+  @query orderBy?: Field;
+  @query direction?: "asc" | "desc" = "asc";
+}
+```
+
+| Query | Type | Default | Checked |
+| --- | --- | --- | --- |
+| `orderBy` | `Field` | none: the server's order, the primary key with `@nxgt/drizzle` | one of the `Field`s |
+| `direction` | `"asc" \| "desc"` | `asc` | `asc` or `desc` |
+
+`?orderBy=email` on `Authors` is a 400: `email` is not one of the fields.
+`?direction=up` is a 400 too. The validators fill in the default, so a
+handler always reads a `direction`.
+
+`Field` is a union of strings: the fields a client may sort by, not every
+property of the model.
+
+## Filters
+
+Each property of the filters model is a query parameter, typed and checked
+like any other. A filter that is not a string says so:
+
+```tsp
+enum PostStatus {
+  draft,
+  published,
+}
+
+model PostFilters {
+  @query status?: PostStatus;
+  @query authorId?: uuid;
+}
+
+@route("/posts")
+interface Posts {
+  @get listPosts(
+    ...PostFilters,
+    ...PageParameters,
+    ...SortParameters<"createdAt" | "title">,
+  ): Page<Post>;
+}
+```
+
+## Serving it with `@nxgt/drizzle`
+
+The handler reads the query the generator checked, and passes it to the
+repository:
+
+```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);
+});
+```
+
+- `authors` is the `@nxgt/drizzle` repository of the table.
+- `where` is an exact equality per field: a filter that is absent is left
+  out, not passed as `undefined`.
+- The sort is spread only when `orderBy` is there, which keeps the call
+  valid under `exactOptionalPropertyTypes`.
+- `paginate` returns the `Page<Author>` the spec declares, as it is.
+
+`paginateByCursor` takes the sort apart instead, `{ orderBy, direction }`, as
+the query has them; spread `CursorPageParameters` in place of
+`PageParameters` for it ([Pagination](pagination.md)).

package/docs/roadmap.md

@@ -6,11 +6,12 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
 
 ## Now
 
-- **One reply per status.** An operation that declares a reply without a
-  body beside one with a body, such as `AuthenticationRequired` and
-  `Unauthorized`, is an error, `duplicate-status-reply`, and two replies with
-  a body of one status code a warning, `merged-status-reply`, instead of
-  replies the emitter merges without a word.
+- **Operation ids as written.** `@operationIds` names each operation
+  exactly as the spec writes it, `findPostComments`, on an interface or on
+  the whole service namespace, instead of `<operation><Interface>`.
+- **No `Resource` template.** A resource's operations are written by hand,
+  each with the name it has in the client; `SortParameters` stays, for the
+  sort of a list.
 
 ## Later
 
@@ -20,6 +21,20 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
 
 ## Shipped
 
+### 0.3.0
+
+- **Resource ids in the singular.** `Resource` named `read`, `create`,
+  `update` and `delete` after its item, `readPost`, and `list` after the
+  interface, `listPosts`.
+
+### 0.2.0
+
+- **One reply per status.** An operation that declares a reply without a
+  body beside one with a body, such as `AuthenticationRequired` and
+  `Unauthorized`, is an error, `duplicate-status-reply`, and two replies with
+  a body of one status code a warning, `merged-status-reply`, instead of
+  replies the emitter merges without a word.
+
 ### 0.1.0
 
 - **Error replies.** The envelope `@nxgt/openapi-hono` sends, and the

package/docs/troubleshooting.md

@@ -13,7 +13,7 @@ one name with `name_collision`.
 optional, and the generator adds its own 400 beside it.
 
 ```tsp
-@patch update(@path postId: string, @body post: MergePatchUpdate<Post>): Post | BadRequest;
+@patch updatePost(@path postId: string, @body post: MergePatchUpdate<Post>): Post | BadRequest;
 ```
 
 ## `Couldn't resolve import "@nxgt/typespec"`
@@ -46,32 +46,52 @@ 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;
+@get getPost(@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`.
+**When:** `tsp compile` runs on a spec where an operation that
+`@operationIds` names has the id of another operation of the same service
+(two `@service` namespaces are two documents, and may reuse a name):
+
+- one name is in two interfaces: `Store.Pets` and `Shelter.Pets` both
+  declare `listPets`;
+- an interface `extends` another, and so copies its operations and their
+  names: `Drafts extends Posts` gives a second `getPost`, and two interfaces
+  extending one template share every operation;
+- an `@operationId` written on another operation is a name `@operationIds`
+  gives;
+- an unmarked operation declared in the service namespace, which the
+  emitter names after itself, has a marked operation's name: `op listPets()`
+  beside `Pets.listPets`.
 
 ```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.
+**Why:** `@operationIds` makes each operation's id its name, as written,
+without its interface or its namespace. `@typespec/openapi3` would emit both
+ids without a word, and the generator would then refuse the spec.
+
+**Fix:** give each operation a name of its own. Declare distinct operations
+rather than extending:
+
+```tsp
+@route("/posts")
+interface Posts {
+  @get getPost(@path postId: uuid): Post | NotFound;
+}
+
+@route("/drafts")
+interface Drafts {
+  @get getDraft(@path draftId: uuid): Post | NotFound;
+}
+```
 
-**Fix:** give one of them its own `@operationId`. An inherited operation takes
-one by being declared again in the interface that extends:
+Or give one of them its own `@operationId`; an inherited operation takes one
+by being declared again in the interface that extends
+([Operation ids](guide/operation-ids.md#two-operations-named-alike)):
 
 ```tsp
 import "@typespec/openapi";
@@ -80,7 +100,7 @@ using OpenAPI;
 
 @route("/drafts")
 interface Drafts extends Posts {
-  @get @operationId("getDraft") read(@path postId: string): Post | NotFound;
+  @get @operationId("getDraft") getPost(@path postId: uuid): Post | NotFound;
 }
 ```
 
@@ -90,11 +110,11 @@ interface Drafts extends Posts {
 one with a body, such as the guard's 401 and the handler's:
 
 ```tsp
-@get list(): Post[] | AuthenticationRequired | Unauthorized;
+@get listPosts(): Post[] | AuthenticationRequired | Unauthorized;
 ```
 
 ```text
-error @nxgt/typespec/duplicate-status-reply: list declares a reply without a body and one with a body of status 401: the emitter merges them into one, and the reply without a body is lost. Declare the one the route sends.
+error @nxgt/typespec/duplicate-status-reply: listPosts declares a reply without a body and one with a body of status 401: the emitter merges them into one, and the reply without a body is lost. Declare the one the route sends.
 ```
 
 **Why:** OpenAPI has one reply per status. `@typespec/openapi3` merges the two
@@ -106,7 +126,7 @@ guard's reply has no body.
 answers with the envelope, `Unauthorized`:
 
 ```tsp
-@get list(): Post[] | AuthenticationRequired;
+@get listPosts(): Post[] | AuthenticationRequired;
 ```
 
 ## `declares two replies with a body of status …`
@@ -116,11 +136,11 @@ status code, such as the idempotent write's 409 beside the optimistic
 lock's, or its 422, `IdempotencyKeyReused`, beside `UnprocessableEntity`:
 
 ```tsp
-@post create(@body post: Post): Post | IdempotencyInProgress | Conflict;
+@post createPost(@body post: Post): Post | IdempotencyInProgress | Conflict;
 ```
 
 ```text
-warning @nxgt/typespec/merged-status-reply: create declares two replies with a body of status 409: the emitter merges their bodies under the first one's description. Declare the one the route sends.
+warning @nxgt/typespec/merged-status-reply: createPost declares two replies with a body of status 409: the emitter merges their bodies under the first one's description. Declare the one the route sends.
 ```
 
 **Why:** `@typespec/openapi3` keeps both bodies, as one reply whose body is
@@ -131,7 +151,7 @@ header either reply declares required becomes optional.
 `message` key tells them apart:
 
 ```tsp
-@post create(@body post: Post): Post | IdempotencyInProgress;
+@post createPost(@body post: Post): Post | IdempotencyInProgress;
 ```
 
 Two plain bodies, `Post | Draft`, are one reply whose body is either; two

package/lib/main.tsp

@@ -8,4 +8,4 @@ import "./auth.tsp";
 import "./scalars.tsp";
 import "./columns.tsp";
 import "./headers.tsp";
-import "./resources.tsp";
+import "./sorting.tsp";

package/lib/operation-ids.tsp

@@ -5,18 +5,23 @@ using TypeSpec.Reflection;
 namespace Nxgt;
 
 /**
- * Names each operation of the interface after its method and the interface,
- * `<operation><Interface>`: `list` in `interface Pets` becomes `listPets`. An
- * operation with its own `@operationId` keeps it. An interface extending a
- * marked one, or an instance of a marked template, is named after itself. An
- * id another operation has is an error, `duplicate-operation-id`.
+ * The id of each operation is its name, as written: `findPostComments` is
+ * `findPostComments`, where `@typespec/openapi3` would write
+ * `Posts_findPostComments`. On an interface, its operations; on a namespace,
+ * every operation in it, however deep. An operation with its own
+ * `@operationId` keeps it. An id another operation of the same service has is an
+ * error, `duplicate-operation-id`.
  *
  * @example
  * ```typespec
+ * @service
  * @operationIds
- * interface Pets {
- *   @get list(): Pet[];
+ * namespace Blog;
+ *
+ * @route("/posts")
+ * interface Posts {
+ *   @get listPosts(): Post[];
  * }
  * ```
  */
-extern dec operationIds(target: Interface);
+extern dec operationIds(target: Interface | Namespace);

package/lib/sorting.tsp

@@ -0,0 +1,20 @@
+import "@typespec/http";
+
+using Http;
+
+namespace Nxgt;
+
+/**
+ * The sort of a list, as `@nxgt/drizzle` takes it: one field, and a
+ * direction. `Field` is the union of the fields a client may sort by.
+ * Spread it into an operation's parameters.
+ */
+model SortParameters<Field extends string> {
+  /** The field to sort by. */
+  @query
+  orderBy?: Field;
+
+  /** `asc` or `desc`. */
+  @query
+  direction?: "asc" | "desc" = "asc";
+}