@antelopejs/interface-data-api 0.1.6 → 0.1.8

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.

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.