@antelopejs/interface-data-api 0.4.0 → 0.6.0

package/docs/2.data-controllers.md

@@ -1,14 +1,18 @@
-# Data Controllers
+---
+title: Data controllers
+description: The DataController function, the RegisterDataController decorator, and the parts every data controller declares.
+mode: reference
+---
 
 ## Overview
 
-A data controller is the central building block of the Data API. It connects a database table to a set of API endpoints, exposing the table fields you declare on the class. The `DataController` function creates a base class that combines your table definition, route definitions, and controller path into a single cohesive unit.
+A data controller connects a database table to a set of API endpoints and exposes the table fields you declare on the class. The `DataController` function returns a base class built from three parts: the table class, the route definitions and the controller base that holds the endpoint path.
 
-## Create a Data Controller
+## Create a data controller
 
-Use the `DataController` function to define a new controller. It accepts three arguments: the table class, a route definition object, and a controller base with the endpoint path.
+`DataController` takes three arguments: the table class, a route definition object, and a controller base with the endpoint path.
 
-This example uses the `myapp` schema and the `my-database` instance. Import the table declaration and await `RegisterSchema("myapp")` in the declaring module before serving requests; provision the named instance through your database setup.
+The example uses the `myapp` schema and the `my-database` instance. Import the table declaration and await `RegisterSchema("myapp")` in the declaring module before it serves requests. Your database setup provisions the named instance.
 
 ```ts docs-check
 import { Controller } from "@antelopejs/interface-api";
@@ -31,7 +35,6 @@ import {
   Table,
 } from "@antelopejs/interface-database-decorators";
 
-// Define the database table
 @RegisterTable("users", "myapp")
 class User extends Table {
   @Field("string")
@@ -44,10 +47,8 @@ class User extends Table {
   declare age: number;
 }
 
-// Create the database model
 class UserModel extends BasicDataModel(User, "users") {}
 
-// Create the data controller
 @RegisterDataController()
 class UserAPI extends DataController(
   User,
@@ -71,50 +72,57 @@ class UserAPI extends DataController(
 }
 ```
 
-## `DataController` Signature
-
-```typescript
-DataController(
-  tableClass: typeof Table,  // Database table class
-  routes: DataControllerDef, // Route definitions (e.g., DefaultRoutes.All)
-  base: typeof Controller,   // Controller base with path
-)
+## `DataController` signature
+
+```typescript fragment
+function DataController<
+  C extends Class,
+  P extends DataControllerDef = DataControllerDef,
+  Base extends ControllerClass = ControllerClass,
+>(
+  tableClass: C,
+  def: P,
+  base: Base,
+): Class<ExtractDefCallbacks<P> & { table: InstanceType<C> }> & Base;
 ```
 
-| Parameter    | Description                                                                                                                       |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| `tableClass` | The database table class decorated with `@RegisterTable`. The controller validates that this table exists in the database schema. |
-| `routes`     | An object mapping endpoint names to route callbacks. Use `DefaultRoutes.All` for standard CRUD or pass a custom subset.           |
-| `base`       | The controller base, typically created with `Controller("/path")`, which sets the URL prefix for all endpoints.                   |
+| Parameter    | Description                                                                                                                                                                                                                   |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tableClass` | The table class decorated with `@RegisterTable`. `DataController` throws `Non-existent Database Schema` when the table's schema is not registered, and `Unregistered Database Table` when the schema does not hold the table. |
+| `def`        | An object that maps endpoint names to route callbacks. Use `DefaultRoutes.All` for the five CRUD routes, or pass a subset or custom routes.                                                                                   |
+| `base`       | The controller base, usually `Controller("/path")` from `@antelopejs/interface-api`. Its location is the URL prefix of every endpoint.                                                                                        |
+
+The returned class extends `base`. Its prototype holds one method per key of `def`, and its instances declare a `table` field typed by the table class.
 
-## Required Components
+## Required components
 
-Every data controller requires the following elements:
+Every data controller declares these four parts.
 
-1. **Table Class** - A database table decorated with `@RegisterTable`, defining the schema.
-2. **Route Definitions** - Which operations to expose. Use `DefaultRoutes.All` or a custom selection.
-3. **Controller Base** - The URL path prefix, created with `Controller("/path")`.
-4. **Model Reference** - A property decorated with `@ModelReference()` that holds a database model instance. This model provides the actual database operations (insert, get, update, delete). A controller derived from another data controller (for example `Controller("/path", ParentController)`) inherits its model reference unless it declares its own.
+1. **Table class.** A database table decorated with `@RegisterTable`, which defines the schema.
+2. **Route definitions.** The operations to expose. Use `DefaultRoutes.All` or a custom selection.
+3. **Controller base.** The URL path prefix, created with `Controller("/path")`.
+4. **Model reference.** A property decorated with `@ModelReference()` that holds a database model instance. The model runs the database operations (insert, get, update and delete). A controller derived from another data controller (for example `Controller("/path", ParentController)`) inherits its model reference unless it declares its own.
 
-## The `@RegisterDataController` Decorator
+## The `@RegisterDataController` decorator
 
-Apply `@RegisterDataController()` to the class to finalize the controller setup. This decorator processes all field decorators, registers the defined routes, and connects parameter providers to each endpoint.
+Apply `@RegisterDataController()` to the class to finish the controller setup. For each route of the definition, the decorator applies the route's parameter decorators, registers a prefix route that records the route entry on the request context, and registers the route method as the handler at `<controller location>/<endpoint>`.
 
-## Field Declarations
+## Field declarations
 
-Fields declared on the data controller class determine which database columns are exposed through the API. Each field can be annotated with decorators to control its behavior:
+The fields you declare on the data controller class decide which table fields the API exposes. Each field takes decorators that set its behaviour:
 
-- `@Access` - Set read/write permissions.
-- `@Listable` - Include the field in list responses.
-- `@Mandatory` - Require the field on specific operations.
-- `@Validator` - Attach a validation function.
-- `@Foreign` - Establish a foreign key relationship.
-- `@Joined` - Flatten a scalar field from another table onto the row.
-- `@Filter` - Enable filtering on the field.
-- `@Sortable` - Allow sorting by the field.
+- `@Access` sets read and write permissions.
+- `@Listable` includes the field in list responses.
+- `@Mandatory` requires the field on specific operations.
+- `@Validator` attaches a validation function.
+- `@Foreign` declares a foreign key relationship.
+- `@Joined` flattens a scalar field from another table onto the row.
+- `@Computed` adds a value the database computes for each row.
+- `@Filter` enables filtering on the field.
+- `@Sortable` allows sorting by the field.
 
-Fields without any decorator are ignored by the Data API and do not appear in API responses or accept input.
+The Data API ignores a field without an access mode. Such a field never appears in responses and never accepts input. `@Access` gives a field its mode, and `@Joined` and `@Computed` make their field read-only.
 
-## Next Steps
+## Next steps
 
-See the [routes documentation](./3.routes.md) to learn about available routes and how to customize them.
+The [routes page](./3.routes.md) lists the available routes and how to customize them.

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`
-
-**Query Parameters:**
+Reads one record by its identifier. The endpoint is `GET /resource/get`.
 
-| Parameter | Required | Description       |
-| --------- | -------- | ----------------- |
-| `id`      | Yes      | Record identifier |
+| Query 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`
-
-**Query Parameters:**
+Reads one page of records, with sorting and filtering. The endpoint is `GET /resource/list`.
 
-| 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.
+Updates a record by its identifier. The endpoint is `PUT /resource/edit`.
 
-**Endpoint:** `PUT /resource/edit`
+| Query parameter | Required | Description       |
+| --------------- | -------- | ----------------- |
+| `id`            | Yes      | Record identifier |
 
-**Query Parameters:**
-
-| 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.
+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.
 
-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`.
-
-**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.
-
-**Endpoint:** `DELETE /resource/delete`
+Deletes one or more records by their identifiers. The endpoint is `DELETE /resource/delete`.
 
-**Query Parameters:**
+| Query parameter | Required | Description                                                                         |
+| --------------- | -------- | ----------------------------------------------------------------------------------- |
+| `id`            | Yes      | Record identifier. Repeat the `id` parameter to delete several records in one call. |
 
-| 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,49 +229,58 @@ 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`, 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 { DefaultRoutes } from "@antelopejs/interface-data-api";
+import {
+  DefaultRoutes,
+  type DataControllerInstance,
+} from "@antelopejs/interface-data-api";
 import {
   type Parameters,
   Validation,
@@ -302,7 +290,7 @@ import type { RequestContext } from "@antelopejs/interface-api";
 const stampedNew = {
   ...DefaultRoutes.New,
   func: function (
-    this: unknown,
+    this: DataControllerInstance,
     ctx: RequestContext,
     params: Parameters.NewParameters,
     body: Buffer,
@@ -314,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";
@@ -324,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");
   },
 );
@@ -335,28 +323,28 @@ const routes = {
 };
 ```
 
-The `GetGuard` callback receives `(ctx, current, params)`. Declare it as a regular function to access the controller through `this`.
+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,
@@ -387,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.