@antelopejs/interface-data-api 0.1.6 → 0.1.7

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.7",
   "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"
+    ]
   }
 }

package/skills/data-api-interface/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: data-api-interface
+description: AntelopeJS interface that generates CRUD REST endpoints from a database table via a DataController class and field decorators (Access, Listable, Mandatory, Sortable, Filter, Foreign, Joined, Computed, Validator). Use when importing @antelopejs/interface-data-api or @antelopejs/interface-data-api/metadata, when building a data controller / data API over an interface-database table, or when working with DataController, DefaultRoutes, RegisterDataController, ModelReference, or filter_/sortKey/sortDirection list query parameters.
+category: antelopejs-interface
+tags: [antelopejs, data-api, crud, rest, decorators]
+---
+
+# Data API Interface
+
+Declarative CRUD layer on top of `@antelopejs/interface-api` (HTTP) and
+`@antelopejs/interface-database(-decorators)` (storage). You build a controller class with
+`DataController(tableClass, routes, Controller("/path"))`, decorate fields to expose them, and get
+`get/list/new/edit/delete` routes generated. Everything here is consumer-side: there is no proxy
+point of its own to implement — the underlying api/database interfaces do the actual crossings, so
+your module must also import those peer interfaces.
+
+## Imports
+
+```typescript
+import { DataController, DefaultRoutes, RegisterDataController, GetDataControllerMeta } from "@antelopejs/interface-data-api";
+import { Access, AccessMode, Listable, Mandatory, Optional, Sortable, Filter, Foreign, Joined, Computed, Validator, ModelReference, ModifierKey } from "@antelopejs/interface-data-api/metadata";
+import { Parameters, Query, Validation } from "@antelopejs/interface-data-api/components";
+```
+
+`/components` is only needed for custom route callbacks (query building, validation helpers).
+
+## Minimal consumption example
+
+```typescript
+import { Controller } from "@antelopejs/interface-api";
+import { DataController, DefaultRoutes, RegisterDataController } from "@antelopejs/interface-data-api";
+import { Access, AccessMode, Listable, Mandatory, ModelReference, Sortable } from "@antelopejs/interface-data-api/metadata";
+import { BasicDataModel, Field, Model, RegisterTable, Table } from "@antelopejs/interface-database-decorators";
+
+@RegisterTable("tasks", "default")
+class Task extends Table {
+  declare _id: string;
+
+  @Field("string")
+  declare summary: string;
+}
+
+class TaskModel extends BasicDataModel(Task, "tasks") {}
+
+@RegisterDataController()
+class TaskAPI extends DataController(Task, DefaultRoutes.All, Controller("/tasks")) {
+  @ModelReference()
+  @Model(TaskModel, "my-database")
+  declare taskModel: TaskModel;
+
+  @Listable()
+  @Access(AccessMode.ReadOnly)
+  declare _id: string;
+
+  @Listable()
+  @Sortable()
+  @Mandatory("new")
+  @Access(AccessMode.ReadWrite)
+  declare summary: string;
+}
+```
+
+This exposes `GET /tasks/get?id=`, `GET /tasks/list`, `POST /tasks/new`, `PUT /tasks/edit?id=`,
+`DELETE /tasks/delete?id=` (repeat `id` to delete several).
+
+## Gotchas
+
+- `@RegisterDataController()` is mandatory: it wires field decorators, parameter providers, and
+  routes. A `@ModelReference()` property holding a `@Model` instance is required too (`Query.GetModel`
+  throws 500 without it).
+- Fields with no decorator are invisible to the API — neither returned nor writable; visibility
+  requires `@Access`. `@Optional()` only registers a field as not-mandatory (it does not expose it).
+- `list` responds `{ results, total, offset, limit }`. `limit` defaults to 10 and is capped at 100
+  (`maxPage`). Sorting uses `sortKey`/`sortDirection` query params and requires `@Sortable` on the
+  field (400 otherwise). List responses only include `@Listable` fields unless `noPluck` is set.
+- Filters come from `filter_<name>=<mode>:<value>` query params (plain value means `eq`); modes are
+  `eq|ne|gt|ge|lt|le` (the default filter compares the raw query-string value — pass a custom filter
+  function to cast for numeric ranges). Only fields declared with `@Filter()` are filterable.
+- `@Joined` and `@Computed` fields are materialized in-database, so `@Sortable` and `@Filter()` work
+  efficiently on them — but those decorators must still be applied explicitly. Such fields are
+  forced read-only and to non-indexed sorting.
+- Route selection: pass a subset like `{ get: DefaultRoutes.Get, list: DefaultRoutes.List }` instead
+  of `DefaultRoutes.All`; use `DefaultRoutes.WithOptions(route, options, endpoint)` to rename an
+  endpoint or preset parameter options.
+- `@Access` accepts per-action overrides, e.g. `@Access(AccessMode.ReadOnly, { edit: AccessMode.ReadWrite })`.
+
+## Deeper reference
+
+See this package's `docs/` chapters — Introduction, Data Controllers, Routes, Access Rights,
+Validators, Listable Fields, Foreign Keys, Filters, Modifiers, Joined Fields, Computed Fields — and
+the shipped `.d.ts` files for exact signatures. Do not duplicate them here.