@antelopejs/interface-data-api 0.5.0 → 0.6.1

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).

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.