@antelopejs/interface-database-decorators 0.1.6 → 0.1.8

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

@@ -15,17 +15,50 @@ Peer interfaces required: `@antelopejs/interface-core`, `@antelopejs/interface-a
 ## Imports
 
 ```typescript
-import { Table, Field, Index, Fixture } from "@antelopejs/interface-database-decorators/table";
-import { RegisterTable, getTablesForSchema } from "@antelopejs/interface-database-decorators/schema";
+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 {
+  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";
+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).
@@ -36,7 +69,8 @@ The package root re-exports everything above and also imports `reflect-metadata`
 @RegisterTable("recipes", "cookbook") // (tableName, schemaName)
 class Recipe extends Table {
   // _id: string is inherited as the primary key
-  @Index() @Field("string")
+  @Index()
+  @Field("string")
   declare slug: string;
   @Field("string")
   declare tagline: string;
@@ -46,7 +80,10 @@ const RecipeModel = BasicDataModel(Recipe); // table name taken from @RegisterTa
 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 });
+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" });
@@ -68,12 +105,16 @@ class RecipesController extends Controller("/recipes") {
 ## Field modifiers
 
 ```typescript
-class Chef extends Table.with(HashModifier, EncryptionModifier, LocalizationModifier) {
-  @Hashed() declare passphrase: string;                   // one-way; test via instance.testHash("passphrase", value)
+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
+  @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
 }
 ```
 
@@ -91,8 +132,12 @@ class Chef extends Table.with(HashModifier, EncryptionModifier, LocalizationModi
   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.
+- `RegisterSchema` binds each registered table class to the `Schema` it builds; call it in the module that declares the tables. `User.table()`, `User.table(instanceId)` and `User.table(db)` then return the class's AQL table, and `GetModel` builds `BasicDataModel` models on that same schema, even when another module (bound to another database) calls them. An unbound class throws rather than looking a schema up by id.
 - 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,