@antelopejs/interface-data-api 0.2.2 → 0.4.0

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) => {
@@ -213,12 +215,12 @@ declare notes: string;
 
 ## Error Handling
 
-When validation or mandatory checks fail, the API returns a `400 Bad Request` response with a plain text message describing the issue.
+When validation or mandatory checks fail, the API returns a `400 Bad Request` response whose JSON body names what went wrong and the fields concerned, for the client to word it and show it under each field:
 
-- **Mandatory failure:** `"Missing mandatory fields: email, password"`
-- **Validator failure:** `"Invalid field type(s): age, email"`
+- **Mandatory failure:** `{ "code": "missing_mandatory_fields", "fields": ["email", "password"] }`
+- **Validator failure:** `{ "code": "invalid_field_types", "fields": ["age", "email"] }`
 
-All fields are checked, and the error message lists every field that failed validation.
+The codes are exported as `Validation.MISSING_MANDATORY_FIELDS` and `Validation.INVALID_FIELD_TYPES` (`@antelopejs/interface-data-api/components`), the body's type as `Validation.FieldsErrorBody`. All fields are checked: `fields` lists every one that failed.
 
 ## Next Steps
 

package/docs/6.listable.md

@@ -224,16 +224,20 @@ 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;
 ```
 
+### Localized Fields
+
+A `@Localized` field is sorted on its value in the request's locale, the one the controller's `@ModifierKey(LocalizationModifier)` field holds. A row with no value in that locale, or an empty one, sorts on its `fallbackLocale` value. This ordering is computed per row, so it never uses an index, whatever `noIndex` says.
+
 ### Example
 
 ```http

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.4.0",
   "description": "AntelopeJS interface that generates CRUD REST endpoints from database tables, with access rules, validation and pagination",
   "keywords": [
     "antelopejs",
@@ -67,8 +67,8 @@
     "@antelopejs/interface-api": "^0.0.15",
     "@antelopejs/interface-api-util": "^0.1.3",
     "@antelopejs/interface-core": "^0.2.4",
-    "@antelopejs/interface-database": "^0.1.10",
-    "@antelopejs/interface-database-decorators": "^0.1.9",
+    "@antelopejs/interface-database": "^0.1.11",
+    "@antelopejs/interface-database-decorators": "^0.1.10",
     "@antelopejs/tooling-configs": "^0.0.9",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
@@ -91,7 +91,7 @@
     "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
     "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0"
+    "@antelopejs/interface-database-decorators": ">=0.1.10 <1.0.0"
   },
   "packageManager": "pnpm@10.6.5",
   "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.