@antelopejs/interface-database-decorators 0.1.5 → 0.1.6

package/docs/1.introduction.md

@@ -0,0 +1,22 @@
+# Interface Database Decorators
+
+## Overview
+
+The Interface Database Decorators package provides a structured, decorator-based framework for defining database tables, applying field-level modifiers (encryption, hashing, localization), building data models with CRUD operations, and injecting models into API controllers. It builds on top of the `@antelopejs/interface-database` package and integrates with the `@antelopejs/interface-api` package for controller parameter injection.
+
+## Dependencies
+
+This package depends on the following:
+
+- [**@antelopejs/interface-database**](https://github.com/AntelopeJS/interface-database) - The underlying database query interface (AQL)
+- [**@antelopejs/interface-api**](https://github.com/AntelopeJS/interface-api) - API controller integration for parameter decoration
+- [**@antelopejs/interface-core**](https://github.com/AntelopeJS/interface-core) - Core decorator utilities
+- [**reflect-metadata**](https://www.npmjs.com/package/reflect-metadata) - Metadata reflection for TypeScript decorators
+- [**randomstring**](https://www.npmjs.com/package/randomstring) - Random string generation for hash salts
+
+## Documentation
+
+- [Table Definitions](./2.table-definitions.md) - Define database tables with the `Table` class, `Index` decorator, and `Fixture` decorator
+- [Table Modifiers](./3.table-modifiers.md) - Apply encryption, hashing, and localization modifiers to table fields, or create custom modifiers
+- [Data Models](./4.data-models.md) - Create data models with `BasicDataModel` for CRUD operations and data conversion
+- [Parameter Decoration](./5.parameter-decoration.md) - Inject model instances into API controller methods with the `Model` decorator

package/docs/2.table-definitions.md

@@ -0,0 +1,260 @@
+# Table Definitions
+
+The Database Decorators package provides a class-based approach to defining database tables. You extend the `Table` base class, declare each field with TypeScript's `declare` keyword and the `@Field` decorator, and use further decorators to configure indexes, relations, and initial data.
+
+## The Table Class
+
+The `Table` class serves as the base class for all table definitions. Every table automatically includes an `_id` field as the primary key.
+
+```typescript
+import { Table, Field } from "@antelopejs/interface-database-decorators";
+
+class User extends Table {
+  @Field("string")
+  declare name: string;
+
+  @Field("string")
+  declare email: string;
+}
+```
+
+### Extend with Modifiers
+
+The `Table.with()` static method incorporates modifier mixins into the table class, adding capabilities like encryption, hashing, or localization:
+
+```typescript
+import { Table, Field, EncryptionModifier, Encrypted } from "@antelopejs/interface-database-decorators";
+
+class SensitiveData extends Table.with(EncryptionModifier) {
+  @Field("string")
+  declare publicContent: string;
+
+  @Encrypted({ secretKey: process.env.SECRET_KEY || "default-key" })
+  @Field("string")
+  declare secureContent: string;
+}
+```
+
+For detailed information about modifiers, see [Table Modifiers](./3.table-modifiers.md).
+
+## The Index Decorator
+
+The `Index` decorator marks a field as a database index. Indexed fields enable efficient lookups through `getAll()` and `between()` on the underlying AQL table.
+
+```typescript
+import { Table, Field, Index } from "@antelopejs/interface-database-decorators";
+
+class User extends Table {
+  @Index()
+  @Field("string")
+  declare email: string;
+
+  @Field("string")
+  declare name: string;
+}
+```
+
+### Options
+
+| Option  | Type     | Description                                     |
+| ------- | -------- | ----------------------------------------------- |
+| `group` | `string` | Assign the field to a named compound index group. |
+
+### Compound Indexes
+
+Assign multiple fields to the same index group to create a compound index:
+
+```typescript
+import { Table, Field, Index, Relation } from "@antelopejs/interface-database-decorators";
+
+class User extends Table {
+  @Field("string")
+  declare name: string;
+}
+
+class UserActivity extends Table {
+  @Index({ group: "user_action" })
+  @Field("string")
+  @Relation({ to: () => User })
+  declare userId: string;
+
+  @Index({ group: "user_action" })
+  @Field("string")
+  declare action: string;
+
+  @Field("date")
+  declare timestamp: Date;
+}
+```
+
+## The Field Decorator
+
+`@Field(type)` declares the field type for a property. The type is forwarded verbatim into the `TableDefinition.fields` map handed to the adapter. It accepts the full `FieldType` union -- primitive tokens (`"string"`, `"number"`, ...), arrays, nested records, or an io-ts codec.
+
+```typescript
+import * as t from "io-ts";
+import { Table, Field, Index, RegisterTable } from "@antelopejs/interface-database-decorators";
+
+@RegisterTable("orders", "shop")
+class Order extends Table {
+  @Field("string")
+  declare id: string;
+
+  @Field(t.union([t.literal("open"), t.literal("closed")]))
+  declare status: "open" | "closed";
+
+  @Index()
+  @Field("number")
+  declare total: number;
+}
+```
+
+Properties without `@Field` are omitted from `fields`. `@Field` stacks freely with `@Index`.
+
+## The Relation Decorator
+
+The `Relation` decorator declares a link from a field to another table. It is **declarative metadata only**: database implementations do not enforce it (no foreign key constraint, no referential validation). Introspection tooling consumes it to expose the links between tables — for example to render schema diagrams or navigate related records.
+
+```typescript
+import { Table, Field, Index, Relation } from "@antelopejs/interface-database-decorators";
+
+class Comment extends Table {
+  @Index()
+  @Field("string")
+  @Relation({ to: () => Post })
+  declare postId: string;
+
+  @Field("string")
+  @Relation({ to: () => Tag, many: true })
+  declare tagIds: string[];
+}
+```
+
+### Options
+
+| Option    | Type                | Description                                                            |
+| --------- | ------------------- | ---------------------------------------------------------------------- |
+| `to`      | `() => typeof Table` | Thunk returning the target table class (lazy to allow forward references). |
+| `toField` | `string`            | Target field name. Defaults to the target table's primary key.         |
+| `many`    | `boolean`           | The decorated field holds multiple target keys (many targets per source record). |
+
+`@Relation` stacks freely with `@Field` and `@Index`.
+
+## The RegisterTable Decorator
+
+The `RegisterTable` class decorator associates a table class with a specific table name and schema. This registration is used by `RegisterSchema` to build the schema definition automatically.
+
+```typescript
+import { Table, Field, Index, RegisterTable } from "@antelopejs/interface-database-decorators";
+
+@RegisterTable("users", "myapp")
+class User extends Table {
+  @Index()
+  @Field("string")
+  declare email: string;
+
+  @Field("string")
+  declare name: string;
+}
+```
+
+The first argument is the table name in the database, and the second is the schema name.
+
+## The Fixture Decorator
+
+The `Fixture` decorator defines default data to insert when a table is first created. It receives a generator function that produces initial records.
+
+```typescript
+import { Table, Field, Fixture } from "@antelopejs/interface-database-decorators";
+
+@Fixture(() => [
+  { _id: "admin", name: "Administrator" },
+  { _id: "user", name: "Standard User" },
+  { _id: "guest", name: "Guest" },
+])
+class UserRole extends Table {
+  @Field("string")
+  declare name: string;
+}
+```
+
+The generator function:
+
+- Receives the table class as its parameter.
+- Can return a single object, an array of objects, or a `Promise` resolving to either.
+- Runs only when the table is empty, preventing duplicate inserts on subsequent starts.
+
+### Async Generators
+
+```typescript
+@Fixture(async () => {
+  const defaults = await loadDefaultConfig();
+  return defaults.map((cfg) => ({
+    _id: cfg.key,
+    value: cfg.value,
+  }));
+})
+class SystemConfig extends Table {
+  @Field("string")
+  declare value: string;
+}
+```
+
+## Inheritance
+
+Tables support standard class inheritance. Define a base table with common fields and extend it for specific use cases:
+
+```typescript
+import { Table, Field, Index, Relation } from "@antelopejs/interface-database-decorators";
+
+class BaseEntity extends Table {
+  @Field("date")
+  declare createdAt: Date;
+
+  @Field("date")
+  declare updatedAt: Date;
+}
+
+class User extends BaseEntity {
+  @Index()
+  @Field("string")
+  declare email: string;
+
+  @Field("string")
+  declare firstName: string;
+
+  @Field("string")
+  declare lastName: string;
+}
+
+class Post extends BaseEntity {
+  @Index()
+  @Field("string")
+  @Relation({ to: () => User })
+  declare authorId: string;
+
+  @Field("string")
+  declare title: string;
+
+  @Field("string")
+  declare content: string;
+}
+```
+
+## Register a Schema
+
+The `RegisterSchema` function builds a `SchemaDefinition` from all tables registered for the given schema id (via `@RegisterTable`), constructs the `Schema` (which the adapter provisions), then inserts any fixture data for tables that are empty.
+
+```typescript
+import { RegisterSchema } from "@antelopejs/interface-database-decorators";
+
+await RegisterSchema("myapp");
+```
+
+### Parameters
+
+| Parameter  | Type     | Description                                                       |
+| ---------- | -------- | ----------------------------------------------------------------- |
+| `schemaId` | `string` | Schema id matching the `@RegisterTable(_, schemaId)` declarations. |
+
+`RegisterSchema` returns `Promise<void>`.

package/docs/3.table-modifiers.md

@@ -0,0 +1,349 @@
+# Table Modifiers
+
+Table modifiers transform field values as they are stored in and retrieved from the database. They enable transparent encryption, hashing, localization, and custom data transformations. Add modifiers to a table class using the `Table.with()` method.
+
+## Built-in Modifiers
+
+### EncryptionModifier
+
+The `EncryptionModifier` encrypts field values before storing them and decrypts them on retrieval. Both operations happen transparently.
+
+```typescript
+import { Table, Field, EncryptionModifier, Encrypted } from "@antelopejs/interface-database-decorators";
+
+class UserCredentials extends Table.with(EncryptionModifier) {
+  @Encrypted({
+    secretKey: process.env.ENCRYPTION_KEY || "default-key",
+    algorithm: "aes-256-gcm",
+    ivSize: 16,
+  })
+  @Field("string")
+  declare creditCardNumber: string;
+
+  @Encrypted({ secretKey: process.env.ENCRYPTION_KEY || "default-key" })
+  @Field("any")
+  declare personalData: {
+    ssn: string;
+    birthDate: string;
+  };
+}
+```
+
+#### How It Works
+
+- Data is encrypted using the specified algorithm before database insertion.
+- A random initialization vector (IV) is generated for each write.
+- For authenticated encryption algorithms (e.g., `aes-256-gcm`), an auth tag is stored alongside the ciphertext.
+- On retrieval, the data is automatically decrypted.
+- Date objects are preserved through JSON serialization with a custom encoder.
+
+#### Options
+
+| Option      | Type     | Default           | Description                      |
+| ----------- | -------- | ----------------- | -------------------------------- |
+| `secretKey` | `string` | (required)        | The encryption key.              |
+| `algorithm` | `string` | `"aes-256-gcm"`   | Encryption algorithm.            |
+| `ivSize`    | `number` | `16`              | Initialization vector size in bytes. |
+
+### HashModifier
+
+The `HashModifier` stores a one-way hash of field values. Unlike encryption, hashing is irreversible -- you cannot retrieve the original value. Use this for passwords and other sensitive data that only needs equality verification.
+
+```typescript
+import { Table, Field, HashModifier, Hashed } from "@antelopejs/interface-database-decorators";
+
+class User extends Table.with(HashModifier) {
+  @Field("string")
+  declare email: string;
+
+  @Hashed({ algorithm: "sha256" })
+  @Field("string")
+  declare password: string;
+
+  verifyPassword(plainPassword: string): boolean {
+    return this.testHash("password", plainPassword);
+  }
+}
+```
+
+#### How It Works
+
+- A random salt is generated and stored in the field's metadata on first write.
+- The value is hashed with the salt using the specified algorithm.
+- The `testHash` method (added by the mixin) hashes a candidate value with the stored salt and compares the result.
+
+#### Options
+
+| Option      | Type     | Default    | Description        |
+| ----------- | -------- | ---------- | ------------------ |
+| `algorithm` | `string` | `"sha256"` | Hashing algorithm. |
+
+#### Mixin Method
+
+The `HashModifier` mixin adds a `testHash` method to table instances:
+
+```typescript
+testHash(field: string, value: unknown): boolean
+```
+
+Returns `true` if `value`, when hashed, matches the stored hash for the given field.
+
+### LocalizationModifier
+
+The `LocalizationModifier` stores multiple language versions of a field value. Access a specific locale by calling `localize()` on the table instance.
+
+```typescript
+import { Table, Field, LocalizationModifier, Localized } from "@antelopejs/interface-database-decorators";
+
+class Product extends Table.with(LocalizationModifier) {
+  @Field("number")
+  declare price: number;
+
+  @Localized({ fallbackLocale: "en" })
+  @Field("string")
+  declare name: string;
+
+  @Localized({ fallbackLocale: "en" })
+  @Field("string")
+  declare description: string;
+}
+```
+
+#### Usage
+
+```typescript
+const product = new Product();
+product._id = "prod-123";
+product.price = 99.99;
+
+// Set localized content
+product.localize("en").name = "Premium Headphones";
+product.localize("fr").name = "Casque Premium";
+product.localize("es").name = "Auriculares Premium";
+
+// Read localized content
+const spanish = product.localize("es");
+console.log(spanish.name); // "Auriculares Premium"
+
+// Fallback to default locale when translation is missing
+const german = product.localize("de");
+console.log(german.name); // "Premium Headphones" (fallback)
+```
+
+#### Wildcard Key
+
+The wildcard key `"*"` retrieves or sets all translations at once:
+
+```typescript
+// Get all translations
+const allNames = product.localize("*").name;
+// { en: "Premium Headphones", fr: "Casque Premium", es: "Auriculares Premium" }
+
+// Set all translations
+product.localize("*").name = {
+  en: "Premium Headphones",
+  fr: "Casque Premium",
+  es: "Auriculares Premium",
+  de: "Premium-Kopfhoerer",
+};
+```
+
+#### Options
+
+| Option           | Type     | Description                                           |
+| ---------------- | -------- | ----------------------------------------------------- |
+| `fallbackLocale` | `string` | Locale to use when the requested locale is unavailable. |
+
+#### Mixin Method
+
+The `LocalizationModifier` mixin adds a `localize` method:
+
+```typescript
+localize(locale: string, fields?: Array<keyof this>): this
+```
+
+Sets the active locale for accessing localized fields. If `fields` is provided, only those fields are unlocked for the specified locale.
+
+### AutoDateModifier
+
+The `AutoDateModifier` automatically populates timestamp fields during insert and update operations. Use the `CreationTime` and `UpdateTime` decorators to mark fields.
+
+```typescript
+import { Table, CreationTime, UpdateTime } from "@antelopejs/interface-database-decorators";
+
+class Article extends Table {
+  declare title: string;
+
+  @CreationTime()
+  declare creationDate: Date;
+
+  @UpdateTime()
+  declare updateDate: Date;
+}
+```
+
+#### How It Works
+
+- On insert, both `CreationTime` and `UpdateTime` fields are set to the current date.
+- On update, `UpdateTime` fields are refreshed while `CreationTime` fields are removed from the payload so the original creation date is preserved.
+- This is an event-only modifier: it does not transform stored values and does not require adding a mixin through `Table.with()`.
+
+## Combine Multiple Modifiers
+
+Pass multiple modifier classes to `Table.with()`:
+
+```typescript
+import {
+  Table,
+  Field,
+  EncryptionModifier,
+  HashModifier,
+  LocalizationModifier,
+  Encrypted,
+  Hashed,
+  Localized,
+} from "@antelopejs/interface-database-decorators";
+
+class UserProfile extends Table.with(EncryptionModifier, HashModifier, LocalizationModifier) {
+  @Encrypted({ secretKey: process.env.SECRET_KEY || "default-key" })
+  @Field("any")
+  declare privateInfo: {
+    address: string;
+    phoneNumber: string;
+  };
+
+  @Hashed()
+  @Field("string")
+  declare password: string;
+
+  @Localized({ fallbackLocale: "en" })
+  @Field("string")
+  declare bio: string;
+}
+```
+
+## Create Custom Modifiers
+
+### OneWayModifier
+
+A `OneWayModifier` transforms data in one direction (when writing to the database). Use it for irreversible transformations like hashing.
+
+```typescript
+import { OneWayModifier, MixinSymbol, attachModifier } from "@antelopejs/interface-database-decorators";
+import { MakePropertyDecorator } from "@antelopejs/interface-core/decorators";
+import { createHash } from "crypto";
+
+class PrefixHashModifier extends OneWayModifier<string | undefined, [], {}, { algorithm?: string }> {
+  public readonly autolock = true;
+
+  public override lock(_locked: string | undefined, value: unknown) {
+    if (value === undefined) return undefined;
+    return createHash(this.options.algorithm || "sha256")
+      .update(JSON.stringify(value))
+      .digest("hex");
+  }
+
+  [MixinSymbol] = class {};
+}
+
+const PrefixHashed = MakePropertyDecorator(
+  (target, propertyKey, options?: { algorithm?: string }) => {
+    attachModifier(target.constructor, PrefixHashModifier, propertyKey, options || {});
+  },
+);
+```
+
+The generic parameters for `OneWayModifier<LockedType, Args, Meta, Options>` are:
+
+| Parameter    | Description                                         |
+| ------------ | --------------------------------------------------- |
+| `LockedType` | The type stored in the database after transformation |
+| `Args`       | Additional arguments for `lock` and `test`           |
+| `Meta`       | Per-field metadata stored alongside the value        |
+| `Options`    | Configuration passed via the decorator               |
+
+### TwoWayModifier
+
+A `TwoWayModifier` extends `OneWayModifier` with an `unlock` method for reversible transformations like encryption:
+
+```typescript
+import { TwoWayModifier, MixinSymbol, attachModifier } from "@antelopejs/interface-database-decorators";
+import { MakePropertyDecorator } from "@antelopejs/interface-core/decorators";
+
+class Base64Modifier extends TwoWayModifier<string, [], {}, { prefix?: string }> {
+  public readonly autolock = true;
+  public readonly autounlock = true;
+
+  public override lock(_locked: string | undefined, value: unknown) {
+    if (value === undefined) return undefined;
+    const prefix = this.options.prefix || "b64-";
+    return `${prefix}${Buffer.from(JSON.stringify(value)).toString("base64")}`;
+  }
+
+  public override unlock(locked: string) {
+    const prefix = this.options.prefix || "b64-";
+    const encoded = locked.substring(prefix.length);
+    return JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+  }
+
+  public override unlockrequest(data: any) {
+    return data;
+  }
+
+  [MixinSymbol] = class {};
+}
+
+const Base64Encoded = MakePropertyDecorator(
+  (target, propertyKey, options?: { prefix?: string }) => {
+    attachModifier(target.constructor, Base64Modifier, propertyKey, options || {});
+  },
+);
+```
+
+### ContainerModifier
+
+For modifiers that store multiple values in a key-value structure (like `LocalizationModifier`), extend `ContainerModifier`. It provides built-in support for the wildcard key `"*"` for bulk operations:
+
+```typescript
+import { ContainerModifier } from "@antelopejs/interface-database-decorators";
+
+class MyContainerModifier extends ContainerModifier<{}, { fallback?: string }> {
+  // Override unlock() to add fallback behavior
+  // Override unlockrequest() for query-time data access
+}
+```
+
+## Modifier Events
+
+Modifiers can hook into the data lifecycle by implementing event handler methods. These methods are called during data conversion and database operations:
+
+| Event           | Triggered When                            |
+| --------------- | ----------------------------------------- |
+| `fromPlainData` | After converting plain data to an instance |
+| `toPlainData`   | After converting an instance to plain data |
+| `fromDatabase`  | After reading from the database            |
+| `toDatabase`    | Before writing to the database             |
+| `insert`        | Before inserting a new record              |
+| `update`        | Before updating an existing record         |
+
+```typescript
+import { Modifier, MixinSymbol } from "@antelopejs/interface-database-decorators";
+
+class TimestampModifier extends Modifier {
+  public insert(instance: any, field: string) {
+    if (field === "createdAt" && !instance[field]) {
+      instance[field] = new Date();
+    }
+  }
+
+  public update(instance: any, field: string) {
+    if (field === "updatedAt") {
+      instance[field] = new Date();
+    }
+  }
+
+  [MixinSymbol] = class {};
+}
+```
+
+Event-only modifiers (without `lock`/`unlock`) are valid and useful for side effects like logging, validation, or auto-populating fields.

package/docs/4.data-models.md

@@ -0,0 +1,183 @@
+# Data Models
+
+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.
+
+## 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.
+
+```typescript
+import { BasicDataModel } from "@antelopejs/interface-database-decorators";
+import { User } from "./user.table";
+
+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) |
+
+When the table class has been decorated with `@RegisterTable`, the `tableName` parameter can be omitted.
+
+## Instantiate a Model
+
+A model instance requires a `SchemaInstance` from the database interface:
+
+```typescript
+import { Schema } from "@antelopejs/interface-database";
+
+const schema = Schema.get("myapp")!;
+const db = schema.instance();
+
+const userModel = new UserModel(db);
+```
+
+## CRUD Operations
+
+### Read
+
+```typescript
+// Get by primary key
+const user = await userModel.get("user-123");
+
+// Get by secondary index
+const admins = await userModel.getBy("role", "admin");
+
+// Get all documents
+const allUsers = await userModel.getAll();
+```
+
+### Create
+
+```typescript
+// Insert a single document
+const ids = await userModel.insert({
+  email: "alice@example.com",
+  name: "Alice",
+});
+
+// Insert multiple documents
+const batchIds = await userModel.insert([
+  { email: "bob@example.com", name: "Bob" },
+  { email: "carol@example.com", name: "Carol" },
+]);
+```
+
+### Update
+
+```typescript
+// Update by ID
+await userModel.update("user-123", { name: "Updated Name" });
+
+// Update by including the primary key in the object
+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.
+
+### Delete
+
+```typescript
+await userModel.delete("user-123");
+```
+
+## Data Conversion
+
+Data models include static methods for converting between different data representations:
+
+### `fromPlainData(obj)`
+
+Convert a plain JavaScript object into a Table class instance. Modifier transformations (like encryption and hashing) are applied during this conversion.
+
+```typescript
+const user = UserModel.fromPlainData({
+  _id: "user-123",
+  email: "user@example.com",
+  name: "John",
+});
+```
+
+### `fromDatabase(obj)`
+
+Convert a raw database record into a Table class instance. This attaches the class prototype and triggers the `fromDatabase` modifier event.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+const result = UserModel.validate({ name: "Alice", age: 30 });
+if (!result.ok) {
+  console.error(result.errors); // [{ field: "age", message: "not number" }, ...]
+}
+```
+
+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.
+
+```typescript
+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`.
+
+## Extend BasicDataModel
+
+Extend the generated model class to add custom query methods:
+
+```typescript
+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[]);
+  }
+
+  async register(email: string, name: string) {
+    const existing = await this.getBy("email", email);
+    if (existing.length > 0) {
+      throw new Error("Email already in use");
+    }
+    return this.insert({ email, name, status: "active" });
+  }
+}
+```
+
+## GetModel
+
+The `GetModel` function retrieves or creates a cached model instance for a given schema:
+
+```typescript
+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. The schema is resolved automatically from the `schemaName` property on the model class.
+
+## Modifier Integration
+
+Data models automatically apply all modifier transformations:
+
+- **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`.
+
+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.

package/docs/5.parameter-decoration.md

@@ -0,0 +1,155 @@
+# Parameter Decoration
+
+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
+
+The `Model` decorator injects a cached model instance. It can be used as either a parameter decorator or a property decorator.
+
+### Static Instance ID
+
+Pass a fixed instance ID to bind the model to a specific schema instance:
+
+```typescript
+import { Controller, Get } from "@antelopejs/interface-api";
+import { Model } from "@antelopejs/interface-database-decorators";
+import { UserModel } from "./user.model";
+
+class UsersController extends Controller("/users") {
+  @Get()
+  async listUsers(@Model(UserModel, "main") userModel: InstanceType<typeof UserModel>) {
+    return await userModel.getAll();
+  }
+}
+```
+
+### Dynamic Instance ID
+
+Pass a callback function to determine the instance ID at request time. The callback receives the request context:
+
+```typescript
+import { Controller, Get, Parameter } from "@antelopejs/interface-api";
+import { Model } from "@antelopejs/interface-database-decorators";
+import { UserModel } from "./user.model";
+
+class MultitenantController extends Controller("/tenants") {
+  @Get("/:tenantId/users")
+  async getTenantUsers(
+    @Parameter("tenantId") tenantId: string,
+    @Model(UserModel, (ctx) => `tenant-${ctx.params.tenantId}`) userModel: InstanceType<typeof UserModel>,
+  ) {
+    return await userModel.getAll();
+  }
+}
+```
+
+## Property Decoration
+
+The `Model` decorator also works as a property decorator. The model is initialized when the controller handles a request:
+
+```typescript
+import { Controller, Get, Parameter } from "@antelopejs/interface-api";
+import { Model } from "@antelopejs/interface-database-decorators";
+import { UserModel } from "./models";
+
+class UsersController extends Controller("/users") {
+  @Model(UserModel, "main")
+  private userModel!: InstanceType<typeof UserModel>;
+
+  @Get()
+  async listUsers() {
+    return await this.userModel.getAll();
+  }
+
+  @Get("/:id")
+  async getUser(@Parameter("id") id: string) {
+    return await this.userModel.get(id);
+  }
+}
+```
+
+## 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:
+
+```typescript
+import { GetModel } from "@antelopejs/interface-database-decorators";
+
+// These return the same instance
+const model1 = GetModel(UserModel, "main");
+const model2 = GetModel(UserModel, "main");
+
+// This returns a different instance
+const model3 = GetModel(UserModel, "other");
+```
+
+## Combine with API Decorators
+
+Model decorators compose naturally with other API decorators for building complete CRUD controllers:
+
+```typescript
+import { Controller, Get, Post, Put, Delete, RawBody, Parameter } from "@antelopejs/interface-api";
+import { Model } from "@antelopejs/interface-database-decorators";
+import { UserModel } from "./user.model";
+
+class UsersController extends Controller("/users") {
+  @Get()
+  async list(@Model(UserModel, "main") model: InstanceType<typeof UserModel>) {
+    return await model.getAll();
+  }
+
+  @Get("/:id")
+  async get(
+    @Parameter("id") id: string,
+    @Model(UserModel, "main") model: InstanceType<typeof UserModel>,
+  ) {
+    return await model.get(id);
+  }
+
+  @Post()
+  async create(
+    @RawBody() body: Buffer,
+    @Model(UserModel, "main") model: InstanceType<typeof UserModel>,
+  ) {
+    const data = JSON.parse(body.toString());
+    return await model.insert(data);
+  }
+
+  @Put("/:id")
+  async update(
+    @Parameter("id") id: string,
+    @RawBody() body: Buffer,
+    @Model(UserModel, "main") model: InstanceType<typeof UserModel>,
+  ) {
+    const data = JSON.parse(body.toString());
+    return await model.update(id, data);
+  }
+
+  @Delete("/:id")
+  async remove(
+    @Parameter("id") id: string,
+    @Model(UserModel, "main") model: InstanceType<typeof UserModel>,
+  ) {
+    return await model.delete(id);
+  }
+}
+```
+
+## Custom Parameter Providers
+
+For more complex injection logic, create custom parameter providers using the core API:
+
+```typescript
+import { SetParameterProvider } from "@antelopejs/interface-api";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import { MakeParameterAndPropertyDecorator } from "@antelopejs/interface-core/decorators";
+
+const CustomModel = MakeParameterAndPropertyDecorator(
+  (target, key, index, modelClass, resolver) => {
+    SetParameterProvider(target, key, index, (ctx) => {
+      const instanceId = resolver(ctx);
+      return GetModel(modelClass, instanceId);
+    });
+  },
+);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-database-decorators",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "AntelopeJS interface for database schema decorators and model definitions",
   "keywords": [
     "antelopejs",
@@ -18,7 +18,9 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "skills"
   ],
   "exports": {
     ".": {
@@ -148,6 +150,9 @@
   },
   "antelopeJs": {
     "standalone": true,
-    "test": "src/antelope.test.ts"
+    "test": "src/antelope.test.ts",
+    "skills": [
+      "./skills"
+    ]
   }
 }

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

@@ -0,0 +1,99 @@
+---
+name: database-decorators-interface
+description: Provides decorator-based database table definitions for AntelopeJS - a Table base class with RegisterTable/Index/Field/Fixture/Relation decorators, field modifiers (Encrypted, Hashed, Localized, CreationTime, UpdateTime), BasicDataModel CRUD models with validation, RegisterSchema provisioning, and the Model decorator for injecting models into API controllers. Use when code imports @antelopejs/interface-database-decorators (root or /table, /schema, /database, /model, /relation, /common, /modifiers/* subpaths), or when asked to define a database table or data model class, add encrypted/hashed/localized/timestamp fields, seed fixture data, register a schema, or inject a data model into an interface-api controller.
+category: antelopejs-interface
+tags: [database, decorators, orm, models, antelopejs]
+---
+
+# Database Decorators Interface
+
+Consumer-side decorator layer on top of `@antelopejs/interface-database` (AQL). This package itself has no proxy
+points and no provider side — you never `ImplementInterface` it. All actual database access flows through
+`Schema`/`Table` from `@antelopejs/interface-database`, which must be implemented by a database module (e.g. MongoDB).
+Peer interfaces required: `@antelopejs/interface-core`, `@antelopejs/interface-api` (only for the `Model` controller decorator), `@antelopejs/interface-database`.
+
+## Imports
+
+```typescript
+import { Table, Field, Index, Fixture } from "@antelopejs/interface-database-decorators/table";
+import { RegisterTable, getTablesForSchema } from "@antelopejs/interface-database-decorators/schema";
+import { RegisterSchema } from "@antelopejs/interface-database-decorators/database";
+import { BasicDataModel, GetModel, Model } from "@antelopejs/interface-database-decorators/model";
+import { Relation } from "@antelopejs/interface-database-decorators/relation";
+import { DatumStaticMetadata, getMetadata } from "@antelopejs/interface-database-decorators/common";
+import { CreationTime, UpdateTime } from "@antelopejs/interface-database-decorators/modifiers/autodate";
+import { Encrypted, EncryptionModifier } from "@antelopejs/interface-database-decorators/modifiers/encryption";
+import { Hashed, HashModifier } from "@antelopejs/interface-database-decorators/modifiers/hash";
+import { Localized, LocalizationModifier } from "@antelopejs/interface-database-decorators/modifiers/localization";
+import { Modifier, OneWayModifier, TwoWayModifier, attachModifier, toPlainData } from "@antelopejs/interface-database-decorators/modifiers/common";
+```
+
+The package root re-exports everything above and also imports `reflect-metadata` (see gotchas).
+
+## Minimal usage
+
+```typescript
+@RegisterTable("recipes", "cookbook") // (tableName, schemaName)
+class Recipe extends Table {
+  // _id: string is inherited as the primary key
+  @Index() @Field("string")
+  declare slug: string;
+  @Field("string")
+  declare tagline: string;
+}
+
+const RecipeModel = BasicDataModel(Recipe); // table name taken from @RegisterTable
+await RegisterSchema("cookbook"); // once at startup: provisions all tables registered for "cookbook", runs fixtures
+
+const recipes = GetModel(RecipeModel); // cached per (model class, instanceId)
+await recipes.insert({ slug: "grilled-halloumi", tagline: "Smoky skewers" }, { validate: true });
+const bySlug = await recipes.getBy("slug", "grilled-halloumi");
+const one = await recipes.get(bySlug[0]._id);
+await recipes.update(one._id, { tagline: "Smoky halloumi skewers" });
+await recipes.delete(one._id);
+```
+
+Controller injection (works as parameter or property decorator; second arg is a static `InstanceId` or a
+`(ctx: RequestContext) => InstanceId | undefined` callback — returning `undefined` falls back to the default schema instance):
+
+```typescript
+class RecipesController extends Controller("/recipes") {
+  @Get()
+  async list(@Model(RecipeModel) recipes: InstanceType<typeof RecipeModel>) {
+    return recipes.getAll();
+  }
+}
+```
+
+## Field modifiers
+
+```typescript
+class Chef extends Table.with(HashModifier, EncryptionModifier, LocalizationModifier) {
+  @Hashed() declare passphrase: string;                   // one-way; test via instance.testHash("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
+  @UpdateTime() declare lastActiveAt: Date;               // refreshed on insert and update
+}
+```
+
+## Gotchas
+
+- Only the package root imports `reflect-metadata`; if you import only subpaths, ensure `reflect-metadata`
+  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`.
+- 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.
+- `@Relation({ to: () => Target })` is declarative metadata only: no foreign-key enforcement, consumed by introspection tooling via `RelationStaticMetadata`.
+- `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).
+- `@Fixture` data is only inserted by `RegisterSchema` when the table is empty (count === 0).
+- `GetModel` caches by model class + instanceId; the same pair always returns the same instance.
+- Serialization of modified instances to plain JSON goes through `toPlainData` (auto-attached as `toJSON`).
+
+Deeper reference: this package's `docs/` chapters — Introduction, Table Definitions, Table Modifiers,
+Data Models, Parameter Decoration — and the shipped `.d.ts` files. Do not duplicate them here.