@antelopejs/interface-database-decorators 0.1.8 → 0.1.9

package/README.md

@@ -1,30 +1,113 @@
-# Interface Database Decorators
+# @antelopejs/interface-database-decorators
 
 <div align="center">
-<a href="https://www.npmjs.com/package/@antelopejs/interface-database-decorators"><img src="https://img.shields.io/npm/v/@antelopejs/interface-database-decorators?style=for-the-badge&labelColor=000000&color=000000" alt="npm"></a>
-<a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=for-the-badge&labelColor=000000"></a>
-<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
-<a href="./docs/1.introduction.md"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
+<a href="https://www.npmjs.com/package/@antelopejs/interface-database-decorators"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-database-decorators?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-database-decorators?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
+<a href="https://interfaces.antelopejs.com/docs/database-decorators"><img alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
 </div>
 
-A structured framework for implementing database operations using TypeScript decorators. Interface Database Decorators provides a flexible, object-oriented approach to defining database tables, models, and operations with full type safety, including built-in support for field-level encryption, hashing, and localization.
+Database tables and data models as TypeScript classes, on top of [`@antelopejs/interface-database`](https://github.com/AntelopeJS/interface-database): declare fields and indexes with decorators, then read and write rows through a typed model.
 
-## Installation
+## What it offers
+
+- `Table`, `@RegisterTable`, `@Field`, `@Index` and `@Fixture` declare tables, indexes and seed rows; `RegisterSchema` provisions them.
+- `BasicDataModel` and `GetModel` give each table typed CRUD methods with optional validation.
+- `@Encrypted`, `@Hashed`, `@Localized`, `@CreationTime` and `@UpdateTime` transform field values on write and read.
+- `@Model` injects a model into an [`@antelopejs/interface-api`](https://github.com/AntelopeJS/interface-api) controller.
+
+## Implementations
+
+The package runs in your module and has no implementing module of its own. The project needs a module that implements `@antelopejs/interface-database`:
+
+| Module                                                             | Notes     |
+| ------------------------------------------------------------------ | --------- |
+| [`@antelopejs/mongodb`](https://github.com/AntelopeJS/mongodb)     | MongoDB   |
+| [`@antelopejs/rethinkdb`](https://github.com/AntelopeJS/rethinkdb) | RethinkDB |
+
+## Install
+
+Add the package to the module that declares tables:
+
+```bash
+pnpm add @antelopejs/interface-database-decorators
+```
+
+Then add a database module to the project:
 
 ```bash
-npm install @antelopejs/interface-database-decorators
+ajs project modules add @antelopejs/mongodb
 ```
 
+## Quick start
+
+```ts
+import {
+  BasicDataModel,
+  Field,
+  GetModel,
+  Index,
+  RegisterSchema,
+  RegisterTable,
+  Table,
+} from "@antelopejs/interface-database-decorators";
+
+@RegisterTable("recipes", "cookbook")
+class Recipe extends Table {
+  @Index()
+  @Field("string")
+  declare slug: string;
+
+  @Field("string")
+  declare tagline: string;
+}
+
+class RecipeModel extends BasicDataModel(Recipe) {}
+
+export async function construct() {
+  await RegisterSchema("cookbook");
+}
+
+export async function start() {
+  const recipes = GetModel(RecipeModel);
+  await recipes.insert({ slug: "grilled-halloumi", tagline: "Smoky skewers" });
+  const [recipe] = await recipes.getBy("slug", "grilled-halloumi");
+  await recipes.update(recipe._id, { tagline: "Smoky halloumi skewers" });
+}
+```
+
+`RegisterSchema` creates every table registered for the schema and inserts their fixtures. Call it once, in the module that declares the tables.
+
 ## Documentation
 
-Detailed documentation is available in the `docs` directory:
+- [Introduction](./docs/1.introduction.md)
+- [Table definitions](./docs/2.table-definitions.md)
+- [Table modifiers](./docs/3.table-modifiers.md)
+- [Data models](./docs/4.data-models.md)
+- [Parameter decoration](./docs/5.parameter-decoration.md)
+
+## Compatibility
+
+Requires AntelopeJS core `1.x` and the following peer dependencies:
 
-- [Introduction](./docs/1.introduction.md) - Overview and dependencies
-- [Table Definitions](./docs/2.table-definitions.md) - Define database tables with decorators, indexes, and fixtures
-- [Table Modifiers](./docs/3.table-modifiers.md) - Encryption, hashing, localization, and custom modifier creation
-- [Data Models](./docs/4.data-models.md) - Create and use data models with CRUD operations
-- [Parameter Decoration](./docs/5.parameter-decoration.md) - Inject models into API controllers
+<!-- docs-compat: ./package.json#peerDependencies -->
+
+| Package                          | Range             |
+| -------------------------------- | ----------------- |
+| `@antelopejs/interface-api`      | `>=0.0.15 <1.0.0` |
+| `@antelopejs/interface-core`     | `>=0.2.4 <1.0.0`  |
+| `@antelopejs/interface-database` | `>=0.1.10 <1.0.0` |
+
+## Contributing
+
+Read [CONTRIBUTING.md](./CONTRIBUTING.md) before you open a pull request. The local checks are:
+
+```bash
+pnpm install
+pnpm lint
+pnpm test
+```
 
 ## License
 
-This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+[Apache-2.0](./LICENSE)

package/docs/2.table-definitions.md

@@ -30,17 +30,22 @@ import {
   Encrypted,
 } from "@antelopejs/interface-database-decorators";
 
+const secretKey = process.env.ENCRYPTION_KEY;
+if (!secretKey || Buffer.byteLength(secretKey, "utf8") !== 32) {
+  throw new Error("ENCRYPTION_KEY must contain exactly 32 UTF-8 bytes");
+}
+
 class SensitiveData extends Table.with(EncryptionModifier) {
   @Field("string")
   declare publicContent: string;
 
-  @Encrypted({ secretKey: process.env.SECRET_KEY || "default-key" })
+  @Encrypted({ secretKey })
   @Field("string")
   declare secureContent: string;
 }
 ```
 
-For detailed information about modifiers, see [Table Modifiers](./3.table-modifiers.md).
+Provide a high-entropy key through your secret manager; do not use a default key. See [Table Modifiers](./3.table-modifiers.md#encryptionmodifier) for key format and date precision constraints.
 
 ## The Index Decorator
 
@@ -161,7 +166,7 @@ class Comment extends Table {
   @Relation({ to: () => Post })
   declare postId: string;
 
-  @Field("string")
+  @Field(["string"])
   @Relation({ to: () => Tag, many: true })
   declare tagIds: string[];
 }

package/docs/3.table-modifiers.md

@@ -8,7 +8,9 @@ Table modifiers transform field values as they are stored in and retrieved from
 
 The `EncryptionModifier` encrypts field values before storing them and decrypts them on retrieval. Both operations happen transparently.
 
-```typescript
+The default `aes-256-gcm` algorithm requires a key of exactly 32 bytes. `secretKey` is passed to Node's cipher as a UTF-8 string, without hex or base64 decoding. Supply a high-entropy, 32-byte UTF-8 value from a secret manager, keep it stable for existing ciphertext, and fail startup if it is missing or invalid; a 64-character hex encoding is not a 32-byte key for this API.
+
+```ts docs-check
 import {
   Table,
   Field,
@@ -16,16 +18,21 @@ import {
   Encrypted,
 } from "@antelopejs/interface-database-decorators";
 
+const secretKey = process.env.ENCRYPTION_KEY;
+if (!secretKey || Buffer.byteLength(secretKey, "utf8") !== 32) {
+  throw new Error("ENCRYPTION_KEY must contain exactly 32 UTF-8 bytes");
+}
+
 class UserCredentials extends Table.with(EncryptionModifier) {
   @Encrypted({
-    secretKey: process.env.ENCRYPTION_KEY || "default-key",
+    secretKey,
     algorithm: "aes-256-gcm",
     ivSize: 16,
   })
   @Field("string")
   declare creditCardNumber: string;
 
-  @Encrypted({ secretKey: process.env.ENCRYPTION_KEY || "default-key" })
+  @Encrypted({ secretKey })
   @Field("any")
   declare personalData: {
     ssn: string;
@@ -40,7 +47,7 @@ class UserCredentials extends Table.with(EncryptionModifier) {
 - 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.
+- Date objects are restored as `Date` instances, but the encoder uses `toUTCString()`, which drops milliseconds. Encrypted dates round-trip only to whole-second precision.
 
 #### Options
 
@@ -52,7 +59,7 @@ class UserCredentials extends Table.with(EncryptionModifier) {
 
 ### 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.
+The `HashModifier` stores a salted one-way hash of field values. Unlike encryption, hashing is irreversible -- you cannot retrieve the original value. Its default SHA-256 hash is fast, not a password-hardening function; use a dedicated password hashing library for production credentials.
 
 ```typescript
 import {
@@ -147,15 +154,18 @@ console.log(german.name); // "Premium Headphones" (fallback)
 
 #### Wildcard Key
 
-The wildcard key `"*"` retrieves or sets all translations at once:
+The wildcard key `"*"` retrieves or sets all translations at once at runtime. `localize()` does not change the property's TypeScript type, so a field declared as `string` needs an explicit view for bulk access:
 
 ```typescript
 // Get all translations
-const allNames = product.localize("*").name;
+const translations = product.localize("*") as unknown as {
+  name: Record<string, string>;
+};
+const allNames = translations.name;
 // { en: "Premium Headphones", fr: "Casque Premium", es: "Auriculares Premium" }
 
 // Set all translations
-product.localize("*").name = {
+translations.name = {
   en: "Premium Headphones",
   fr: "Casque Premium",
   es: "Auriculares Premium",
@@ -177,7 +187,7 @@ The `LocalizationModifier` mixin adds a `localize` method:
 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.
+Sets the active locale for accessing localized fields and returns the same, mutated object. It does not make a locale-specific copy: `spanish`, `german`, and `product` above all refer to the same object, and subsequent calls change what all those references read. If `fields` is provided, only those fields are unlocked for the specified locale. Copy the values you need before changing locales, and do not share one instance between concurrent locale-specific operations.
 
 ### AutoDateModifier
 
@@ -223,12 +233,17 @@ import {
   Localized,
 } from "@antelopejs/interface-database-decorators";
 
+const secretKey = process.env.ENCRYPTION_KEY;
+if (!secretKey || Buffer.byteLength(secretKey, "utf8") !== 32) {
+  throw new Error("ENCRYPTION_KEY must contain exactly 32 UTF-8 bytes");
+}
+
 class UserProfile extends Table.with(
   EncryptionModifier,
   HashModifier,
   LocalizationModifier,
 ) {
-  @Encrypted({ secretKey: process.env.SECRET_KEY || "default-key" })
+  @Encrypted({ secretKey })
   @Field("any")
   declare privateInfo: {
     address: string;
@@ -303,16 +318,17 @@ The generic parameters for `OneWayModifier<LockedType, Args, Meta, Options>` are
 
 A `TwoWayModifier` extends `OneWayModifier` with an `unlock` method for reversible transformations like encryption:
 
-```typescript
+```ts docs-check
 import {
   TwoWayModifier,
   MixinSymbol,
   attachModifier,
 } from "@antelopejs/interface-database-decorators";
 import { MakePropertyDecorator } from "@antelopejs/interface-core/decorators";
+import type { ValueProxy } from "@antelopejs/interface-database";
 
 class Base64Modifier extends TwoWayModifier<
-  string,
+  string | undefined,
   [],
   {},
   { prefix?: string }
@@ -326,14 +342,17 @@ class Base64Modifier extends TwoWayModifier<
     return `${prefix}${Buffer.from(JSON.stringify(value)).toString("base64")}`;
   }
 
-  public override unlock(locked: string) {
+  public override unlock(locked: string | undefined): unknown {
+    if (locked === undefined) return undefined;
     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;
+  public override unlockrequest(
+    data: ValueProxy<string | undefined>,
+  ): ValueProxy<unknown> {
+    return data.cast<unknown>();
   }
 
   [MixinSymbol] = class {};
@@ -351,6 +370,8 @@ const Base64Encoded = MakePropertyDecorator(
 );
 ```
 
+Base64 is encoding, not encryption. This example's `unlockrequest()` leaves the encoded value unchanged in database expressions; only instance reads decode it.
+
 ### 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:

package/docs/4.data-models.md

@@ -37,6 +37,18 @@ const userModel = new UserModel(db);
 
 ## CRUD Operations
 
+For a model created with `BasicDataModel(User)`, the return values are:
+
+| Method                               | Declared return                  | Meaning                                                             |
+| ------------------------------------ | -------------------------------- | ------------------------------------------------------------------- |
+| `get(id)`                            | `PromiseLike<User \| undefined>` | The converted row, or `undefined` when the provider returns no row. |
+| `getBy(index, ...keys)` / `getAll()` | `PromiseLike<User[]>`            | Converted rows, not an AQL query to chain.                          |
+| `insert(data, options?)`             | `Promise<string[]>`              | Inserted document IDs.                                              |
+| `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.
+
 ### Read
 
 ```typescript

package/docs/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "noEmit": true,
+    "composite": false,
+    "incremental": false
+  },
+  "include": ["../src/**/*.ts", "./**/*.ts"]
+}

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@antelopejs/interface-database-decorators",
-  "version": "0.1.8",
-  "description": "AntelopeJS interface for database schema decorators and model definitions",
+  "version": "0.1.9",
+  "description": "AntelopeJS decorators for database tables and typed data models, with encrypted, hashed and localized fields",
   "keywords": [
     "antelopejs",
     "database",
     "decorators",
     "interface",
+    "model",
     "orm"
   ],
+  "homepage": "https://interfaces.antelopejs.com/docs/database-decorators",
+  "bugs": {
+    "url": "https://github.com/AntelopeJS/interface-database-decorators/issues"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -129,11 +134,11 @@
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@antelopejs/core": "^1.13.4",
-    "@antelopejs/interface-api": "^0.0.13",
-    "@antelopejs/interface-core": "^0.1.1",
-    "@antelopejs/interface-database": "^0.1.8",
-    "@antelopejs/tooling-configs": "^0.0.6",
+    "@antelopejs/core": "^1.16.0",
+    "@antelopejs/interface-api": "^0.0.15",
+    "@antelopejs/interface-core": "^0.2.4",
+    "@antelopejs/interface-database": "^0.1.10",
+    "@antelopejs/tooling-configs": "^0.0.9",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
@@ -152,9 +157,9 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@antelopejs/interface-api": ">=0.0.13 <1.0.0",
-    "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.8 <1.0.0"
+    "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
+    "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.10 <1.0.0"
   },
   "packageManager": "pnpm@10.6.5",
   "antelopeJs": {