@antelopejs/interface-data-api 0.1.6 → 0.1.7

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.

package/docs/4.access-rights.md

@@ -0,0 +1,148 @@
+# Access Rights
+
+## Overview
+
+The `@Access` decorator controls how fields are read and written through the API. Each field can be set to read-only, write-only, or read-write, providing fine-grained control over data exposure. Access modes can also be overridden on a per-action basis, allowing different permissions for `get`, `list`, `new`, and `edit` operations.
+
+## Access Modes
+
+The `AccessMode` enum defines three permission levels:
+
+```typescript
+import { Access, AccessMode } from "@antelopejs/interface-data-api/metadata";
+```
+
+| Mode | Value | Description |
+| ---- | ----- | ----------- |
+| `AccessMode.ReadOnly` | `1` | Field appears in GET and LIST responses but is ignored in POST and PUT bodies |
+| `AccessMode.WriteOnly` | `2` | Field is accepted in POST and PUT bodies but never appears in responses |
+| `AccessMode.ReadWrite` | `3` | Field is both readable and writable |
+
+## Basic Usage
+
+### Read-Only Fields
+
+Read-only fields appear in API responses but cannot be modified through create or update requests. Values sent for these fields in request bodies are silently ignored.
+
+```typescript
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  DefaultRoutes.All,
+  Controller("/users"),
+) {
+  @ModelReference()
+  @Model(UserModel, "my-database")
+  declare userModel: UserModel;
+
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  @Access(AccessMode.ReadOnly)
+  declare createdAt: string;
+
+  @Access(AccessMode.ReadWrite)
+  declare name: string;
+}
+```
+
+A PUT request to `/users/edit?id=user-123` with `{ "createdAt": "2025-01-01", "name": "Alice" }` updates only `name`. The `createdAt` field is ignored.
+
+### Write-Only Fields
+
+Write-only fields accept input during create and update operations but are never included in API responses. This is useful for sensitive data like passwords.
+
+```typescript
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  DefaultRoutes.All,
+  Controller("/users"),
+) {
+  @ModelReference()
+  @Model(UserModel, "my-database")
+  declare userModel: UserModel;
+
+  @Access(AccessMode.ReadWrite)
+  declare name: string;
+
+  @Access(AccessMode.ReadWrite)
+  declare email: string;
+
+  @Access(AccessMode.WriteOnly)
+  declare password: string;
+}
+```
+
+A GET request to `/users/get?id=user-123` returns `name` and `email` but never includes `password`:
+
+```json
+{
+  "name": "Bob",
+  "email": "bob@example.com"
+}
+```
+
+### Read-Write Fields
+
+Read-write fields are fully accessible: they appear in responses and accept input in request bodies.
+
+```typescript
+@Access(AccessMode.ReadWrite)
+declare email: string;
+
+@Access(AccessMode.ReadWrite)
+declare name: string;
+```
+
+## Per-Action Overrides
+
+The `@Access` decorator accepts an optional second argument to override the access mode for specific actions. This allows a field to behave differently depending on the operation being performed.
+
+```typescript
+@Access(defaultMode: AccessMode, overrides?: Record<string, AccessMode>)
+```
+
+The `overrides` object maps action names (`"get"`, `"list"`, `"new"`, `"edit"`) to an `AccessMode` value. Actions not listed in the overrides use the default mode.
+
+### Example: Writable on Create, Read-Only on Edit
+
+```typescript
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  DefaultRoutes.All,
+  Controller("/users"),
+) {
+  @ModelReference()
+  @Model(UserModel, "my-database")
+  declare userModel: UserModel;
+
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  @Access(AccessMode.ReadWrite)
+  declare name: string;
+
+  // role can be set when creating, but cannot be changed during edit
+  @Access(AccessMode.ReadWrite, { edit: AccessMode.ReadOnly })
+  declare role: string;
+
+  // age is read-only by default, but writable during creation
+  @Access(AccessMode.ReadOnly, { new: AccessMode.ReadWrite })
+  declare age: number;
+}
+```
+
+In this configuration:
+
+- `role` is readable and writable in all operations except `edit`, where it becomes read-only.
+- `age` is read-only by default but can be set during `new` (create) operations.
+
+## Fields Without `@Access`
+
+Fields declared without the `@Access` decorator are not exposed through the API at all. They do not appear in responses and are not accepted in request bodies. To include a field in the API, you must explicitly set its access mode.
+
+## Next Steps
+
+See the [validators documentation](./5.validators.md) to learn how to enforce validation rules on field values.

package/docs/5.validators.md

@@ -0,0 +1,204 @@
+# Validators
+
+## Overview
+
+Validators provide field-level data integrity checks that run automatically during create and update operations. The `@Validator` decorator attaches a custom validation function to a field, while `@Mandatory` ensures that specific fields are present in request bodies for given operations. The `@Optional` decorator explicitly marks a field as not mandatory.
+
+## The `@Validator` Decorator
+
+### Basic Usage
+
+The `@Validator` decorator accepts a function that receives the field value and returns `true` if valid or `false` if invalid. The function can also return a `Promise<boolean>` for asynchronous validation.
+
+```typescript
+import { Validator } from "@antelopejs/interface-data-api/metadata";
+
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  DefaultRoutes.All,
+  Controller("/users"),
+) {
+  @ModelReference()
+  @Model(UserModel, "my-database")
+  declare userModel: UserModel;
+
+  @Access(AccessMode.ReadWrite)
+  @Validator((value) => typeof value === "string" && value.trim().length > 0)
+  declare name: string;
+
+  @Access(AccessMode.ReadWrite)
+  @Validator((value) => typeof value === "number" && value >= 0 && value <= 120)
+  declare age: number;
+}
+```
+
+### Validation Function Signature
+
+```typescript
+type ValidatorFunction = (value: unknown) => boolean | Promise<boolean>;
+```
+
+The function:
+
+- Receives the raw field value from the request body.
+- Returns `true` when the value is valid.
+- Returns `false` when the value is invalid, which triggers a `400 Bad Request` response.
+- Should handle unexpected types gracefully (e.g., check `typeof` before accessing properties).
+
+## Common Validation Patterns
+
+### String Validation
+
+```typescript
+// Minimum length
+@Validator((value) => typeof value === "string" && value.length >= 2)
+declare firstName: string;
+
+// Email format
+const emailRegex = /^[\w](\.?[\w-]+)*@(?:[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*\.)+[a-zA-Z]{2,}$/;
+@Validator((value) => typeof value === "string" && emailRegex.test(value))
+declare email: string;
+
+// Enum-like constraint
+const VALID_ROLES = ["admin", "editor", "viewer"];
+@Validator((value) => typeof value === "string" && VALID_ROLES.includes(value))
+declare role: string;
+```
+
+### Number Validation
+
+```typescript
+// Range
+@Validator((value) => typeof value === "number" && value >= 0 && value <= 120)
+declare age: number;
+
+// Integer only
+@Validator((value) => typeof value === "number" && Number.isInteger(value))
+declare quantity: number;
+
+// Positive
+@Validator((value) => typeof value === "number" && value > 0)
+declare price: number;
+```
+
+### Date Validation
+
+```typescript
+// Valid date string
+@Validator((value) => typeof value === "string" && !isNaN(Date.parse(value)))
+declare birthDate: string;
+
+// Future date only
+@Validator((value) =>
+  typeof value === "string" &&
+  !isNaN(Date.parse(value)) &&
+  new Date(value) > new Date()
+)
+declare appointmentDate: string;
+```
+
+### Async Validation
+
+```typescript
+// Check uniqueness against the database
+@Validator(async (value) => {
+  if (typeof value !== "string") return false;
+  const existing = await lookupByEmail(value);
+  return !existing;
+})
+declare email: string;
+```
+
+## The `@Mandatory` Decorator
+
+The `@Mandatory` decorator specifies which operations require a field to be present in the request body. Unlike `@Validator`, which checks field content, `@Mandatory` only verifies that the field exists in the payload.
+
+```typescript
+import { Mandatory } from "@antelopejs/interface-data-api/metadata";
+```
+
+### Usage
+
+Pass one or more operation names as arguments. Common operation names are `"new"` (create) and `"edit"` (update).
+
+```typescript
+@RegisterDataController()
+class UserAPI extends DataController(
+  User,
+  DefaultRoutes.All,
+  Controller("/users"),
+) {
+  @ModelReference()
+  @Model(UserModel, "my-database")
+  declare userModel: UserModel;
+
+  @Access(AccessMode.ReadWrite)
+  @Mandatory("new", "edit")
+  declare email: string;
+
+  @Access(AccessMode.WriteOnly)
+  @Mandatory("new")
+  declare password: string;
+
+  @Access(AccessMode.ReadWrite)
+  @Mandatory("edit")
+  declare status: string;
+
+  @Access(AccessMode.ReadWrite)
+  declare notes: string; // Not mandatory for any operation
+}
+```
+
+In this example:
+
+- `email` must be provided in both create and update requests.
+- `password` is required only when creating a new record.
+- `status` is required only when editing an existing record.
+- `notes` is always optional.
+
+### Skip Mandatory Validation
+
+Use `DefaultRoutes.WithOptions` with the `noMandatory` option to create an endpoint that skips mandatory field checks.
+
+```typescript
+const routes = {
+  edit: DefaultRoutes.Edit,
+  patchEdit: DefaultRoutes.WithOptions(DefaultRoutes.Edit, {
+    noMandatory: "true",
+  }),
+};
+
+@RegisterDataController()
+class UserAPI extends DataController(User, routes, Controller("/users")) {
+  @Access(AccessMode.ReadWrite)
+  @Mandatory("edit")
+  declare status: string;
+}
+```
+
+Requests to `/users/edit` require `status`, while requests to `/users/patchEdit` do not.
+
+## The `@Optional` Decorator
+
+The `@Optional` decorator explicitly marks a field as not mandatory for any operation. Use it on fields that have no other decorators but still need to be recognized by the Data API metadata system.
+
+```typescript
+import { Optional } from "@antelopejs/interface-data-api/metadata";
+
+@Optional()
+declare notes: string;
+```
+
+## Error Handling
+
+When validation or mandatory checks fail, the API returns a `400 Bad Request` response with a plain text message describing the issue.
+
+- **Mandatory failure:** `"Missing mandatory fields: email, password"`
+- **Validator failure:** `"Invalid field type(s): age, email"`
+
+All fields are checked, and the error message lists every field that failed validation.
+
+## Next Steps
+
+See the [listable fields documentation](./6.listable.md) to learn how to control field visibility in list operations and configure pagination.