@antelopejs/interface-data-api 0.1.6 → 0.1.7

package/docs/6.listable.md

@@ -0,0 +1,257 @@
+# Listable Fields
+
+## Overview
+
+The `@Listable` decorator controls which fields are included in list endpoint responses. By default, list operations only return fields explicitly marked as listable, keeping payloads lightweight. The decorator supports multiple pluck modes for different levels of detail, and list responses include built-in pagination metadata.
+
+The `@Sortable` decorator marks fields that can be used as a sorting key in list queries.
+
+## Basic Usage
+
+Fields decorated with `@Listable()` are included in list responses. Fields without this decorator are excluded from list results but still appear in single-record `get` responses (provided they have read access).
+
+```typescript
+import {
+  Access,
+  AccessMode,
+  Listable,
+  ModelReference,
+} from "@antelopejs/interface-data-api/metadata";
+
+@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.ReadOnly)
+  declare email: string;
+
+  @Access(AccessMode.ReadOnly)
+  declare biography: string; // Excluded from list, included in get
+}
+```
+
+A request to `GET /users/list` returns `_id` and `email` for each record. A request to `GET /users/get?id=user-123` returns all three fields.
+
+## Pluck Modes
+
+Pluck modes allow a single controller to serve multiple list views with different field selections. Each `@Listable` call can target a named mode.
+
+### Default Mode
+
+Calling `@Listable()` without a mode name registers the field under the default `"list"` mode.
+
+```typescript
+@Listable()
+declare name: string;
+```
+
+### Custom Modes
+
+Pass `true` and a mode name to register a field under a specific pluck mode.
+
+```typescript
+@Listable()                    // Included in default "list" mode
+@Listable(true, "detailed")   // Also included in "detailed" mode
+declare name: string;
+
+@Listable(true, "detailed")   // Only in "detailed" mode
+declare internalNotes: string;
+
+@Listable()                    // Only in default "list" mode
+declare email: string;
+```
+
+### Exclude from a Mode
+
+Pass `false` to explicitly exclude a field from a mode.
+
+```typescript
+@Listable()
+@Listable(false, "minimal")   // Excluded from "minimal" mode
+declare description: string;
+```
+
+### Access Pluck Modes via Routes
+
+Define separate routes for each pluck mode using `DefaultRoutes.WithOptions` with the `pluckMode` option.
+
+```typescript
+const routes = {
+  list: DefaultRoutes.List,
+  detailed: DefaultRoutes.WithOptions(DefaultRoutes.List, {
+    pluckMode: "detailed",
+  }),
+};
+
+@RegisterDataController()
+class UserAPI extends DataController(User, routes, Controller("/users")) {
+  @ModelReference()
+  @Model(UserModel, "my-database")
+  declare userModel: UserModel;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare name: string;
+
+  @Listable(true, "detailed")
+  @Access(AccessMode.ReadOnly)
+  declare internalNotes: string;
+}
+```
+
+- `GET /users/list` returns only `name`.
+- `GET /users/detailed` returns both `name` and `internalNotes`.
+
+### 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.
+
+```typescript
+@Listable(["firstName", "lastName"])
+@Access(AccessMode.ReadOnly)
+get fullName() {
+  return `${this.firstName} ${this.lastName}`;
+}
+```
+
+## Pagination
+
+List responses include pagination metadata. The response structure is:
+
+```typescript
+{
+  results: T[];     // Records for the current page
+  total: number;    // Total number of matching records
+  offset: number;   // Number of records skipped
+  limit: number;    // Maximum records per page
+}
+```
+
+### Query Parameters
+
+| Parameter | Default | Description |
+| --------- | ------- | ----------- |
+| `limit` | `10` | Maximum number of records to return |
+| `offset` | `0` | Number of records to skip |
+
+### Example
+
+```http
+GET /users/list?limit=2&offset=4
+```
+
+```json
+{
+  "results": [
+    { "_id": "user-5", "name": "Eve" },
+    { "_id": "user-6", "name": "Frank" }
+  ],
+  "total": 100,
+  "offset": 4,
+  "limit": 2
+}
+```
+
+### Limit Maximum Page Size
+
+Use the `maxPage` route option to cap the `limit` parameter. If a request specifies a `limit` larger than `maxPage`, the value is clamped to `maxPage`.
+
+```typescript
+const routes = {
+  list: DefaultRoutes.WithOptions(DefaultRoutes.List, { maxPage: 25 }),
+};
+
+@RegisterDataController()
+class UserAPI extends DataController(User, routes, Controller("/users")) {
+  // A request with ?limit=100 returns at most 25 records
+}
+```
+
+## Sorting with `@Sortable`
+
+The `@Sortable` decorator marks a field as eligible for use as a sorting key in list operations.
+
+```typescript
+import { Sortable } from "@antelopejs/interface-data-api/metadata";
+
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  DefaultRoutes.All,
+  Controller("/users"),
+) {
+  @ModelReference()
+  @Model(UserModel, "my-database")
+  declare userModel: UserModel;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  @Sortable()
+  declare _id: string;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  @Sortable({ noIndex: true })
+  declare name: string;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  @Sortable({ noIndex: true })
+  declare age: number;
+}
+```
+
+### Sort Query Parameters
+
+| Parameter | Description |
+| --------- | ----------- |
+| `sortKey` | The field name to sort by. Must be decorated with `@Sortable`. |
+| `sortDirection` | `"asc"` (ascending) or `"desc"` (descending). Defaults to `"asc"`. |
+
+### 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.
+
+```typescript
+@Sortable()                    // Uses database index for sorting
+declare _id: string;
+
+@Sortable({ noIndex: true })   // In-memory sort, no index required
+declare name: string;
+```
+
+### Example
+
+```http
+GET /users/list?sortKey=age&sortDirection=desc&limit=3
+```
+
+```json
+{
+  "results": [
+    { "_id": "user-1", "name": "Senior", "age": 65 },
+    { "_id": "user-2", "name": "Adult", "age": 30 },
+    { "_id": "user-3", "name": "Young", "age": 18 }
+  ],
+  "total": 3,
+  "offset": 0,
+  "limit": 3
+}
+```
+
+If `sortKey` refers to a field that is not marked with `@Sortable`, the API returns a `400 Bad Request` error.
+
+## Next Steps
+
+See the [foreign keys documentation](./7.foreign-keys.md) to learn how to establish relationships between tables.

package/docs/7.foreign-keys.md

@@ -0,0 +1,285 @@
+# Foreign Keys
+
+## Overview
+
+The `@Foreign` decorator establishes relationships between database tables in your data controller. When a field holds a foreign key (an ID referencing another table), the Data API automatically resolves the reference and includes the related record in API responses. This works for both single references and arrays of references.
+
+## Basic Usage
+
+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.
+
+```typescript
+import { Foreign } 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;
+
+  @Field("string")
+  declare email: 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;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  @Foreign(User)
+  declare userId: User;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare total: number;
+}
+```
+
+A GET request to `/orders/get?id=order-123` returns the full user object instead of a raw ID:
+
+```json
+{
+  "_id": "order-123",
+  "userId": {
+    "_id": "user-456",
+    "name": "Bob",
+    "email": "bob@example.com"
+  },
+  "total": 99.99
+}
+```
+
+## Decorator Parameters
+
+```typescript
+@Foreign(table, index?, multi?, pluck?, schema?)
+```
+
+| Parameter | Type | Required | Default | Description |
+| --------- | ---- | -------- | ------- | ----------- |
+| `table` | `Class<Table>` or `string` | Yes | - | The target table class or table name string |
+| `index` | `string` | No | `"_id"` | The index on the target table to match against |
+| `multi` | `boolean` | No | `false` | Set to `true` when the field holds an array of foreign keys |
+| `pluck` | `string[]` | No | All fields | List of fields to include from the referenced record |
+| `schema` | `string` | No | Controller schema | Name of the schema the target table is registered in, when it differs from the controller's schema |
+
+## Table Reference Methods
+
+### Class Reference
+
+Pass the table class directly. This provides IDE autocompletion, refactoring support, and compile-time validation.
+
+```typescript
+@Foreign(User)
+declare userId: User;
+```
+
+### String Reference
+
+Pass the registered table name as a string. Use this when importing the class would create circular dependencies.
+
+```typescript
+@Foreign("users")
+declare userId: User;
+```
+
+## Multi-Record References
+
+When a field stores an array of foreign key IDs, set the `multi` parameter to `true`. The API resolves each ID and returns an array of full records.
+
+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")
+class Cart extends Table {
+  @Index({ primary: true })
+  @Field("string")
+  declare _id: string;
+
+  @Field(["string"])
+  @Relation({ to: () => CartItem, many: true })
+  declare items: string[]; // Array of CartItem IDs
+}
+
+@RegisterTable("cart_items")
+class CartItem extends Table {
+  @Index({ primary: true })
+  @Field("string")
+  declare _id: string;
+
+  @Field("string")
+  declare name: string;
+
+  @Field("number")
+  declare price: number;
+}
+
+@RegisterDataController()
+class CartAPI extends DataController(
+  Cart,
+  DefaultRoutes.All,
+  Controller("/carts"),
+) {
+  @ModelReference()
+  @Model(CartModel, "my-database")
+  declare cartModel: CartModel;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  @Foreign(CartItem, undefined, true)
+  declare items: CartItem[];
+}
+```
+
+Response:
+
+```json
+{
+  "_id": "cart-123",
+  "items": [
+    { "_id": "item-1", "name": "Widget", "price": 9.99 },
+    { "_id": "item-2", "name": "Gadget", "price": 24.99 }
+  ]
+}
+```
+
+## Selective Field Retrieval with Pluck
+
+The `pluck` parameter limits which fields are included from the referenced record. This reduces response payload size when you only need specific fields.
+
+```typescript
+@RegisterDataController()
+class CartAPI extends DataController(
+  Cart,
+  DefaultRoutes.All,
+  Controller("/carts"),
+) {
+  @ModelReference()
+  @Model(CartModel, "my-database")
+  declare cartModel: CartModel;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  // Only include name and email from User
+  @Access(AccessMode.ReadOnly)
+  @Foreign(User, undefined, false, ["name", "email"])
+  declare userId: User;
+
+  // Only include name and price from CartItem
+  @Access(AccessMode.ReadOnly)
+  @Foreign(CartItem, undefined, true, ["name", "price"])
+  declare items: CartItem[];
+}
+```
+
+Response without pluck:
+
+```json
+{
+  "_id": "cart-123",
+  "userId": {
+    "_id": "user-456",
+    "name": "Bob",
+    "email": "bob@example.com",
+    "password": "hashed_value",
+    "internalNotes": "..."
+  }
+}
+```
+
+Response with `pluck: ["name", "email"]`:
+
+```json
+{
+  "_id": "cart-123",
+  "userId": {
+    "name": "Bob",
+    "email": "bob@example.com"
+  }
+}
+```
+
+## Custom Index
+
+Use the `index` parameter to match against a secondary index instead of the primary key.
+
+```typescript
+// Match userId against the "email" index on the User table
+@Foreign(User, "email")
+declare userEmail: User;
+```
+
+## Cross-Schema References
+
+By default, the target table is resolved in the same schema as the controller's table. Use the `schema` parameter to reference a table registered in a different schema. At runtime the foreign lookup is resolved against that schema's default instance.
+
+```typescript
+// Resolve userId against the User table registered in the "auth" schema
+@Access(AccessMode.ReadOnly)
+@Foreign(User, undefined, false, undefined, "auth")
+declare userId: User;
+```
+
+When a table class is passed (instead of a string), its schema is inferred from its `@RegisterTable` metadata, so the `schema` parameter is only needed to override that or when passing a string table name. If both the class metadata and the explicit `schema` option specify a schema and they disagree, an error is thrown.
+
+## Disable Foreign Key Resolution
+
+Use the `noForeign` route option to skip foreign key resolution for specific endpoints. This returns raw IDs instead of resolved objects.
+
+```typescript
+const routes = {
+  get: DefaultRoutes.Get,
+  getRaw: DefaultRoutes.WithOptions(DefaultRoutes.Get, { noForeign: "true" }),
+};
+```
+
+## Error Handling
+
+- **Missing References** - If a referenced record does not exist, the field value is `null`.
+- **Invalid IDs** - Invalid foreign key values result in `null` for the resolved field.
+- **Arrays with Missing Items** - In multi-record references, missing items appear as `null` in the array.
+
+## Next Steps
+
+See the [filters documentation](./8.filters.md) to learn how to add filtering capabilities to list endpoints.

package/docs/8.filters.md

@@ -0,0 +1,175 @@
+# Filters
+
+## Overview
+
+The `@Filter` decorator adds filtering capabilities to list endpoints. Filters allow clients to narrow down results using query parameters. The module provides a default filter with standard comparison operators and supports custom filter functions for advanced logic.
+
+## Basic Usage
+
+### Default Filter
+
+Apply `@Filter()` without arguments to enable standard comparison filtering on a field.
+
+```typescript
+import { Filter } from "@antelopejs/interface-data-api/metadata";
+
+@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)
+  @Filter()
+  declare age: number;
+
+  @Listable()
+  @Access(AccessMode.ReadWrite)
+  @Filter()
+  declare isActive: boolean;
+}
+```
+
+### Query Parameter Format
+
+Filters are applied through query parameters using the following format:
+
+```
+filter_<fieldName>=<value>
+filter_<fieldName>=<operator>:<value>
+```
+
+When no operator is specified, `eq` (equal) is used by default.
+
+### Comparison Operators
+
+| Operator | Description |
+| -------- | ----------- |
+| `eq` | Equal to (default) |
+| `ne` | Not equal to |
+| `gt` | Greater than |
+| `ge` | Greater than or equal to |
+| `lt` | Less than |
+| `le` | Less than or equal to |
+
+### Examples
+
+Retrieve users older than 30:
+
+```http
+GET /users/list?filter_age=gt:30
+```
+
+Retrieve active users:
+
+```http
+GET /users/list?filter_isActive=true
+```
+
+Combine multiple filters (users under 25 who are active):
+
+```http
+GET /users/list?filter_age=lt:25&filter_isActive=true
+```
+
+## Custom Filters
+
+For filtering logic beyond simple comparisons, pass a custom filter function to `@Filter`.
+
+### Filter Function Signature
+
+```typescript
+type FilterFunction<T, U> = (
+  context: RequestContext & { this: T },
+  proxy: ValueProxy<any>,
+  key: string,
+  value: string,
+  mode: "eq" | "ne" | "gt" | "ge" | "lt" | "le",
+  row: ValueProxy<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` |
+
+### Example: Pattern Matching Filter
+
+```typescript
+function filterByEmailDomain(
+  context: RequestContext,
+  proxy: ValueProxy<any>,
+  key: string,
+  value: string,
+  mode: string,
+  row: ValueProxy<Record<string, any>>,
+) {
+  return proxy.match(`@${value}$`);
+}
+
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  DefaultRoutes.All,
+  Controller("/users"),
+) {
+  @ModelReference()
+  @Model(UserModel, "my-database")
+  declare userModel: UserModel;
+
+  @Listable()
+  @Access(AccessMode.ReadWrite)
+  @Filter(filterByEmailDomain)
+  declare email: string;
+
+  @Listable()
+  @Access(AccessMode.ReadWrite)
+  @Filter()
+  declare age: number;
+}
+```
+
+Query for users with Gmail addresses:
+
+```http
+GET /users/list?filter_email=gmail.com
+```
+
+### 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.
+
+```typescript
+@Filter(undefined, true)   // Default filter with index optimization
+declare status: string;
+
+@Filter(customFilter, false) // Custom filter without index optimization
+declare name: string;
+```
+
+When `useIndex` is not specified:
+
+- Default filters (no custom function) automatically use the index if the field has one.
+- Custom filters default to no index usage.
+
+Index-optimized filters with an `eq` operator perform an indexed lookup instead of a full table scan, which significantly improves performance on large datasets.
+
+## 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.
+
+For raw database values, use the `row` parameter and access the field directly.