@antelopejs/interface-database-decorators 0.1.4 → 0.1.6

package/dist/tests/schema.test.js.map

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

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.