@antelopejs/interface-database-decorators 0.1.11 → 0.2.0

package/docs/4.data-models.md

@@ -1,12 +1,16 @@
-# Data Models
+---
+title: Data models
+description: Reference for BasicDataModel, its CRUD methods and return values, the data conversions, validation, and GetModel.
+mode: reference
+---
 
-Data models provide a high-level interface for interacting with database tables. They handle conversion between database records and TypeScript class instances, and expose methods for common CRUD operations.
+A data model reads and writes one table. It converts between stored records and instances of the table class, and has methods for the common CRUD operations.
 
-## BasicDataModel
+## `BasicDataModel`
 
-The `BasicDataModel` function creates a model class for a specific table. It wraps the underlying AQL table with methods that automatically apply modifier transformations.
+The `BasicDataModel` function creates a model class for a table. The class wraps the AQL table with methods that apply the modifier transformations.
 
-```typescript
+```typescript fragment
 import { BasicDataModel } from "@antelopejs/interface-database-decorators";
 import { User } from "./user.table";
 
@@ -15,27 +19,28 @@ const UserModel = BasicDataModel(User, "users");
 
 ### Parameters
 
-| Parameter   | Type               | Description                                                           |
-| ----------- | ------------------ | --------------------------------------------------------------------- |
-| `dataType`  | `Constructible<T>` | The Table class representing your table                               |
-| `tableName` | `string`           | The table name in the database (optional if `@RegisterTable` is used) |
+| Parameter   | Type               | Description                                                             |
+| ----------- | ------------------ | ----------------------------------------------------------------------- |
+| `dataType`  | `Constructible<T>` | The table class.                                                        |
+| `tableName` | `string`           | The table name in the database. Optional when `@RegisterTable` sets it. |
 
-When the table class has been decorated with `@RegisterTable`, the `tableName` parameter can be omitted.
+When the table class has `@RegisterTable`, you can omit `tableName`. Without either, `BasicDataModel` throws `tableName must be provided or set via @RegisterTable`.
 
-## Instantiate a Model
+## Instantiate a model
 
-A model instance requires a `SchemaInstance` from the database interface:
+A model instance needs a `SchemaInstance` from the database interface:
 
-```typescript
+```typescript fragment
 import { Schema } from "@antelopejs/interface-database";
 
-const schema = Schema.get("myapp")!;
+const schema = Schema.get("myapp");
+if (!schema) throw new Error("Schema myapp is not registered");
 const db = schema.instance();
 
 const userModel = new UserModel(db);
 ```
 
-## CRUD Operations
+## Read and write rows
 
 For a model created with `BasicDataModel(User)`, the return values are:
 
@@ -47,11 +52,11 @@ For a model created with `BasicDataModel(User)`, the return values are:
 | `update(...)`                        | `Promise<number>`                | Number of modified documents.                                       |
 | `delete(id)`                         | `Promise<number>`                | Number of deleted documents.                                        |
 
-Use `model.table` to compose AQL queries before execution. The static `fromDatabase()` conversion can return `undefined`; `toDatabase()` returns a plain `Record<string, any>`, not a saved record or a write result.
+Use `model.table` to compose an AQL query before you run it. The static `fromDatabase()` conversion returns `undefined` when the record is `null` or `undefined`, as `table.get` gives for a missing ID. The static `toDatabase()` returns a `StoredRow<T>`, the record to store, not a saved record or a write result.
 
 ### Read
 
-```typescript
+```typescript fragment
 // Get by primary key
 const user = await userModel.get("user-123");
 
@@ -64,7 +69,7 @@ const allUsers = await userModel.getAll();
 
 ### Create
 
-```typescript
+```typescript fragment
 // Insert a single document
 const ids = await userModel.insert({
   email: "alice@example.com",
@@ -80,7 +85,7 @@ const batchIds = await userModel.insert([
 
 ### Update
 
-```typescript
+```typescript fragment
 // Update by ID
 await userModel.update("user-123", { name: "Updated Name" });
 
@@ -88,17 +93,17 @@ await userModel.update("user-123", { name: "Updated Name" });
 await userModel.update({ _id: "user-123", name: "Updated Name" });
 ```
 
-> **Important:** When calling `update` without a separate ID argument, the object must include the primary key field.
+When you call `update` without a separate ID argument, the object must include the primary key. Its type requires `_id`, and a call without it throws `Missing primary key in object update.`
 
 ### Delete
 
-```typescript
+```typescript fragment
 await userModel.delete("user-123");
 ```
 
-## Data Conversion
+## Data conversion
 
-Data models include static methods for converting between different data representations:
+A model class has static methods that convert between the forms of a row:
 
 | Starting value          | Conversion      | Result                                            | Persists data? |
 | ----------------------- | --------------- | ------------------------------------------------- | -------------- |
@@ -106,15 +111,15 @@ Data models include static methods for converting between different data represe
 | Raw database record     | `fromDatabase`  | Table instance with read modifier events applied  | No             |
 | Table instance          | `toDatabase`    | Plain storage representation                      | No             |
 
-Use `insert` or `update` to perform a write; conversion alone does not save anything. Reads through `get`, `getBy`, and `getAll` apply `fromDatabase` for you. A custom query through `model.table` returns AQL results, so apply conversion explicitly when you need model instances.
+Use `insert` or `update` to write. A conversion alone saves nothing. Reads through `get`, `getBy`, and `getAll` apply `fromDatabase` for you. A custom query through `model.table` returns AQL results, so apply conversion explicitly when you need model instances.
 
-![Model writes convert input, trigger insert or update events, convert to storage, then execute AQL. Model reads convert fetched records; direct model.table queries bypass model conversion.](./assets/model-conversion.svg){width="480"}
+![Model writes convert input, trigger insert or update events, convert to storage, then execute AQL. Model reads convert fetched records. Direct model.table queries bypass model conversion.](./assets/model-conversion.svg "illustration"){width="480"}
 
 ### `fromPlainData(obj)`
 
-Convert a plain JavaScript object into a Table class instance. Modifier transformations (like encryption and hashing) are applied during this conversion.
+Converts a plain JavaScript object into an instance of the table class. Each key is assigned, so modifiers such as encryption and hashing transform the values during this conversion. An instance of the table class is returned as it is.
 
-```typescript
+```typescript fragment
 const user = UserModel.fromPlainData({
   _id: "user-123",
   email: "user@example.com",
@@ -122,56 +127,62 @@ const user = UserModel.fromPlainData({
 });
 ```
 
+The object is a `PlainData<T>`. Every field is optional and may be partial, and a field under a container modifier may hold its value per key, as a localized field holds one text per locale. `toPlainData` gives the reverse form, a `PlainRow<T>`.
+
 ### `fromDatabase(obj)`
 
-Convert a raw database record into a Table class instance. This attaches the class prototype and triggers the `fromDatabase` modifier event.
+Converts a stored record into an instance of the table class. It copies the record, sets the class prototype on the copy, and triggers the `fromDatabase` modifier event. It returns `undefined` when the record is `null` or `undefined`, as `table.get` gives for a missing ID. An empty object still gives an instance.
 
-```typescript
+```typescript fragment
 const user = UserModel.fromDatabase(rawDbRecord);
 ```
 
 ### `toDatabase(obj)`
 
-Convert a Table class instance into a plain object suitable for database storage. Modifier events like `toDatabase` are triggered.
+Converts an instance of the table class, or plain data, into the record to store, and triggers the `toDatabase` modifier event. The result is a `StoredRow<T>`. It holds the fields that are set, has no prototype, and keeps its modified fields locked in `_internal` instead of at the top level.
 
-```typescript
+```typescript fragment
 const dbReady = UserModel.toDatabase(userInstance);
 ```
 
 ## Validation
 
-`Model.validate(obj)` runs every io-ts codec attached via `@Field` against the matching property of `obj`. String-token fields and properties without `@Field` are skipped.
+`Model.validate(obj)` runs every io-ts codec that `@Field` attached against the matching property of `obj`. It skips string-token fields and properties without `@Field`. A failure's `message` is the first message the codec reports, or `invalid <field>` when the codec reports none, as io-ts's built-in codecs do.
 
-```typescript
+```typescript fragment
 const result = UserModel.validate({ name: "Alice", age: 30 });
 if (!result.ok) {
-  console.error(result.errors); // [{ field: "age", message: "not number" }, ...]
+  console.error(result.errors); // [{ field: "age", message: "invalid age" }]
 }
 ```
 
-Pass `{ validate: true }` to `insert` or `update` to gate the write on validation. On failure the call throws an `Error` whose `errors` property holds the per-field details; on success the original object passes through unchanged.
+Pass `{ validate: true }` to `insert` or `update` to validate before the write. On failure the call throws an `Error` with the message `validation failed: <field> (<message>), ...` and an `errors` property that holds the details per field. On success the write goes on with the object unchanged.
 
-```typescript
+```typescript fragment
 await userModel.insert({ name: "Alice", age: 30 }, { validate: true });
 await userModel.update("user-123", { name: "Bob" }, { validate: true });
 ```
 
-`insert` validates every annotated codec field. `update` is partial: only fields present on the patch object are checked, so omitting fields you don't intend to modify is fine. Use `Model.validate(obj, { partial: true })` for the same patch semantics outside of `update`.
+`insert` validates every codec field of each row. `update` validates only the fields present on the patch object, so you can leave out the fields you do not change. For the same patch check outside `update`, use `Model.validate(obj, { partial: true })`.
 
-## Extend BasicDataModel
+## Extend `BasicDataModel`
 
-Extend the generated model class to add custom query methods:
+Extend the generated model class to add custom query methods.
 
-The `register` method below checks for an existing email to provide early feedback. It does not guarantee uniqueness under concurrent writes; enforce that constraint in the database where supported and handle conflicts.
+The `register` method below checks for an existing email to report a duplicate early. It does not guarantee uniqueness under concurrent writes. Enforce that constraint in the database with a unique index where the database module supports it, and handle the conflict. `findActive` converts each row with `fromDatabase`, which returns `undefined` only when the record is `null` or `undefined`, and the filter drops a missing row.
 
-```typescript
+```typescript fragment
 const UserModelBase = BasicDataModel(User, "users");
 
 class CustomUserModel extends UserModelBase {
   async findActive() {
     return this.table
       .filter((u) => u.key("status").eq("active"))
-      .then((rows) => rows.map(CustomUserModel.fromDatabase) as User[]);
+      .then((rows) =>
+        rows
+          .map((row) => CustomUserModel.fromDatabase(row))
+          .filter((user) => user !== undefined),
+      );
   }
 
   async register(email: string, name: string) {
@@ -184,24 +195,24 @@ class CustomUserModel extends UserModelBase {
 }
 ```
 
-## GetModel
+## `GetModel`
 
-The `GetModel` function retrieves or creates a cached model instance for a given schema:
+The `GetModel` function returns the cached model instance for a model class and an instance ID, and creates it on the first call:
 
-```typescript
+```typescript fragment
 import { GetModel } from "@antelopejs/interface-database-decorators";
 
 const userModel = GetModel(UserModel, "instance-id");
 ```
 
-Model instances are cached by class and instance ID, so repeated calls with the same arguments return the same instance. A model built by `BasicDataModel` uses the schema its table class was bound to by `RegisterSchema`, so it stays on the declaring module's database even when another module calls `GetModel`; an unbound table class throws. A custom model class without a `tableClass` is resolved from its `schemaName` with `Schema.get`.
+The cache key is the class and the instance ID, so repeated calls with the same arguments return the same instance. Without an instance ID, the model uses the default instance. A model built by `BasicDataModel` uses the schema that `RegisterSchema` bound its table class to, so it stays on the declaring module's database even when another module calls `GetModel`. An unbound table class whose schema name has no schema throws `<Class> is not bound to a schema`. A custom model class without a `tableClass` gets its schema from its `schemaName` through `Schema.get`.
 
-## Modifier Integration
+## Modifier integration
 
-Data models automatically apply all modifier transformations:
+Data models apply every modifier transformation:
 
-- **On insert** - `fromPlainData` conversion is applied, the `insert` event fires, and the result is converted with `toDatabase` before writing.
-- **On update** - The same conversion pipeline applies with the `update` event.
-- **On read** - Results from `get`, `getBy`, and `getAll` are converted with `fromDatabase`.
+- On insert, the model converts the data with `fromPlainData`, fires the `insert` event, and converts the result with `toDatabase` before the write.
+- On update, the model runs the same conversions with the `update` event. It leaves out an empty `_internal`, so a patch keeps what the row stores there.
+- On read, the model converts the results of `get`, `getBy`, and `getAll` with `fromDatabase`.
 
-This means encrypted fields are encrypted before storage and decrypted on retrieval, hashed fields are hashed on write, and localized fields follow their configured locale behavior -- all transparently.
+As a result, encrypted fields are encrypted before storage and decrypted on read, hashed fields are hashed on write, and localized fields follow their locale settings.

package/docs/5.parameter-decoration.md

@@ -1,16 +1,20 @@
-# Parameter Decoration
+---
+title: Parameter decoration
+description: Inject a data model into an API controller method or property with the Model decorator, with a fixed or a per-request instance ID.
+mode: how-to
+---
 
-The Database Decorators package provides the `Model` decorator for injecting data model instances into API controller methods. This decorator integrates with the `@antelopejs/interface-api` package's parameter provider system.
+The `Model` decorator injects a data model instance into an API controller method. It registers a parameter provider of `@antelopejs/interface-api` through `SetParameterProvider`.
 
-## The Model Decorator
+## The `Model` decorator
 
-The `Model` decorator injects a cached model instance. It can be used as either a parameter decorator or a property decorator.
+The `Model` decorator injects the cached model instance that `GetModel` returns. It works as a parameter decorator and as a property decorator.
 
-### Static Instance ID
+### Pass a fixed instance
 
-Pass a fixed instance ID to bind the model to a specific schema instance:
+To bind the model to one schema instance, pass a fixed instance ID:
 
-```typescript
+```typescript fragment
 import { Controller, Get } from "@antelopejs/interface-api";
 import { Model } from "@antelopejs/interface-database-decorators";
 import { UserModel } from "./user.model";
@@ -25,13 +29,13 @@ class UsersController extends Controller("/users") {
 }
 ```
 
-### Dynamic Instance ID
+### Pick the instance per request
 
-Pass a callback function to determine the instance ID at request time. The callback receives the request context:
+To pick the instance ID for each request, pass a callback. It receives the request context and returns an instance ID, or `undefined` for the default instance.
 
-Authorize access to the requested tenant before reading or writing through the injected model. The callback selects an instance; a URL parameter alone is not proof that the caller belongs to that tenant.
+Authorize access to the requested tenant before you read or write through the injected model. The callback only selects an instance, and a URL parameter alone does not prove that the caller belongs to that tenant.
 
-```typescript
+```typescript fragment
 import { Controller, Get, Parameter } from "@antelopejs/interface-api";
 import { Model } from "@antelopejs/interface-database-decorators";
 import { UserModel } from "./user.model";
@@ -40,7 +44,7 @@ class MultitenantController extends Controller("/tenants") {
   @Get("/:tenantId/users")
   async getTenantUsers(
     @Parameter("tenantId") tenantId: string,
-    @Model(UserModel, (ctx) => `tenant-${ctx.params.tenantId}`)
+    @Model(UserModel, (ctx) => `tenant-${ctx.routeParameters.tenantId}`)
     userModel: InstanceType<typeof UserModel>,
   ) {
     return await userModel.getAll();
@@ -48,11 +52,11 @@ class MultitenantController extends Controller("/tenants") {
 }
 ```
 
-## Property Decoration
+## Property decoration
 
-The `Model` decorator also works as a property decorator. The model is initialized when the controller handles a request:
+The `Model` decorator also works as a property decorator. The property gets its model when the controller handles a request. Outside a request handler, the property is unset, although the `!` declaration types it as always present:
 
-```typescript
+```typescript fragment
 import { Controller, Get, Parameter } from "@antelopejs/interface-api";
 import { Model } from "@antelopejs/interface-database-decorators";
 import { UserModel } from "./models";
@@ -73,11 +77,11 @@ class UsersController extends Controller("/users") {
 }
 ```
 
-## Model Caching
+## Model caching
 
-The `Model` decorator uses `GetModel` internally, which caches model instances by class and instance ID. Multiple decorators referencing the same model class and instance ID share a single instance:
+The `Model` decorator calls `GetModel`, which caches model instances by class and instance ID. Decorators that name the same model class and instance ID share one instance:
 
-```typescript
+```typescript fragment
 import { GetModel } from "@antelopejs/interface-database-decorators";
 
 // These return the same instance
@@ -88,13 +92,13 @@ const model2 = GetModel(UserModel, "main");
 const model3 = GetModel(UserModel, "other");
 ```
 
-## Combine with API Decorators
+## Combine with API decorators
 
-Model decorators compose naturally with other API decorators for building complete CRUD controllers:
+`@Model` combines with the other API decorators in a CRUD controller.
 
-This example demonstrates injection, not a complete public API policy. Before exposing writes, reject malformed or non-object JSON, allow only permitted fields, validate their values, and authorize the operation. `JSON.parse` and `@Model` do not provide these checks; string-token `@Field` declarations do not validate input either.
+This example shows injection, not a complete public API policy. Before you expose writes, reject malformed or non-object JSON, allow only permitted fields, validate their values, and authorize the operation. `JSON.parse` and `@Model` do none of these checks, and string-token `@Field` declarations do not validate input either.
 
-```typescript
+```typescript fragment
 import {
   Controller,
   Get,
@@ -150,9 +154,9 @@ class UsersController extends Controller("/users") {
 }
 ```
 
-## Custom Parameter Providers
+## Custom parameter providers
 
-For more complex injection logic, create custom parameter providers using the core API:
+For other injection logic, write your own decorator that registers a parameter provider:
 
 ```typescript
 import { SetParameterProvider } from "@antelopejs/interface-api";

package/docs/tsconfig.json

@@ -2,6 +2,9 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "rootDir": "..",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "declaration": false,
     "noEmit": true,
     "composite": false,
     "incremental": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-database-decorators",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "AntelopeJS decorators for database tables and typed data models, with encrypted, hashed and localized fields",
   "keywords": [
     "antelopejs",
@@ -131,9 +131,7 @@
     "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",
@@ -144,11 +142,11 @@
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@antelopejs/core": "^1.16.0",
+    "@antelopejs/core": "^1.20.0",
     "@antelopejs/interface-api": "^0.0.15",
-    "@antelopejs/interface-core": "^0.2.4",
-    "@antelopejs/interface-database": "^0.1.11",
-    "@antelopejs/tooling-configs": "^0.2.11",
+    "@antelopejs/interface-core": "^0.4.0",
+    "@antelopejs/interface-database": "^0.3.0",
+    "@antelopejs/tooling-configs": "^0.2.17",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
@@ -172,12 +170,15 @@
     "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.11 <1.0.0"
   },
-  "packageManager": "pnpm@10.6.5",
+  "packageManager": "pnpm@10.33.0",
   "antelopeJs": {
     "standalone": true,
     "test": "src/antelope.test.ts",
     "skills": [
       "./skills"
-    ]
+    ],
+    "docs": {
+      "standard": true
+    }
   }
 }

package/skills/database-decorators-interface/SKILL.md

@@ -110,7 +110,7 @@ class Chef extends Table.with(
   EncryptionModifier,
   LocalizationModifier,
 ) {
-  @Hashed() declare passphrase: string; // one-way; test via instance.testHash("passphrase", value)
+  @Hashed() declare passphrase: string; // one-way scrypt; test via await instance.testHashAsync("passphrase", value)
   @Encrypted({ secretKey }) declare supplierCode: string; // transparent encrypt/decrypt (autolock + autounlock)
   @Localized() declare motto: string; // read AND write via instance.localize("en", ["motto"])
   @CreationTime() declare hiredAt: Date; // set on insert, stripped from updates
@@ -124,7 +124,9 @@ class Chef extends Table.with(
   is loaded once before decorators run (e.g. `import "@antelopejs/interface-database-decorators"`).
 - `Hashed`, `Encrypted`, and `Localized` require the matching modifier class in `Table.with(...)`; `CreationTime`/`UpdateTime` are event-only and need no mixin.
 - Modifier ordering matters: `attachModifier` throws if you stack a modifier after a one-way modifier (e.g. anything after `@Hashed` on the same field).
-- Hashed fields cannot be read back or queried directly — only equality-tested with `testHash`.
+- Hashed fields cannot be read back or queried directly — only equality-tested with `testHashAsync`, or `testHash`, which blocks the event loop for one scrypt run.
+- A row can hold an older hash that still verifies. After a successful test, when `instance.isHashOutdated(field)` is true, assign the tested value and save the row.
+- `@Hashed({ algorithm })` stores a fast digest instead of scrypt: use it only for non-secret fingerprints, never for credentials.
 - Localized fields must be written through a localized instance (`instance.localize(locale).field = ...`);
   values assigned before `localize()` are held in floating state and silently dropped on insert/update.
 - A localized value `""` is stored as no value: reads and queries in that locale get the `fallbackLocale` value.
@@ -132,7 +134,8 @@ class Chef extends Table.with(
 - `Model.validate` (and `{ validate: true }` on insert/update) only checks fields whose `@Field` type is an
   io-ts-style codec with `.decode`; plain string field tokens are skipped. Update validates with
   `{ partial: true }` semantics.
-- `update(obj)` without an explicit id asserts that the object carries the primary key (`_id` by default).
+- `update(obj)` without an explicit id takes an object typed with the primary key `_id`, and asserts at run time that it carries it.
+- A row has three forms. `fromPlainData` reads a `PlainData<T>` (every field optional, a localized field possibly one text per locale), `toPlainData` gives a `PlainRow<T>`, and `toDatabase` gives a `StoredRow<T>`, its modified fields locked in `_internal`. `fromDatabase` takes the row the database answered, unchecked.
 - Indexes are scoped to the schema instance. Add `@Index({ crossInstance: true })` only for indexes also queried
   across all instances (`CROSS_INSTANCE`); it never changes results, only speed. On a group, one member setting it
   applies it to the whole group.