@antelopejs/interface-data-api 0.4.0 → 0.6.0

package/dist/tests/utils.test.js

@@ -5,22 +5,21 @@ const chai_1 = require("chai");
 const utils_1 = require("./utils");
 const WRAPPER_DEPTHS = [1, 2, 5, 20];
 describe("Test utils", () => {
-    it("returns the name of the calling function", () => returnsTheCallerName());
-    it("skips frames added outside the tests folder", () => skipsFramesAddedOutsideTheTestsFolder());
+    it("returns the name of the calling function", () => expectReturnsTheCallerName());
+    it("skips frames added outside the tests folder", () => expectSkipsFramesAddedOutsideTheTestsFolder());
 });
-function returnsTheCallerName() {
-    (0, chai_1.expect)((0, utils_1.getFunctionName)()).to.equal("returnsTheCallerName");
+function expectReturnsTheCallerName() {
+    (0, chai_1.expect)((0, utils_1.getFunctionName)()).to.equal("expectReturnsTheCallerName");
 }
 function nameSeenThroughAsyncContexts(depth) {
     const storage = new node_async_hooks_1.AsyncLocalStorage();
-    const run = storage.run.bind(storage);
-    const nestedRuns = Array.from({ length: depth - 1 }, (_, store) => [
-        run,
-        store,
-    ]).flat();
-    return run(depth, ...nestedRuns, utils_1.getFunctionName);
+    let read = utils_1.getFunctionName;
+    for (let store = 0; store < depth; store++) {
+        read = storage.run.bind(storage, store, read);
+    }
+    return read();
 }
-function skipsFramesAddedOutsideTheTestsFolder() {
+function expectSkipsFramesAddedOutsideTheTestsFolder() {
     for (const depth of WRAPPER_DEPTHS) {
         (0, chai_1.expect)(nameSeenThroughAsyncContexts(depth)).to.equal("nameSeenThroughAsyncContexts");
     }

package/dist/tests/utils.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.test.js","sourceRoot":"","sources":["../../src/tests/utils.test.ts"],"names":[],"mappings":";;AAAA,uDAAqD;AACrD,+BAA8B;AAE9B,mCAA0C;AAI1C,MAAM,cAAc,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AAErC,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC7E,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE,CACrD,qCAAqC,EAAE,CAAC,CAAC;AAC7C,CAAC,CAAC,CAAC;AAEH,SAAS,oBAAoB;IAC3B,IAAA,aAAM,EAAC,IAAA,uBAAe,GAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;AAC7D,CAAC;AAED,SAAS,4BAA4B,CAAC,KAAa;IACjD,MAAM,OAAO,GAAG,IAAI,oCAAiB,EAAU,CAAC;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAa,CAAC;IAClD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACjE,GAAG;QACH,KAAK;KACN,CAAC,CAAC,IAAI,EAAE,CAAC;IACV,OAAO,GAAG,CAAC,KAAK,EAAE,GAAG,UAAU,EAAE,uBAAe,CAAC,CAAC;AACpD,CAAC;AAED,SAAS,qCAAqC;IAC5C,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,IAAA,aAAM,EAAC,4BAA4B,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAClD,8BAA8B,CAC/B,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"utils.test.js","sourceRoot":"","sources":["../../src/tests/utils.test.ts"],"names":[],"mappings":";;AAAA,uDAAqD;AACrD,+BAA8B;AAE9B,mCAA0C;AAI1C,MAAM,cAAc,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AAErC,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE,CAClD,0BAA0B,EAAE,CAAC,CAAC;IAChC,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE,CACrD,2CAA2C,EAAE,CAAC,CAAC;AACnD,CAAC,CAAC,CAAC;AAEH,SAAS,0BAA0B;IACjC,IAAA,aAAM,EAAC,IAAA,uBAAe,GAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,4BAA4B,CAAC,KAAa;IACjD,MAAM,OAAO,GAAG,IAAI,oCAAiB,EAAU,CAAC;IAChD,IAAI,IAAI,GAAe,uBAAe,CAAC;IACvC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3C,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAKrB,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,IAAI,EAAE,CAAC;AAChB,CAAC;AAED,SAAS,2CAA2C;IAClD,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,IAAA,aAAM,EAAC,4BAA4B,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAClD,8BAA8B,CAC/B,CAAC;IACJ,CAAC;AACH,CAAC"}

package/docs/1.introduction.md

@@ -1,21 +1,27 @@
-# Expose database records through an API
+---
+title: Expose database records through an API
+description: Build a first data controller that serves CRUD routes for a users table, then check which fields it reads and writes.
+mode: tutorial
+---
 
 ## Overview
 
-Use `@antelopejs/interface-data-api` to expose a table through named CRUD routes and an explicit field policy. A data controller connects the table model to HTTP handlers; its metadata decides which fields clients may read, write, list, and filter.
+In this tutorial, we expose a `users` table through five CRUD routes with `@antelopejs/interface-data-api`. A data controller connects the table model to HTTP handlers. Its metadata decides which fields clients can read, write, list and filter.
 
 ## Build one resource first
 
-1. **Prepare the database.** Define a table and register its schema with database-decorators. Your AntelopeJS module needs a database provider and an API provider.
-2. **Choose the routes.** Start with the [route set](./3.routes.md) your clients need, rather than exposing every write operation by default.
-3. **Set the field policy.** Add [access rights](./4.access-rights.md), [validators](./5.validators.md), and [list fields](./6.listable.md). Field permissions are not user authentication or row-level authorization.
-4. **Check one read and one rejected write.** Confirm the response excludes private fields and that invalid input cannot reach storage. Then add [relationships](./7.foreign-keys.md) and [filters](./8.filters.md).
+We build one resource in four steps.
 
-## Quick Start
+1. **Prepare the database.** Define a table and register its schema with database-decorators. The AntelopeJS project needs a database module and an API module.
+2. **Choose the routes.** Start with the [route set](./3.routes.md) your clients need, instead of exposing every write route by default.
+3. **Set the field policy.** Add [access rights](./4.access-rights.md), [validators](./5.validators.md) and [list fields](./6.listable.md). Field permissions do not authenticate users and do not authorize access to rows.
+4. **Check one read and one rejected write.** Confirm that the response leaves out private fields and that invalid input never reaches storage. Then add [relationships](./7.foreign-keys.md) and [filters](./8.filters.md).
 
-The following example declares all five CRUD routes for a `users` table. It assumes a configured provider and an existing `my-database` instance. Import the table declaration before calling `await RegisterSchema("myapp")` in the declaring module's initialization; await that setup before serving requests.
+## Quick start
 
-This is a field-policy example, not a production account system: write-only prevents a password from appearing in responses, but does not hash it or authenticate requests. Add an appropriate [database modifier](./9.modifiers.md) and your authentication policy before accepting real credentials.
+The example declares all five CRUD routes for a `users` table. It assumes a configured database module and an existing `my-database` instance. Import the table declaration, then `await RegisterSchema("myapp")` when the declaring module initializes. Wait for that setup to finish before the module serves requests.
+
+This example sets a field policy. It is not a production account system. `AccessMode.WriteOnly` keeps the password out of responses, but it does not hash the password or authenticate requests. Add a [database modifier](./9.modifiers.md) and your authentication policy before you accept real credentials.
 
 ```ts docs-check
 import { Controller } from "@antelopejs/interface-api";
@@ -40,7 +46,6 @@ import {
   Table,
 } from "@antelopejs/interface-database-decorators";
 
-// Define the database table
 @RegisterTable("users", "myapp")
 class User extends Table {
   @Field("string")
@@ -57,10 +62,8 @@ class User extends Table {
   declare password: string;
 }
 
-// Create the database model
 class UserModel extends BasicDataModel(User, "users") {}
 
-// Create the data controller
 @RegisterDataController()
 class UserAPI extends DataController(
   User,
@@ -91,38 +94,38 @@ class UserAPI extends DataController(
 }
 ```
 
-This generates the following REST endpoints:
+The controller serves these REST endpoints.
 
-| Method | Endpoint                | Description                |
-| ------ | ----------------------- | -------------------------- |
-| GET    | `/users/get?id=<id>`    | Retrieve a single user     |
-| GET    | `/users/list?limit=10`  | List users with pagination |
-| POST   | `/users/new`            | Create a new user          |
-| PUT    | `/users/edit?id=<id>`   | Update an existing user    |
-| DELETE | `/users/delete?id=<id>` | Delete a user              |
+| Method | Endpoint                | Description          |
+| ------ | ----------------------- | -------------------- |
+| GET    | `/users/get?id=<id>`    | Read one user        |
+| GET    | `/users/list?limit=10`  | List users, one page |
+| POST   | `/users/new`            | Create a user        |
+| PUT    | `/users/edit?id=<id>`   | Update a user        |
+| DELETE | `/users/delete?id=<id>` | Delete a user        |
 
 ### Check the field policy
 
-Use disposable data and your configured API base URL. Create a user with `name`, `email`, and a dummy `password`; the response is an array of inserted IDs. Use the first ID for the following checks:
+Use disposable data and the base URL of your API module. First, create a user with `POST /users/new` and a body that holds `name`, `email` and a dummy `password`. The response is the created user, with its `_id` and without `password`. Use that `_id` in the next checks.
 
-1. `GET /users/get?id=<id>` returns the readable fields, never `password`.
-2. `GET /users/list?limit=10` includes `_id`, `name`, and `email` in `results`.
-3. `PUT /users/edit?id=<id>` with `{ "name": "Updated" }` preserves the omitted email. With `{ "email": "" }`, it returns `400` because email is mandatory on edit.
+1. `GET /users/get?id=<id>` returns the readable fields. You see `_id`, `email` and `name`, and never `password`.
+2. `GET /users/list?limit=10` returns `_id`, `name` and `email` for each entry of `results`.
+3. `PUT /users/edit?id=<id>` with `{ "name": "Updated" }` keeps the email you did not send. With `{ "email": "" }`, the route answers `400`, because `email` is mandatory on `edit`.
 
-`@Mandatory` does not check email syntax or password strength. Add [validators](./5.validators.md) before accepting untrusted input.
+`@Mandatory` does not check the email syntax or the password strength. Add [validators](./5.validators.md) before you accept untrusted input.
 
 ## Core guides
 
-- [Data Controllers](./2.data-controllers.md) - Create and configure data controllers
-- [Routes](./3.routes.md) - Default routes, custom routes, and route options
-- [Access Rights](./4.access-rights.md) - Control field read/write permissions
-- [Validators](./5.validators.md) - Field-level validation and mandatory fields
-- [Listable Fields](./6.listable.md) - Pagination, pluck modes, and sorting
+- [Data controllers](./2.data-controllers.md). Create and configure data controllers.
+- [Routes](./3.routes.md). Default routes, custom routes and route options.
+- [Access rights](./4.access-rights.md). Which fields each action reads and writes.
+- [Validators](./5.validators.md). Field validation and mandatory fields.
+- [Listable fields](./6.listable.md). Pagination, pluck modes and sorting.
 
 ## Relationships and advanced queries
 
-- [Foreign Keys](./7.foreign-keys.md) - Establish relationships between tables
-- [Filters](./8.filters.md) - Add filtering capabilities to list endpoints
-- [Modifiers](./9.modifiers.md) - Automatic data transformation with database-decorators
-- [Joined Fields](./10.joined.md) - Flatten a remote field onto rows for native sort/filter
-- [Computed Fields](./11.computed.md) - In-database computed values, sortable and pageable natively
+- [Foreign keys](./7.foreign-keys.md). Relations between tables.
+- [Filters](./8.filters.md). Filters on list endpoints.
+- [Modifiers](./9.modifiers.md). Data transformation with database-decorators modifiers.
+- [Joined fields](./10.joined.md). A remote field flattened onto each row, sortable and filterable in the database.
+- [Computed fields](./11.computed.md). Values computed in the database, sortable and pageable there.

package/docs/10.joined.md

@@ -1,18 +1,22 @@
-# Joined Fields
+---
+title: Joined fields
+description: Flatten one field of another table onto each row with @Joined, so list requests sort and filter on it in the database.
+mode: reference
+---
 
 ## Overview
 
-The `@Joined` decorator imports a single scalar field from another table and flattens it onto each row at query time. Unlike `@Foreign`, which embeds the full referenced record as a nested object in the response, `@Joined` copies one remote field to the top level of the row before sorting and filtering are applied. This makes the joined field natively sortable, filterable, and searchable in the database.
+The `@Joined` decorator copies one scalar field from another table onto each row at query time. `@Foreign` nests the whole referenced record under the field. `@Joined` puts one remote field at the top level of the row, before the list query sorts and filters. The database can therefore sort, filter, and search on the joined field.
 
-Joined fields are read-only: the value is set by a lookup at query time and is never persisted on the controller's own table. Declaring a field as joined automatically sets its access mode to read-only and forces non-indexed sorting.
+Joined fields are meant to be read-only. A lookup sets the value at query time, and the controller's own table never stores it. `@Joined` sets the field's access mode to read-only when it runs. An `@Access` written above it runs later and replaces that mode, so do not combine the two. `@Joined` also makes the field's sort non-indexed, whatever the decorator order.
 
-## Basic Usage
+## Basic usage
 
-Apply `@Joined` to a field that should be populated from a remote table. The local row must carry a foreign key (`localKey`) that matches the remote table's `remoteIndex`.
+Apply `@Joined` to a field that takes its value from a remote table. The local row must hold a key (`localKey`) that matches the remote table's `remoteIndex`.
 
-Use [foreign keys](./7.foreign-keys.md) when the response needs a nested record instead. The snippets below assume the controller imports and model from the [quick start](./1.introduction.md#quick-start), with `myapp` registered before requests are served.
+Use [foreign keys](./7.foreign-keys.md) when the response needs a nested record instead. The snippets below assume the controller imports and the model from the [quick start](./1.introduction.md#quick-start), with `myapp` registered before the module serves requests.
 
-```typescript
+```typescript fragment
 import { Joined } from "@antelopejs/interface-data-api/metadata";
 import {
   Field,
@@ -84,25 +88,27 @@ A GET request to `/orders/get?id=order-123` returns the joined value at the top
 }
 ```
 
-## Decorator Parameters
+## Decorator parameters
 
-```typescript
+```typescript fragment
 @Joined({ table, localKey, remoteField, remoteIndex?, schema? })
 ```
 
 | Option        | Type                       | Required | Default           | Description                                                                                        |
 | ------------- | -------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------- |
-| `table`       | `Class<Table>` or `string` | Yes      | -                 | The remote table class or registered table name string                                             |
-| `localKey`    | `string`                   | Yes      | -                 | The field on the local row holding the value matched against the remote table                      |
-| `remoteField` | `string`                   | Yes      | -                 | The remote field whose value is flattened onto the row                                             |
+| `table`       | `Class<Table>` or `string` | Yes      | None              | The remote table class or registered table name string                                             |
+| `localKey`    | `string`                   | Yes      | None              | The field on the local row holding the value matched against the remote table                      |
+| `remoteField` | `string`                   | Yes      | None              | The remote field whose value is flattened onto the row                                             |
 | `remoteIndex` | `string`                   | No       | `"_id"`           | The index on the remote table to match `localKey` against                                          |
 | `schema`      | `string`                   | No       | Controller schema | Name of the schema the remote table is registered in, when it differs from the controller's schema |
 
-## Sorting and Filtering
+When a list mode includes a joined field, the mode also selects the field's `localKey`.
 
-Because the join is applied to the underlying query before sorting and filtering, joined fields behave like native columns. Combine `@Joined` with `@Sortable` or `@Filter` to order or filter by the imported value.
+## Sorting and filtering
 
-```typescript
+The list query applies the join before it sorts and filters, so a joined field behaves like a stored column. Combine `@Joined` with `@Sortable` or `@Filter` to sort or filter on the joined value.
+
+```typescript fragment
 @Sortable()
 @Filter()
 @Joined({
@@ -113,30 +119,35 @@ Because the join is applied to the underlying query before sorting and filtering
 declare userName: string;
 ```
 
-Joined fields are always sorted without a database index (`@Sortable` is forced to non-indexed for them), since the value comes from a runtime lookup rather than a stored column.
+A joined field always sorts without a database index, because its value comes from a lookup at query time and not from a stored column. `@Sortable` on a joined field is always non-indexed.
 
-## Deferred Resolution on Lists
+## Deferred resolution on lists
 
-The default list route handles this scheduling for you. Continue with [cross-schema joins](#cross-schema-joins) unless you are building a custom route with `Query.List`.
+The default list route schedules the lookups itself. Skip to [cross-schema joins](#cross-schema-joins) unless you are building a custom route with `Query.List`.
 
-![Joined fields used by filters are resolved before counting; sort fields before paging; display-only fields after paging in the default list route.](./assets/joined-list.svg){width="480"}
+![Joined fields used by filters are resolved before counting; sort fields before paging; display-only fields after paging in the default list route.](./assets/joined-list.svg "illustration"){width="480"}
 
 ### Advanced: composing `Query.List`
 
-`Query.List` only materializes the joined groups that the request's sort or filters reference before the count. The remaining display-only groups are deferred: the returned stream resolves them itself as soon as an operation can observe them, so destructuring `[query, total]` alone always yields rows with every `@Joined` field resolved.
+`Query.List` resolves the joined fields that the request's filters read before it counts the rows. It resolves the joined fields that the sort reads after the count and before the sort. It defers the remaining display-only joined fields. The returned stream resolves them as soon as an operation can read rows, so destructuring `[query, total]` alone always gives rows with every `@Joined` field resolved.
 
-- Paging the stream (`slice`, `nth`) appends the lookups after the page boundary, so they only run on the returned rows.
-- A bare `count()` — and any field aggregate (`sum`, `min`, `distinct(field)`, ...) on a non-joined field — skips them entirely (left-join lookups never change the row count nor other fields).
-- `changes()` attaches to the raw stream, since change feeds cannot carry the join lookups.
-- Any other operation (`filter`, `orderBy`, `map`, ...) materializes them first, since it may read the joined values.
+- Paging the stream (`slice`, `nth`) adds the lookups after the page boundary, so they run only on the returned rows.
+- A bare `count()` skips the lookups, and so does a field aggregate such as `sum`, `min`, or `distinct(field)` on a field that is not joined. A left-join lookup never changes the row count or the other fields.
+- `changes()` attaches to the raw stream, because change feeds cannot carry the join lookups.
+- Any other operation, such as `filter`, `orderBy`, or `map`, resolves the lookups first, because it may read the joined values.
 
-The page-only benefit therefore holds as long as paging is the first thing the caller does. An operation applied to the whole stream before paging — a filter, a sort, or the `lookup` that `Query.Foreign` stages for a `@Foreign` field — materializes the joined groups over the whole matched set instead. The lookups still stay out of the count pipeline, but a caller that wants them strictly on the page must pass `{ exposeDeferredJoined: true }` to `Query.List` and resolve them itself after the slice: the raw stream is then returned unchanged and the third tuple element names the joined fields left to resolve with `Query.Joined`. This is what the default list route does, which also lets it limit the page lookups to the plucked fields.
+The lookups therefore run on the page only when paging is the first operation the caller applies. An operation on the whole stream before paging resolves the joined fields over the whole matched set. Such operations include a filter, a sort, and the `lookup` that `Query.Foreign` adds for a `@Foreign` field. The lookups still stay out of the count. A caller that wants them on the page only must pass `{ exposeDeferredJoined: true }` to `Query.List` and resolve them after the slice. `Query.List` then returns the raw stream unchanged, and the third tuple element names the joined fields to resolve with `Query.Joined`. The default list route works this way, which also lets it limit the page lookups to the plucked fields.
 
 ### Reading a page: `Query.ListPage`
 
-A custom list route over `Query.List` reads its page with `Query.ListPage` rather than chaining the steps itself. It slices the stream, then resolves on the page only, in this order: the deferred joined groups, the `@Computed` fields the filters and the sort did not already merge, the `@Foreign` relations (last, since a computed expression may read a relation's key), and the pluck.
+A custom list route over `Query.List` reads its page with `Query.ListPage` instead of chaining the steps itself. `Query.ListPage` slices the stream, then resolves these on the page only, in this order:
+
+1. The deferred joined fields.
+2. The `@Computed` fields that the filters and the sort did not already merge.
+3. The `@Foreign` relations. They come last because a computed expression may read a relation's key.
+4. The pluck.
 
-```typescript
+```typescript fragment
 const [query, total, deferredJoined] = Query.List(
   this,
   meta,
@@ -158,11 +169,11 @@ const rows = await Query.ListPage(model.database, meta, query, {
 });
 ```
 
-## Cross-Schema Joins
+## Cross-schema joins
 
-By default, the remote table is resolved in the same schema as the controller's table. Use the `schema` option to join against a table registered in a different schema; the join is resolved through the remote table's class, against the default instance of the schema `RegisterSchema` bound it to. The remote class must be registered with `@RegisterTable` before the field is declared; a string table name with no registered class in that schema throws at declaration.
+By default, the Data API looks for the remote table in the schema of the controller's table. The `schema` option joins a table registered in a different schema. The join goes through the remote table's class, against the default instance of the schema that `RegisterSchema` bound it to. Register the remote class with `@RegisterTable` before you declare the field. A string table name with no registered class in that schema throws at declaration.
 
-```typescript
+```typescript fragment
 @Joined({
   table: "users",
   localKey: "userId",
@@ -172,17 +183,17 @@ By default, the remote table is resolved in the same schema as the controller's
 declare userName: string;
 ```
 
-When a table class is passed, its schema is inferred from its `@RegisterTable` metadata. If both the class metadata and the explicit `schema` option specify a schema and they disagree, an error is thrown.
+When you pass a table class, the Data API reads its schema from its `@RegisterTable` metadata. If the class metadata and the `schema` option name different schemas, the declaration throws.
 
-## Joined vs. Foreign
+## `@Joined` compared with `@Foreign`
 
-| Aspect              | `@Joined`                                    | `@Foreign`                                                            |
-| ------------------- | -------------------------------------------- | --------------------------------------------------------------------- |
-| Result shape        | A single scalar value flattened onto the row | The full referenced record (or plucked subset) nested under the field |
-| Access              | Read-only (enforced)                         | Configurable via `@Access`                                            |
-| Sort / filter       | Native (join applied before sort/filter)     | Not natively sortable/filterable on remote fields                     |
-| Multiple references | One remote field per decorator               | Single or array (`multi`) references                                  |
+| Aspect              | `@Joined`                                       | `@Foreign`                                                                |
+| ------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
+| Result shape        | A single scalar value flattened onto the row    | The full referenced record, or its plucked fields, nested under the field |
+| Access              | Read-only, unless a later `@Access` replaces it | Set with `@Access`                                                        |
+| Sort and filter     | In the database, join applied before both       | No sort or filter on remote fields                                        |
+| Multiple references | One remote field per decorator                  | Single or array (`multi`) references                                      |
 
-## Next Steps
+## Next steps
 
-See the [computed fields documentation](./11.computed.md) to generalize this merge mechanism to arbitrary in-database expressions, or the [modifiers documentation](./9.modifiers.md) to learn how automatic data transformation integrates with the Data API.
+To merge any in-database expression onto rows, see [Computed fields](./11.computed.md). To see how modifiers transform data in the Data API, see [Modifiers](./9.modifiers.md).

package/docs/11.computed.md

@@ -1,19 +1,45 @@
-# Computed Fields
+---
+title: Computed fields
+description: Compute a field in the database with @Computed, from the row or from a per-row subquery, and sort, filter, and page on it.
+mode: reference
+---
 
 ## Overview
 
-The `@Computed` decorator declares a field whose value is computed in the database from an expression, then merged onto each row at query time. The expression can be a row-local computation (derived from other fields of the same row) or a per-row subquery, such as an aggregate over another table. Because the merge happens before sorting and filtering, computed fields are natively sortable, filterable, and pageable in DB — no fetch-all or in-memory sorting required.
+The `@Computed` decorator declares a field whose value the database computes from an expression and merges onto each row at query time. The expression can compute from other fields of the same row, or run a per-row subquery such as an aggregate over another table. The merge happens before the list query sorts and filters, so the database sorts, filters, and pages computed fields. The API never fetches every row or sorts in memory.
 
-Computed fields are read-only: the value is produced by the query and is never persisted on the controller's table. Declaring a field as computed automatically sets its access mode to read-only and forces non-indexed sorting, regardless of decorator order.
+Computed fields are meant to be read-only. The query produces the value, and the controller's table never stores it. `@Computed` sets the field's access mode to read-only when it runs. An `@Access` written above it runs later and replaces that mode, so do not combine the two. `@Computed` also makes the field's sort non-indexed, whatever the decorator order.
 
-## Basic Usage
+## Basic usage
 
-The expression receives the row proxy and the schema instance of the controller's table. It must return a value built from the query builder (`ValueProxy` operations or a subquery), not plain JavaScript computed at request time.
+The expression receives the row proxy and the schema instance of the controller's table. It must return a value built with the query builder (`ValueProxy` operations or a subquery), not plain JavaScript computed at request time.
 
-The snippets extend the [quick-start controller pattern](./1.introduction.md#quick-start); define `GroupModel` with `BasicDataModel(Group)` and register the `myapp` schema before serving requests. Check [driver support](#driver-support) before using aggregate subqueries.
+The example follows the [quick-start controller pattern](./1.introduction.md#quick-start). Register the `myapp` schema before the module serves requests. Check [driver support](#driver-support) before you use aggregate subqueries.
 
 ```typescript
-import { Computed } from "@antelopejs/interface-data-api/metadata";
+import { Controller } from "@antelopejs/interface-api";
+import {
+  DataController,
+  DefaultRoutes,
+  RegisterDataController,
+} from "@antelopejs/interface-data-api";
+import {
+  Access,
+  AccessMode,
+  Computed,
+  Listable,
+  ModelReference,
+  Sortable,
+} from "@antelopejs/interface-data-api/metadata";
+import {
+  BasicDataModel,
+  Field,
+  Index,
+  Model,
+  RegisterTable,
+  Relation,
+  Table,
+} from "@antelopejs/interface-database-decorators";
 
 @RegisterTable("groups", "myapp")
 class Group extends Table {
@@ -35,6 +61,8 @@ class Device extends Table {
   declare group_id: string;
 }
 
+class GroupModel extends BasicDataModel(Group, "groups") {}
+
 @RegisterDataController()
 class GroupAPI extends DataController(
   Group,
@@ -56,7 +84,11 @@ class GroupAPI extends DataController(
   // Aggregate: number of devices referencing this group, computed in DB
   @Listable()
   @Computed(
-    (row, db) => db.table("devices").getAll(row.key("_id"), "group_id").count(),
+    (row, db) =>
+      db
+        .table("devices")
+        .filter((device) => device.key("group_id").eq(row.key("_id")))
+        .count(),
     { default: 0 },
   )
   @Sortable()
@@ -64,11 +96,13 @@ class GroupAPI extends DataController(
 
   // Row-local expression
   @Listable()
-  @Computed((row) => (row.key("name") as ValueProxy<string>).concat("!"))
+  @Computed((row) => row.key("name").concat("!"))
   declare display_name: string;
 }
 ```
 
+The row proxy types every field as a `FieldValue`. The subquery compares each device's `group_id` with the row's `_id` through `eq`, which accepts that type. This filter checks every device for each row and does not use the `group_id` index. `getAll(row.key("_id"), "group_id")` would use the index, but `getAll` does not accept a row key typed as a `FieldValue`, so it compiles only with a cast.
+
 A GET request to `/groups/get?id=group-123` returns the computed values at the top level:
 
 ```json
@@ -80,69 +114,79 @@ A GET request to `/groups/get?id=group-123` returns the computed values at the t
 }
 ```
 
-## Decorator Parameters
+## Decorator parameters
 
-```typescript
+```typescript fragment
 @Computed(expr, options?)
 ```
 
-| Parameter         | Type                      | Required | Description                                                                                                           |
-| ----------------- | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
-| `expr`            | `(row, db) => expression` | Yes      | Expression receiving the row proxy and the schema instance; returns a `ValueProxy` expression or a subquery (`Datum`) |
-| `options.default` | `unknown`                 | No       | Fallback merged over the computed value when the expression yields `null`                                             |
+| Parameter         | Type                      | Required | Description                                                                                                                        |
+| ----------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `expr`            | `(row, db) => expression` | Yes      | Expression receiving the row proxy and the schema instance. Returns a `ValueProxy` expression, a subquery (`Query`), or a constant |
+| `options.default` | `FieldValue`              | No       | Fallback merged over the computed value when the expression yields `null`                                                          |
 
 ### The `default` option
 
-Aggregate subqueries yield `null` instead of their natural zero value when the underlying set is empty (a `count()` over a group with no devices returns `null`, not `0`). Calling `.default(0)` inside the subquery expression does not help: the aggregation produces no document at all, so there is nothing to apply the default to. The `options.default` value solves this by being applied at the row level, after the merge:
-
-```typescript
-@Computed((row, db) => db.table("devices").getAll(row.key("_id"), "group_id").count(), {
-  default: 0,
-})
+An aggregate subquery over an empty set yields `null` instead of its zero value. A `count()` over a group with no devices returns `null`, not `0`. Calling `.default(0)` inside the subquery expression does not help, because the aggregation produces no document to apply the default to. The `options.default` value works because the Data API applies it to the row, after the merge:
+
+```typescript fragment
+@Computed(
+  (row, db) =>
+    db
+      .table("devices")
+      .filter((device) => device.key("group_id").eq(row.key("_id")))
+      .count(),
+  { default: 0 },
+)
 declare devices_count: number;
 ```
 
-Without it, rows with an empty aggregate carry `null`, which breaks equality filters (`filter_devices_count=eq:0`) and makes sort ordering depend on BSON type ordering.
+Without it, a row with an empty aggregate holds `null`. An equality filter such as `filter_devices_count=eq:0` then misses the row, and the sort order depends on BSON type ordering.
 
-## Sorting, Filtering, and Pagination
+## Sorting, filtering, and pagination
 
-Computed fields combine with `@Sortable` and `@Filter` like native columns. The framework injects the computation lazily, only when and where the value is needed:
+Computed fields combine with `@Sortable` and `@Filter` like stored columns. The list query merges each computed field only where a step needs its value:
 
-- A computed field referenced by an active filter is merged before filters run.
-- A computed field used as the sort key is merged after the total count is captured and before the non-indexed `orderBy`, so the aggregate is not paid twice.
-- A computed field requested only for display (in the pluck, neither sorted nor filtered) is merged after pagination (`slice`), so it is computed only for the returned page, not the whole collection.
+- A computed field that an active filter reads is merged before the filters run.
+- A computed field used as the sort key is merged after the total count and before the non-indexed `orderBy`, so the count does not compute the aggregate.
+- A computed field requested only for display, in the pluck and neither sorted nor filtered, is merged after pagination (`slice`). The database computes it for the returned page only.
 
-Sorting and pagination both stay in the database: sorting by a computed aggregate with `limit`/`offset` produces correct pages and a constant `total`.
+Sorting and pagination both stay in the database. Sorting by a computed aggregate with `limit` and `offset` gives correct pages and the same `total` on every page.
 
-Computed fields are always sorted without a database index (`@Sortable` is forced to non-indexed), since the value does not exist as a stored column.
+A computed field always sorts without a database index, because its value is not a stored column. `@Sortable` on a computed field is always non-indexed.
 
 ### Filtering on numeric computed fields
 
-Filter values arrive as strings from the query string. Use the validated `numberFilter` from [Numeric and Boolean Filters](./8.filters.md#numeric-and-boolean-filters), imported into the controller file. It rejects invalid numbers and honors the requested comparison operator; `parseFloat` alone accepts partial input such as `"3devices"`.
-
-```typescript
-@Computed((row, db) => db.table("devices").getAll(row.key("_id"), "group_id").count(), {
-  default: 0,
-})
+Filter values arrive as strings from the query string. Import the validated `numberFilter` from [Numeric and boolean filters](./8.filters.md#numeric-and-boolean-filters) into the controller file. It rejects invalid numbers and applies the requested comparison operator. `parseFloat` alone accepts partial input such as `"3devices"`.
+
+```typescript fragment
+@Computed(
+  (row, db) =>
+    db
+      .table("devices")
+      .filter((device) => device.key("group_id").eq(row.key("_id")))
+      .count(),
+  { default: 0 },
+)
 @Filter(numberFilter, false)
 declare devices_count: number;
 ```
 
-## Computed vs. Joined
+## `@Computed` compared with `@Joined`
 
-| Aspect        | `@Computed`                                                     | `@Joined`                                                    |
-| ------------- | --------------------------------------------------------------- | ------------------------------------------------------------ |
-| Source        | Arbitrary expression: row-local computation or per-row subquery | One scalar field from another table matched by a foreign key |
-| Typical use   | Aggregates (`count`, `sum`), derived values                     | Flattening a referenced record's field                       |
-| Access        | Read-only (enforced)                                            | Read-only (enforced)                                         |
-| Sort / filter | Native, lazily injected only where needed                       | Native, always applied before sort/filter                    |
+| Aspect          | `@Computed`                                                      | `@Joined`                                                    |
+| --------------- | ---------------------------------------------------------------- | ------------------------------------------------------------ |
+| Source          | Any expression: a computation over the row or a per-row subquery | One scalar field from another table matched by a foreign key |
+| Typical use     | Aggregates (`count`, `sum`), derived values                      | Flattening a field of a referenced record                    |
+| Access          | Read-only, unless a later `@Access` replaces it                  | Read-only, unless a later `@Access` replaces it              |
+| Sort and filter | In the database, merged only where a step needs the value        | In the database, join applied before sort and filter         |
 
-`@Joined` remains the simpler choice for the 1:1 flattening case; `@Computed` generalizes the same merge mechanism to arbitrary expressions.
+For one field copied from one referenced record, `@Joined` is simpler. `@Computed` applies the same merge to any expression.
 
-## Driver Support
+## Driver support
 
-The aggregate form relies on the database driver translating a per-row subquery inside a merge into a correlated lookup (`$lookup` with `let`/`pipeline` on MongoDB). This is supported by `@antelopejs/mongodb` >= 1.2.1. Row-local expressions only use standard expression compilation and work on any driver.
+The aggregate form needs a database driver that turns a per-row subquery inside a merge into a correlated lookup. On MongoDB, the lookup is a `$lookup` with `let` and `pipeline`. The `@antelopejs/mongodb` changelog names the release that added this translation. Row-local expressions use standard expression compilation and work on any driver.
 
-## Next Steps
+## Next steps
 
-See the [joined fields documentation](./10.joined.md) for the dedicated 1:1 flattening decorator.
+For the decorator that copies one field from a referenced record, see [Joined fields](./10.joined.md).