@antelopejs/interface-database-decorators 0.1.9 → 0.1.11

package/docs/3.table-modifiers.md

@@ -95,6 +95,8 @@ class User extends Table.with(HashModifier) {
 | ----------- | -------- | ---------- | ------------------ |
 | `algorithm` | `string` | `"sha256"` | Hashing algorithm. |
 
+`LocalizationModifier.fallbackLocaleOf(TableClass, field)` returns a field's `fallbackLocale`, or `undefined` when the field is not localized or declares none. Generated forms use it to require a value in that locale.
+
 #### Mixin Method
 
 The `HashModifier` mixin adds a `testHash` method to table instances:
@@ -175,9 +177,9 @@ translations.name = {
 
 #### Options
 
-| Option           | Type     | Description                                             |
-| ---------------- | -------- | ------------------------------------------------------- |
-| `fallbackLocale` | `string` | Locale to use when the requested locale is unavailable. |
+| Option           | Type     | Description                                                           |
+| ---------------- | -------- | --------------------------------------------------------------------- |
+| `fallbackLocale` | `string` | Locale to use when the requested locale has no value or an empty one. |
 
 #### Mixin Method
 
@@ -187,7 +189,11 @@ The `LocalizationModifier` mixin adds a `localize` method:
 localize(locale: string, fields?: Array<keyof this>): this
 ```
 
-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.
+`localize()` changes the active locale and returns the same object, not a locale-specific copy.
+
+- **References share state.** `spanish`, `german`, and `product` above refer to one object. A later `localize()` call changes what all three references read.
+- **Fields can be restricted.** When you supply `fields`, only those fields are unlocked for the selected locale.
+- **Copy values before switching.** Save the values you need before changing locales, and do not share one instance between concurrent locale-specific operations.
 
 ### AutoDateModifier
 

package/docs/4.data-models.md

@@ -100,6 +100,16 @@ await userModel.delete("user-123");
 
 Data models include static methods for converting between different data representations:
 
+| Starting value          | Conversion      | Result                                            | Persists data? |
+| ----------------------- | --------------- | ------------------------------------------------- | -------------- |
+| Plain application input | `fromPlainData` | Table instance with input modifier events applied | No             |
+| Raw database record     | `fromDatabase`  | Table instance with read modifier events applied  | No             |
+| Table instance          | `toDatabase`    | Plain storage representation                      | No             |
+
+Use `insert` or `update` to perform a write; conversion alone does not save anything. Reads through `get`, `getBy`, and `getAll` apply `fromDatabase` for you. A custom query through `model.table` returns AQL results, so apply conversion explicitly when you need model instances.
+
+![Model writes convert input, trigger insert or update events, convert to storage, then execute AQL. Model reads convert fetched records; direct model.table queries bypass model conversion.](./assets/model-conversion.svg){width="480"}
+
 ### `fromPlainData(obj)`
 
 Convert a plain JavaScript object into a Table class instance. Modifier transformations (like encryption and hashing) are applied during this conversion.
@@ -152,6 +162,8 @@ await userModel.update("user-123", { name: "Bob" }, { validate: true });
 
 Extend the generated model class to add custom query methods:
 
+The `register` method below checks for an existing email to provide early feedback. It does not guarantee uniqueness under concurrent writes; enforce that constraint in the database where supported and handle conflicts.
+
 ```typescript
 const UserModelBase = BasicDataModel(User, "users");
 

package/docs/5.parameter-decoration.md

@@ -29,6 +29,8 @@ class UsersController extends Controller("/users") {
 
 Pass a callback function to determine the instance ID at request time. The callback receives the request context:
 
+Authorize access to the requested tenant before reading or writing through the injected model. The callback selects an instance; a URL parameter alone is not proof that the caller belongs to that tenant.
+
 ```typescript
 import { Controller, Get, Parameter } from "@antelopejs/interface-api";
 import { Model } from "@antelopejs/interface-database-decorators";
@@ -90,6 +92,8 @@ const model3 = GetModel(UserModel, "other");
 
 Model decorators compose naturally with other API decorators for building complete CRUD controllers:
 
+This example demonstrates injection, not a complete public API policy. Before exposing writes, reject malformed or non-object JSON, allow only permitted fields, validate their values, and authorize the operation. `JSON.parse` and `@Model` do not provide these checks; string-token `@Field` declarations do not validate input either.
+
 ```typescript
 import {
   Controller,

package/docs/assets/model-conversion.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 460" role="img" aria-labelledby="title desc">
+  <title id="title">Model conversion and database execution</title>
+  <desc id="desc">Writing through a model converts plain input, triggers insert or update modifier events, converts to storage, and executes an AQL write. Reading through a model converts a fetched record with fromDatabase. Static conversion functions do not persist data, and model.table returns raw AQL results.</desc>
+  <rect width="480" height="460" rx="16" fill="#f5f7fb"/>
+  <g font-family="system-ui, sans-serif" fill="#172b45">
+    <text x="24" y="36" font-size="20" font-weight="700">Conversion is not persistence</text>
+    <rect x="24" y="58" width="432" height="160" rx="10" fill="#e1ecfa"/>
+    <text x="42" y="87" font-size="18" font-weight="700">Model write · insert / update</text>
+    <text x="42" y="118" font-size="16">Input → fromPlainData</text>
+    <text x="42" y="145" font-size="16">→ insert / update modifier events</text>
+    <text x="42" y="172" font-size="16">→ toDatabase → storage representation</text>
+    <text x="42" y="199" font-size="16">→ AQL write → IDs / modified count</text>
+    <rect x="24" y="238" width="432" height="100" rx="10" fill="#d9eee8"/>
+    <text x="42" y="267" font-size="18" font-weight="700">Model read · get / getBy / getAll</text>
+    <text x="42" y="296" font-size="16">AQL read → fetched record</text>
+    <text x="42" y="323" font-size="16">→ fromDatabase → table instance</text>
+    <text x="24" y="375" font-size="16" font-weight="700">Taking the direct AQL path?</text>
+    <text x="24" y="403" font-size="16">model.table builds queries without model conversion.</text>
+    <text x="24" y="431" font-size="16">Apply fromDatabase to raw rows when needed.</text>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-database-decorators",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "AntelopeJS decorators for database tables and typed data models, with encrypted, hashed and localized fields",
   "keywords": [
     "antelopejs",
@@ -127,7 +127,17 @@
     "release": "pnpm run lint && pnpm run prepack && release-it",
     "test": "pnpm run build && ajs module test .",
     "format:check": "oxfmt --check .",
-    "knip": "knip"
+    "knip": "knip",
+    "prepare": "if git rev-parse --is-inside-work-tree >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1; then lefthook install; fi",
+    "checks": "antelopejs-checks",
+    "size": "antelopejs-check-size",
+    "ratchet": "antelopejs-ratchet",
+    "sync": "antelopejs-sync",
+    "ratchet:update": "antelopejs-ratchet --update",
+    "sync:check": "antelopejs-sync --check",
+    "typecheck": "tsc --noEmit",
+    "suppressions": "antelopejs-suppressions",
+    "suppressions:update": "antelopejs-suppressions --update"
   },
   "dependencies": {
     "randomstring": "^1.3.1",
@@ -137,8 +147,8 @@
     "@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",
+    "@antelopejs/interface-database": "^0.1.11",
+    "@antelopejs/tooling-configs": "^0.2.11",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
@@ -147,6 +157,7 @@
     "chai": "^4.5.0",
     "eslint-plugin-perfectionist": "^5.11.0",
     "knip": "^6.34.0",
+    "lefthook": "^2.2.2",
     "mongodb-memory-server-core": "^10.4.3",
     "oxfmt": "^0.66.0",
     "oxlint": "1.81.0",
@@ -159,7 +170,7 @@
   "peerDependencies": {
     "@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"
+    "@antelopejs/interface-database": ">=0.1.11 <1.0.0"
   },
   "packageManager": "pnpm@10.6.5",
   "antelopeJs": {

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

@@ -127,6 +127,7 @@ class Chef extends Table.with(
 - 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.
+- A localized value `""` is stored as no value: reads and queries in that locale get the `fallbackLocale` value.
 - `@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
@@ -135,6 +136,9 @@ class Chef extends Table.with(
 - 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.
+- `@Index({ unique: true })` refuses two rows of an instance with the same key: the write throws `DuplicateKeyError`
+  (test with `IsDuplicateKeyError` from `@antelopejs/interface-database`). 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.

package/skills/database-decorators-interface/cases.json

@@ -0,0 +1,71 @@
+{
+  "version": 1,
+  "cases": [
+    {
+      "id": "table-relations",
+      "area": "framework",
+      "style": "clean",
+      "prompt": "How do I define relations between tables?",
+      "origin": "docs-assistant",
+      "expect": {
+        "skills": ["database-decorators-interface"],
+        "acceptable": ["database-interface"],
+        "mustMention": ["Relation"]
+      }
+    },
+    {
+      "id": "table-relations-casual",
+      "area": "framework",
+      "style": "casual",
+      "prompt": "how do i link two tables together",
+      "origin": "docs-assistant",
+      "expect": {
+        "skills": ["database-decorators-interface"],
+        "acceptable": ["database-interface"],
+        "mustMention": ["Relation"]
+      }
+    },
+    {
+      "id": "database-decorators-interface-aql-neighbour",
+      "area": "framework",
+      "style": "clean",
+      "prompt": "Write a query that returns the novels with at least 300 pages, sorted by page count descending, and watch the table for changes.",
+      "expect": {
+        "skills": ["database-interface"],
+        "acceptable": ["antelopejs", "ajs-consume-interface"],
+        "avoid": ["database-decorators-interface"]
+      }
+    },
+    {
+      "id": "database-decorators-interface-modifiers",
+      "area": "framework",
+      "style": "clean",
+      "prompt": "On my user table class, store the password so it can only be verified, encrypt the API key transparently, and keep created and updated timestamps.",
+      "expect": {
+        "skills": ["database-decorators-interface"],
+        "acceptable": [
+          "database-interface",
+          "antelopejs",
+          "ajs-consume-interface"
+        ],
+        "mustMention": [
+          "Hashed",
+          "Encrypted",
+          "HashModifier",
+          "EncryptionModifier"
+        ]
+      }
+    },
+    {
+      "id": "database-decorators-interface-fixture-casual",
+      "area": "framework",
+      "style": "casual",
+      "prompt": "how do i seed some default rows when the table is empty",
+      "expect": {
+        "skills": ["database-decorators-interface"],
+        "acceptable": ["database-interface", "antelopejs"],
+        "mustMention": ["Fixture", "RegisterSchema"]
+      }
+    }
+  ]
+}