@antelopejs/interface-data-api 0.2.1 → 0.3.0

package/dist/tests/utils.d.ts

@@ -6,7 +6,7 @@
  * context wrappers) do not change the result.
  */
 export declare function getFunctionName(): string;
-export declare function request(functionName: string, uri: string, method: string, payload?: unknown, queryParams?: Record<string, string>): Promise<Response>;
+export declare function request(functionName: string, uri: string, method: string, payload?: unknown, queryParams?: Record<string, string> | [string, string][]): Promise<Response>;
 export declare function newRequest(functionName: string, payload: unknown, queryParams?: Record<string, string>): Promise<Response>;
 export declare function getRequest(functionName: string, queryParams?: Record<string, string>): Promise<Response>;
 export declare function listRequest(functionName: string, queryParams?: Record<string, string>): Promise<Response>;
@@ -17,3 +17,8 @@ export declare function getSchemaInstance(schemaName: string): import("@antelope
 export declare function validateObjectList<T extends {
     _id: string;
 }>(objectList: T[], expectedObjectList: Partial<T>[], fieldsToCheck: (keyof T)[]): Promise<void>;
+/** What the `new` route answers: the created row, with its key. */
+export interface CreatedRow {
+    _id: string;
+    [field: string]: unknown;
+}

package/dist/tests/utils.js

@@ -62,7 +62,9 @@ function getFunctionName() {
     const caller = captureCallSites().find(isTestCallSite);
     return caller?.getFunctionName() ?? UNKNOWN_FUNCTION_NAME;
 }
-async function request(functionName, uri, method, payload, queryParams) {
+async function request(functionName, uri, method, payload, 
+// Pairs repeat a key (`filter_x=a&filter_x=b`).
+queryParams) {
     return await fetch(`${constants_1.URL_BASE}/${functionName}/${uri}?${new URLSearchParams(queryParams).toString()}`, {
         method,
         headers: {

package/dist/tests/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tests/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tests/utils.ts"],"names":[],"mappings":"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"}

package/docs/1.introduction.md

@@ -1,35 +1,23 @@
-# Data API Documentation
+# Expose database records through an API
 
 ## Overview
 
-The Data API interface provides a declarative approach to building RESTful APIs with automatic CRUD operations. It connects your database models directly to API endpoints, handling validation, access control, foreign key resolution, and pagination with minimal boilerplate.
+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.
 
-## Key Features
+## Build one resource first
 
-- **Database-to-API Mapping** - Expose database tables as REST endpoints through data controllers.
-- **Default CRUD Routes** - Built-in `get`, `list`, `new`, `edit`, and `delete` operations that work out of the box.
-- **Access Control** - Define read-only, write-only, or read-write permissions per field, with per-action overrides.
-- **Field Validation** - Attach custom validation functions to individual fields and enforce mandatory fields per operation.
-- **Listable Fields and Pagination** - Control which fields appear in list responses, with support for multiple pluck modes and paginated results.
-- **Sorting** - Mark fields as sortable to enable ordering in list queries.
-- **Foreign Key Resolution** - Automatically resolve relationships between tables with optional field plucking.
-- **Joined Fields** - Flatten a scalar field from another table onto each row so it can be sorted, filtered, and searched natively in the database.
-- **Computed Fields** - Merge in-database computed expressions (row-local values or aggregates over other tables) onto each row, natively sortable, filterable, and pageable.
-- **Filters** - Add default or custom filter logic to list endpoints using query parameters.
-- **Modifier Integration** - Automatic data transformation (encryption, hashing, localization) through database-decorators.
-
-## Dependencies
-
-This interface relies on the following AntelopeJS packages:
-
-- [@antelopejs/interface-api](https://github.com/AntelopeJS/interface-api) - API controllers and route registration.
-- [@antelopejs/interface-database-decorators](https://github.com/AntelopeJS/interface-database-decorators) - Database table definitions and models.
+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).
 
 ## Quick Start
 
-The following example creates a full CRUD API for a `users` table.
+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.
 
-```typescript
+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.
+
+```ts docs-check
 import { Controller } from "@antelopejs/interface-api";
 import {
   DataController,
@@ -53,9 +41,8 @@ import {
 } 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;
 
@@ -114,13 +101,26 @@ This generates the following REST endpoints:
 | PUT    | `/users/edit?id=<id>`   | Update an existing user    |
 | DELETE | `/users/delete?id=<id>` | Delete a user              |
 
-## Documentation Sections
+### 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:
+
+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.
+
+`@Mandatory` does not check email syntax or password strength. Add [validators](./5.validators.md) before accepting 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
+
+## 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

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.
@@ -258,12 +266,13 @@ class UserAPI extends DataController(User, routes, Controller("/users")) {
 
 **List:**
 
-| Option      | Type      | Description                                            |
-| ----------- | --------- | ------------------------------------------------------ |
-| `maxPage`   | `number`  | Maximum allowed value for `limit` (caps the page size) |
-| `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`)            |
+| Option      | Type                          | Description                                                                                                                  |
+| ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `maxPage`   | `number`                      | Maximum allowed value for `limit` (caps the page size)                                                                       |
+| `noForeign` | `boolean`                     | Skip foreign key resolution                                                                                                  |
+| `noPluck`   | `boolean`                     | Return all database fields instead of plucked fields                                                                         |
+| `pluckMode` | `string`                      | Select a named pluck mode (see `@Listable`)                                                                                  |
+| `filters`   | `Record<string, FieldFilter>` | Mandatory filters merged with request filters; route field keys win (see [filters](./8.filters.md#mandatory-route-filters)). |
 
 **New:**
 
@@ -278,6 +287,71 @@ 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.
+
+```ts docs-check
+import { DefaultRoutes } from "@antelopejs/interface-data-api";
+import { assert } from "@antelopejs/interface-api-util";
+
+const invoiceGet = DefaultRoutes.WithGetGuard(
+  async function (ctx, current, params) {
+    // documentType can be stored without being exposed through @Access.
+    assert(current.documentType === "invoice", 404, "Not Found");
+  },
+);
+
+// Pass this route map to DataController(Document, routes, Controller("/invoices")).
+const routes = {
+  get: DefaultRoutes.WithOptions(invoiceGet, { noForeign: "true" }),
+};
+```
+
+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:
+
+- **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
 
 For operations beyond CRUD, define a custom route callback with `func`, `args`, and `method` properties.

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

@@ -101,6 +101,7 @@ class UserAPI extends DataController(User, routes, Controller("/users")) {
   declare userModel: UserModel;
 
   @Listable()
+  @Listable(true, "detailed")
   @Access(AccessMode.ReadOnly)
   declare name: string;
 
@@ -113,6 +114,8 @@ class UserAPI extends DataController(User, routes, Controller("/users")) {
 - `GET /users/list` returns only `name`.
 - `GET /users/detailed` returns both `name` and `internalNotes`.
 
+Modes are independent field sets: `"detailed"` does not inherit `"list"`. The example includes `name` in both modes explicitly. A registered list route whose `pluckMode` has never been declared returns `400 Bad Request` unless `noPluck` is enabled; an unregistered URL instead returns `404`.
+
 ### Listable with Getters
 
 When a field uses a getter (computed property), the `@Listable` decorator must specify which database fields the getter depends on. This ensures those fields are fetched from the database.
@@ -221,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;