@antelopejs/interface-data-api 0.1.9 → 0.2.0

package/docs/5.validators.md

@@ -8,7 +8,7 @@ Validators provide field-level data integrity checks that run automatically duri
 
 ### 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.
+The `@Validator` decorator accepts a function that receives the field value and returns `true` if valid or `false` if invalid. It can instead return a parse result (see [Parsed Values](#parsed-values)) so that the parsed value is written. The function can also return a `Promise` of either for asynchronous validation.
 
 ```typescript
 import { Validator } from "@antelopejs/interface-data-api/metadata";
@@ -36,16 +36,34 @@ class UserAPI extends DataController(
 ### Validation Function Signature
 
 ```typescript
-type ValidatorFunction = (value: unknown) => boolean | Promise<boolean>;
+type FieldValidator = (
+  value: unknown,
+) => FieldValidationResult | Promise<FieldValidationResult>;
+
+type FieldValidationResult =
+  boolean | { success: true; data: unknown } | { success: false };
 ```
 
 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.
+- Returns `true` when the value is valid: the raw value is written.
+- Returns `{ success: true, data }` when the value is valid: `data` is written instead of the raw value.
+- Returns `false` or `{ success: 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).
 
+### Parsed Values
+
+A validator returning a parse result writes the parsed value on both `new` and `edit`. The result has the shape of zod's `safeParse`, so a zod schema can be used directly:
+
+```typescript
+const startsAtSchema = z.coerce.date();
+
+@Access(AccessMode.ReadWrite)
+@Validator((value) => startsAtSchema.safeParseAsync(value))
+declare startsAt: Date; // "2026-01-15" is stored as a Date
+```
+
 ## Common Validation Patterns
 
 ### String Validation
@@ -112,7 +130,10 @@ 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.
+The `@Mandatory` decorator specifies which operations require a field in the request body. Unlike `@Validator`, which checks field content, `@Mandatory` only verifies that the field is provided:
+
+- On `"edit"`, the body only carries the fields to update: a mandatory field absent from the body keeps its stored value and is accepted, while a mandatory field cleared by the body (`null`, `""` or `[]`) is rejected.
+- On any other operation (such as `"new"`), a mandatory field must be present in the body.
 
 ```typescript
 import { Mandatory } from "@antelopejs/interface-data-api/metadata";
@@ -152,9 +173,9 @@ class UserAPI extends DataController(
 
 In this example:
 
-- `email` must be provided in both create and update requests.
+- `email` must be provided when creating a record and cannot be cleared when editing one.
 - `password` is required only when creating a new record.
-- `status` is required only when editing an existing record.
+- `status` cannot be cleared when editing an existing record.
 - `notes` is always optional.
 
 ### Skip Mandatory Validation
@@ -177,7 +198,7 @@ class UserAPI extends DataController(User, routes, Controller("/users")) {
 }
 ```
 
-Requests to `/users/edit` require `status`, while requests to `/users/patchEdit` do not.
+Requests to `/users/edit` cannot clear `status`, while requests to `/users/patchEdit` can.
 
 ## The `@Optional` Decorator
 

package/docs/6.listable.md

@@ -140,10 +140,10 @@ List responses include pagination metadata. The response structure is:
 
 ### Query Parameters
 
-| Parameter | Default | Description |
-| --------- | ------- | ----------- |
-| `limit` | `10` | Maximum number of records to return |
-| `offset` | `0` | Number of records to skip |
+| Parameter | Default | Description                         |
+| --------- | ------- | ----------------------------------- |
+| `limit`   | `10`    | Maximum number of records to return |
+| `offset`  | `0`     | Number of records to skip           |
 
 ### Example
 
@@ -214,9 +214,9 @@ class UserAPI extends DataController(
 
 ### Sort Query Parameters
 
-| Parameter | Description |
-| --------- | ----------- |
-| `sortKey` | The field name to sort by. Must be decorated with `@Sortable`. |
+| 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

package/docs/7.foreign-keys.md

@@ -90,13 +90,13 @@ A GET request to `/orders/get?id=order-123` returns the full user object instead
 @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 |
+| 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
 

package/docs/8.filters.md

@@ -52,14 +52,14 @@ 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 |
+| 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
 
@@ -98,14 +98,14 @@ type FilterFunction<T, 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` |
+| 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
 

package/docs/9.modifiers.md

@@ -20,8 +20,8 @@ import { ModifierKey } from "@antelopejs/interface-data-api/metadata";
 @ModifierKey(modifierClass: typeof ContainerModifier<any>)
 ```
 
-| Parameter | Description |
-| --------- | ----------- |
+| Parameter       | Description                                                                   |
+| --------------- | ----------------------------------------------------------------------------- |
 | `modifierClass` | The modifier class that requires a runtime key (e.g., `LocalizationModifier`) |
 
 ### Example: Localized Content

package/package.json

@@ -1,26 +1,35 @@
 {
   "name": "@antelopejs/interface-data-api",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "AntelopeJS interface for data API with CRUD controllers and route generation",
   "keywords": [
     "antelopejs",
-    "interface",
+    "crud",
     "data-api",
-    "crud"
+    "interface"
   ],
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AntelopeJS/interface-data-api.git"
   },
-  "license": "Apache-2.0",
-  "packageManager": "pnpm@10.6.5",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "files": [
     "dist",
     "docs",
     "skills"
   ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "components": [
+        "dist/components.d.ts"
+      ],
+      "metadata": [
+        "dist/metadata.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -32,54 +41,53 @@
     },
     "./package.json": "./package.json"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "build": "rimraf dist && tsc",
-    "format": "biome format --write .",
-    "lint:fix": "biome check --write .",
-    "lint": "biome check .",
+    "format": "oxfmt .",
+    "lint:fix": "oxlint --fix",
+    "lint": "oxlint",
     "prepack": "pnpm run build",
     "release": "pnpm run lint && pnpm run prepack && release-it",
-    "test": "pnpm run build && ajs module test ."
+    "test": "pnpm run build && ajs module test .",
+    "format:check": "oxfmt --check .",
+    "knip": "knip"
   },
   "devDependencies": {
-    "@antelopejs/interface-api": "^0.0.5",
-    "@antelopejs/interface-api-util": "^0.1.1",
-    "@antelopejs/interface-core": "^0.0.5",
-    "@antelopejs/interface-database": "^0.1.3",
-    "@antelopejs/interface-database-decorators": "^0.1.4",
-    "@biomejs/biome": "2.3.2",
+    "@antelopejs/core": "^1.13.4",
+    "@antelopejs/interface-api": "^0.0.13",
+    "@antelopejs/interface-api-util": "^0.1.2",
+    "@antelopejs/interface-core": "^0.1.1",
+    "@antelopejs/interface-database": "^0.1.7",
+    "@antelopejs/interface-database-decorators": "^0.1.6",
+    "@antelopejs/tooling-configs": "^0.0.6",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
     "@types/semver": "^7.7.1",
     "chai": "^4.5.0",
+    "eslint-plugin-perfectionist": "^5.11.0",
+    "knip": "^6.34.0",
     "mongodb-memory-server-core": "^10.4.3",
+    "oxfmt": "^0.66.0",
+    "oxlint": "1.81.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "release-it": "^19.2.4",
     "release-it-changelogen": "^0.1.0",
     "rimraf": "^6.1.3",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@antelopejs/interface-api": ">=0.0.3 <1.0.0",
-    "@antelopejs/interface-api-util": ">=0.0.4 <1.0.0",
-    "@antelopejs/interface-core": ">=0.0.3 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.2 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.1 <1.0.0"
-  },
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
-  },
-  "typesVersions": {
-    "*": {
-      "components": [
-        "dist/components.d.ts"
-      ],
-      "metadata": [
-        "dist/metadata.d.ts"
-      ]
-    }
+    "@antelopejs/interface-api": ">=0.0.13 <1.0.0",
+    "@antelopejs/interface-api-util": ">=0.1.2 <1.0.0",
+    "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.7 <1.0.0",
+    "@antelopejs/interface-database-decorators": ">=0.1.6 <1.0.0"
   },
+  "packageManager": "pnpm@10.6.5",
   "antelopeJs": {
     "standalone": true,
     "test": "src/antelope.test.ts",

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

@@ -17,9 +17,32 @@ 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";
+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).
@@ -28,9 +51,26 @@ import { Parameters, Query, Validation } from "@antelopejs/interface-data-api/co
 
 ```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";
+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 {
@@ -43,7 +83,11 @@ class Task extends Table {
 class TaskModel extends BasicDataModel(Task, "tasks") {}
 
 @RegisterDataController()
-class TaskAPI extends DataController(Task, DefaultRoutes.All, Controller("/tasks")) {
+class TaskAPI extends DataController(
+  Task,
+  DefaultRoutes.All,
+  Controller("/tasks"),
+) {
   @ModelReference()
   @Model(TaskModel, "my-database")
   declare taskModel: TaskModel;
@@ -67,7 +111,8 @@ This exposes `GET /tasks/get?id=`, `GET /tasks/list`, `POST /tasks/new`, `PUT /t
 
 - `@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).
+  throws 500 without it). A controller derived from another data controller inherits it unless it
+  declares its own.
 - 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
@@ -83,6 +128,11 @@ This exposes `GET /tasks/get?id=`, `GET /tasks/list`, `POST /tasks/new`, `PUT /t
   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 })`.
+- `edit` is a partial update: a field absent from the body is left unchanged, `null` clears it, and
+  setters only run for the fields present. `@Mandatory("edit")` rejects a field cleared by the body
+  (`null`, `""`, `[]`), not an absent one. `new` still writes every writable field and runs every setter.
+- A `@Validator` may return a parse result `{ success, data }` (e.g. zod's `safeParseAsync(value)`)
+  instead of a boolean: `data` is then written in place of the raw value.
 
 ## Deeper reference