@antelopejs/interface-data-api 0.5.0 → 0.6.0

package/docs/3.routes.md

@@ -1,18 +1,22 @@
-# Routes
+---
+title: Routes
+description: The default CRUD routes, their parameters and responses, the WithOptions and WithGetGuard helpers, custom routes, and route errors.
+mode: reference
+---
 
 ## Overview
 
-Routes define which operations are available on a data controller. The module provides predefined route configurations that automatically generate endpoints with the correct HTTP methods, parameter extraction, and response handling.
+Routes define which operations a data controller serves. The `DefaultRoutes` namespace holds ready-made routes. Each one sets its HTTP method, the parameters it reads from the request and the response it sends.
 
-## Default Routes
+## Default routes
 
-The `DefaultRoutes` namespace provides five built-in routes covering standard CRUD operations.
+The `DefaultRoutes` namespace holds five routes for the CRUD operations.
 
 ```typescript
 import { DefaultRoutes } from "@antelopejs/interface-data-api";
 ```
 
-| Route  | Object                 | HTTP Method | Endpoint Pattern           |
+| Route  | Object                 | HTTP method | Endpoint pattern           |
 | ------ | ---------------------- | ----------- | -------------------------- |
 | Get    | `DefaultRoutes.Get`    | GET         | `/resource/get?id=<id>`    |
 | List   | `DefaultRoutes.List`   | GET         | `/resource/list`           |
@@ -20,13 +24,13 @@ import { DefaultRoutes } from "@antelopejs/interface-data-api";
 | Edit   | `DefaultRoutes.Edit`   | PUT         | `/resource/edit?id=<id>`   |
 | Delete | `DefaultRoutes.Delete` | DELETE      | `/resource/delete?id=<id>` |
 
-Use `DefaultRoutes.All` to include all five routes at once.
+`DefaultRoutes.All` holds all five routes under the keys `get`, `list`, `new`, `edit` and `delete`.
 
-## Route Configuration
+## Route configuration
 
-Pass a route definition object to `DataController` to control which endpoints are created.
+The route definition object you pass to `DataController` decides which endpoints exist. Each key is an endpoint name.
 
-```typescript
+```typescript fragment
 // All CRUD routes
 @RegisterDataController()
 class UserAPI extends DataController(
@@ -48,31 +52,27 @@ class UserAPI extends DataController(
   },
   Controller("/users"),
 ) {
-  // edit and delete endpoints are not created
+  // no edit or delete endpoint
 }
 ```
 
-## Route Details
+## Route details
 
 ### Get
 
-Retrieves a single record by its identifier.
-
-**Endpoint:** `GET /resource/get`
+Reads one record by its identifier. The endpoint is `GET /resource/get`.
 
-**Query Parameters:**
+| Query parameter | Required | Description       |
+| --------------- | -------- | ----------------- |
+| `id`            | Yes      | Record identifier |
 
-| Parameter | Required | Description       |
-| --------- | -------- | ----------------- |
-| `id`      | Yes      | Record identifier |
-
-**Example:**
+A request without `id` answers `400` with `Missing id.`. A missing record answers `404 Not Found`.
 
 ```http
 GET /users/get?id=user-123
 ```
 
-**Response:**
+The response holds the readable fields of the record.
 
 ```json
 {
@@ -84,26 +84,21 @@ GET /users/get?id=user-123
 
 ### List
 
-Retrieves multiple records with pagination, sorting, and filtering support.
-
-**Endpoint:** `GET /resource/list`
+Reads one page of records, with sorting and filtering. The endpoint is `GET /resource/list`.
 
-**Query Parameters:**
-
-| Parameter       | Required | Default | Description                                   |
-| --------------- | -------- | ------- | --------------------------------------------- |
-| `limit`         | No       | `10`    | Maximum number of records to return           |
-| `offset`        | No       | `0`     | Number of records to skip                     |
-| `sortKey`       | No       | -       | Field to sort by (must be marked `@Sortable`) |
-| `sortDirection` | No       | `asc`   | Sort direction: `asc` or `desc`               |
-
-**Example:**
+| Query parameter  | Required | Default              | Description                                                                                      |
+| ---------------- | -------- | -------------------- | ------------------------------------------------------------------------------------------------ |
+| `limit`          | No       | `maxPage`, else `10` | Maximum number of records to return. The route caps it at `maxPage`, or at `100` without one.    |
+| `offset`         | No       | `0`                  | Number of records to skip                                                                        |
+| `sortKey`        | No       | none                 | Field to sort by. The field needs `@Sortable`, or the route answers `400 Field is not sortable.` |
+| `sortDirection`  | No       | `asc`                | `asc` or `desc`. Any other value sorts ascending.                                                |
+| `filter_<field>` | No       | none                 | A filter on a field declared with `@Filter`. See [filters](./8.filters.md).                      |
 
 ```http
 GET /users/list?limit=10&offset=0&sortKey=name&sortDirection=asc
 ```
 
-**Response:**
+The response holds the page, the total count of matching records, and the `offset` and `limit` the route used.
 
 ```json
 {
@@ -119,13 +114,7 @@ GET /users/list?limit=10&offset=0&sortKey=name&sortDirection=asc
 
 ### New
 
-Creates a new record. The request body must be a JSON object with the fields to set.
-
-**Endpoint:** `POST /resource/new`
-
-**Body:** JSON object with field values.
-
-**Example:**
+Creates a record. The endpoint is `POST /resource/new`, and the body is a JSON object with the field values.
 
 ```http
 POST /users/new
@@ -138,7 +127,7 @@ Content-Type: application/json
 }
 ```
 
-**Response:** the created record, as [Get](#get) answers it, with its `_id` even when `get` does not read it.
+The response is the created record, as [Get](#get) answers it, with its `_id` even when `get` does not read `_id`.
 
 ```json
 {
@@ -148,23 +137,19 @@ Content-Type: application/json
 }
 ```
 
-Every writable field is written: a field absent from the body is written as `undefined`, and every writable setter of the controller runs (with `undefined` for absent fields). A body that is not valid JSON or not a JSON object is rejected with `400 Bad Request`.
+The row starts from the defaults the controller class declares. Every writable field is then written. A field absent from the body is written as `undefined`, and every writable setter of the controller runs, with `undefined` for an absent field. The route answers `400 Bad Request` for a body that is not valid JSON or not a JSON object.
 
-Before inserting, the `insert` event is triggered on any table modifiers attached to the database table.
+Before the insert, the route triggers the `insert` event on the modifiers of the table.
 
 ### Edit
 
-Updates an existing record by its identifier.
-
-**Endpoint:** `PUT /resource/edit`
+Updates a record by its identifier. The endpoint is `PUT /resource/edit`.
 
-**Query Parameters:**
+| Query parameter | Required | Description       |
+| --------------- | -------- | ----------------- |
+| `id`            | Yes      | Record identifier |
 
-| Parameter | Required | Description       |
-| --------- | -------- | ----------------- |
-| `id`      | Yes      | Record identifier |
-
-**Body:** JSON object with the fields to update. Only the fields present in the body are written:
+The body is a JSON object with the fields to update. The route writes only the fields present in the body.
 
 | In the body | Effect on the field |
 | ----------- | ------------------- |
@@ -172,11 +157,9 @@ Updates an existing record by its identifier.
 | `null`      | cleared             |
 | a value     | set                 |
 
-Writable setters only run for the fields present in the body. Modifier fields (localized, encrypted…) absent from the body keep their stored value in every language.
-
-A missing record answers `404 Not Found`. A body that is not valid JSON or not a JSON object is rejected with `400 Bad Request`.
+Writable setters run only for the fields present in the body. A modifier field (localized or encrypted, for example) absent from the body keeps its stored value in every language.
 
-**Example:**
+A request without `id` answers `400` with `Missing id.`. A missing record answers `404 Not Found`. A body that is not valid JSON or not a JSON object answers `400 Bad Request`.
 
 ```http
 PUT /users/edit?id=user-123
@@ -188,7 +171,7 @@ Content-Type: application/json
 }
 ```
 
-**Response:** the stored record after the update, as [Get](#get) answers it (joined, computed and foreign fields included), so the caller needs no second read.
+The response is the stored record after the update, as [Get](#get) answers it, with joined, computed and foreign fields. The caller needs no second read.
 
 ```json
 {
@@ -198,49 +181,45 @@ Content-Type: application/json
 }
 ```
 
-Before updating, the `update` event is triggered on any table modifiers attached to the database table.
+Before the update, the route triggers the `update` event on the modifiers of the table.
 
 ### Delete
 
-Deletes one or more records by their identifiers.
+Deletes one or more records by their identifiers. The endpoint is `DELETE /resource/delete`.
 
-**Endpoint:** `DELETE /resource/delete`
+| Query parameter | Required | Description                                                                         |
+| --------------- | -------- | ----------------------------------------------------------------------------------- |
+| `id`            | Yes      | Record identifier. Repeat the `id` parameter to delete several records in one call. |
 
-**Query Parameters:**
-
-| Parameter | Required | Description                                                                            |
-| --------- | -------- | -------------------------------------------------------------------------------------- |
-| `id`      | Yes      | Record identifier(s). Pass multiple `id` parameters to delete several records at once. |
-
-**Example:**
+A request without `id` answers `400` with `Missing id.`.
 
 ```http
 DELETE /users/delete?id=user-123
 ```
 
-**Response:**
+The route answers `200 OK`. The body is the number of records the database deleted. An identifier that matches no record is not an error.
 
 ```http
 200 OK
 ```
 
-## Route Options with `WithOptions`
+## Route options with `WithOptions`
 
-The `DefaultRoutes.WithOptions` function customizes route behavior by overriding query parameters or route settings.
+`DefaultRoutes.WithOptions` customizes a route. It sets route options, which take precedence over the query parameters of the same name, and it can rename the endpoint.
 
-```typescript
+```typescript fragment
 DefaultRoutes.WithOptions(callback, options?, endpoint?)
 ```
 
-| Parameter  | Description                                                                          |
-| ---------- | ------------------------------------------------------------------------------------ |
-| `callback` | The route callback to customize (e.g., `DefaultRoutes.Edit`).                        |
-| `options`  | An object with option overrides. These values take precedence over query parameters. |
-| `endpoint` | An optional custom endpoint path. Defaults to the route key name.                    |
+| Parameter  | Description                                                                                                                      |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `callback` | The route to customize, such as `DefaultRoutes.Edit`, or a route `WithOptions` already returned. In that case the options merge. |
+| `options`  | An object of option values. A query parameter with the same name is ignored. Route `filters` combine with the request's filters. |
+| `endpoint` | A custom endpoint path. It defaults to the route key in the definition object.                                                   |
 
 ### Example
 
-```typescript
+```typescript fragment
 const routes = {
   edit: DefaultRoutes.Edit,
   quickEdit: DefaultRoutes.WithOptions(DefaultRoutes.Edit, {
@@ -250,48 +229,52 @@ const routes = {
 
 @RegisterDataController()
 class UserAPI extends DataController(User, routes, Controller("/users")) {
-  // /users/edit enforces mandatory fields
-  // /users/quickEdit skips mandatory field validation
+  // /users/edit checks mandatory fields
+  // /users/quickEdit skips the mandatory field check
 }
 ```
 
-### Available Options per Route
+### Available options per route
+
+The string options `noForeign` and `noMandatory` take effect for any non-empty string, `"false"` included.
 
-**Get:**
+The Get route takes these options.
 
-| Option      | Type     | Description                                      |
-| ----------- | -------- | ------------------------------------------------ |
-| `index`     | `string` | Use a secondary index instead of the primary key |
-| `noForeign` | `string` | Skip foreign key resolution                      |
+| Option      | Type     | Description                                                          |
+| ----------- | -------- | -------------------------------------------------------------------- |
+| `index`     | `string` | Read the record through a secondary index instead of the primary key |
+| `noForeign` | `string` | Skip foreign key resolution                                          |
 
-**List:**
+The List route takes these options.
 
 | Option      | Type                          | Description                                                                                                                  |
 | ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `maxPage`   | `number`                      | Maximum allowed value for `limit` (caps the page size)                                                                       |
+| `maxPage`   | `number`                      | Maximum value of `limit`, and the page size when the request sends no `limit`. Without it, the cap is `100`.                 |
 | `noForeign` | `boolean`                     | Skip foreign key resolution                                                                                                  |
-| `noPluck`   | `boolean`                     | Return all database fields instead of plucked fields                                                                         |
-| `pluckMode` | `string`                      | Select a named pluck mode (see `@Listable`)                                                                                  |
-| `filters`   | `Record<string, FieldFilter>` | Mandatory filters merged with request filters; route field keys win (see [filters](./8.filters.md#mandatory-route-filters)). |
+| `noPluck`   | `boolean`                     | Skip the database pluck. The response still holds only the fields readable in `list`                                         |
+| `pluckMode` | `string`                      | Select a named pluck mode (see `@Listable`). A mode that no field declares answers `400`.                                    |
+| `filters`   | `Record<string, FieldFilter>` | Mandatory filters merged with request filters. Route field keys win (see [filters](./8.filters.md#mandatory-route-filters)). |
 
-**New:**
+The New route takes this option.
 
-| Option        | Type     | Description                     |
-| ------------- | -------- | ------------------------------- |
-| `noMandatory` | `string` | Skip mandatory field validation |
+| Option        | Type     | Description                    |
+| ------------- | -------- | ------------------------------ |
+| `noMandatory` | `string` | Skip the mandatory field check |
 
-**Edit:**
+The Edit route takes these options.
 
-| Option        | Type     | Description                                      |
-| ------------- | -------- | ------------------------------------------------ |
-| `index`       | `string` | Use a secondary index instead of the primary key |
-| `noMandatory` | `string` | Skip mandatory field validation                  |
+| Option        | Type     | Description                                                                                                                          |
+| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `index`       | `string` | Find the record and read the response through a secondary index. The update itself targets the record whose primary key equals `id`. |
+| `noMandatory` | `string` | Skip the mandatory field check                                                                                                       |
 
-## Amending the Body of New and Edit
+## Amending the body of `new` and `edit`
 
-The `new` and `edit` routes take the raw request body (`Buffer`) or a body already parsed (`Validation.WrittenBody`). A route wrapping them can parse the body, amend it (stamp a field, drop one) and hand the object on: the route validates and writes it as handed, without a second serialization.
+The `new` and `edit` routes take the raw request body (`Buffer`) or a body already parsed (`Validation.WrittenBody`). A route that wraps them can parse the body, amend it (stamp a field or drop one) and pass the object on. The route validates and writes the object as it receives it, with no second serialization.
 
-A parsed body is `FieldValues`: fields by name, each holding a `FieldValue` (a string, number, boolean, `null`, `Date`, or an array or plain object of those). `Validation.ParseBody` answers 400 for anything else, whether it comes from a `Buffer` or from a body already parsed: a function, a class instance, a `bigint`, a cycle or an `undefined` array element. The default routes run with the controller as `this`, so a wrapping function declares `this: DataControllerInstance` and calls `route.func.call(this, ...)`.
+A parsed body is `FieldValues`, which holds fields by name. Each field holds a `FieldValue`: a string, a number, a boolean, `null`, a `Date`, or an array or plain object of those. `Validation.ParseBody` answers `400` for anything else, whether it comes from a `Buffer` or from a body already parsed. That includes a function, a class instance, a `bigint`, a cycle and an `undefined` array element.
+
+The default routes run with the controller as `this`. A wrapping function declares `this: DataControllerInstance` and calls `route.func.call(this, ...)`.
 
 ```ts docs-check
 import {
@@ -319,9 +302,9 @@ const stampedNew = {
 };
 ```
 
-## Loaded-Model Guards with `WithGetGuard`
+## Loaded-model guards with `WithGetGuard`
 
-`DefaultRoutes.WithGetGuard(guard)` returns a Get route that awaits a guard after loading and unlocking the model, but before selecting readable fields and applying response getters. Use it to check a stored discriminator or ownership field that must not appear in the response.
+`DefaultRoutes.WithGetGuard(guard)` returns a Get route that awaits a guard after it loads and unlocks the model. The guard runs before the route selects the readable fields and applies the response getters. A guard can check a stored discriminator or ownership field that never appears in the response.
 
 ```ts docs-check
 import { DefaultRoutes } from "@antelopejs/interface-data-api";
@@ -329,7 +312,7 @@ import { assert } from "@antelopejs/interface-api-util";
 
 const invoiceGet = DefaultRoutes.WithGetGuard(
   async function (ctx, current, params) {
-    // documentType can be stored without being exposed through @Access.
+    // The table stores documentType, and no @Access exposes it.
     assert(current.documentType === "invoice", 404, "Not Found");
   },
 );
@@ -340,28 +323,28 @@ const routes = {
 };
 ```
 
-The `GetGuard` callback receives `(ctx, current, params)`. Declare it as a regular function to access the controller through `this`, typed `DataControllerInstance`. `current` is `FieldValues`.
+The `GetGuard` callback receives `(ctx, current, params)`. Declare it as a regular function to reach the controller through `this`, typed `DataControllerInstance`. That type is `object`, with no string index, so narrow `this` (with `instanceof` your controller class, for example) before you read a controller field. `current` is `RowFields`, whose values are `unknown`.
 
-| Argument  | Contents                                                                                | Use it for                                     |
-| --------- | --------------------------------------------------------------------------------------- | ---------------------------------------------- |
-| `ctx`     | Request context                                                                         | Request-specific policy.                       |
-| `current` | Loaded model, including non-readable fields and normal Get joined/computed/foreign data | Inspecting stored ownership or discriminators. |
-| `params`  | `Parameters.GetParameters`                                                              | The parsed Get parameters.                     |
+| Argument  | Contents                                                                                          | Use it for                                  |
+| --------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `ctx`     | Request context                                                                                   | Policy that depends on the request          |
+| `current` | Loaded model, with the fields no `@Access` reads and the joined, computed and foreign data of Get | Checking stored ownership or discriminators |
+| `params`  | `Parameters.GetParameters`                                                                        | The parsed Get parameters                   |
 
-Treat `current` as read-only: it is not the response DTO and the API does not freeze it.
+Treat `current` as read-only. It is not the response object, and the API does not freeze it.
 
-Keep these boundaries when writing a guard:
+A guard follows these rules.
 
-- **Deny by throwing.** Throw an `HTTPResult` or use `assert`. A normal return permits the read, including a return value of `false`.
-- **Missing records bypass the guard.** The route returns `404` without invoking it.
-- **Use the already-loaded model.** The guard does not issue a second read or change field-access rules.
-- **Protect each route deliberately.** The guard applies only to the route using it, not list, edit, or delete routes.
+- **Deny by throwing.** Throw an `HTTPResult` or call `assert`. A normal return allows the read, even a return value of `false`.
+- **A missing record skips the guard.** The route answers `404` without calling it.
+- **The guard reads the loaded model.** It issues no second read and does not change field access rules.
+- **Each route needs its own guard.** The guard applies only to the route that uses it, not to the list, edit or delete routes.
 
-## Custom Routes
+## Custom routes
 
-For operations beyond CRUD, define a custom route callback with `func`, `args`, and `method` properties.
+For operations beyond CRUD, define a route callback with `func`, `args` and `method` properties.
 
-```typescript
+```typescript fragment
 import { Context } from "@antelopejs/interface-api";
 import {
   DataController,
@@ -392,20 +375,54 @@ class UserAPI extends DataController(
 }
 ```
 
-The `args` array contains parameter decorators that extract values from the request context. Each decorator corresponds to a parameter in the `func` callback, in order.
+The `args` array holds parameter decorators that read values from the request context. Entry `i` of `args` supplies parameter `i` of `func`.
+
+`DataControllerCallback<O, R, A>` states that pairing. `A` is the tuple of what `func` receives, and `args` holds one decorator per element of `A`. The default routes declare their tuple. `DefaultRoutes.Get` takes `[RequestContext, Parameters.GetParameters]`, and `DefaultRoutes.New` and `DefaultRoutes.Edit` add the `Validation.WrittenBody`. A route that wraps one of them can be generic over the tuple and call `route.func.call(this, ...)` with typed arguments. Without `A`, the parameters are unknown and unchecked. A `DataControllerDef` holds routes of that type.
+
+```ts docs-check
+import type { RequestContext } from "@antelopejs/interface-api";
+import {
+  type DataControllerCallback,
+  type DataControllerInstance,
+  DefaultRoutes,
+} from "@antelopejs/interface-data-api";
+import type { Parameters } from "@antelopejs/interface-data-api/components";
+
+function withLoggedId<O, R, Rest extends unknown[]>(
+  route: DataControllerCallback<
+    O,
+    R,
+    [RequestContext, Parameters.GetParameters, ...Rest]
+  >,
+): DataControllerCallback<
+  O,
+  R,
+  [RequestContext, Parameters.GetParameters, ...Rest]
+> {
+  return {
+    ...route,
+    func: function (this: DataControllerInstance, ctx, params, ...rest) {
+      console.log(params.id);
+      return route.func.call(this, ctx, params, ...rest);
+    },
+  };
+}
+
+const loggedGet = withLoggedId(DefaultRoutes.Get);
+```
 
-## Error Handling
+## Error handling
 
-Default routes return standard HTTP error responses:
+The default routes answer with these HTTP errors.
 
-| Status                      | Condition                                                        |
-| --------------------------- | ---------------------------------------------------------------- |
-| `400 Bad Request`           | Validation fails, missing required fields, or invalid parameters |
-| `404 Not Found`             | Record does not exist                                            |
-| `500 Internal Server Error` | Database operation fails                                         |
+| Status                      | Condition                                                                                                                      |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `400 Bad Request`           | A field fails its validator, a mandatory field is missing, the body is not a JSON object, or a parameter is missing or invalid |
+| `404 Not Found`             | The record does not exist                                                                                                      |
+| `500 Internal Server Error` | The database operation fails, or the controller holds no model                                                                 |
 
-Error messages are returned as plain text in the response body.
+A failed mandatory or validator check answers a JSON body with a `code` and the `fields` concerned (see [validators](./5.validators.md#error-handling)). Every other error the routes raise answers its message as text, such as `Missing id.` or `Not Found`.
 
-## Next Steps
+## Next steps
 
-See the [access rights documentation](./4.access-rights.md) to learn how to control field read/write permissions.
+The [access rights page](./4.access-rights.md) covers which fields each action reads and writes.