@nxgt/typespec 0.6.0 → 0.7.0

package/README.md

@@ -131,6 +131,24 @@ The generator also declares the validators' own 400, `ValidationErrorBody`,
 on every operation that takes a parameter or a body. With `BadRequest`, a
 400 reply is typed `BadRequestBody | ValidationErrorBody`.
 
+Each verb has an alias for the errors it usually answers, so a resource's
+operations do not repeat the same unions. Combine them, and add a response
+an alias leaves out:
+
+```tsp
+@route("/users")
+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;
+  @delete delete(@path id: uuid): NoContentResponse | DeleteErrors;
+}
+```
+
+An alias is exactly its union, so the OpenAPI it emits is the same as
+writing the responses out.
+
 ### Pagination
 
 Spread the query of a page into the operation's parameters, and answer the
@@ -445,6 +463,15 @@ envelope and the rate limit's headers.
 `@error` model with its `@statusCode` and body, and
 `ErrorResponse<Status>` for any other status.
 
+| Alias | What it is |
+| --- | --- |
+| `ListErrors` | `BadRequest` |
+| `GetErrors` | `NotFound` |
+| `CreateErrors` | `BadRequest \| Conflict` |
+| `UpdateErrors` | `BadRequest \| NotFound \| Conflict` |
+| `DeleteErrors` | `NotFound` |
+| `AuthErrors` | `Unauthorized \| Forbidden`, with the envelope; a route that answers without a body declares `AuthenticationRequired \| AccessDenied` instead |
+
 ## Traps
 
 - **Do not declare a schema named `ValidationErrorBody`.** The generator
@@ -466,7 +493,8 @@ envelope and the rate limit's headers.
 - **One status, one reply.** `@typespec/openapi3` merges two replies of one
   status into one. With `AuthenticationRequired` and `Unauthorized`, the 401
   keeps the envelope and the reply without a body is lost: the library
-  refuses it, `duplicate-status-reply`. With `Conflict` beside
+  refuses it, `duplicate-status-reply`. With `Conflict` (which
+  `CreateErrors` and `UpdateErrors` hold) beside
   `IdempotencyInProgress`, or `UnprocessableEntity` beside
   `IdempotencyKeyReused`, both bodies stay, under the first reply's
   description: the library warns, `merged-status-reply`. Declare the one the
@@ -503,8 +531,8 @@ envelope and the rate limit's headers.
 
 ## Documentation
 
-- [Error replies](docs/guide/errors.md): the envelope, each response, and
-  what the generator makes of them;
+- [Error replies](docs/guide/errors.md): the envelope, each response, the
+  aliases by verb, and what the generator makes of them;
 - [Pagination](docs/guide/pagination.md): offset and cursor pages, and
   what a handler answers;
 - [Authentication](docs/guide/auth.md): `JanusAuth`, and the guards'

package/docs/guide/errors.md

@@ -173,6 +173,71 @@ Name them in an operation's return type, beside the success:
 @get getPost(@path postId: string): Post | NotFound | Unauthorized | Forbidden;
 ```
 
+## Aliases by verb
+
+Most operations of a resource answer the same errors. Each verb has an alias
+for them:
+
+| Alias | Responses | Statuses |
+| --- | --- | --- |
+| `ListErrors` | `BadRequest` | 400 |
+| `GetErrors` | `NotFound` | 404 |
+| `CreateErrors` | `BadRequest \| Conflict` | 400, 409 |
+| `UpdateErrors` | `BadRequest \| NotFound \| Conflict` | 400, 404, 409 |
+| `DeleteErrors` | `NotFound` | 404 |
+| `AuthErrors` | `Unauthorized \| Forbidden` | 401, 403 |
+
+```tsp
+import "@typespec/http";
+import "@nxgt/typespec";
+
+using Http;
+using Nxgt;
+
+@service
+namespace Shop;
+
+model User {
+  id: uuid;
+}
+
+@route("/users")
+interface Users {
+  @get list(...PageParameters): Page<User> | ListErrors;
+  @get get(@path id: uuid): User | GetErrors;
+  @post create(@body user: User): User | CreateErrors;
+  @patch update(@path id: uuid, @body user: User): User | UpdateErrors;
+  @delete delete(@path id: uuid): NoContentResponse | DeleteErrors;
+  @get @route("/me") me(): User | AuthErrors;
+}
+```
+
+An alias is a union, and nothing more: it emits the same OpenAPI as the
+responses written out. Combine aliases, and add a response an alias leaves
+out:
+
+```tsp
+@post create(@body user: User): User | CreateErrors | AuthErrors | TooManyRequests;
+```
+
+A union of your own names the errors your routes share:
+
+```tsp
+alias WriteErrors = CreateErrors | AuthErrors | TooManyRequests;
+```
+
+Do not add a response the alias already holds. `UpdateErrors | NotFound`
+declares the 404 twice, and the library warns, `merged-status-reply`. A 409
+beside `CreateErrors` or `UpdateErrors`, such as `IdempotencyInProgress`,
+warns too: declare the responses one by one there
+([Headers](headers.md), [troubleshooting](../troubleshooting.md)).
+
+`AuthErrors` carries the envelope, for a handler's own refusal. A route
+whose guard answers the 401 and 403 without a body, as `@nxgt/janus-hono`'s
+do, declares `AuthenticationRequired | AccessDenied` instead
+([Authentication](auth.md)). The two in one operation are an error,
+`duplicate-status-reply`.
+
 ## Another status, named
 
 `ErrorResponse<503>` works, but its body is emitted inline and generated as

package/docs/roadmap.md

@@ -6,11 +6,10 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
 
 ## Now
 
-- **Verbs name their methods.** An operation named after one of the
-  library's verbs and sent with another method is a warning,
-  `verb-method-mismatch`: `create` is a `POST`, `list` a `GET` or a `HEAD`,
-  `search` a `GET` or a `POST`. `#suppress` silences one operation.
-- **`query`, a verb.** `query` in `Users` is `queryUsers`, like `search`.
+- **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.
 
 ## Later
 
@@ -24,6 +23,14 @@ generated by `@nxgt/openapi-codegen` in CI before it ships.
 
 ## Shipped
 
+### 0.6.0
+
+- **Verbs name their methods.** An operation named after one of the
+  library's verbs and sent with another method is a warning,
+  `verb-method-mismatch`: `create` is a `POST`, `list` a `GET` or a `HEAD`,
+  `search` a `GET` or a `POST`. `#suppress` silences one operation.
+- **`query`, a verb.** `query` in `Users` is `queryUsers`, like `search`.
+
 ### 0.5.0
 
 - **Verbs in operation ids.** In an interface `@operationIds` marks, a known

package/docs/troubleshooting.md

@@ -281,6 +281,15 @@ header either reply declares required becomes optional.
 @post createPost(@body post: Post): Post | IdempotencyInProgress;
 ```
 
+An alias can hide the duplicate: `CreateErrors` holds a `Conflict`, so
+`Post | CreateErrors | IdempotencyInProgress` declares two 409s, and
+`UpdateErrors | NotFound` two 404s. Spell the alias's other errors out
+instead:
+
+```tsp
+@post createPost(@body post: Post): Post | BadRequest | IdempotencyInProgress;
+```
+
 Two plain bodies, `Post | Draft`, are one reply whose body is either; two
 `@error` models without a `@statusCode` share `default`, and one
 description; bodies of different content types are negotiated. All three

package/lib/errors.tsp

@@ -146,3 +146,31 @@ model ErrorResponse<Status extends integer> {
   @statusCode _: Status;
   @body body: ErrorBody<Status>;
 }
+
+/**
+ * The errors a list declares: a query its validators refuse.
+ *
+ * ```tsp
+ * @get list(...PageParameters): Page<User> | ListErrors;
+ * ```
+ */
+alias ListErrors = BadRequest;
+
+/** The errors a read of one declares: nothing at that id. */
+alias GetErrors = NotFound;
+
+/** The errors a create declares: a body refused, or one that conflicts. */
+alias CreateErrors = BadRequest | Conflict;
+
+/** The errors an update declares: a body refused, nothing at that id, or a conflict. */
+alias UpdateErrors = BadRequest | NotFound | Conflict;
+
+/** The errors a delete declares: nothing at that id. */
+alias DeleteErrors = NotFound;
+
+/**
+ * The errors of an operation behind authentication, with the nxgt envelope.
+ * A route that answers them without a body, as Janus does, declares
+ * `AuthenticationRequired | AccessDenied` instead.
+ */
+alias AuthErrors = Unauthorized | Forbidden;

package/package.json

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