@antelopejs/interface-database-decorators 0.2.0 → 0.2.2

package/docs/3.table-modifiers.md

@@ -110,13 +110,13 @@ A field with an `algorithm` stores the base64 digest of the row's salt followed
 The `HashModifier` mixin adds these methods to table instances:
 
 ```typescript fragment
-testHash<This extends {}, F extends keyof This>(this: This, field: F, value: This[F]): unknown
+testHash<This extends {}, F extends keyof This>(this: This, field: F, value: This[F]): boolean
 testHashAsync<This extends {}, F extends keyof This>(this: This, field: F, value: This[F]): Promise<boolean>
 isHashOutdated<This extends {}>(this: This, field: keyof This): boolean
 ```
 
 - `testHashAsync` resolves whether `value` matches the stored hash. It runs scrypt on the thread pool, so use it on a server. It rejects with `Field <name> is not hashed` for a field without `@Hashed`.
-- `testHash` gives the same result and blocks the event loop while scrypt runs. Its declared return type is `unknown`. On a hashed field, the value is a boolean.
+- `testHash` gives the same result and blocks the event loop while scrypt runs. It throws `Field <name> is not hashed` for a field without `@Hashed`.
 - `isHashOutdated` returns whether the stored hash differs from what the field writes today, which is any stored string that does not start with `$scrypt$ln=15,r=8,p=3$`. It returns `false` when nothing is stored, and always on a field with an `algorithm`. It throws `Field <name> is not hashed` for a field without `@Hashed`.
 
 #### Upgrade stored hashes
@@ -187,11 +187,11 @@ console.log(german.name); // "Premium Headphones" (fallback)
 
 #### Wildcard key
 
-The wildcard key `"*"` reads or writes all translations at once. `localize()` does not change the property's TypeScript type, so a field declared as `string` holds a record of texts by locale under `"*"`. Read that record as `unknown` and check it before use. Write it with `Object.assign`, which calls the field's setter:
+The wildcard key `"*"` reads or writes all translations at once. List the localized fields with it, and `localize("*", fields)` types each listed field as its values by locale, a `LocalizedRecords<T, K>`: a field declared as `string` reads as a `Record<string, string>`. Calling `localize()` on that view with one locale gives back the row type. The view is not the row type, so pass the row itself to `insert()` or `update()`. Write all translations with `Object.assign`, which calls the field's setter. `undefined` or `null` clears every translation. Any other value that is not a record, such as a single text, throws a `TypeError` and leaves the stored translations as they were:
 
 ```typescript fragment
 // Get all translations
-const allNames: unknown = product.localize("*").name;
+const allNames: Record<string, string> = product.localize("*", ["name"]).name;
 // { en: "Premium Headphones", fr: "Casque Premium", es: "Auriculares Premium" }
 
 // Set all translations
@@ -216,9 +216,12 @@ Object.assign(product.localize("*"), {
 The `LocalizationModifier` mixin adds a `localize` method:
 
 ```typescript fragment
-localize<This extends { constructor: any }>(this: This, locale: string, fields?: Array<keyof This>): This
+localize<This extends { constructor: any }, K extends keyof This>(this: This, locale: "*", fields: readonly K[]): LocalizedRecords<This, K>
+localize<This extends { constructor: any }>(this: This, locale: string, fields?: ReadonlyArray<keyof This>): This
 ```
 
+Without `fields`, `localize("*")` unlocks every localized field but keeps the class's field types. A listed method stays callable.
+
 `localize()` changes the active locale and returns the same object, not a copy for that locale.
 
 - **References share state.** `spanish`, `german`, and `product` above refer to one object. A later `localize()` call changes what all three references read.
@@ -410,7 +413,7 @@ Base64 is an encoding, not encryption. The example declares its `LockedType` as
 
 ### `ContainerModifier`
 
-A modifier that stores several values under keys, as `LocalizationModifier` does, extends `ContainerModifier`. Its `lock`, `unlock`, and `unlockrequest` take the key as their argument. `lock` and `unlock` treat the wildcard key `"*"` as the whole record:
+A modifier that stores several values under keys, as `LocalizationModifier` does, extends `ContainerModifier`. Its `lock`, `unlock`, and `unlockrequest` take the key as their argument, a `string` or `undefined`. `lock` and `unlock` treat the wildcard key `"*"` as the whole record, and `lock` throws a `TypeError` for a value under `"*"` that is not a record. `undefined` is no key: `lock` stores nothing under it, and `unlock` and `unlockrequest` find no value, so a `LocalizationModifier` answers its `fallbackLocale`:
 
 ```typescript
 import { ContainerModifier } from "@antelopejs/interface-database-decorators";

package/docs/4.data-models.md

@@ -95,6 +95,8 @@ await userModel.update({ _id: "user-123", name: "Updated Name" });
 
 When you call `update` without a separate ID argument, the object must include the primary key. Its type requires `_id`, and a call without it throws `Missing primary key in object update.`
 
+An update with plain data that sets a field whose modifiers lock without arguments, such as an encrypted or hashed field, first reads the row's stored modifier state, then locks the new value onto it. The row keeps its other modified fields and its hash salt. A table instance, such as one read with `get`, already holds that state and costs no extra read.
+
 ### Delete
 
 ```typescript fragment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-database-decorators",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "AntelopeJS decorators for database tables and typed data models, with encrypted, hashed and localized fields",
   "keywords": [
     "antelopejs",
@@ -128,7 +128,7 @@
     "test": "pnpm run build && ajs module test .",
     "format:check": "oxfmt --check .",
     "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",
+    "prepare": "if [ -e .git ] && command -v git >/dev/null 2>&1 && command -v lefthook >/dev/null 2>&1 && GIT_DIR=.git GIT_WORK_TREE=. git rev-parse --git-dir >/dev/null 2>&1; then GIT_DIR=.git GIT_WORK_TREE=. lefthook install; fi",
     "checks": "antelopejs-checks",
     "size": "antelopejs-check-size",
     "sync": "antelopejs-sync",
@@ -142,11 +142,11 @@
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@antelopejs/core": "^1.20.0",
+    "@antelopejs/core": "^1.21.0",
     "@antelopejs/interface-api": "^0.0.15",
     "@antelopejs/interface-core": "^0.4.0",
     "@antelopejs/interface-database": "^0.3.0",
-    "@antelopejs/tooling-configs": "^0.2.17",
+    "@antelopejs/tooling-configs": "^0.4.0",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",

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

@@ -129,7 +129,10 @@ class Chef extends Table.with(
 - `@Hashed({ algorithm })` stores a fast digest instead of scrypt: use it only for non-secret fingerprints, never for credentials.
 - 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.
+- `instance.localize("*", ["motto"])` reads and writes every locale at once, typed `Record<string, string>` for each listed field (`LocalizedRecords<T, K>`); without a field list the field types stay unchanged.
+- Under `localize("*")` a localized field takes the record of texts by locale, and `undefined` or `null` clears every locale. A single text throws a `TypeError`, whether it is assigned or held from `fromPlainData` when `localize("*")` runs.
 - A localized value `""` is stored as no value: reads and queries in that locale get the `fallbackLocale` value.
+- A `ContainerModifier` key of `undefined` is no key: writes store nothing under it, and reads and queries get no value, or the `fallbackLocale` value for a localized field.
 - `@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
@@ -144,7 +147,7 @@ class Chef extends Table.with(
   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.
+- `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 whose schema name has a schema uses that schema; one whose schema name has none throws `<Class> is not bound to a schema`.
 - 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,