@antelopejs/interface-data-api 0.1.6 → 0.1.7

package/docs/1.introduction.md

@@ -0,0 +1,128 @@
+# Data API Documentation
+
+## 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.
+
+## Key Features
+
+- **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.
+
+## Quick Start
+
+The following example creates a full CRUD API for a `users` table.
+
+```typescript
+import { Controller } from "@antelopejs/interface-api";
+import {
+  DataController,
+  DefaultRoutes,
+  RegisterDataController,
+} from "@antelopejs/interface-data-api";
+import {
+  Access,
+  AccessMode,
+  Listable,
+  Mandatory,
+  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;
+
+  @Index()
+  @Field("string")
+  declare email: string;
+
+  @Field("string")
+  declare name: string;
+
+  @Field("string")
+  declare password: string;
+}
+
+// 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)
+  @Mandatory("new", "edit")
+  declare email: string;
+
+  @Listable()
+  @Access(AccessMode.ReadWrite)
+  @Mandatory("new")
+  declare name: string;
+
+  @Access(AccessMode.WriteOnly)
+  @Mandatory("new")
+  declare password: string;
+}
+```
+
+This generates the following REST endpoints:
+
+| Method | Endpoint | Description |
+| ------ | -------- | ----------- |
+| GET | `/users/get?id=<id>` | Retrieve a single user |
+| GET | `/users/list?limit=10` | List users with pagination |
+| POST | `/users/new` | Create a new user |
+| PUT | `/users/edit?id=<id>` | Update an existing user |
+| DELETE | `/users/delete?id=<id>` | Delete a user |
+
+## Documentation Sections
+
+- [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
+- [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
+- [Joined Fields](./10.joined.md) - Flatten a remote field onto rows for native sort/filter
+- [Computed Fields](./11.computed.md) - In-database computed values, sortable and pageable natively

package/docs/10.joined.md

@@ -0,0 +1,146 @@
+# Joined Fields
+
+## Overview
+
+The `@Joined` decorator imports a single scalar field from another table and flattens it onto each row at query time. Unlike `@Foreign`, which embeds the full referenced record as a nested object in the response, `@Joined` copies one remote field to the top level of the row before sorting and filtering are applied. This makes the joined field natively sortable, filterable, and searchable in the database.
+
+Joined fields are read-only: the value is set by a lookup at query time and is never persisted on the controller's own table. Declaring a field as joined automatically sets its access mode to read-only and forces non-indexed sorting.
+
+## Basic Usage
+
+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`.
+
+```typescript
+import { Joined } from "@antelopejs/interface-data-api/metadata";
+import {
+  Field,
+  Index,
+  RegisterTable,
+  Relation,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+
+@RegisterTable("users")
+class User extends Table {
+  @Index({ primary: true })
+  @Field("string")
+  declare _id: string;
+
+  @Field("string")
+  declare name: string;
+}
+
+@RegisterTable("orders")
+class Order extends Table {
+  @Index({ primary: true })
+  @Field("string")
+  declare _id: string;
+
+  @Field("string")
+  @Relation({ to: () => User })
+  declare userId: string;
+
+  @Field("number")
+  declare total: number;
+}
+
+@RegisterDataController()
+class OrderAPI extends DataController(
+  Order,
+  DefaultRoutes.All,
+  Controller("/orders"),
+) {
+  @ModelReference()
+  @Model(OrderModel, "my-database")
+  declare orderModel: OrderModel;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  declare userId: string;
+
+  // Pull the remote "name" field from the User referenced by userId
+  @Listable()
+  @Joined({
+    table: User,
+    localKey: "userId",
+    remoteField: "name",
+  })
+  declare userName: string;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare total: number;
+}
+```
+
+A GET request to `/orders/get?id=order-123` returns the joined value at the top level:
+
+```json
+{
+  "_id": "order-123",
+  "userName": "Bob",
+  "total": 99.99
+}
+```
+
+## Decorator Parameters
+
+```typescript
+@Joined({ table, localKey, remoteField, remoteIndex?, schema? })
+```
+
+| Option | Type | Required | Default | Description |
+| ------ | ---- | -------- | ------- | ----------- |
+| `table` | `Class<Table>` or `string` | Yes | - | The remote table class or registered table name string |
+| `localKey` | `string` | Yes | - | The field on the local row holding the value matched against the remote table |
+| `remoteField` | `string` | Yes | - | The remote field whose value is flattened onto the row |
+| `remoteIndex` | `string` | No | `"_id"` | The index on the remote table to match `localKey` against |
+| `schema` | `string` | No | Controller schema | Name of the schema the remote table is registered in, when it differs from the controller's schema |
+
+## Sorting and Filtering
+
+Because the join is applied to the underlying query before sorting and filtering, joined fields behave like native columns. Combine `@Joined` with `@Sortable` or `@Filter` to order or filter by the imported value.
+
+```typescript
+@Sortable()
+@Filter()
+@Joined({
+  table: User,
+  localKey: "userId",
+  remoteField: "name",
+})
+declare userName: string;
+```
+
+Joined fields are always sorted without a database index (`@Sortable` is forced to non-indexed for them), since the value comes from a runtime lookup rather than a stored column.
+
+## 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 against that schema's default instance.
+
+```typescript
+@Joined({
+  table: "users",
+  localKey: "userId",
+  remoteField: "name",
+  schema: "auth",
+})
+declare userName: string;
+```
+
+When a table class is passed, its schema is inferred from its `@RegisterTable` metadata. If both the class metadata and the explicit `schema` option specify a schema and they disagree, an error is thrown.
+
+## Joined vs. Foreign
+
+| Aspect | `@Joined` | `@Foreign` |
+| ------ | --------- | ---------- |
+| Result shape | A single scalar value flattened onto the row | The full referenced record (or plucked subset) nested under the field |
+| Access | Read-only (enforced) | Configurable via `@Access` |
+| Sort / filter | Native (join applied before sort/filter) | Not natively sortable/filterable on remote fields |
+| Multiple references | One remote field per decorator | Single or array (`multi`) references |
+
+## Next Steps
+
+See the [computed fields documentation](./11.computed.md) to generalize this merge mechanism to arbitrary in-database expressions, or the [modifiers documentation](./9.modifiers.md) to learn how automatic data transformation integrates with the Data API.

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.