@antelopejs/interface-data-api 0.1.6 → 0.1.8

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.

package/docs/9.modifiers.md

@@ -0,0 +1,137 @@
+# Modifiers
+
+## Overview
+
+Modifiers from `@antelopejs/interface-database-decorators` work automatically with the Data API. Modifiers such as `@Hashed` or `@Encrypted` transform data transparently during read and write operations without any additional configuration in the data controller.
+
+Some modifiers require a runtime parameter (for example, a locale key for localization). The `@ModifierKey` decorator bridges this gap by mapping a controller field to a modifier's runtime key.
+
+## The `@ModifierKey` Decorator
+
+Use `@ModifierKey` when a modifier needs a runtime value that varies per request. The decorator associates a controller field with a specific modifier class. The field's value at request time is passed to the modifier during lock and unlock operations.
+
+```typescript
+import { ModifierKey } from "@antelopejs/interface-data-api/metadata";
+```
+
+### Signature
+
+```typescript
+@ModifierKey(modifierClass: typeof ContainerModifier<any>)
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `modifierClass` | The modifier class that requires a runtime key (e.g., `LocalizationModifier`) |
+
+### Example: Localized Content
+
+The `LocalizationModifier` requires a locale identifier to determine which translation to store or retrieve. Use `@ModifierKey` to supply this value from an HTTP header.
+
+```typescript
+import { Controller, Parameter } from "@antelopejs/interface-api";
+import {
+  DataController,
+  DefaultRoutes,
+  RegisterDataController,
+} from "@antelopejs/interface-data-api";
+import {
+  Access,
+  AccessMode,
+  Listable,
+  ModelReference,
+  ModifierKey,
+} from "@antelopejs/interface-data-api/metadata";
+import {
+  BasicDataModel,
+  Field,
+  Index,
+  Localized,
+  LocalizationModifier,
+  Model,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+
+@RegisterTable("content")
+class Content extends Table.with(LocalizationModifier) {
+  @Index({ primary: true })
+  @Field("string")
+  declare _id: string;
+
+  @Localized()
+  @Field("string")
+  declare title: string;
+
+  @Localized()
+  @Field("string")
+  declare description: string;
+}
+
+class ContentModel extends BasicDataModel(Content, "content") {}
+
+@RegisterDataController()
+class ContentAPI extends DataController(
+  Content,
+  DefaultRoutes.All,
+  Controller("/content"),
+) {
+  @ModelReference()
+  @Model(ContentModel, "my-database")
+  declare contentModel: ContentModel;
+
+  @Parameter("x-content-language", "header")
+  @ModifierKey(LocalizationModifier)
+  declare language: string;
+
+  @Listable()
+  @Access(AccessMode.ReadWrite)
+  declare title: string;
+
+  @Listable()
+  @Access(AccessMode.ReadWrite)
+  declare description: string;
+}
+```
+
+### How It Works
+
+1. The HTTP request includes the header `x-content-language: fr`.
+2. The `language` property receives the value `"fr"`.
+3. During write operations, the modifier uses `"fr"` as the key to store the localized value.
+4. During read operations, the modifier uses `"fr"` to retrieve the correct localized value.
+
+**Example request:**
+
+```http
+POST /content/new
+x-content-language: fr
+Content-Type: application/json
+
+{
+  "title": "Titre en francais",
+  "description": "Description en francais"
+}
+```
+
+The data is stored under the `"fr"` locale key. A subsequent request with `x-content-language: en` accesses different localized values for the same record.
+
+> **Note:** Most modifiers (such as `@Hashed` and `@Encrypted`) do not require `@ModifierKey`. Only modifiers that need a runtime parameter per request require this decorator.
+
+## Integration with Other Features
+
+### Foreign Keys
+
+Modifiers work automatically with foreign key relationships. When the Data API resolves foreign records, modifier-protected fields on those records are properly unlocked during retrieval. See the [foreign keys documentation](./7.foreign-keys.md) for details.
+
+### 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.
+
+## Learn More
+
+For the full list of available modifiers and instructions on creating custom ones, see the [@antelopejs/interface-database-decorators documentation](https://github.com/AntelopeJS/interface-database-decorators).
+
+## Next Steps
+
+See the [joined fields documentation](./10.joined.md) to learn how to flatten a remote field onto rows for native sorting and filtering.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-data-api",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "AntelopeJS interface for data API with CRUD controllers and route generation",
   "keywords": [
     "antelopejs",
@@ -17,7 +17,9 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "skills"
   ],
   "exports": {
     ".": {
@@ -79,6 +81,9 @@
   },
   "antelopeJs": {
     "standalone": true,
-    "test": "src/antelope.test.ts"
+    "test": "src/antelope.test.ts",
+    "skills": [
+      "./skills"
+    ]
   }
 }