@nxgt/typespec 0.10.0 → 0.11.0

package/README.md

@@ -125,7 +125,7 @@ namespace Blog;
 @route("/posts")
 interface Posts {
   @get getPost(@path postId: string): Post | NotFound | Unauthorized;
-  @post createPost(@body post: Create<Post>): {
+  @post createPost(@body post: CreateRequest<Post>): {
     @statusCode _: 201;
     @body post: Post;
   } | BadRequest | Conflict | ErrorResponse<503>;
@@ -175,8 +175,9 @@ an alias leaves out:
 interface Users {
   @get list(...PageParameters): Page<User> | ListErrors;
   @get get(@path id: uuid): User | GetErrors;
-  @post create(@body user: User): User | CreateErrors | AuthErrors | TooManyRequests;
-  @patch update(@path id: uuid, @body user: User): User | UpdateErrors;
+  @post create(@body user: CreateRequest<User>): User | CreateErrors | AuthErrors | TooManyRequests;
+  @put update(@path id: uuid, @body user: UpdateRequest<User>): User | UpdateErrors;
+  @patch patch(@path id: uuid, @body user: PatchRequest<User>): User | UpdateErrors;
   @delete delete(@path id: uuid): NoContentResponse | DeleteErrors;
 }
 ```
@@ -184,6 +185,26 @@ interface Users {
 An alias is exactly its union, so the OpenAPI it emits is the same as
 writing the responses out.
 
+### Request bodies
+
+`CreateRequest<T>`, `UpdateRequest<T>` and `PatchRequest<T>` are TypeSpec's own
+`Create`, `Update` and `MergePatchUpdate`, named so the generated types and
+schemas read `CreatePostRequest`, `UpdatePostRequest` and `PatchPostRequest`:
+
+```tsp
+@post createPost(@body post: CreateRequest<Post>): {
+  @statusCode _: 201;
+  @body post: Post;
+} | BadRequest;
+@put updatePost(@path postId: uuid, @body post: UpdateRequest<Post>): Post | BadRequest | NotFound;
+@patch patchPost(@path postId: uuid, @body post: PatchRequest<Post>): Post | BadRequest | NotFound;
+```
+
+A `PUT` body keeps each property as optional as the model declares it; a
+`PATCH` body is a JSON Merge Patch, `application/merge-patch+json`, with
+every property optional. `Create<Post, "New{name}">` names a body your own
+way. See [Request bodies](docs/guide/requests.md).
+
 ### Pagination
 
 Spread the query of a page into the operation's parameters, and answer the
@@ -293,9 +314,9 @@ model Post {
 | --- | --- | --- | --- |
 | `uuid` | the schema `UUID`, `format: uuid`, a pattern for versions 1–8 | `UUID`, `z.guid().regex(…)` | `id()` |
 | `email` | `emailAddress`, the schema `EmailAddress`, `format: email` | `EmailAddress`, `z.string().regex(…)` | |
-| `...Timestamps` | `createdAt`, `updatedAt`, read-only | left out of `Create<T>` and updates | `timestamps()` |
+| `...Timestamps` | `createdAt`, `updatedAt`, read-only | left out of `CreateRequest<T>` and updates | `timestamps()` |
 | `...SoftDelete` | `deletedAt: utcDateTime \| null`, read-only | | `softDelete()` |
-| `...Versioned` | `version: integer`, read and update | kept in `MergePatchUpdate<T>` | `version()` |
+| `...Versioned` | `version: integer`, read and update | kept in `UpdateRequest<T>` and `PatchRequest<T>` | `version()` |
 | `...Actors<Id = uuid>` | `createdBy`, `updatedBy`, `deletedBy`, `Id \| null`, read-only | | `actors()` |
 
 Every scalar of [`@nxgt/graphql-scalars`](https://www.npmjs.com/package/@nxgt/graphql-scalars)
@@ -326,7 +347,7 @@ Spread the headers of an idempotent write and of a rate limit into an
 operation and its replies:
 
 ```tsp
-@post createPost(...IdempotencyKeyHeader, @body post: Create<Post>): {
+@post createPost(...IdempotencyKeyHeader, @body post: CreateRequest<Post>): {
   @statusCode _: 201;
   ...IdempotentReplayedHeader;
   ...RateLimitHeaders;
@@ -507,6 +528,9 @@ In the ruleset `@nxgt/typespec/recommended`; each is a warning, and named
 | `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` |
+| `CreateRequest<T>` | `Create<T, "Create{name}Request">`: the body of a create, `CreatePostRequest` |
+| `UpdateRequest<T>` | `Update<T, "Update{name}Request">`: the body of a `PUT`, `UpdatePostRequest` |
+| `PatchRequest<T>` | `MergePatchUpdate<T, "Patch{name}Request">`: a merge patch, all optional, `PatchPostRequest` |
 | `ValidationIssue` | `{ target: ValidationTarget, path: (string \| integer)[], code: string, message: string }` |
 | `ValidationTarget` | `"param" \| "query" \| "header" \| "json" \| "form" \| "body" \| "response"` |
 
@@ -653,6 +677,8 @@ envelope and the rate limit's headers.
   `Retry-After`;
 - [Sorting](docs/guide/sorting.md): `orderBy` and `direction` beside a
   list's filters, and the `@nxgt/drizzle` call they map to;
+- [Request bodies](docs/guide/requests.md): `CreateRequest`, `UpdateRequest`
+  and `PatchRequest`, and naming your own;
 - [Operation ids](docs/guide/operation-ids.md): `@operationIds`, each
   operation named as written or a verb with its resource, the method each
   verb is sent with, the options, and the ids it refuses;

package/docs/README.md

@@ -5,6 +5,7 @@ The [package README](../README.md) is the short version.
 | Page | Read it when |
 | --- | --- |
 | [Getting started](guide/getting-started.md) | starting a new API project from the `tsp init` template, up to a Hono route |
+| [Request bodies](guide/requests.md) | naming the body of a create, a `PUT` and a `PATCH`: `CreatePostRequest`, `UpdatePostRequest`, `PatchPostRequest` |
 | [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 |

package/docs/guide/auth.md

@@ -91,7 +91,7 @@ operation can declare the guard's 401 and the handler's 403:
 
 ```tsp
 @useAuth(JanusAuth)
-@post createPost(@body post: Create<Post>): {
+@post createPost(@body post: CreateRequest<Post>): {
   @statusCode _: 201;
   @body post: Post;
 } | BadRequest | AuthenticationRequired | Forbidden;

package/docs/guide/columns.md

@@ -80,9 +80,9 @@ model Post {
 | `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.
+The server sets every read-only column, so `CreateRequest<Post>` and
+`PatchRequest<Post>` leave them out, and the generated `CreatePostRequest` and
+`PatchPostRequest` have no `createdAt` a client could send.
 `Actors<string>` or `Actors<integer>` match `actors('text')` or
 `actors('integer')`.
 
@@ -94,7 +94,7 @@ that version, and throws `OptimisticLockError` otherwise. Declare the
 `Conflict` it becomes:
 
 ```tsp
-@patch updatePost(@path postId: uuid, @body post: MergePatchUpdate<Post>):
+@patch patchPost(@path postId: uuid, @body post: PatchRequest<Post>):
   Post | BadRequest | NotFound | Conflict;
 ```
 

package/docs/guide/errors.md

@@ -143,7 +143,7 @@ A handler may send a 400 of its own, without `issues`. `BadRequestBody`
 describes both, with `issues` optional:
 
 ```tsp
-@patch updatePost(@path postId: string, @body post: MergePatchUpdate<Post>): Post | BadRequest;
+@patch patchPost(@path postId: string, @body post: PatchRequest<Post>): Post | BadRequest;
 ```
 
 The generator declares the validators' 400 itself, as `ValidationErrorBody`,

package/docs/guide/getting-started.md

@@ -99,13 +99,16 @@ interface Users {
   get(@path id: uuid): User | GetErrors;
 
   @post
-  create(@body user: Create<User>): {
+  create(@body user: CreateRequest<User>): {
     @statusCode _: 201;
     @body user: User;
   } | CreateErrors;
 
+  @put
+  update(@path id: uuid, @body user: UpdateRequest<User>): User | UpdateErrors;
+
   @patch
-  update(@path id: uuid, @body user: MergePatchUpdate<User>): User | UpdateErrors;
+  patch(@path id: uuid, @body user: PatchRequest<User>): User | UpdateErrors;
 
   @delete
   delete(@path id: uuid): NoContentResponse | DeleteErrors;
@@ -113,7 +116,10 @@ interface Users {
 ```
 
 `@operationIds` names the operations `listUsers`, `getUser`, `createUser`,
-`updateUser` and `deleteUser` ([Operation ids](operation-ids.md)).
+`updateUser`, `patchUser` and `deleteUser` ([Operation ids](operation-ids.md)).
+`update` replaces the whole user with a `PUT` (`UpdateRequest`), `patch`
+changes some of it with a merge patch (`PatchRequest`); see
+[Request bodies](requests.md).
 
 ```ts
 // openapi-codegen.config.ts
@@ -250,13 +256,16 @@ interface Pets {
   get(@path id: uuid): Pet | GetErrors;
 
   @post
-  create(@body pet: Create<Pet>): {
+  create(@body pet: CreateRequest<Pet>): {
     @statusCode _: 201;
     @body pet: Pet;
   } | CreateErrors;
 
+  @put
+  update(@path id: uuid, @body pet: UpdateRequest<Pet>): Pet | UpdateErrors;
+
   @patch
-  update(@path id: uuid, @body pet: MergePatchUpdate<Pet>): Pet | UpdateErrors;
+  patch(@path id: uuid, @body pet: PatchRequest<Pet>): Pet | UpdateErrors;
 
   @delete
   delete(@path id: uuid): NoContentResponse | DeleteErrors;
@@ -264,8 +273,8 @@ interface Pets {
 ```
 
 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
+interface, so the ids become `listPets`, `getPet`, `createPet`, `updatePet`,
+`patchPet` 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)).

package/docs/guide/headers.md

@@ -19,7 +19,7 @@ namespace Blog;
 
 @route("/posts")
 interface Posts {
-  @post createPost(...IdempotencyKeyHeader, @body post: Create<Post>): {
+  @post createPost(...IdempotencyKeyHeader, @body post: CreateRequest<Post>): {
     @statusCode _: 201;
     ...IdempotentReplayedHeader;
     @body post: Post;
@@ -48,7 +48,7 @@ lock, gets one 409 with the description of the first, and the library warns,
 ## A rate limit
 
 ```tsp
-@post createPost(@body post: Create<Post>): {
+@post createPost(@body post: CreateRequest<Post>): {
   @statusCode _: 201;
   ...RateLimitHeaders;
   @body post: Post;

package/docs/guide/operation-ids.md

@@ -147,7 +147,7 @@ Give the operation its verb's method, or a name that is not a verb, which
 is then its id as written:
 
 ```tsp
-@patch @route("/{id}") update(@path id: uuid, @body user: User): User;  // updateUser
+@put @route("/{id}") update(@path id: uuid, @body user: User): User;    // updateUser
 @post @route("/lookup") lookUpUser(@body id: uuid): User;                // lookUpUser
 ```
 

package/docs/guide/requests.md

@@ -0,0 +1,145 @@
+# Request bodies
+
+`CreateRequest<T>`, `UpdateRequest<T>` and `PatchRequest<T>` are TypeSpec's own
+`Create`, `Update` and `MergePatchUpdate` with a name template, so the body of
+each write is a component with a name you can read: `CreatePostRequest`.
+
+## Why names
+
+TypeSpec's templates name what they emit from the model: `Create<Post>` is
+the component `CreatePost` and `MergePatchUpdate<Post>` is
+`PostMergePatchUpdate`. Two conventions in one spec, and a type in the
+generated client that reads unlike the rest. The aliases give each body the
+name `<Verb><Model>Request`, and `@nxgt/openapi-codegen` generates the types
+and the Zod schemas under it.
+
+## The smallest example
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+namespace Blog;
+
+model Post {
+  @visibility(Lifecycle.Read) id: uuid;
+  @minLength(1) title: string;
+  body: string;
+  tags?: string[];
+  ...Timestamps;
+  ...Versioned;
+}
+
+@route("/posts")
+interface Posts {
+  @post createPost(@body post: CreateRequest<Post>): {
+    @statusCode _: 201;
+    @body post: Post;
+  } | BadRequest;
+
+  @put updatePost(@path postId: uuid, @body post: UpdateRequest<Post>):
+    Post | BadRequest | NotFound | Conflict;
+
+  @patch patchPost(@path postId: uuid, @body post: PatchRequest<Post>):
+    Post | BadRequest | NotFound | Conflict;
+}
+```
+
+| Alias | Is | Component | Content type | Properties |
+| --- | --- | --- | --- | --- |
+| `CreateRequest<T>` | `Create<T, "Create{name}Request">` | `CreatePostRequest` | `application/json` | those visible on create, as `T` declares them |
+| `UpdateRequest<T>` | `Update<T, "Update{name}Request">` | `UpdatePostRequest` | `application/json` | those visible on update, as `T` declares them |
+| `PatchRequest<T>` | `MergePatchUpdate<T, "Patch{name}Request">` | `PatchPostRequest` | `application/merge-patch+json` | those visible on update, all optional |
+
+```ts
+import type {
+	CreatePostRequest,
+	PatchPostRequest,
+	UpdatePostRequest,
+} from './generated/types';
+```
+
+```tsp
+alias CreateRequest<T extends Reflection.Model> = Create<T, "Create{name}Request">;
+alias UpdateRequest<T extends Reflection.Model> = Update<T, "Update{name}Request">;
+alias PatchRequest<T extends Reflection.Model> = MergePatchUpdate<T, "Patch{name}Request">;
+```
+
+Read-only properties (`id`, `Timestamps`, `Actors`) are in none of the three.
+`version` from `Versioned` is read and update, so it is in
+`UpdatePostRequest` and `PatchPostRequest`, and not in `CreatePostRequest`.
+
+## `PUT` replaces, `PATCH` merges
+
+`UpdateRequest<Post>` is the whole resource: each property is as optional as
+`Post` declares it, so `title` is required and `tags?` is not. Send it with
+`@put`.
+
+`PatchRequest<Post>` is a JSON Merge Patch: every property is optional, and a
+nullable one is sent as `null` to clear it. The body's content type is
+`application/merge-patch+json`, where the others are `application/json`.
+
+```yaml
+# openapi.yaml (excerpt)
+PUT:
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/UpdatePostRequest'
+PATCH:
+  requestBody:
+    content:
+      application/merge-patch+json:
+        schema:
+          $ref: '#/components/schemas/PatchPostRequest'
+```
+
+A client sending a patch sets the header `Content-Type:
+application/merge-patch+json`. The component `UpdatePostRequest` requires
+`title`; `PatchPostRequest` requires nothing.
+
+## Nested models
+
+A nested model the template filters is named by the same template; one it
+leaves whole keeps its name.
+
+```tsp
+model Address {
+  @visibility(Lifecycle.Read) id: uuid;
+  street: string;
+}
+
+model Author {
+  @visibility(Lifecycle.Read) id: uuid;
+  name: string;
+  address: Address;
+}
+
+@post createAuthor(@body author: CreateRequest<Author>): Author;
+// CreateAuthorRequest.address is CreateAddressRequest, without `id`
+```
+
+A model with no property the filter changes, such as a `Tag` with only
+`name`, is referenced under its own name, `Tag`.
+
+## Your own name template
+
+The aliases fix the convention. Another one is the same template, inline, and
+`Create<T>` and `MergePatchUpdate<T>` stay usable:
+
+```tsp
+@post createPost(@body post: Create<Post, "New{name}">): Post;   // NewPost
+@patch patchPost(@path postId: uuid, @body post: MergePatchUpdate<Post, "{name}Changes">): Post;
+```
+
+`{name}` is the model's name. Without a template, TypeSpec names the
+components `CreatePost` and `PostMergePatchUpdate`.
+
+## Next
+
+The columns a request leaves out are on [Scalars and columns](columns.md); the
+errors a write answers on [Error replies](errors.md).

package/docs/roadmap.md

@@ -26,6 +26,14 @@ Nothing in progress.
 
 ## Shipped
 
+### 0.11.0
+
+- **Request body aliases.** `CreateRequest<T>`, `UpdateRequest<T>` and
+  `PatchRequest<T>` are TypeSpec's `Create`, `Update` and `MergePatchUpdate`
+  named `Create<T>Request`, `Update<T>Request` and `Patch<T>Request`, so the
+  generated types and schemas share one convention. `Create<T>` and
+  `MergePatchUpdate<T>` stay usable.
+
 ### 0.10.0
 
 - **Every scalar of `@nxgt/graphql-scalars`.** The scalars, under the same

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 updatePost(@path postId: string, @body post: MergePatchUpdate<Post>): Post | BadRequest;
+@patch patchPost(@path postId: string, @body post: PatchRequest<Post>): Post | BadRequest;
 ```
 
 ## `Couldn't resolve import "@nxgt/typespec"`

package/lib/main.tsp

@@ -9,3 +9,4 @@ import "./scalars.tsp";
 import "./columns.tsp";
 import "./headers.tsp";
 import "./sorting.tsp";
+import "./requests.tsp";

package/lib/requests.tsp

@@ -0,0 +1,36 @@
+import "@typespec/http";
+
+using Http;
+
+namespace Nxgt;
+
+/**
+ * The body of a create: the properties of `T` visible on create, named
+ * `Create<T>Request` (`CreatePostRequest`). A nested model filtered the same
+ * way is named alike (`CreateAddressRequest`); one left whole keeps its name.
+ */
+alias CreateRequest<T extends Reflection.Model> = Create<
+  T,
+  "Create{name}Request"
+>;
+
+/**
+ * The body of a full update, as a `PUT` replaces the resource: the properties
+ * of `T` visible on update, each as optional as `T` declares it, named
+ * `Update<T>Request` (`UpdatePostRequest`).
+ */
+alias UpdateRequest<T extends Reflection.Model> = Update<
+  T,
+  "Update{name}Request"
+>;
+
+/**
+ * The body of a partial update, as a JSON Merge Patch
+ * (`application/merge-patch+json`): the properties of `T` visible on update,
+ * all optional, a nullable one sent as `null` to clear it, named
+ * `Patch<T>Request` (`PatchPostRequest`).
+ */
+alias PatchRequest<T extends Reflection.Model> = MergePatchUpdate<
+  T,
+  "Patch{name}Request"
+>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/typespec",
-	"version": "0.10.0",
+	"version": "0.11.0",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",

package/templates/nxgt/main.tsp

@@ -50,16 +50,23 @@ interface Users {
 
   /** Creates a user. */
   @post
-  create(@body user: Create<User>): {
+  create(@body user: CreateRequest<User>): {
     @statusCode _: 201;
     @body user: User;
   } | CreateErrors;
 
-  /** Updates a user with a merge patch. */
-  @patch
+  /** Replaces a user: the whole body, as a `PUT` sends it. */
+  @put
   update(
     @path id: uuid,
-    @body user: MergePatchUpdate<User>,
+    @body user: UpdateRequest<User>,
+  ): User | UpdateErrors;
+
+  /** Updates some of a user's properties, with a merge patch. */
+  @patch
+  patch(
+    @path id: uuid,
+    @body user: PatchRequest<User>,
   ): User | UpdateErrors;
 
   /** Deletes a user. */