@antelopejs/interface-database-decorators 0.1.5 → 0.1.7

package/docs/5.parameter-decoration.md

@@ -0,0 +1,166 @@
+# 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,25 +1,63 @@
 {
   "name": "@antelopejs/interface-database-decorators",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "AntelopeJS interface for database schema decorators and model definitions",
   "keywords": [
     "antelopejs",
-    "interface",
     "database",
     "decorators",
+    "interface",
     "orm"
   ],
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AntelopeJS/interface-database-decorators.git"
   },
-  "license": "Apache-2.0",
-  "packageManager": "pnpm@10.6.5",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "skills"
   ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "common": [
+        "dist/common.d.ts"
+      ],
+      "database": [
+        "dist/database.d.ts"
+      ],
+      "model": [
+        "dist/model.d.ts"
+      ],
+      "relation": [
+        "dist/relation.d.ts"
+      ],
+      "schema": [
+        "dist/schema.d.ts"
+      ],
+      "table": [
+        "dist/table.d.ts"
+      ],
+      "modifiers/autodate": [
+        "dist/modifiers/autodate.d.ts"
+      ],
+      "modifiers/common": [
+        "dist/modifiers/common.d.ts"
+      ],
+      "modifiers/encryption": [
+        "dist/modifiers/encryption.d.ts"
+      ],
+      "modifiers/hash": [
+        "dist/modifiers/hash.d.ts"
+      ],
+      "modifiers/localization": [
+        "dist/modifiers/localization.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -71,83 +109,59 @@
     },
     "./package.json": "./package.json"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "build": "rimraf dist && tsc",
-    "format": "biome format --write .",
-    "lint:fix": "biome check --write .",
-    "lint": "biome check .",
+    "format": "oxfmt .",
+    "lint:fix": "oxlint --fix",
+    "lint": "oxlint",
     "prepack": "pnpm run build",
     "release": "pnpm run lint && pnpm run prepack && release-it",
-    "test": "pnpm run build && ajs module test ."
+    "test": "pnpm run build && ajs module test .",
+    "format:check": "oxfmt --check .",
+    "knip": "knip"
   },
   "dependencies": {
     "randomstring": "^1.3.1",
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@antelopejs/interface-api": "^0.0.5",
-    "@antelopejs/interface-core": "^0.0.5",
-    "@antelopejs/interface-database": "^0.1.3",
-    "@biomejs/biome": "2.3.2",
+    "@antelopejs/core": "^1.9.1",
+    "@antelopejs/interface-api": "^0.0.13",
+    "@antelopejs/interface-core": "^0.1.1",
+    "@antelopejs/interface-database": "^0.1.8",
+    "@antelopejs/tooling-configs": "^0.0.6",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
     "@types/randomstring": "^1.3.0",
     "@types/semver": "^7.7.1",
     "chai": "^4.5.0",
+    "eslint-plugin-perfectionist": "^5.11.0",
+    "knip": "^6.34.0",
     "mongodb-memory-server-core": "^10.4.3",
+    "oxfmt": "^0.66.0",
+    "oxlint": "1.81.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "release-it": "^19.2.4",
     "release-it-changelogen": "^0.1.0",
     "rimraf": "^6.1.3",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@antelopejs/interface-api": ">=0.0.3 <1.0.0",
-    "@antelopejs/interface-core": ">=0.0.3 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.1 <1.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "typesVersions": {
-    "*": {
-      "common": [
-        "dist/common.d.ts"
-      ],
-      "database": [
-        "dist/database.d.ts"
-      ],
-      "model": [
-        "dist/model.d.ts"
-      ],
-      "relation": [
-        "dist/relation.d.ts"
-      ],
-      "schema": [
-        "dist/schema.d.ts"
-      ],
-      "table": [
-        "dist/table.d.ts"
-      ],
-      "modifiers/autodate": [
-        "dist/modifiers/autodate.d.ts"
-      ],
-      "modifiers/common": [
-        "dist/modifiers/common.d.ts"
-      ],
-      "modifiers/encryption": [
-        "dist/modifiers/encryption.d.ts"
-      ],
-      "modifiers/hash": [
-        "dist/modifiers/hash.d.ts"
-      ],
-      "modifiers/localization": [
-        "dist/modifiers/localization.d.ts"
-      ]
-    }
+    "@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"
   },
+  "packageManager": "pnpm@10.6.5",
   "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,143 @@
+---
+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).
+- 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.
+- `@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.