@antelopejs/interface-data-api 0.2.2 → 0.3.0

package/docs/10.joined.md

@@ -10,19 +10,19 @@ Joined fields are read-only: the value is set by a lookup at query time and is n
 
 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`.
 
+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.
+
 ```typescript
 import { Joined } from "@antelopejs/interface-data-api/metadata";
 import {
   Field,
-  Index,
   RegisterTable,
   Relation,
   Table,
 } from "@antelopejs/interface-database-decorators";
 
-@RegisterTable("users")
+@RegisterTable("users", "myapp")
 class User extends Table {
-  @Index({ primary: true })
   @Field("string")
   declare _id: string;
 
@@ -30,9 +30,8 @@ class User extends Table {
   declare name: string;
 }
 
-@RegisterTable("orders")
+@RegisterTable("orders", "myapp")
 class Order extends Table {
-  @Index({ primary: true })
   @Field("string")
   declare _id: string;
 
@@ -118,6 +117,12 @@ Joined fields are always sorted without a database index (`@Sortable` is forced
 
 ## 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`.
+
+![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"}
+
+### 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.
 
 - Paging the stream (`slice`, `nth`) appends the lookups after the page boundary, so they only run on the returned rows.
@@ -127,6 +132,32 @@ Joined fields are always sorted without a database index (`@Sortable` is forced
 
 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.
 
+### 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.
+
+```typescript
+const [query, total, deferredJoined] = Query.List(
+  this,
+  meta,
+  model.table,
+  ctx,
+  [params.sortKey, params.sortDirection],
+  params.filters,
+  model.database,
+  { exposeDeferredJoined: true },
+);
+const rows = await Query.ListPage(model.database, meta, query, {
+  offset: params.offset ?? 0,
+  limit: params.limit ?? 10,
+  filters: params.filters,
+  sortKey: params.sortKey,
+  pluck, // Set of field names; every field when unset
+  noForeign: params.noForeign,
+  deferredJoined,
+});
+```
+
 ## 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.

package/docs/11.computed.md

@@ -10,10 +10,12 @@ Computed fields are read-only: the value is produced by the query and is never p
 
 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 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.
+
 ```typescript
 import { Computed } from "@antelopejs/interface-data-api/metadata";
 
-@RegisterTable("groups")
+@RegisterTable("groups", "myapp")
 class Group extends Table {
   @Field("string")
   declare _id: string;
@@ -22,7 +24,7 @@ class Group extends Table {
   declare name: string;
 }
 
-@RegisterTable("devices")
+@RegisterTable("devices", "myapp")
 class Device extends Table {
   @Field("string")
   declare _id: string;
@@ -116,15 +118,13 @@ Computed fields are always sorted without a database index (`@Sortable` is force
 
 ### Filtering on numeric computed fields
 
-Filter values arrive as strings from the query string. The default filter compares them as-is, which never matches a numeric computed value (`"0"` is not `0` in BSON). Provide a custom filter function that coerces the value:
+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((_context, proxy, _key, value) =>
-  (proxy as ValueProxy<number>).eq(parseFloat(value)),
-)
+@Filter(numberFilter, false)
 declare devices_count: number;
 ```
 

package/docs/2.data-controllers.md

@@ -8,7 +8,9 @@ A data controller is the central building block of the Data API. It connects a d
 
 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.
 
-```typescript
+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.
+
+```ts docs-check
 import { Controller } from "@antelopejs/interface-api";
 import {
   DataController,
@@ -24,16 +26,14 @@ import {
 import {
   BasicDataModel,
   Field,
-  Index,
   Model,
   RegisterTable,
   Table,
 } from "@antelopejs/interface-database-decorators";
 
 // Define the database table
-@RegisterTable("users")
+@RegisterTable("users", "myapp")
 class User extends Table {
-  @Index({ primary: true })
   @Field("string")
   declare _id: string;
 

package/docs/3.routes.md

@@ -138,10 +138,14 @@ Content-Type: application/json
 }
 ```
 
-**Response:**
+**Response:** the created record, as [Get](#get) answers it, with its `_id` even when `get` does not read it.
 
 ```json
-["user-789"]
+{
+  "_id": "user-789",
+  "name": "Bob",
+  "email": "bob@example.com"
+}
 ```
 
 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`.
@@ -184,10 +188,14 @@ Content-Type: application/json
 }
 ```
 
-**Response:**
+**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.
 
-```http
-200 OK
+```json
+{
+  "_id": "user-123",
+  "name": "Robert",
+  "email": "robert@example.com"
+}
 ```
 
 Before updating, the `update` event is triggered on any table modifiers attached to the database table.
@@ -264,7 +272,7 @@ class UserAPI extends DataController(User, routes, Controller("/users")) {
 | `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, FilterValue>` | Mandatory filters merged with request filters; route field keys win (see [filters](./8.filters.md#mandatory-route-filters)). |
+| `filters`   | `Record<string, FieldFilter>` | Mandatory filters merged with request filters; route field keys win (see [filters](./8.filters.md#mandatory-route-filters)). |
 
 **New:**
 
@@ -279,6 +287,33 @@ class UserAPI extends DataController(User, routes, Controller("/users")) {
 | `index`       | `string` | Use a secondary index instead of the primary key |
 | `noMandatory` | `string` | Skip mandatory field validation                  |
 
+## 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.
+
+```ts docs-check
+import { DefaultRoutes } from "@antelopejs/interface-data-api";
+import {
+  type Parameters,
+  Validation,
+} from "@antelopejs/interface-data-api/components";
+import type { RequestContext } from "@antelopejs/interface-api";
+
+const stampedNew = {
+  ...DefaultRoutes.New,
+  func: function (
+    this: unknown,
+    ctx: RequestContext,
+    params: Parameters.NewParameters,
+    body: Buffer,
+  ) {
+    const parsed = Validation.ParseBody(body);
+    parsed.source = "import";
+    return DefaultRoutes.New.func.call(this, ctx, params, parsed);
+  },
+};
+```
+
 ## 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.
@@ -300,9 +335,22 @@ const routes = {
 };
 ```
 
-The `GetGuard` callback receives `(ctx, current, params)` and runs with the controller as `this` when declared as a regular function. `ctx` is the request context, `current` is the loaded model including non-readable fields and the normal Get joined/computed/foreign data, and `params` is `Parameters.GetParameters`. Treat `current` as read-only: it is not the response DTO and is not frozen by the API.
+The `GetGuard` callback receives `(ctx, current, params)`. Declare it as a regular function to access the controller through `this`.
+
+| 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.                     |
+
+Treat `current` as read-only: it is not the response DTO and the API does not freeze it.
+
+Keep these boundaries when writing a guard:
 
-Throw an `HTTPResult` (or use `assert`) to deny the read. A normal return permits it; returning `false` is not a denial mechanism. Missing records return `404` without invoking the guard. The guard does not issue a second read, does not change field-access rules, and applies only to the route using it, not list/edit/delete routes.
+- **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.
 
 ## Custom Routes
 

package/docs/4.access-rights.md

@@ -4,6 +4,19 @@
 
 The `@Access` decorator controls how fields are read and written through the API. Each field can be set to read-only, write-only, or read-write, providing fine-grained control over data exposure. Access modes can also be overridden on a per-action basis, allowing different permissions for `get`, `list`, `new`, and `edit` operations.
 
+## Separate field policy from caller permissions
+
+`@Access` answers “may this action read or write this field?”, not “may this user access this record?”. Authenticate the caller and apply record-level policy separately. A write-only password is hidden from responses, but this decorator does not hash it.
+
+Build the field policy in this order:
+
+1. Set `@Access` for each public field. Undecorated fields remain private.
+2. Add action overrides for differences between creation and editing.
+3. Add `@Listable` for the fields selected by list responses; readable alone does not define a list projection.
+4. Add validators and mandatory-field rules for writable inputs.
+
+For example, a display name can be readable and writable, an ID readable only, and a password writable only. Test each direction: attempting to write a read-only field is ignored, while omitting a mandatory writable field is a validation concern.
+
 ## Access Modes
 
 The `AccessMode` enum defines three permission levels:
@@ -12,11 +25,11 @@ The `AccessMode` enum defines three permission levels:
 import { Access, AccessMode } from "@antelopejs/interface-data-api/metadata";
 ```
 
-| Mode                   | Value | Description                                                                   |
-| ---------------------- | ----- | ----------------------------------------------------------------------------- |
-| `AccessMode.ReadOnly`  | `1`   | Field appears in GET and LIST responses but is ignored in POST and PUT bodies |
-| `AccessMode.WriteOnly` | `2`   | Field is accepted in POST and PUT bodies but never appears in responses       |
-| `AccessMode.ReadWrite` | `3`   | Field is both readable and writable                                           |
+| Mode                   | Value | Description                                                                                         |
+| ---------------------- | ----- | --------------------------------------------------------------------------------------------------- |
+| `AccessMode.ReadOnly`  | `1`   | Field is readable; list responses also require selection by the pluck mode. POST and PUT ignore it. |
+| `AccessMode.WriteOnly` | `2`   | Field is accepted in POST and PUT bodies but never appears in responses                             |
+| `AccessMode.ReadWrite` | `3`   | Field is both readable and writable                                                                 |
 
 ## Basic Usage
 
@@ -105,6 +118,8 @@ The `@Access` decorator accepts an optional second argument to override the acce
 
 The `overrides` object maps action names (`"get"`, `"list"`, `"new"`, `"edit"`) to an `AccessMode` value. Actions not listed in the overrides use the default mode.
 
+To read the access a field has in one action, outside the routes (to render a form read-only on edit, for example), call `GetEffectiveMode(field, action)` from `@antelopejs/interface-data-api/metadata` with the field's metadata (`meta.fields[name]`). It is the mode the routes apply.
+
 ### Example: Writable on Create, Read-Only on Edit
 
 ```typescript
@@ -141,7 +156,7 @@ In this configuration:
 
 ## Fields Without `@Access`
 
-Fields declared without the `@Access` decorator are not exposed through the API at all. They do not appear in responses and are not accepted in request bodies. To include a field in the API, you must explicitly set its access mode.
+Ordinary fields need `@Access` to appear in responses or accept input; `@Listable` alone does not grant access. The derived-field decorators [`@Joined`](./10.joined.md) and [`@Computed`](./11.computed.md) are exceptions: they set read-only access themselves.
 
 ## Next Steps
 

package/docs/5.validators.md

@@ -118,6 +118,8 @@ declare appointmentDate: string;
 
 ### Async Validation
 
+An asynchronous lookup can give early feedback, but a check followed by an insert is not a uniqueness guarantee: concurrent requests can both pass. Enforce uniqueness in the database where supported, and handle write conflicts. `lookupByEmail` below is an application-supplied function.
+
 ```typescript
 // Check uniqueness against the database
 @Validator(async (value) => {

package/docs/6.listable.md

@@ -224,13 +224,13 @@ class UserAPI extends DataController(
 
 ### The `noIndex` Option
 
-By default, `@Sortable()` assumes the field has a database index and uses indexed ordering. Set `noIndex: true` when the field is not indexed, so the framework performs an in-memory sort instead.
+By default, `@Sortable()` marks the field for indexed ordering. Set `noIndex: true` when it is not indexed. Both paths build an AQL `orderBy` operation; this option changes where sorting is staged, not whether rows are sorted in application memory. The provider determines how the database executes that ordering.
 
 ```typescript
 @Sortable()                    // Uses database index for sorting
 declare _id: string;
 
-@Sortable({ noIndex: true })   // In-memory sort, no index required
+@Sortable({ noIndex: true })   // Non-indexed query ordering
 declare name: string;
 ```
 

package/docs/7.foreign-keys.md

@@ -8,19 +8,21 @@ The `@Foreign` decorator establishes relationships between database tables in yo
 
 Apply `@Foreign` to a field that stores a foreign key value. The decorator replaces the raw ID in the response with the full referenced record.
 
+Choose the response fields explicitly with `pluck`. A foreign lookup reads the target table, not its API controller: do not rely on the target controller's `@Access` policy to hide passwords or internal fields. The example below selects only the user's ID, name, and email.
+
+The snippets use the `myapp` schema. Register it in the declaring module before serving requests, as in the [quick start](./1.introduction.md#quick-start). Controller snippets assume the corresponding model and shared imports are already declared.
+
 ```typescript
 import { Foreign } from "@antelopejs/interface-data-api/metadata";
 import {
   Field,
-  Index,
   RegisterTable,
   Relation,
   Table,
 } from "@antelopejs/interface-database-decorators";
 
-@RegisterTable("users")
+@RegisterTable("users", "myapp")
 class User extends Table {
-  @Index({ primary: true })
   @Field("string")
   declare _id: string;
 
@@ -31,9 +33,8 @@ class User extends Table {
   declare email: string;
 }
 
-@RegisterTable("orders")
+@RegisterTable("orders", "myapp")
 class Order extends Table {
-  @Index({ primary: true })
   @Field("string")
   declare _id: string;
 
@@ -61,7 +62,7 @@ class OrderAPI extends DataController(
 
   @Listable()
   @Access(AccessMode.ReadOnly)
-  @Foreign(User)
+  @Foreign(User, undefined, false, ["_id", "name", "email"])
   declare userId: User;
 
   @Listable()
@@ -125,9 +126,8 @@ When a field stores an array of foreign key IDs, set the `multi` parameter to `t
 The table-level `@Relation({ many: true })` is declarative metadata recording that the field holds multiple target keys; API-side resolution is controlled solely by the `multi` parameter of `@Foreign`.
 
 ```typescript
-@RegisterTable("carts")
+@RegisterTable("carts", "myapp")
 class Cart extends Table {
-  @Index({ primary: true })
   @Field("string")
   declare _id: string;
 
@@ -136,9 +136,8 @@ class Cart extends Table {
   declare items: string[]; // Array of CartItem IDs
 }
 
-@RegisterTable("cart_items")
+@RegisterTable("cart_items", "myapp")
 class CartItem extends Table {
-  @Index({ primary: true })
   @Field("string")
   declare _id: string;
 

package/docs/8.filters.md

@@ -81,6 +81,14 @@ Combine multiple filters:
 GET /users/list?filter_status=active&filter_role=ne:admin
 ```
 
+Filter one field several times to keep the rows that pass every filter (AND):
+
+```http
+GET /users/list?filter_age=ge:18&filter_age=lt:65
+```
+
+The route receives that field's filters as a list of `FilterValue` tuples (`FieldFilter`); a field filtered once keeps a single tuple. Read either shape with `FilterValuesOf(filter)` from `@antelopejs/interface-data-api/metadata`. An indexed equality filter only uses its index when it is the field's only filter.
+
 ### Numeric and Boolean Filters
 
 Parse and validate values explicitly in a custom filter. These filters support the six numeric comparisons and boolean equality/inequality; unsupported input throws an HTTP 400 response.
@@ -148,14 +156,14 @@ type FilterFunction<T, U> = (
 ) => ValueProxyOrValue<boolean>;
 ```
 
-| Parameter | Description                                                                                                    |
-| --------- | -------------------------------------------------------------------------------------------------------------- |
-| `context` | The request context, extended with `this` referencing the controller instance                                  |
-| `proxy`   | A `ValueProxy` representing the field value with modifier transformations applied (e.g., decrypted, localized) |
-| `key`     | The field name being filtered                                                                                  |
-| `value`   | The filter value from the query parameter                                                                      |
-| `mode`    | The comparison operator from the query parameter                                                               |
-| `row`     | The full database row as a `ValueProxy`                                                                        |
+| Parameter | Description                                                                                             |
+| --------- | ------------------------------------------------------------------------------------------------------- |
+| `context` | The request context, extended with `this` referencing the controller instance                           |
+| `proxy`   | A query expression produced by the field modifier's `unlockrequest()` method; see the limitations below |
+| `key`     | The field name being filtered                                                                           |
+| `value`   | The filter value from the query parameter                                                               |
+| `mode`    | The comparison operator from the query parameter                                                        |
+| `row`     | The full database row as a `ValueProxy`                                                                 |
 
 ### Example: Pattern Matching Filter
 
@@ -168,7 +176,9 @@ function filterByEmailDomain(
   mode: string,
   row: ValueProxy<Record<string, any>>,
 ) {
-  return proxy.match(`@${value}$`);
+  assert(mode === "eq", 400, "Only equality is supported for email domains");
+  const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return proxy.match(`@${escaped}$`);
 }
 
 @RegisterDataController()
@@ -199,6 +209,8 @@ Query for users with Gmail addresses:
 GET /users/list?filter_email=gmail.com
 ```
 
+Import `assert` from `@antelopejs/interface-api-util`. Escaping the domain makes the dot literal rather than a regular-expression wildcard. This example deliberately rejects operators other than `eq` instead of silently treating every request as equality.
+
 ### The `useIndex` Parameter
 
 The `@Filter` decorator accepts an optional second parameter, `useIndex`, that controls whether the filter can use a database index for optimized lookups.
@@ -234,6 +246,6 @@ On a controller with a `status` filter, `?filter_status=inactive&filter_role=adm
 
 ## Modifier Integration
 
-The `proxy` parameter in custom filter functions provides the field value after modifier transformations have been applied. For example, if a field uses an encryption modifier, `proxy` contains the decrypted value. This ensures filters work correctly with modifier-protected data.
+The `proxy` parameter is a database expression, not an unlocked model instance. The Data API calls the modifier's `unlockrequest()` method to build that expression. Localization can select a locale at query time, but the built-in `EncryptionModifier.unlockrequest()` returns the stored expression unchanged: it does not decrypt ciphertext in the database. A custom modifier must explicitly support query-time access before a filter can operate on its logical value.
 
 For raw database values, use the `row` parameter and access the field directly.

package/docs/9.modifiers.md

@@ -45,7 +45,6 @@ import {
 import {
   BasicDataModel,
   Field,
-  Index,
   Localized,
   LocalizationModifier,
   Model,
@@ -53,9 +52,8 @@ import {
   Table,
 } from "@antelopejs/interface-database-decorators";
 
-@RegisterTable("content")
+@RegisterTable("content", "myapp")
 class Content extends Table.with(LocalizationModifier) {
-  @Index({ primary: true })
   @Field("string")
   declare _id: string;
 
@@ -126,7 +124,7 @@ Modifiers work automatically with foreign key relationships. When the Data API r
 
 ### Filters
 
-When filtering modifier-protected fields, custom filter functions receive the unlocked (transformed) value through the `proxy` parameter. This ensures filters operate on the correct data. See the [filters documentation](./8.filters.md) for details.
+Custom filters receive a query expression produced by the modifier's `unlockrequest()` method, not a decrypted JavaScript value. Localization supports query-time access; the built-in encryption modifier leaves its stored representation unchanged in query expressions. Do not use it to filter by plaintext. See the [filters documentation](./8.filters.md#modifier-integration) for details.
 
 ## Learn More
 

package/docs/assets/joined-list.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 510" role="img" aria-labelledby="title desc">
+  <title id="title">When the default list route resolves joined fields</title>
+  <desc id="desc">Resolve fields needed by filters before filtering and counting. Resolve sort fields before ordering and paging. Resolve remaining selected display fields only for the page. This describes the default list route, not arbitrary Query.List composition.</desc>
+  <rect width="480" height="510" rx="16" fill="#f5f7fb"/>
+  <g font-family="system-ui, sans-serif" fill="#172b45">
+    <text x="24" y="36" font-size="20" font-weight="700">Joined fields in a default list request</text>
+    <rect x="24" y="58" width="432" height="100" rx="10" fill="#e1ecfa"/>
+    <text x="42" y="87" font-size="18" font-weight="700">1. Needed by a filter</text>
+    <text x="42" y="116" font-size="16">Resolve → filter matching rows</text>
+    <text x="42" y="143" font-size="16">Count these rows for total.</text>
+    <path d="M240 168v24m-6-6 6 6 6-6" fill="none" stroke="#526780" stroke-width="2"/>
+    <rect x="24" y="204" width="432" height="100" rx="10" fill="#e1ecfa"/>
+    <text x="42" y="233" font-size="18" font-weight="700">2. Needed only for sorting</text>
+    <text x="42" y="262" font-size="16">Resolve → sort matching rows</text>
+    <text x="42" y="289" font-size="16">Then select the requested page.</text>
+    <path d="M240 314v24m-6-6 6 6 6-6" fill="none" stroke="#526780" stroke-width="2"/>
+    <rect x="24" y="350" width="432" height="100" rx="10" fill="#d9eee8"/>
+    <text x="42" y="379" font-size="18" font-weight="700">3. Needed only for display</text>
+    <text x="42" y="408" font-size="16">Resolve selected fields on the page</text>
+    <text x="42" y="435" font-size="16">Return results with pagination metadata.</text>
+    <text x="24" y="484" font-size="15">A field resolved earlier is not deferred again.</text>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-data-api",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "AntelopeJS interface that generates CRUD REST endpoints from database tables, with access rules, validation and pagination",
   "keywords": [
     "antelopejs",

package/skills/data-api-interface/SKILL.md

@@ -121,6 +121,8 @@ This exposes `GET /tasks/get?id=`, `GET /tasks/list`, `POST /tasks/new`, `PUT /t
 - Filters come from `filter_<name>=<mode>:<value>` query params (plain value means `eq`); modes are
   `eq|ne|gt|ge|lt|le` (the default filter compares the raw query-string value — pass a custom filter
   function to cast for numeric ranges). Only fields declared with `@Filter()` are filterable.
+  Repeating a field's filter (`filter_age=ge:18&filter_age=lt:65`) keeps the rows passing them all;
+  the route then receives a list of tuples for it (`FieldFilter`, read with `FilterValuesOf`).
 - `@Joined` and `@Computed` fields are materialized in-database, so `@Sortable` and `@Filter()` work
   efficiently on them — but those decorators must still be applied explicitly. Such fields are
   forced read-only and to non-indexed sorting.
@@ -128,6 +130,13 @@ This exposes `GET /tasks/get?id=`, `GET /tasks/list`, `POST /tasks/new`, `PUT /t
   of `DefaultRoutes.All`; use `DefaultRoutes.WithOptions(route, options, endpoint)` to rename an
   endpoint or preset parameter options.
 - `@Access` accepts per-action overrides, e.g. `@Access(AccessMode.ReadOnly, { edit: AccessMode.ReadWrite })`.
+  `GetEffectiveMode(field, action)` reads the mode a field has in one action.
+- A custom list route reads its page with `Query.ListPage(db, meta, query, options)` (`offset`,
+  `limit`, `filters`, `sortKey`, `pluck`, `noForeign`, `deferredJoined`): joined, then computed, then
+  foreign, then pluck.
+- `new` answers the created row as `get` reads it, with its `_id`; `edit` answers the stored row after
+  the update. Both accept a body already parsed (`Validation.WrittenBody`), so a wrapping route can
+  amend it before the write.
 - `edit` is a partial update: a field absent from the body is left unchanged, `null` clears it, and
   setters only run for the fields present. `@Mandatory("edit")` rejects a field cleared by the body
   (`null`, `""`, `[]`), not an absent one. `new` still writes every writable field and runs every setter.