@antelopejs/interface-data-api 0.1.10 → 0.2.0

package/dist/tests/index/inheritance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/index/inheritance.test.js

@@ -0,0 +1,122 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const interface_api_1 = require("@antelopejs/interface-api");
+const metadata_1 = require("@antelopejs/interface-data-api/metadata");
+const interface_data_api_1 = require("@antelopejs/interface-data-api");
+const interface_database_decorators_1 = require("@antelopejs/interface-database-decorators");
+const utils_1 = require("../utils");
+const NOTE_TABLE = "inheritance-notes";
+const ARCHIVE_TABLE = "inheritance-archives";
+const SCHEMA = "default";
+const DERIVED_LOCATION = "inheritance-derived";
+const OVERRIDE_LOCATION = "inheritance-override";
+const OK = 200;
+const NOT_FOUND = 404;
+let Note = class Note extends interface_database_decorators_1.Table {
+};
+__decorate([
+    (0, interface_database_decorators_1.Field)("string"),
+    __metadata("design:type", String)
+], Note.prototype, "title", void 0);
+Note = __decorate([
+    (0, interface_database_decorators_1.RegisterTable)(NOTE_TABLE, SCHEMA)
+], Note);
+class NoteModel extends (0, interface_database_decorators_1.BasicDataModel)(Note, NOTE_TABLE) {
+}
+let Archive = class Archive extends interface_database_decorators_1.Table {
+};
+__decorate([
+    (0, interface_database_decorators_1.Field)("string"),
+    __metadata("design:type", String)
+], Archive.prototype, "title", void 0);
+Archive = __decorate([
+    (0, interface_database_decorators_1.RegisterTable)(ARCHIVE_TABLE, SCHEMA)
+], Archive);
+class ArchiveModel extends (0, interface_database_decorators_1.BasicDataModel)(Archive, ARCHIVE_TABLE) {
+}
+class NoteBaseAPI extends (0, interface_data_api_1.DataController)(Note, {}, (0, interface_api_1.Controller)("/inheritance-base")) {
+}
+__decorate([
+    (0, metadata_1.ModelReference)(),
+    (0, interface_database_decorators_1.Model)(NoteModel),
+    __metadata("design:type", NoteModel)
+], NoteBaseAPI.prototype, "model", void 0);
+__decorate([
+    (0, metadata_1.Listable)(),
+    (0, metadata_1.Access)(metadata_1.AccessMode.ReadOnly),
+    __metadata("design:type", String)
+], NoteBaseAPI.prototype, "_id", void 0);
+__decorate([
+    (0, metadata_1.Listable)(),
+    (0, metadata_1.Access)(metadata_1.AccessMode.ReadWrite),
+    __metadata("design:type", String)
+], NoteBaseAPI.prototype, "title", void 0);
+let _DerivedNoteAPI = class _DerivedNoteAPI extends (0, interface_data_api_1.DataController)(Note, interface_data_api_1.DefaultRoutes.All, (0, interface_api_1.Controller)(`/${DERIVED_LOCATION}`, NoteBaseAPI)) {
+};
+_DerivedNoteAPI = __decorate([
+    (0, interface_data_api_1.RegisterDataController)()
+], _DerivedNoteAPI);
+let _ArchiveAPI = class _ArchiveAPI extends (0, interface_data_api_1.DataController)(Archive, { get: interface_data_api_1.DefaultRoutes.Get }, (0, interface_api_1.Controller)(`/${OVERRIDE_LOCATION}`, NoteBaseAPI)) {
+};
+__decorate([
+    (0, metadata_1.ModelReference)(),
+    (0, interface_database_decorators_1.Model)(ArchiveModel),
+    __metadata("design:type", ArchiveModel)
+], _ArchiveAPI.prototype, "archiveModel", void 0);
+_ArchiveAPI = __decorate([
+    (0, interface_data_api_1.RegisterDataController)()
+], _ArchiveAPI);
+describe("Derived data controllers", () => {
+    let noteModel;
+    let archiveModel;
+    before(async () => {
+        await (0, interface_database_decorators_1.RegisterSchema)(SCHEMA);
+        noteModel = new NoteModel((0, utils_1.getSchemaInstance)(SCHEMA));
+        archiveModel = new ArchiveModel((0, utils_1.getSchemaInstance)(SCHEMA));
+    });
+    it("inherits the parent model reference for get and list", async () => {
+        const [id] = await noteModel.insert({ title: "Inherited" });
+        const get = await (0, utils_1.getRequest)(DERIVED_LOCATION, { id });
+        (0, chai_1.expect)(get.status).to.equal(OK);
+        (0, chai_1.expect)(await get.json()).to.deep.equal({ _id: id, title: "Inherited" });
+        const list = await (0, utils_1.listRequest)(DERIVED_LOCATION);
+        (0, chai_1.expect)(list.status).to.equal(OK);
+        const { results } = (await list.json());
+        (0, chai_1.expect)(results).to.deep.include({ _id: id, title: "Inherited" });
+    });
+    it("inherits the parent model reference for new, edit and delete", async () => {
+        const created = await (0, utils_1.newRequest)(DERIVED_LOCATION, { title: "Created" });
+        (0, chai_1.expect)(created.status).to.equal(OK);
+        const [id] = (await created.json());
+        (0, chai_1.expect)(await noteModel.get(id)).to.have.property("title", "Created");
+        const edited = await (0, utils_1.editRequest)(DERIVED_LOCATION, { title: "Edited" }, { id });
+        (0, chai_1.expect)(edited.status).to.equal(OK);
+        (0, chai_1.expect)(await noteModel.get(id)).to.have.property("title", "Edited");
+        const deleted = await (0, utils_1.deleteRequest)(DERIVED_LOCATION, { id });
+        (0, chai_1.expect)(deleted.status).to.equal(OK);
+        (0, chai_1.expect)(await noteModel.get(id)).to.equal(undefined);
+    });
+    it("prefers the child's own model reference over the parent's", async () => {
+        const [archiveId] = await archiveModel.insert({ title: "Archived" });
+        const [noteId] = await noteModel.insert({ title: "Note" });
+        const archive = await (0, utils_1.getRequest)(OVERRIDE_LOCATION, { id: archiveId });
+        (0, chai_1.expect)(archive.status).to.equal(OK);
+        (0, chai_1.expect)(await archive.json()).to.deep.equal({
+            _id: archiveId,
+            title: "Archived",
+        });
+        const note = await (0, utils_1.getRequest)(OVERRIDE_LOCATION, { id: noteId });
+        (0, chai_1.expect)(note.status).to.equal(NOT_FOUND);
+    });
+});
+//# sourceMappingURL=inheritance.test.js.map

package/dist/tests/index/inheritance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inheritance.test.js","sourceRoot":"","sources":["../../../src/tests/index/inheritance.test.ts"],"names":[],"mappings":"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"}

package/docs/2.data-controllers.md

@@ -94,7 +94,7 @@ Every data controller requires the following elements:
 1. **Table Class** - A database table decorated with `@RegisterTable`, defining the schema.
 2. **Route Definitions** - Which operations to expose. Use `DefaultRoutes.All` or a custom selection.
 3. **Controller Base** - The URL path prefix, created with `Controller("/path")`.
-4. **Model Reference** - A property decorated with `@ModelReference()` that holds a database model instance. This model provides the actual database operations (insert, get, update, delete).
+4. **Model Reference** - A property decorated with `@ModelReference()` that holds a database model instance. This model provides the actual database operations (insert, get, update, delete). A controller derived from another data controller (for example `Controller("/path", ParentController)`) inherits its model reference unless it declares its own.
 
 ## The `@RegisterDataController` Decorator
 

package/docs/3.routes.md

@@ -144,6 +144,8 @@ Content-Type: application/json
 ["user-789"]
 ```
 
+Every writable field is written: a field absent from the body is written as `undefined`, and every writable setter of the controller runs (with `undefined` for absent fields). A body that is not valid JSON or not a JSON object is rejected with `400 Bad Request`.
+
 Before inserting, the `insert` event is triggered on any table modifiers attached to the database table.
 
 ### Edit
@@ -158,7 +160,17 @@ Updates an existing record by its identifier.
 | --------- | -------- | ----------------- |
 | `id`      | Yes      | Record identifier |
 
-**Body:** JSON object with fields to update.
+**Body:** JSON object with the fields to update. Only the fields present in the body are written:
+
+| In the body | Effect on the field |
+| ----------- | ------------------- |
+| key absent  | unchanged           |
+| `null`      | cleared             |
+| a value     | set                 |
+
+Writable setters only run for the fields present in the body. Modifier fields (localized, encrypted…) absent from the body keep their stored value in every language.
+
+A missing record answers `404 Not Found`. A body that is not valid JSON or not a JSON object is rejected with `400 Bad Request`.
 
 **Example:**
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-data-api",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "description": "AntelopeJS interface for data API with CRUD controllers and route generation",
   "keywords": [
     "antelopejs",

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

@@ -111,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
@@ -127,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