@antelopejs/interface-data-api 0.2.1 → 0.3.0

package/docs/8.filters.md

@@ -8,7 +8,7 @@ The `@Filter` decorator adds filtering capabilities to list endpoints. Filters a
 
 ### Default Filter
 
-Apply `@Filter()` without arguments to enable standard comparison filtering on a field.
+Apply `@Filter()` without arguments to enable standard comparison filtering on a string field. Query filter values remain strings: TypeScript annotations, `@Field`, and write validators do not parse them into numbers or booleans.
 
 ```typescript
 import { Filter } from "@antelopejs/interface-data-api/metadata";
@@ -30,12 +30,12 @@ class UserAPI extends DataController(
   @Listable()
   @Access(AccessMode.ReadWrite)
   @Filter()
-  declare age: number;
+  declare status: string;
 
   @Listable()
   @Access(AccessMode.ReadWrite)
   @Filter()
-  declare isActive: boolean;
+  declare role: string;
 }
 ```
 
@@ -63,24 +63,82 @@ When no operator is specified, `eq` (equal) is used by default.
 
 ### Examples
 
-Retrieve users older than 30:
+Retrieve active users:
 
 ```http
-GET /users/list?filter_age=gt:30
+GET /users/list?filter_status=active
 ```
 
-Retrieve active users:
+Retrieve users whose role is not admin:
+
+```http
+GET /users/list?filter_role=ne:admin
+```
+
+Combine multiple filters:
 
 ```http
-GET /users/list?filter_isActive=true
+GET /users/list?filter_status=active&filter_role=ne:admin
 ```
 
-Combine multiple filters (users under 25 who are active):
+Filter one field several times to keep the rows that pass every filter (AND):
 
 ```http
-GET /users/list?filter_age=lt:25&filter_isActive=true
+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.
+
+```ts docs-check
+import { assert } from "@antelopejs/interface-api-util";
+import type { FilterFunction } from "@antelopejs/interface-data-api/metadata";
+
+export const numberFilter: FilterFunction<Record<string, unknown>> = (
+  _context,
+  proxy,
+  _key,
+  raw,
+  mode,
+) => {
+  const value = Number(raw);
+  assert(raw.trim() !== "" && Number.isFinite(value), 400, "Invalid number");
+  assert(
+    ["eq", "ne", "gt", "ge", "lt", "le"].includes(mode),
+    400,
+    "Invalid comparison",
+  );
+  return proxy[mode](value);
+};
+
+export const booleanFilter: FilterFunction<Record<string, unknown>> = (
+  _context,
+  proxy,
+  _key,
+  raw,
+  mode,
+) => {
+  assert(raw === "true" || raw === "false", 400, "Invalid boolean");
+  assert(mode === "eq" || mode === "ne", 400, "Invalid comparison");
+  return proxy[mode](raw === "true");
+};
 ```
 
+Apply the functions to the corresponding fields in your controller:
+
+```typescript
+@Filter(numberFilter, false)
+declare age: number;
+
+@Filter(booleanFilter, false)
+declare isActive: boolean;
+```
+
+With these custom filters, `?filter_age=gt:30&filter_isActive=true` compares against `30` and `true`, not `"30"` and `"true"`. Keep `useIndex` false for callbacks that parse values: indexed equality uses the raw string directly and bypasses the filter callback.
+
 ## Custom Filters
 
 For filtering logic beyond simple comparisons, pass a custom filter function to `@Filter`.
@@ -98,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
 
@@ -118,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()
@@ -138,7 +198,7 @@ class UserAPI extends DataController(
 
   @Listable()
   @Access(AccessMode.ReadWrite)
-  @Filter()
+  @Filter(numberFilter, false)
   declare age: number;
 }
 ```
@@ -149,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.
@@ -168,8 +230,22 @@ When `useIndex` is not specified:
 
 Index-optimized filters with an `eq` operator perform an indexed lookup instead of a full table scan, which significantly improves performance on large datasets.
 
+## Mandatory Route Filters
+
+Use `DefaultRoutes.WithOptions` to constrain a list route. The `filters` map contains `[stringValue, comparison]` tuples for fields declared with `@Filter`. Request filters for other fields are retained, but a route filter wins when both specify the same field.
+
+```ts docs-check
+import { DefaultRoutes } from "@antelopejs/interface-data-api";
+
+const activeUsers = DefaultRoutes.WithOptions(DefaultRoutes.List, {
+  filters: { status: ["active", "eq"] },
+});
+```
+
+On a controller with a `status` filter, `?filter_status=inactive&filter_role=admin` still restricts `status` to `"active"` while retaining the requested `role`. Route filters are list-query constraints, not authorization for separate get/edit/delete routes.
+
 ## 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/docs/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "rootDir": "..",
+    "composite": false,
+    "incremental": false,
+    "noEmit": true
+  },
+  "include": ["../src", "./**/*.ts"]
+}

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@antelopejs/interface-data-api",
-  "version": "0.2.1",
-  "description": "AntelopeJS interface for data API with CRUD controllers and route generation",
+  "version": "0.3.0",
+  "description": "AntelopeJS interface that generates CRUD REST endpoints from database tables, with access rules, validation and pagination",
   "keywords": [
     "antelopejs",
+    "api",
     "crud",
     "data-api",
-    "interface"
+    "interface",
+    "rest"
   ],
+  "homepage": "https://interfaces.antelopejs.com/docs/data-api",
+  "bugs": {
+    "url": "https://github.com/AntelopeJS/interface-data-api/issues"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -57,13 +63,13 @@
     "knip": "knip"
   },
   "devDependencies": {
-    "@antelopejs/core": "^1.13.4",
-    "@antelopejs/interface-api": "^0.0.13",
-    "@antelopejs/interface-api-util": "^0.1.2",
-    "@antelopejs/interface-core": "^0.1.1",
-    "@antelopejs/interface-database": "^0.1.9",
-    "@antelopejs/interface-database-decorators": "^0.1.8",
-    "@antelopejs/tooling-configs": "^0.0.8",
+    "@antelopejs/core": "^1.16.0",
+    "@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/tooling-configs": "^0.0.9",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
@@ -81,11 +87,11 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@antelopejs/interface-api": ">=0.0.13 <1.0.0",
-    "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
-    "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.9 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.8 <1.0.0"
+    "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
+    "@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"
   },
   "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.