@antelopejs/interface-data-api 0.1.5 → 0.1.7

package/docs/11.computed.md

@@ -0,0 +1,152 @@
+# Computed Fields
+
+## Overview
+
+The `@Computed` decorator declares a field whose value is computed in the database from an expression, then merged onto each row at query time. The expression can be a row-local computation (derived from other fields of the same row) or a per-row subquery, such as an aggregate over another table. Because the merge happens before sorting and filtering, computed fields are natively sortable, filterable, and pageable in DB — no fetch-all or in-memory sorting required.
+
+Computed fields are read-only: the value is produced by the query and is never persisted on the controller's table. Declaring a field as computed automatically sets its access mode to read-only and forces non-indexed sorting, regardless of decorator order.
+
+## Basic Usage
+
+The expression receives the row proxy and the schema instance of the controller's table. It must return a value built from the query builder (`ValueProxy` operations or a subquery), not plain JavaScript computed at request time.
+
+```typescript
+import { Computed } from "@antelopejs/interface-data-api/metadata";
+
+@RegisterTable("groups")
+class Group extends Table {
+  @Field("string")
+  declare _id: string;
+
+  @Field("string")
+  declare name: string;
+}
+
+@RegisterTable("devices")
+class Device extends Table {
+  @Field("string")
+  declare _id: string;
+
+  @Index()
+  @Field("string")
+  @Relation({ to: () => Group })
+  declare group_id: string;
+}
+
+@RegisterDataController()
+class GroupAPI extends DataController(
+  Group,
+  DefaultRoutes.All,
+  Controller("/groups"),
+) {
+  @ModelReference()
+  @Model(GroupModel)
+  declare groupModel: GroupModel;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  @Listable()
+  @Access(AccessMode.ReadWrite)
+  declare name: string;
+
+  // Aggregate: number of devices referencing this group, computed in DB
+  @Listable()
+  @Computed(
+    (row, db) =>
+      db
+        .table("devices")
+        .getAll(row.key("_id"), "group_id")
+        .count(),
+    { default: 0 },
+  )
+  @Sortable()
+  declare devices_count: number;
+
+  // Row-local expression
+  @Listable()
+  @Computed((row) => (row.key("name") as ValueProxy<string>).concat("!"))
+  declare display_name: string;
+}
+```
+
+A GET request to `/groups/get?id=group-123` returns the computed values at the top level:
+
+```json
+{
+  "_id": "group-123",
+  "name": "Alpha",
+  "devices_count": 3,
+  "display_name": "Alpha!"
+}
+```
+
+## Decorator Parameters
+
+```typescript
+@Computed(expr, options?)
+```
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `expr` | `(row, db) => expression` | Yes | Expression receiving the row proxy and the schema instance; returns a `ValueProxy` expression or a subquery (`Datum`) |
+| `options.default` | `unknown` | No | Fallback merged over the computed value when the expression yields `null` |
+
+### The `default` option
+
+Aggregate subqueries yield `null` instead of their natural zero value when the underlying set is empty (a `count()` over a group with no devices returns `null`, not `0`). Calling `.default(0)` inside the subquery expression does not help: the aggregation produces no document at all, so there is nothing to apply the default to. The `options.default` value solves this by being applied at the row level, after the merge:
+
+```typescript
+@Computed((row, db) => db.table("devices").getAll(row.key("_id"), "group_id").count(), {
+  default: 0,
+})
+declare devices_count: number;
+```
+
+Without it, rows with an empty aggregate carry `null`, which breaks equality filters (`filter_devices_count=eq:0`) and makes sort ordering depend on BSON type ordering.
+
+## Sorting, Filtering, and Pagination
+
+Computed fields combine with `@Sortable` and `@Filter` like native columns. The framework injects the computation lazily, only when and where the value is needed:
+
+- A computed field referenced by an active filter is merged before filters run.
+- A computed field used as the sort key is merged after the total count is captured and before the non-indexed `orderBy`, so the aggregate is not paid twice.
+- A computed field requested only for display (in the pluck, neither sorted nor filtered) is merged after pagination (`slice`), so it is computed only for the returned page, not the whole collection.
+
+Sorting and pagination both stay in the database: sorting by a computed aggregate with `limit`/`offset` produces correct pages and a constant `total`.
+
+Computed fields are always sorted without a database index (`@Sortable` is forced to non-indexed), since the value does not exist as a stored column.
+
+### 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:
+
+```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)),
+)
+declare devices_count: number;
+```
+
+## Computed vs. Joined
+
+| Aspect | `@Computed` | `@Joined` |
+| ------ | ----------- | --------- |
+| Source | Arbitrary expression: row-local computation or per-row subquery | One scalar field from another table matched by a foreign key |
+| Typical use | Aggregates (`count`, `sum`), derived values | Flattening a referenced record's field |
+| Access | Read-only (enforced) | Read-only (enforced) |
+| Sort / filter | Native, lazily injected only where needed | Native, always applied before sort/filter |
+
+`@Joined` remains the simpler choice for the 1:1 flattening case; `@Computed` generalizes the same merge mechanism to arbitrary expressions.
+
+## Driver Support
+
+The aggregate form relies on the database driver translating a per-row subquery inside a merge into a correlated lookup (`$lookup` with `let`/`pipeline` on MongoDB). This is supported by `@antelopejs/mongodb` >= 1.2.1. Row-local expressions only use standard expression compilation and work on any driver.
+
+## Next Steps
+
+See the [joined fields documentation](./10.joined.md) for the dedicated 1:1 flattening decorator.

package/docs/2.data-controllers.md

@@ -0,0 +1,120 @@
+# Data Controllers
+
+## Overview
+
+A data controller is the central building block of the Data API. It connects a database table to a set of API endpoints, exposing the table fields you declare on the class. The `DataController` function creates a base class that combines your table definition, route definitions, and controller path into a single cohesive unit.
+
+## Create a Data Controller
+
+Use the `DataController` function to define a new controller. It accepts three arguments: the table class, a route definition object, and a controller base with the endpoint path.
+
+```typescript
+import { Controller } from "@antelopejs/interface-api";
+import {
+  DataController,
+  DefaultRoutes,
+  RegisterDataController,
+} from "@antelopejs/interface-data-api";
+import {
+  Access,
+  AccessMode,
+  Listable,
+  ModelReference,
+} from "@antelopejs/interface-data-api/metadata";
+import {
+  BasicDataModel,
+  Field,
+  Index,
+  Model,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+
+// Define the database table
+@RegisterTable("users")
+class User extends Table {
+  @Index({ primary: true })
+  @Field("string")
+  declare _id: string;
+
+  @Field("string")
+  declare email: string;
+
+  @Field("number")
+  declare age: number;
+}
+
+// Create the database model
+class UserModel extends BasicDataModel(User, "users") {}
+
+// Create the data controller
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  DefaultRoutes.All,
+  Controller("/users"),
+) {
+  @ModelReference()
+  @Model(UserModel, "my-database")
+  declare userModel: UserModel;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  @Listable()
+  @Access(AccessMode.ReadWrite)
+  declare email: string;
+
+  @Access(AccessMode.ReadWrite)
+  declare age: number;
+}
+```
+
+## `DataController` Signature
+
+```typescript
+DataController(
+  tableClass: typeof Table,  // Database table class
+  routes: DataControllerDef, // Route definitions (e.g., DefaultRoutes.All)
+  base: typeof Controller,   // Controller base with path
+)
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `tableClass` | The database table class decorated with `@RegisterTable`. The controller validates that this table exists in the database schema. |
+| `routes` | An object mapping endpoint names to route callbacks. Use `DefaultRoutes.All` for standard CRUD or pass a custom subset. |
+| `base` | The controller base, typically created with `Controller("/path")`, which sets the URL prefix for all endpoints. |
+
+## Required Components
+
+Every data controller requires the following elements:
+
+1. **Table Class** - A database table decorated with `@RegisterTable`, defining the schema.
+2. **Route Definitions** - Which operations to expose. Use `DefaultRoutes.All` or a custom selection.
+3. **Controller Base** - The URL path prefix, created with `Controller("/path")`.
+4. **Model Reference** - A property decorated with `@ModelReference()` that holds a database model instance. This model provides the actual database operations (insert, get, update, delete).
+
+## The `@RegisterDataController` Decorator
+
+Apply `@RegisterDataController()` to the class to finalize the controller setup. This decorator processes all field decorators, registers the defined routes, and connects parameter providers to each endpoint.
+
+## Field Declarations
+
+Fields declared on the data controller class determine which database columns are exposed through the API. Each field can be annotated with decorators to control its behavior:
+
+- `@Access` - Set read/write permissions.
+- `@Listable` - Include the field in list responses.
+- `@Mandatory` - Require the field on specific operations.
+- `@Validator` - Attach a validation function.
+- `@Foreign` - Establish a foreign key relationship.
+- `@Joined` - Flatten a scalar field from another table onto the row.
+- `@Filter` - Enable filtering on the field.
+- `@Sortable` - Allow sorting by the field.
+
+Fields without any decorator are ignored by the Data API and do not appear in API responses or accept input.
+
+## Next Steps
+
+See the [routes documentation](./3.routes.md) to learn about available routes and how to customize them.

package/docs/3.routes.md

@@ -0,0 +1,320 @@
+# Routes
+
+## Overview
+
+Routes define which operations are available on a data controller. The module provides predefined route configurations that automatically generate endpoints with the correct HTTP methods, parameter extraction, and response handling.
+
+## Default Routes
+
+The `DefaultRoutes` namespace provides five built-in routes covering standard CRUD operations.
+
+```typescript
+import { DefaultRoutes } from "@antelopejs/interface-data-api";
+```
+
+| Route | Object | HTTP Method | Endpoint Pattern |
+| ----- | ------ | ----------- | ---------------- |
+| Get | `DefaultRoutes.Get` | GET | `/resource/get?id=<id>` |
+| List | `DefaultRoutes.List` | GET | `/resource/list` |
+| New | `DefaultRoutes.New` | POST | `/resource/new` |
+| Edit | `DefaultRoutes.Edit` | PUT | `/resource/edit?id=<id>` |
+| Delete | `DefaultRoutes.Delete` | DELETE | `/resource/delete?id=<id>` |
+
+Use `DefaultRoutes.All` to include all five routes at once.
+
+## Route Configuration
+
+Pass a route definition object to `DataController` to control which endpoints are created.
+
+```typescript
+// All CRUD routes
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  DefaultRoutes.All,
+  Controller("/users"),
+) {
+  // ...
+}
+
+// Only specific routes
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  {
+    get: DefaultRoutes.Get,
+    list: DefaultRoutes.List,
+    new: DefaultRoutes.New,
+  },
+  Controller("/users"),
+) {
+  // edit and delete endpoints are not created
+}
+```
+
+## Route Details
+
+### Get
+
+Retrieves a single record by its identifier.
+
+**Endpoint:** `GET /resource/get`
+
+**Query Parameters:**
+
+| Parameter | Required | Description |
+| --------- | -------- | ----------- |
+| `id` | Yes | Record identifier |
+
+**Example:**
+
+```http
+GET /users/get?id=user-123
+```
+
+**Response:**
+
+```json
+{
+  "_id": "user-123",
+  "name": "Bob",
+  "email": "bob@example.com"
+}
+```
+
+### List
+
+Retrieves multiple records with pagination, sorting, and filtering support.
+
+**Endpoint:** `GET /resource/list`
+
+**Query Parameters:**
+
+| Parameter | Required | Default | Description |
+| --------- | -------- | ------- | ----------- |
+| `limit` | No | `10` | Maximum number of records to return |
+| `offset` | No | `0` | Number of records to skip |
+| `sortKey` | No | - | Field to sort by (must be marked `@Sortable`) |
+| `sortDirection` | No | `asc` | Sort direction: `asc` or `desc` |
+
+**Example:**
+
+```http
+GET /users/list?limit=10&offset=0&sortKey=name&sortDirection=asc
+```
+
+**Response:**
+
+```json
+{
+  "results": [
+    { "_id": "user-123", "name": "Alice", "email": "alice@example.com" },
+    { "_id": "user-456", "name": "Bob", "email": "bob@example.com" }
+  ],
+  "total": 42,
+  "offset": 0,
+  "limit": 10
+}
+```
+
+### New
+
+Creates a new record. The request body must be a JSON object with the fields to set.
+
+**Endpoint:** `POST /resource/new`
+
+**Body:** JSON object with field values.
+
+**Example:**
+
+```http
+POST /users/new
+Content-Type: application/json
+
+{
+  "name": "Bob",
+  "email": "bob@example.com",
+  "password": "secure123"
+}
+```
+
+**Response:**
+
+```json
+["user-789"]
+```
+
+Before inserting, the `insert` event is triggered on any table modifiers attached to the database table.
+
+### Edit
+
+Updates an existing record by its identifier.
+
+**Endpoint:** `PUT /resource/edit`
+
+**Query Parameters:**
+
+| Parameter | Required | Description |
+| --------- | -------- | ----------- |
+| `id` | Yes | Record identifier |
+
+**Body:** JSON object with fields to update.
+
+**Example:**
+
+```http
+PUT /users/edit?id=user-123
+Content-Type: application/json
+
+{
+  "name": "Robert",
+  "email": "robert@example.com"
+}
+```
+
+**Response:**
+
+```http
+200 OK
+```
+
+Before updating, the `update` event is triggered on any table modifiers attached to the database table.
+
+### Delete
+
+Deletes one or more records by their identifiers.
+
+**Endpoint:** `DELETE /resource/delete`
+
+**Query Parameters:**
+
+| Parameter | Required | Description |
+| --------- | -------- | ----------- |
+| `id` | Yes | Record identifier(s). Pass multiple `id` parameters to delete several records at once. |
+
+**Example:**
+
+```http
+DELETE /users/delete?id=user-123
+```
+
+**Response:**
+
+```http
+200 OK
+```
+
+## Route Options with `WithOptions`
+
+The `DefaultRoutes.WithOptions` function customizes route behavior by overriding query parameters or route settings.
+
+```typescript
+DefaultRoutes.WithOptions(callback, options?, endpoint?)
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `callback` | The route callback to customize (e.g., `DefaultRoutes.Edit`). |
+| `options` | An object with option overrides. These values take precedence over query parameters. |
+| `endpoint` | An optional custom endpoint path. Defaults to the route key name. |
+
+### Example
+
+```typescript
+const routes = {
+  edit: DefaultRoutes.Edit,
+  quickEdit: DefaultRoutes.WithOptions(DefaultRoutes.Edit, {
+    noMandatory: "true",
+  }),
+};
+
+@RegisterDataController()
+class UserAPI extends DataController(User, routes, Controller("/users")) {
+  // /users/edit enforces mandatory fields
+  // /users/quickEdit skips mandatory field validation
+}
+```
+
+### Available Options per Route
+
+**Get:**
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `index` | `string` | Use a secondary index instead of the primary key |
+| `noForeign` | `string` | Skip foreign key resolution |
+
+**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`) |
+
+**New:**
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `noMandatory` | `string` | Skip mandatory field validation |
+
+**Edit:**
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `index` | `string` | Use a secondary index instead of the primary key |
+| `noMandatory` | `string` | Skip mandatory field validation |
+
+## Custom Routes
+
+For operations beyond CRUD, define a custom route callback with `func`, `args`, and `method` properties.
+
+```typescript
+import { Context } from "@antelopejs/interface-api";
+import {
+  DataController,
+  DefaultRoutes,
+  RegisterDataController,
+} from "@antelopejs/interface-data-api";
+import { Parameters } from "@antelopejs/interface-data-api/components";
+
+const Search = {
+  func: async (ctx, params) => {
+    // Custom search logic
+    return { results: [] };
+  },
+  args: [Context(), Parameters.List()],
+  method: "get",
+};
+
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  {
+    ...DefaultRoutes.All,
+    search: Search,
+  },
+  Controller("/users"),
+) {
+  // All default routes plus a custom /users/search endpoint
+}
+```
+
+The `args` array contains parameter decorators that extract values from the request context. Each decorator corresponds to a parameter in the `func` callback, in order.
+
+## Error Handling
+
+Default routes return standard HTTP error responses:
+
+| Status | Condition |
+| ------ | --------- |
+| `400 Bad Request` | Validation fails, missing required fields, or invalid parameters |
+| `404 Not Found` | Record does not exist |
+| `500 Internal Server Error` | Database operation fails |
+
+Error messages are returned as plain text in the response body.
+
+## Next Steps
+
+See the [access rights documentation](./4.access-rights.md) to learn how to control field read/write permissions.