@antelopejs/interface-data-api 0.3.0 → 0.5.0

package/docs/3.routes.md

@@ -291,8 +291,13 @@ class UserAPI extends DataController(User, routes, Controller("/users")) {
 
 The `new` and `edit` routes take the raw request body (`Buffer`) or a body already parsed (`Validation.WrittenBody`). A route wrapping them can parse the body, amend it (stamp a field, drop one) and hand the object on: the route validates and writes it as handed, without a second serialization.
 
+A parsed body is `FieldValues`: fields by name, each holding a `FieldValue` (a string, number, boolean, `null`, `Date`, or an array or plain object of those). `Validation.ParseBody` answers 400 for anything else, whether it comes from a `Buffer` or from a body already parsed: a function, a class instance, a `bigint`, a cycle or an `undefined` array element. The default routes run with the controller as `this`, so a wrapping function declares `this: DataControllerInstance` and calls `route.func.call(this, ...)`.
+
 ```ts docs-check
-import { DefaultRoutes } from "@antelopejs/interface-data-api";
+import {
+  DefaultRoutes,
+  type DataControllerInstance,
+} from "@antelopejs/interface-data-api";
 import {
   type Parameters,
   Validation,
@@ -302,7 +307,7 @@ import type { RequestContext } from "@antelopejs/interface-api";
 const stampedNew = {
   ...DefaultRoutes.New,
   func: function (
-    this: unknown,
+    this: DataControllerInstance,
     ctx: RequestContext,
     params: Parameters.NewParameters,
     body: Buffer,
@@ -335,7 +340,7 @@ const routes = {
 };
 ```
 
-The `GetGuard` callback receives `(ctx, current, params)`. Declare it as a regular function to access the controller through `this`.
+The `GetGuard` callback receives `(ctx, current, params)`. Declare it as a regular function to access the controller through `this`, typed `DataControllerInstance`. `current` is `FieldValues`.
 
 | Argument  | Contents                                                                                | Use it for                                     |
 | --------- | --------------------------------------------------------------------------------------- | ---------------------------------------------- |

package/docs/5.validators.md

@@ -36,17 +36,26 @@ class UserAPI extends DataController(
 ### Validation Function Signature
 
 ```typescript
+type FieldValue =
+  string | number | boolean | null | Date | FieldValue[] | FieldValues;
+
+interface FieldValues {
+  [field: string]: FieldValue | undefined;
+}
+
 type FieldValidator = (
-  value: unknown,
+  value: FieldValue | undefined,
 ) => FieldValidationResult | Promise<FieldValidationResult>;
 
 type FieldValidationResult =
-  boolean | { success: true; data: unknown } | { success: false };
+  | boolean
+  | { success: true; data: FieldValue | undefined }
+  | { success: false };
 ```
 
 The function:
 
-- Receives the raw field value from the request body.
+- Receives the raw field value from the request body: JSON, or a `Date` or `undefined` when a route wrapping `new` or `edit` amended the parsed body. `FieldValue | undefined` has to be narrowed before use.
 - 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.
@@ -215,12 +224,12 @@ 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.
+When validation or mandatory checks fail, the API returns a `400 Bad Request` response whose JSON body names what went wrong and the fields concerned, for the client to word it and show it under each field:
 
-- **Mandatory failure:** `"Missing mandatory fields: email, password"`
-- **Validator failure:** `"Invalid field type(s): age, email"`
+- **Mandatory failure:** `{ "code": "missing_mandatory_fields", "fields": ["email", "password"] }`
+- **Validator failure:** `{ "code": "invalid_field_types", "fields": ["age", "email"] }`
 
-All fields are checked, and the error message lists every field that failed validation.
+The codes are exported as `Validation.MISSING_MANDATORY_FIELDS` and `Validation.INVALID_FIELD_TYPES` (`@antelopejs/interface-data-api/components`), the body's type as `Validation.FieldsErrorBody`. All fields are checked: `fields` lists every one that failed.
 
 ## Next Steps
 

package/docs/6.listable.md

@@ -234,6 +234,10 @@ declare _id: string;
 declare name: string;
 ```
 
+### Localized Fields
+
+A `@Localized` field is sorted on its value in the request's locale, the one the controller's `@ModifierKey(LocalizationModifier)` field holds. A row with no value in that locale, or an empty one, sorts on its `fallbackLocale` value. This ordering is computed per row, so it never uses an index, whatever `noIndex` says.
+
 ### Example
 
 ```http

package/docs/8.filters.md

@@ -150,9 +150,11 @@ type FilterFunction<T, U> = (
   context: RequestContext & { this: T },
   proxy: ValueProxy<any>,
   key: string,
-  value: string,
-  mode: "eq" | "ne" | "gt" | "ge" | "lt" | "le",
-  row: ValueProxy<U>,
+  ...rest: [
+    value: string,
+    mode: "eq" | "ne" | "gt" | "ge" | "lt" | "le",
+    row: ValueProxy<U>,
+  ]
 ) => ValueProxyOrValue<boolean>;
 ```
 
@@ -165,6 +167,8 @@ type FilterFunction<T, U> = (
 | `mode`    | The comparison operator from the query parameter                                                        |
 | `row`     | The full database row as a `ValueProxy`                                                                 |
 
+`value`, `mode` and `row` are one rest tuple, so that the function type stays within five parameters. A function that declares them as separate parameters is assignable to it, and `Parameters<FilterFunction<T, U>>` lists all six.
+
 ### Example: Pattern Matching Filter
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-data-api",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "AntelopeJS interface that generates CRUD REST endpoints from database tables, with access rules, validation and pagination",
   "keywords": [
     "antelopejs",
@@ -60,16 +60,26 @@
     "release": "pnpm run lint && pnpm run prepack && release-it",
     "test": "pnpm run build && ajs module test .",
     "format:check": "oxfmt --check .",
-    "knip": "knip"
+    "knip": "knip",
+    "prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
+    "checks": "antelopejs-checks",
+    "size": "antelopejs-check-size",
+    "ratchet": "antelopejs-ratchet",
+    "sync": "antelopejs-sync",
+    "ratchet:update": "antelopejs-ratchet --update",
+    "sync:check": "antelopejs-sync --check",
+    "typecheck": "tsc --noEmit",
+    "suppressions": "antelopejs-suppressions",
+    "suppressions:update": "antelopejs-suppressions --update"
   },
   "devDependencies": {
     "@antelopejs/core": "^1.16.0",
     "@antelopejs/interface-api": "^0.0.15",
     "@antelopejs/interface-api-util": "^0.1.3",
     "@antelopejs/interface-core": "^0.2.4",
-    "@antelopejs/interface-database": "^0.1.10",
-    "@antelopejs/interface-database-decorators": "^0.1.9",
-    "@antelopejs/tooling-configs": "^0.0.9",
+    "@antelopejs/interface-database": "^0.1.11",
+    "@antelopejs/interface-database-decorators": "^0.1.10",
+    "@antelopejs/tooling-configs": "^0.2.11",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
@@ -77,6 +87,7 @@
     "chai": "^4.5.0",
     "eslint-plugin-perfectionist": "^5.11.0",
     "knip": "^6.34.0",
+    "lefthook": "^2.2.2",
     "mongodb-memory-server-core": "^10.4.3",
     "oxfmt": "^0.66.0",
     "oxlint": "1.81.0",
@@ -91,7 +102,7 @@
     "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
     "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0"
+    "@antelopejs/interface-database-decorators": ">=0.1.10 <1.0.0"
   },
   "packageManager": "pnpm@10.6.5",
   "antelopeJs": {

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

@@ -140,6 +140,10 @@ This exposes `GET /tasks/get?id=`, `GET /tasks/list`, `POST /tasks/new`, `PUT /t
 - `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 parsed request body is `FieldValues` (fields by name; a `FieldValue` is JSON or a `Date`). A
+  `@Validator` receives `FieldValue | undefined`, and `Validation.ParseBody` answers 400 for a body that
+  holds anything else, even one a wrapping route already parsed. The default routes run with the
+  controller as `this` (`DataControllerInstance`); a wrapper calls `route.func.call(this, ...)`.
 - 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.
 

package/skills/data-api-interface/cases.json

@@ -0,0 +1,99 @@
+{
+  "version": 1,
+  "cases": [
+    {
+      "id": "data-api-interface-crud-endpoints",
+      "area": "framework",
+      "style": "clean",
+      "prompt": "Expose my orders table as REST endpoints for get, list, create, update and delete. Only the status column should be sortable and customer filterable.",
+      "expect": {
+        "skills": ["data-api-interface"],
+        "acceptable": [
+          "api-interface",
+          "database-decorators-interface",
+          "database-interface",
+          "ajs-consume-interface",
+          "antelopejs"
+        ],
+        "mustMention": [
+          "DataController",
+          "RegisterDataController",
+          "Sortable",
+          "Filter"
+        ]
+      }
+    },
+    {
+      "id": "data-api-interface-crud-casual",
+      "area": "framework",
+      "style": "casual",
+      "prompt": "can i get a crud api straight from my table without writing every route",
+      "expect": {
+        "skills": ["data-api-interface"],
+        "acceptable": [
+          "api-interface",
+          "database-decorators-interface",
+          "database-interface",
+          "antelopejs"
+        ],
+        "mustMention": ["DataController", "DefaultRoutes"]
+      }
+    },
+    {
+      "id": "data-api-interface-field-hidden",
+      "area": "framework",
+      "style": "clean",
+      "prompt": "The list endpoint I generated from my table never returns the email field and I cannot write to it either. Why?",
+      "expect": {
+        "skills": ["data-api-interface"],
+        "acceptable": [
+          "api-interface",
+          "database-decorators-interface",
+          "ajs-consume-interface"
+        ],
+        "mustMention": ["Access"]
+      }
+    },
+    {
+      "id": "data-api-interface-sort-400-casual",
+      "area": "framework",
+      "style": "casual",
+      "prompt": "sorting the list by createdAt gives me a 400",
+      "expect": {
+        "skills": ["data-api-interface"],
+        "acceptable": ["api-interface", "database-decorators-interface"],
+        "mustMention": ["Sortable"]
+      }
+    },
+    {
+      "id": "data-api-interface-table-neighbour",
+      "area": "framework",
+      "style": "clean",
+      "prompt": "Add a hashed passphrase and an encrypted supplier code to my chef table class, plus created and updated timestamps.",
+      "expect": {
+        "skills": ["database-decorators-interface"],
+        "acceptable": [
+          "database-interface",
+          "antelopejs",
+          "ajs-consume-interface"
+        ],
+        "avoid": ["data-api-interface"]
+      }
+    },
+    {
+      "id": "data-api-interface-wrap-new-stamp",
+      "area": "framework",
+      "style": "clean",
+      "prompt": "I want the generated create route to stamp a source field on every body before it is validated and written. How do I wrap it, and what type does the parsed body have?",
+      "expect": {
+        "skills": ["data-api-interface"],
+        "acceptable": [
+          "api-interface",
+          "database-decorators-interface",
+          "ajs-consume-interface"
+        ],
+        "mustMention": ["ParseBody", "WrittenBody", "FieldValues"]
+      }
+    }
+  ]
+}