@antelopejs/interface-database-decorators 0.1.6 → 0.1.8

package/docs/2.table-definitions.md

@@ -23,7 +23,12 @@ class User extends Table {
 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";
+import {
+  Table,
+  Field,
+  EncryptionModifier,
+  Encrypted,
+} from "@antelopejs/interface-database-decorators";
 
 class SensitiveData extends Table.with(EncryptionModifier) {
   @Field("string")
@@ -56,16 +61,38 @@ class User extends Table {
 
 ### Options
 
-| Option  | Type     | Description                                     |
-| ------- | -------- | ----------------------------------------------- |
-| `group` | `string` | Assign the field to a named compound index group. |
+| Option          | Type      | Description                                                         |
+| --------------- | --------- | ------------------------------------------------------------------- |
+| `group`         | `string`  | Assign the field to a named compound index group.                   |
+| `crossInstance` | `boolean` | Also keep the index fast for queries that run across all instances. |
+
+### Cross-Instance Indexes
+
+Every index is scoped to the schema instance, so queries on a single instance always use it. Set `crossInstance: true` when the index is also queried across all instances (queries on the `CROSS_INSTANCE` instance), so the database driver maintains an additional index for those queries.
+
+The option never changes query results. Without it, cross-instance queries that name the index still return the same rows but run slower, and the driver logs a warning once per index. Leave it unset for indexes that are only queried within one instance, since each extra index costs storage and write time.
+
+```typescript
+class User extends Table {
+  @Index({ crossInstance: true })
+  @Field("string")
+  declare email: string;
+}
+```
+
+For a compound index, setting `crossInstance: true` on any field of the group applies it to the whole 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";
+import {
+  Table,
+  Field,
+  Index,
+  Relation,
+} from "@antelopejs/interface-database-decorators";
 
 class User extends Table {
   @Field("string")
@@ -93,7 +120,12 @@ class UserActivity extends Table {
 
 ```typescript
 import * as t from "io-ts";
-import { Table, Field, Index, RegisterTable } from "@antelopejs/interface-database-decorators";
+import {
+  Table,
+  Field,
+  Index,
+  RegisterTable,
+} from "@antelopejs/interface-database-decorators";
 
 @RegisterTable("orders", "shop")
 class Order extends Table {
@@ -116,7 +148,12 @@ Properties without `@Field` are omitted from `fields`. `@Field` stacks freely wi
 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";
+import {
+  Table,
+  Field,
+  Index,
+  Relation,
+} from "@antelopejs/interface-database-decorators";
 
 class Comment extends Table {
   @Index()
@@ -132,11 +169,11 @@ class Comment extends Table {
 
 ### 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). |
+| 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`.
 
@@ -145,7 +182,12 @@ class Comment extends Table {
 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";
+import {
+  Table,
+  Field,
+  Index,
+  RegisterTable,
+} from "@antelopejs/interface-database-decorators";
 
 @RegisterTable("users", "myapp")
 class User extends Table {
@@ -165,7 +207,11 @@ The first argument is the table name in the database, and the second is the sche
 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";
+import {
+  Table,
+  Field,
+  Fixture,
+} from "@antelopejs/interface-database-decorators";
 
 @Fixture(() => [
   { _id: "admin", name: "Administrator" },
@@ -205,7 +251,12 @@ class SystemConfig extends Table {
 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";
+import {
+  Table,
+  Field,
+  Index,
+  Relation,
+} from "@antelopejs/interface-database-decorators";
 
 class BaseEntity extends Table {
   @Field("date")
@@ -243,7 +294,9 @@ class Post extends BaseEntity {
 
 ## 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.
+The `RegisterSchema` function builds a `SchemaDefinition` from all tables registered for the given schema id (via `@RegisterTable`), constructs the `Schema` (which the adapter provisions), binds each table class to that `Schema` (see [Open a Table from its Class](#open-a-table-from-its-class)), then inserts any fixture data for tables that are empty.
+
+Call it in the module that declares the tables: the binding then follows that module's database, whichever module later uses the classes.
 
 ```typescript
 import { RegisterSchema } from "@antelopejs/interface-database-decorators";
@@ -253,8 +306,27 @@ await RegisterSchema("myapp");
 
 ### Parameters
 
-| Parameter  | Type     | Description                                                       |
-| ---------- | -------- | ----------------------------------------------------------------- |
+| Parameter  | Type     | Description                                                        |
+| ---------- | -------- | ------------------------------------------------------------------ |
 | `schemaId` | `string` | Schema id matching the `@RegisterTable(_, schemaId)` declarations. |
 
 `RegisterSchema` returns `Promise<void>`.
+
+## Open a Table from its Class
+
+`Table.table()` returns the AQL table a class describes, in the schema `RegisterSchema` bound it to:
+
+```typescript
+@RegisterTable("users", "myapp")
+class User extends Table {
+  declare name: string;
+}
+
+await RegisterSchema("myapp");
+
+User.table(); // default instance of "myapp"
+User.table("tenant-1"); // instance "tenant-1" (CROSS_INSTANCE is accepted too)
+User.table(db); // db.table("users") on a SchemaInstance you already hold
+```
+
+When given a `SchemaInstance`, `table()` takes the table from it as is: pass an instance of the class's own schema. A class that no `RegisterSchema` call bound throws, naming the class.

package/docs/3.table-modifiers.md

@@ -9,7 +9,12 @@ 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
-import { Table, Field, EncryptionModifier, Encrypted } from "@antelopejs/interface-database-decorators";
+import {
+  Table,
+  Field,
+  EncryptionModifier,
+  Encrypted,
+} from "@antelopejs/interface-database-decorators";
 
 class UserCredentials extends Table.with(EncryptionModifier) {
   @Encrypted({
@@ -39,18 +44,23 @@ class UserCredentials extends Table.with(EncryptionModifier) {
 
 #### 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. |
+| 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";
+import {
+  Table,
+  Field,
+  HashModifier,
+  Hashed,
+} from "@antelopejs/interface-database-decorators";
 
 class User extends Table.with(HashModifier) {
   @Field("string")
@@ -93,7 +103,12 @@ Returns `true` if `value`, when hashed, matches the stored hash for the given fi
 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";
+import {
+  Table,
+  Field,
+  LocalizationModifier,
+  Localized,
+} from "@antelopejs/interface-database-decorators";
 
 class Product extends Table.with(LocalizationModifier) {
   @Field("number")
@@ -150,8 +165,8 @@ product.localize("*").name = {
 
 #### Options
 
-| Option           | Type     | Description                                           |
-| ---------------- | -------- | ----------------------------------------------------- |
+| Option           | Type     | Description                                             |
+| ---------------- | -------- | ------------------------------------------------------- |
 | `fallbackLocale` | `string` | Locale to use when the requested locale is unavailable. |
 
 #### Mixin Method
@@ -169,7 +184,11 @@ Sets the active locale for accessing localized fields. If `fields` is provided,
 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";
+import {
+  Table,
+  CreationTime,
+  UpdateTime,
+} from "@antelopejs/interface-database-decorators";
 
 class Article extends Table {
   declare title: string;
@@ -204,7 +223,11 @@ import {
   Localized,
 } from "@antelopejs/interface-database-decorators";
 
-class UserProfile extends Table.with(EncryptionModifier, HashModifier, LocalizationModifier) {
+class UserProfile extends Table.with(
+  EncryptionModifier,
+  HashModifier,
+  LocalizationModifier,
+) {
   @Encrypted({ secretKey: process.env.SECRET_KEY || "default-key" })
   @Field("any")
   declare privateInfo: {
@@ -229,11 +252,20 @@ class UserProfile extends Table.with(EncryptionModifier, HashModifier, Localizat
 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 {
+  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 }> {
+class PrefixHashModifier extends OneWayModifier<
+  string | undefined,
+  [],
+  {},
+  { algorithm?: string }
+> {
   public readonly autolock = true;
 
   public override lock(_locked: string | undefined, value: unknown) {
@@ -248,15 +280,20 @@ class PrefixHashModifier extends OneWayModifier<string | undefined, [], {}, { al
 
 const PrefixHashed = MakePropertyDecorator(
   (target, propertyKey, options?: { algorithm?: string }) => {
-    attachModifier(target.constructor, PrefixHashModifier, propertyKey, options || {});
+    attachModifier(
+      target.constructor,
+      PrefixHashModifier,
+      propertyKey,
+      options || {},
+    );
   },
 );
 ```
 
 The generic parameters for `OneWayModifier<LockedType, Args, Meta, Options>` are:
 
-| Parameter    | Description                                         |
-| ------------ | --------------------------------------------------- |
+| 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        |
@@ -267,10 +304,19 @@ The generic parameters for `OneWayModifier<LockedType, Args, Meta, Options>` are
 A `TwoWayModifier` extends `OneWayModifier` with an `unlock` method for reversible transformations like encryption:
 
 ```typescript
-import { TwoWayModifier, MixinSymbol, attachModifier } from "@antelopejs/interface-database-decorators";
+import {
+  TwoWayModifier,
+  MixinSymbol,
+  attachModifier,
+} from "@antelopejs/interface-database-decorators";
 import { MakePropertyDecorator } from "@antelopejs/interface-core/decorators";
 
-class Base64Modifier extends TwoWayModifier<string, [], {}, { prefix?: string }> {
+class Base64Modifier extends TwoWayModifier<
+  string,
+  [],
+  {},
+  { prefix?: string }
+> {
   public readonly autolock = true;
   public readonly autounlock = true;
 
@@ -295,7 +341,12 @@ class Base64Modifier extends TwoWayModifier<string, [], {}, { prefix?: string }>
 
 const Base64Encoded = MakePropertyDecorator(
   (target, propertyKey, options?: { prefix?: string }) => {
-    attachModifier(target.constructor, Base64Modifier, propertyKey, options || {});
+    attachModifier(
+      target.constructor,
+      Base64Modifier,
+      propertyKey,
+      options || {},
+    );
   },
 );
 ```
@@ -317,8 +368,8 @@ class MyContainerModifier extends ContainerModifier<{}, { fallback?: string }> {
 
 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                            |
-| --------------- | ----------------------------------------- |
+| 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            |
@@ -327,7 +378,10 @@ Modifiers can hook into the data lifecycle by implementing event handler methods
 | `update`        | Before updating an existing record         |
 
 ```typescript
-import { Modifier, MixinSymbol } from "@antelopejs/interface-database-decorators";
+import {
+  Modifier,
+  MixinSymbol,
+} from "@antelopejs/interface-database-decorators";
 
 class TimestampModifier extends Modifier {
   public insert(instance: any, field: string) {

package/docs/4.data-models.md

@@ -15,10 +15,10 @@ const UserModel = BasicDataModel(User, "users");
 
 ### Parameters
 
-| Parameter   | Type              | Description                                          |
-| ----------- | ----------------- | ---------------------------------------------------- |
-| `dataType`  | `Constructible<T>`| The Table class representing your table              |
-| `tableName` | `string`          | The table name in the database (optional if `@RegisterTable` is used) |
+| Parameter   | Type               | Description                                                           |
+| ----------- | ------------------ | --------------------------------------------------------------------- |
+| `dataType`  | `Constructible<T>` | The Table class 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.
 
@@ -170,7 +170,7 @@ 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.
+Model instances are cached by class and instance ID, so repeated calls with the same arguments return the same instance. A model built by `BasicDataModel` uses the schema its table class was bound to by `RegisterSchema`, so it stays on the declaring module's database even when another module calls `GetModel`; an unbound table class throws. A custom model class without a `tableClass` is resolved from its `schemaName` with `Schema.get`.
 
 ## Modifier Integration
 

package/docs/5.parameter-decoration.md

@@ -17,7 +17,9 @@ import { UserModel } from "./user.model";
 
 class UsersController extends Controller("/users") {
   @Get()
-  async listUsers(@Model(UserModel, "main") userModel: InstanceType<typeof UserModel>) {
+  async listUsers(
+    @Model(UserModel, "main") userModel: InstanceType<typeof UserModel>,
+  ) {
     return await userModel.getAll();
   }
 }
@@ -36,7 +38,8 @@ 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>,
+    @Model(UserModel, (ctx) => `tenant-${ctx.params.tenantId}`)
+    userModel: InstanceType<typeof UserModel>,
   ) {
     return await userModel.getAll();
   }
@@ -88,7 +91,15 @@ const model3 = GetModel(UserModel, "other");
 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 {
+  Controller,
+  Get,
+  Post,
+  Put,
+  Delete,
+  RawBody,
+  Parameter,
+} from "@antelopejs/interface-api";
 import { Model } from "@antelopejs/interface-database-decorators";
 import { UserModel } from "./user.model";
 

package/package.json

@@ -1,27 +1,63 @@
 {
   "name": "@antelopejs/interface-database-decorators",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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",
     "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",
@@ -73,81 +109,54 @@
     },
     "./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.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",
     "@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",