@incoqnito.io/bajadab 1.2.2 → 1.3.0

package/README.md

@@ -1,174 +1,192 @@
-# bajadab
-
-A lightweight JSON-file-backed database for small, single-machine setups. No server, no native bindings — just collections of values persisted as JSON under a directory you choose.
-
-## Features
-
-- Collections stored as plain JSON files, one directory per database.
-- `MAP` (keyed by id) or `ARRAY` (ordered list) in-memory storage per collection.
-- Configurable behavior for duplicate ids, missing ids, array deletion, auto-flush, and unloading dirty data.
-- Custom id extraction/assignment via a pluggable function registry.
-- Optional secondary indexes for fast lookup by a derived key.
-- Atomic writes (write-to-temp, then rename) and, on POSIX systems, owner-only file permissions (`0600` files, `0700` directories).
-- In-process concurrency safety per collection and per database.
-- `db.snapshot(targetDir, options?)` to copy the whole database into a new timestamped version folder, optionally pruning older ones.
-- `db.transaction(collectionNames, fn)` to apply reads and writes across several collections as one unit — committed together, or not applied at all.
-
-## Install
-
-```
-npm install @incoqnito.io/bajadab
-```
-
-Requires Node.js `>= 24`.
-
-## Quick start
-
-```ts
-import { getDatabase, EBMemStorageStrategy } from "@incoqnito.io/bajadab";
-
-const db = await getDatabase("./data");
-
-const notes = await db.getCollection<{ id?: string; text: string }>("notes", {
-    ...db.config.defaultCollectionConfig,
-    memStorageStrategy: EBMemStorageStrategy.ARRAY,
-});
-
-await notes.add({ text: "hello" });
-const all = await notes.get();
-const some = await notes.get(n => n.text.startsWith("h"));
-
-await notes.delete(n => n.text === "hello");
-await db.dropCollection("notes");
-```
-
-`getDatabase(basePath)` opens the database at `basePath`, creating it if it doesn't exist. `db.getCollection(name, config?)` returns the named collection, creating it with `config` (or the database's default) if it doesn't exist yet; `db.createCollection(name, config?)` instead rejects if one already exists. Collection names are matched case- and whitespace-insensitively (`"Notes"` and `"  notes "` refer to the same collection).
-
-## Configuring a collection
-
-Every collection has an `IBCollectionConfig`. `db.config.defaultCollectionConfig` holds the database's defaults — spread it and override what you need, as above.
-
-| Option | Values | Meaning |
-| --- | --- | --- |
-| `memStorageStrategy` | `MAP` (default) / `ARRAY` | Keyed lookup by id, or an ordered list. |
-| `autoIDStrategy` | `AUTO_ID_UUID` (default) / `NO_AUTO_ID` | Generate a `uuidv7` for values with no id, or reject them. |
-| `duplicateIDStrategy` | `OVERWRITE` (default) / `ERROR` / `IGNORE` | What `add()` does when a value's id already exists. |
-| `arrayDeletionStrategy` | `IN_PLACE` (default) / `NEW_ARRAY` | How `delete()` removes matches from an `ARRAY` collection. |
-| `autoFlushStrategy` | `ALWAYS_AUTO_FLUSH` (default) / `NO_AUTO_FLUSH` | Whether every mutation is written to disk immediately, or only on an explicit `flush()`. |
-| `dirtyUnloadStrategy` | `FLUSH` (default) / `ERROR` / `IGNORE` | What `unload()` does with unsaved changes. |
-| `getID` / `setID` | registry key (optional) | Custom id accessors — see below. Omit to use the default, which reads/writes a plain `.id` property. |
-| `indexes` | `{ [indexKey: string]: registry key }` (optional) | Secondary indexes — see below. Omit for no indexes. |
-
-## Custom ids
-
-By default, a value's id is its `.id` property. To use something else, implement `IBFunctionRegistry` and register `getID`/`setID` functions under whatever keys you configure:
-
-```ts
-import { getDatabase, IBFunctionRegistry } from "@incoqnito.io/bajadab";
-
-class Registry implements IBFunctionRegistry {
-    private fns = new Map<string, Function>([
-        ["userGetID", async (v: any) => v.userId],
-        ["userSetID", async (v: any, id: string) => { v.userId = id; }],
-    ]);
-    fetch(key?: string) {
-        return key ? this.fns.get(key) : undefined;
-    }
-}
-
-const db = await getDatabase("./data", new Registry());
-const users = await db.createCollection("users", {
-    ...db.config.defaultCollectionConfig,
-    getID: "userGetID",
-    setID: "userSetID",
-});
-```
-
-A `getID`/`setID` key that isn't found in the registry causes `add()` to reject, rather than silently falling back to the default.
-
-## Indexes
-
-A collection can declare secondary indexes for fast lookup by a derived key. Like `getID`/`setID`, the extractor function lives in the registry — only its key is part of the (persisted) collection config:
-
-```ts
-class Registry implements IBFunctionRegistry {
-    private fns = new Map<string, Function>([
-        ["byEmail", async (v: any) => v.email],
-    ]);
-    fetch(key?: string) {
-        return key ? this.fns.get(key) : undefined;
-    }
-}
-
-const db = await getDatabase("./data", new Registry());
-const users = await db.createCollection("users", {
-    ...db.config.defaultCollectionConfig,
-    indexes: { email: "byEmail" },
-});
-
-await users.add({ email: "a@example.com", name: "A" });
-const matches = await users.getByIndex("email", "a@example.com");
-```
-
-An extractor returns a `string`, a `string[]` for a multi-valued index, or `undefined` to leave a value out of the index. `getByIndex()` rejects if `indexKey` isn't configured. A configured index whose registry key isn't found rejects on the collection's first use after it's (re)loaded — `get()`, `add()`, whatever comes first — not just the mutations that actually need indexing; that's a wider blast radius than `getID`/`setID`, which only ever fail inside `add()`.
-
-The index is maintained incrementally: `add()`/`update()`/`delete()` update only the affected buckets, not the whole index. A full rebuild only happens once, right after `reload()` loads fresh data from disk.
-
-## Persistence and file layout
-
-Each database directory contains:
-
-- `dbmeta.json` — the database config and a name → id map for its collections.
-- `<id>.json` — per-collection metadata (name, config, id).
-- `<id>_data/data.json` — the collection's actual values.
-
-Collections are addressed by a stable id, not by name, so a handle to a since-renamed-or-recreated collection can't end up reading or writing the wrong data. Every write goes through a temp-file-then-rename step to avoid partial writes. On POSIX systems, created files get mode `0600` and directories `0700`; this has no effect on Windows, which has no equivalent permission bits.
-
-## Concurrency
-
-Operations on the same collection, and database-level operations (`create`/`get`/`has`/`dropCollection`), are serialized within one process. There is no cross-process locking — multiple processes pointed at the same directory can still race on the underlying files.
-
-## Snapshots
-
-`db.snapshot(targetDir, options?)` flushes every loaded collection, then copies the whole database directory into a new version folder under `targetDir` (created if it doesn't exist yet). The version folder is named after a sortable timestamp (e.g. `20260904T153012345Z`) and is itself a complete, independent database — open it directly with `getDatabase(versionPath)`.
-
-```ts
-const versionPath = await db.snapshot("./backups");
-// later, e.g. after a bad deploy:
-const restored = await getDatabase(versionPath);
-```
-
-`targetDir` is a pool that can hold several versions; each call adds one more. Options:
-
-| Option | Values | Meaning |
-| --- | --- | --- |
-| `label` | string (optional) | Appended to the version folder's timestamp, e.g. `..._before-deploy`. Letters, digits, `-` and `_` only. |
-| `keepLast` | number (optional) | Older version folders under `targetDir` to keep besides the one just created. `0` keeps only the new one. Omit to keep everything. Negative values reject. |
-
-Pruning only ever deletes folders matching bajadab's own naming scheme — anything else you keep in `targetDir` is left alone.
-
-`snapshot()` blocks every other operation on the database (same as `dropCollection()`, just across all collections at once) for as long as the copy takes, to guarantee a consistent point-in-time copy. There's no separate `restoreSnapshot()` — restoring means copying a version folder back over the original `basePath` (while nothing has it open), or just pointing `getDatabase()` at the version folder directly.
-
-## Transactions
-
-`db.transaction(collectionNames, fn)` runs `fn` against isolated, in-memory working copies of the named collections. Reads and writes inside `fn` only see the transaction's own state until it resolves:
-
-```ts
-await db.transaction(["accounts", "orders"], async (tx) => {
-    const accounts = await tx.getCollection<Account>("accounts");
-    const orders = await tx.getCollection<Order>("orders");
-
-    await accounts.update(a => a.id === "u1", async a => ({ ...a, balance: a.balance - 10 }));
-    await orders.add({ userId: "u1", total: 10 });
-});
-```
-
-If `fn` resolves, every declared collection's live state is replaced by its working copy and flushed; `ADD`/`UPDATE`/`DELETE` handlers registered with `on()` fire once per collection, for the net difference between the state before the transaction and the committed state — a value added and later deleted within the same transaction fires nothing, and a value updated twice fires one `UPDATE` carrying the pre-transaction value and the final value. If `fn` throws, nothing is applied, nothing is flushed, and no handler fires — every declared collection stays exactly as it was.
-
-`tx.getCollection(name)` only accepts names passed to `transaction()`; anything else throws. It mirrors `IBCollection`'s read/write surface (`get`/`has`/`count`/`getByIndex`/`add`/`update`/`delete`) but not `flush`/`reload`/`unload`/`on` — those don't make sense against a working copy that might still be rolled back.
-
-`transaction()` locks every declared collection for its whole duration (like `snapshot()` locks the whole database), so nothing else can read or write them until it resolves. Across collections, disk writes at commit still happen one file at a time — a crash mid-commit can leave a transaction partially applied on disk. There's no cross-process locking here either, same as everywhere else in bajadab.
-
-## License
-
-See [LICENSE](./LICENSE).
+# bajadab
+
+A lightweight JSON-file-backed database for small, single-machine setups. No server, no native bindings — just collections of values persisted as JSON under a directory you choose.
+
+## Features
+
+- Collections stored as plain JSON files, one directory per database.
+- `MAP` (keyed by id) or `ARRAY` (ordered list) in-memory storage per collection.
+- Configurable behavior for duplicate ids, missing ids, array deletion, auto-flush, and unloading dirty data.
+- Custom id extraction/assignment via a pluggable function registry.
+- Optional secondary indexes for fast lookup by a derived key.
+- Atomic writes (write-to-temp, then rename) and, on POSIX systems, owner-only file permissions (`0600` files, `0700` directories).
+- In-process concurrency safety via one lock per database — deadlock-free, even when handlers touch other collections.
+- `db.snapshot(targetDir, options?)` to copy the whole database into a new timestamped version folder, optionally pruning older ones.
+- `db.transaction(collectionNames, fn)` to apply reads and writes across several collections as one unit — committed together, or not applied at all.
+
+## Install
+
+```
+npm install @incoqnito.io/bajadab
+```
+
+Requires Node.js `>= 24`.
+
+## Quick start
+
+```ts
+import { getDatabase, EBMemStorageStrategy } from "@incoqnito.io/bajadab";
+
+const db = await getDatabase("./data");
+
+const notes = await db.getCollection<{ id?: string; text: string }>("notes", {
+    ...db.config.defaultCollectionConfig,
+    memStorageStrategy: EBMemStorageStrategy.ARRAY,
+});
+
+await notes.add({ text: "hello" });
+const all = await notes.get();
+const some = await notes.get(n => n.text.startsWith("h"));
+
+await notes.delete(n => n.text === "hello");
+await db.dropCollection("notes");
+```
+
+`getDatabase(basePath)` opens the database at `basePath`, creating it if it doesn't exist. `db.getCollection(name, config?)` returns the named collection, creating it with `config` (or the database's default) if it doesn't exist yet; `db.createCollection(name, config?)` instead rejects if one already exists. Collection names are matched case- and whitespace-insensitively (`"Notes"` and `"  notes "` refer to the same collection).
+
+## Configuring a collection
+
+Every collection has an `IBCollectionConfig`. `db.config.defaultCollectionConfig` holds the database's defaults — spread it and override what you need, as above.
+
+| Option | Values | Meaning |
+| --- | --- | --- |
+| `memStorageStrategy` | `MAP` (default) / `ARRAY` | Keyed lookup by id, or an ordered list. |
+| `autoIDStrategy` | `AUTO_ID_UUID` (default) / `NO_AUTO_ID` | Generate a `uuidv7` for values with no id, or reject them. |
+| `duplicateIDStrategy` | `OVERWRITE` (default) / `ERROR` / `IGNORE` | What `add()` does when a value's id already exists. |
+| `arrayDeletionStrategy` | `IN_PLACE` (default) / `NEW_ARRAY` | How `delete()` removes matches from an `ARRAY` collection. |
+| `autoFlushStrategy` | `ALWAYS_AUTO_FLUSH` (default) / `NO_AUTO_FLUSH` | Whether every mutation is written to disk immediately, or only on an explicit `flush()`. |
+| `dirtyUnloadStrategy` | `FLUSH` (default) / `ERROR` / `IGNORE` | What `unload()` does with unsaved changes. |
+| `getID` / `setID` | registry key (optional) | Custom id accessors — see below. Omit to use the default, which reads/writes a plain `.id` property. |
+| `indexes` | `{ [indexKey: string]: registry key }` (optional) | Secondary indexes — see below. Omit for no indexes. |
+
+## Custom ids
+
+By default, a value's id is its `.id` property. To use something else, implement `IBFunctionRegistry` and register `getID`/`setID` functions under whatever keys you configure:
+
+```ts
+import { getDatabase, IBFunctionRegistry } from "@incoqnito.io/bajadab";
+
+class Registry implements IBFunctionRegistry {
+    private fns = new Map<string, Function>([
+        ["userGetID", async (v: any) => v.userId],
+        ["userSetID", async (v: any, id: string) => { v.userId = id; }],
+    ]);
+    fetch(key?: string) {
+        return key ? this.fns.get(key) : undefined;
+    }
+}
+
+const db = await getDatabase("./data", new Registry());
+const users = await db.createCollection("users", {
+    ...db.config.defaultCollectionConfig,
+    getID: "userGetID",
+    setID: "userSetID",
+});
+```
+
+A `getID`/`setID` key that isn't found in the registry causes `add()` to reject, rather than silently falling back to the default.
+
+## Indexes
+
+A collection can declare secondary indexes for fast lookup by a derived key. Like `getID`/`setID`, the extractor function lives in the registry — only its key is part of the (persisted) collection config:
+
+```ts
+class Registry implements IBFunctionRegistry {
+    private fns = new Map<string, Function>([
+        ["byEmail", async (v: any) => v.email],
+    ]);
+    fetch(key?: string) {
+        return key ? this.fns.get(key) : undefined;
+    }
+}
+
+const db = await getDatabase("./data", new Registry());
+const users = await db.createCollection("users", {
+    ...db.config.defaultCollectionConfig,
+    indexes: { email: "byEmail" },
+});
+
+await users.add({ email: "a@example.com", name: "A" });
+const matches = await users.getByIndex("email", "a@example.com");
+```
+
+An extractor returns a `string`, a `string[]` for a multi-valued index, or `undefined` to leave a value out of the index. `getByIndex()` rejects if `indexKey` isn't configured. A configured index whose registry key isn't found rejects on the collection's first use after it's (re)loaded — `get()`, `add()`, whatever comes first — not just the mutations that actually need indexing; that's a wider blast radius than `getID`/`setID`, which only ever fail inside `add()`.
+
+The index is maintained incrementally: `add()`/`update()`/`delete()` update only the affected buckets, not the whole index. A full rebuild only happens once, right after `reload()` loads fresh data from disk. Each value remembers the keys it was indexed under, so re-adding a value that was mutated in place moves it out of its old buckets correctly.
+
+## Values are stored by reference
+
+bajadab keeps the objects you hand it; it doesn't copy them. `get()`/`getByIndex()` return a new array, but the values in it are the stored objects themselves, and `update()`'s updater receives the stored object too. Change values only by passing a new object to `update()` (`async v => ({ ...v, value: 5 })`) or to `add()` with an existing id:
+
+- Mutating a value you got from `get()` changes the in-memory state without marking the collection dirty, updating indexes, or firing handlers.
+- An updater that mutates in place and returns the same object still keeps indexes consistent, but the `UPDATE` handler receives that same object as both `previous` and `updated`.
+- Inside a transaction, in-place mutations are outside transactional safety: they aren't reverted on rollback. A value mutated directly fires nothing on commit; an in-place updater passed to `update()` fires `UPDATE` with the same object as both `previous` and `updated`, same as outside a transaction.
+
+`update()` is all-or-nothing: if the updater throws or returns `undefined` for any matching item, no item is replaced.
+
+**Ids are immutable.** Once a value is stored, never change its id — neither in place nor through the object `update()`'s updater returns. bajadab doesn't check this; a changed id leaves the collection inconsistent (a `MAP` entry stored under its old key, a duplicate id in an `ARRAY`). To "rename" a value, `delete()` it and `add()` it under the new id.
+
+## Persistence and file layout
+
+Each database directory contains:
+
+- `dbmeta.json` — the database config and a name → id map for its collections.
+- `<id>.json` — per-collection metadata (name, config, id).
+- `<id>_data/data.json` — the collection's actual values.
+
+Collections are addressed by a stable id, not by name, so a handle to a since-renamed-or-recreated collection can't end up reading or writing the wrong data. Every write goes through a temp-file-then-rename step to avoid partial writes. A rename that fails with `EPERM`/`EBUSY`/`EACCES` (typically a virus scanner or indexer briefly holding the file on Windows) is retried a few times before giving up; a failed write never leaves its temp file behind. On POSIX systems, created files get mode `0600` and directories `0700`; this has no effect on Windows, which has no equivalent permission bits.
+
+## Concurrency
+
+All operations on a database — on any of its collections as well as `create`/`get`/`has`/`dropCollection()`, `snapshot()` and `transaction()` — are serialized within one process by a single lock per database. The lock is reentrant: code that runs while an operation holds it (handlers, predicates, updaters, a transaction's `fn`) can call any other operation on the same database without deadlocking. The flip side is that such code blocks the whole database while it runs, so keep `EBHandlerMode.SYNC` handlers and transaction callbacks short, and don't await anything slow or external inside them. There is no cross-process locking — multiple processes pointed at the same directory can still race on the underlying files.
+
+## Snapshots
+
+`db.snapshot(targetDir, options?)` flushes every loaded collection, then copies the whole database directory into a new version folder under `targetDir` (created if it doesn't exist yet). The version folder is named after a sortable timestamp (e.g. `20260904T153012345Z`) and is itself a complete, independent database — open it directly with `getDatabase(versionPath)`.
+
+```ts
+const versionPath = await db.snapshot("./backups");
+// later, e.g. after a bad deploy:
+const restored = await getDatabase(versionPath);
+```
+
+`targetDir` is a pool that can hold several versions; each call adds one more. Options:
+
+| Option | Values | Meaning |
+| --- | --- | --- |
+| `label` | string (optional) | Appended to the version folder's timestamp, e.g. `..._before-deploy`. Letters, digits, `-` and `_` only. |
+| `keepLast` | number (optional) | Older version folders under `targetDir` to keep besides the one just created. `0` keeps only the new one. Omit to keep everything. Negative values reject. |
+
+Pruning only ever deletes folders matching bajadab's own naming scheme — anything else you keep in `targetDir` is left alone.
+
+Version folder names have millisecond resolution. Two `snapshot()` calls into the same `targetDir` within the same millisecond (and with the same or no `label`) resolve to the same folder name: the second copy is merged into the first, and if that copy fails, the cleanup removes the earlier snapshot along with it. Don't take snapshots into the same `targetDir` in such quick succession.
+
+`snapshot()` blocks every other operation on the database for as long as the copy takes, to guarantee a consistent point-in-time copy. There's no separate `restoreSnapshot()` — restoring means copying a version folder back over the original `basePath` (while nothing has it open), or just pointing `getDatabase()` at the version folder directly.
+
+## Transactions
+
+`db.transaction(collectionNames, fn)` runs `fn` against isolated, in-memory working copies of the named collections. Reads and writes inside `fn` only see the transaction's own state until it resolves:
+
+```ts
+await db.transaction(["accounts", "orders"], async (tx) => {
+    const accounts = await tx.getCollection<Account>("accounts");
+    const orders = await tx.getCollection<Order>("orders");
+
+    await accounts.update(a => a.id === "u1", async a => ({ ...a, balance: a.balance - 10 }));
+    await orders.add({ userId: "u1", total: 10 });
+});
+```
+
+Every name passed to `transaction()` must be an existing collection; otherwise it rejects before `fn` runs, and nothing is created.
+
+If `fn` resolves, every declared collection's working copy is first written to a temp file. If any of these writes fails, all temp files are discarded and nothing is applied. Otherwise the temp files replace the collections' files, every live state is replaced by its working copy, and only then do the `ADD`/`UPDATE`/`DELETE` handlers registered with `on()` fire — so a handler that reads or writes another declared collection already sees its committed state. They fire once per id the transaction touched, typed by the last operation on it, the same way as outside a transaction: `ADD` if the value is new or was last stored via `add()` (including an id-based overwrite), `UPDATE` (pre-transaction value → final value) if it was last changed via `update()`, `DELETE` if it's gone. A value added and later deleted within the same transaction fires nothing, and a value updated twice fires one `UPDATE`. If `fn` throws, nothing is applied, nothing is flushed, and no handler fires — every declared collection stays exactly as it was. This only covers changes made through the working copies' `add()`/`update()`/`delete()`; values mutated in place are shared with the live collection and aren't isolated (see "Values are stored by reference").
+
+`tx.getCollection(name)` only accepts names passed to `transaction()`; anything else throws. It mirrors `IBCollection`'s read/write surface (`get`/`has`/`count`/`getByIndex`/`add`/`update`/`delete`) but not `flush`/`reload`/`unload`/`on` — those don't make sense against a working copy that might still be rolled back.
+
+Inside `fn`, `add()`/`update()`/`delete()` through a declared collection's regular handle (the one from `db.getCollection()`) reject — those writes would otherwise be overwritten by the commit. Reading through it is fine and shows the pre-transaction state; collections not declared to the transaction stay fully usable, but writes to them aren't part of the transaction. Calling `transaction()` again from inside `fn` rejects as well, whichever collections it names.
+
+`transaction()` holds the database lock for its whole duration, so every other operation on the database — on any collection — waits until it resolves. Across collections, the final renames at commit still happen one file at a time — a crash, or a rename that keeps failing, between them can leave a transaction partially applied. If a rename fails, the collections renamed so far are applied (on disk and in memory, and their handlers fire), the rest are discarded, and `transaction()` rejects. There's no cross-process locking here either, same as everywhere else in bajadab.
+
+## License
+
+See [LICENSE](./LICENSE).

package/dist/base.d.ts

@@ -97,12 +97,16 @@ export interface IBDatabase {
      */
     snapshot(targetDir: string, options?: IBSnapshotOptions): Promise<string>;
     /**
-     * Runs `fn` against isolated, in-memory working copies of `collectionNames`. Reads and writes inside `fn`
-     * are visible only within the transaction. If `fn` resolves, every working copy replaces its collection's
-     * live state and is flushed, then `ADD`/`UPDATE`/`DELETE` handlers fire once per net change between the
-     * state before the transaction and the committed state - a value added and later deleted within the same
-     * transaction fires nothing. If `fn` throws, nothing is applied, nothing is flushed, and no handler fires.
-     * Only collections named in `collectionNames` can be reached from within `fn`.
+     * Runs `fn` against isolated, in-memory working copies of `collectionNames`, which must all exist. Reads and
+     * writes inside `fn` are visible only within the transaction. If `fn` resolves, every working copy is written
+     * to a temp file first - if any of those writes fails, nothing is applied - then all of them replace their
+     * files and their collections' live state, and only then do `ADD`/`UPDATE`/`DELETE` handlers fire: once per
+     * id the transaction touched, typed by the last operation on it, same as outside a transaction - a value
+     * added and later deleted within the same transaction fires nothing. If `fn` throws, nothing is applied,
+     * nothing is flushed, and no handler fires.
+     * Only collections named in `collectionNames` can be reached from within `fn`; writing to one of them through
+     * its regular {@link IBCollection} handle inside `fn` rejects, and so does a nested `transaction()` call.
+     * Values mutated in place are shared with the live collection and are neither isolated nor reverted.
      */
     transaction(collectionNames: string[], fn: (tx: IBTransaction) => Promise<void>): Promise<void>;
 }
@@ -141,7 +145,7 @@ export interface IBCollection<T = any> {
     readonly collectionName: string;
     /** Stable identity used to address this collection's storage, independent of its name. */
     readonly collectionID: string;
-    /** All items, or only those matching `predicate`. Always a defensive copy, never the live storage. */
+    /** All items, or only those matching `predicate`. A new array, but holding the stored objects themselves - don't mutate them in place. */
     get(predicate?: (v: T) => boolean): Promise<T[]>;
     /** Deletes matching items. Returns the number removed. */
     delete(predicate: (v: T) => boolean): Promise<number>;
@@ -149,11 +153,11 @@ export interface IBCollection<T = any> {
     has(predicate: (v: T) => boolean): Promise<boolean>;
     /** Adds values, resolving/assigning ids per the collection's id strategies. Returns the number added. */
     add(...v: T[]): Promise<number>;
-    /** Replaces each item matching `predicate` with the (defined) result of `updater`. Returns the number updated. */
+    /** Replaces each item matching `predicate` with the (defined) result of `updater`; all-or-nothing if `updater` throws or returns `undefined`. `updater` receives the stored object - return a new one rather than mutating it, and never change its id. Returns the number updated. */
     update(predicate: (v: T) => boolean, updater: (v: T) => Promise<T>): Promise<number>;
     /** Number of items, or only those matching `predicate`. */
     count(predicate?: (v: T) => boolean): Promise<number>;
-    /** Items whose {@link IBCollectionConfig.indexes}-configured `indexKey` extracts `key`. Always a defensive copy. Throws if `indexKey` isn't configured. */
+    /** Items whose {@link IBCollectionConfig.indexes}-configured `indexKey` extracts `key`. A new array, but holding the stored objects themselves. Throws if `indexKey` isn't configured. */
     getByIndex(indexKey: string, key: string): Promise<T[]>;
     /** Subscribes to `add()` mutations. Fires after the value is stored, including any auto-flush to disk. `mode` defaults to {@link EBHandlerMode.SYNC}. A handler's own errors never fail the triggering call; they're logged only. */
     on(modificationType: EBModificationType.ADD, handler: TAddHandler<T>, mode?: EBHandlerMode): Promise<IHandlerRegistration>;

package/dist/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/main/base.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IACxB,mCAAmC;IACnC,6CAAyB,CAAA;IACzB,mEAAmE;IACnE,iDAA6B,CAAA;AACjC,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAED,uDAAuD;AACvD,MAAM,CAAN,IAAY,oBAMX;AAND,WAAY,oBAAoB;IAC5B,oEAAoE;IACpE,mCAAW,CAAA;IACX,+BAA+B;IAC/B,gDAAgD;IAChD,uCAAe,CAAA;AACnB,CAAC,EANW,oBAAoB,KAApB,oBAAoB,QAM/B;AAED,iFAAiF;AACjF,MAAM,CAAN,IAAY,qBAOX;AAPD,WAAY,qBAAqB;IAC7B,kCAAkC;IAClC,gDAAuB,CAAA;IACvB,6BAA6B;IAC7B,wCAAe,CAAA;IACf,iDAAiD;IACjD,0CAAiB,CAAA;AACrB,CAAC,EAPW,qBAAqB,KAArB,qBAAqB,QAOhC;AAED,wFAAwF;AACxF,MAAM,CAAN,IAAY,uBAKX;AALD,WAAY,uBAAuB;IAC/B,wCAAwC;IACxC,kDAAuB,CAAA;IACvB,2CAA2C;IAC3C,gDAAqB,CAAA;AACzB,CAAC,EALW,uBAAuB,KAAvB,uBAAuB,QAKlC;AAED,6DAA6D;AAC7D,MAAM,CAAN,IAAY,mBAKX;AALD,WAAY,mBAAmB;IAC3B,2DAA2D;IAC3D,sDAA+B,CAAA;IAC/B,2DAA2D;IAC3D,8DAAuC,CAAA;AAC3C,CAAC,EALW,mBAAmB,KAAnB,mBAAmB,QAK9B;AAED,kEAAkE;AAClE,MAAM,CAAN,IAAY,qBAOX;AAPD,WAAY,qBAAqB;IAC7B,yBAAyB;IACzB,wCAAe,CAAA;IACf,gCAAgC;IAChC,wCAAe,CAAA;IACf,4CAA4C;IAC5C,0CAAiB,CAAA;AACrB,CAAC,EAPW,qBAAqB,KAArB,qBAAqB,QAOhC;AAqED,4FAA4F;AAC5F,MAAM,CAAN,IAAY,kBAOX;AAPD,WAAY,kBAAkB;IAC1B,uEAAuE;IACvE,iCAAW,CAAA;IACX,0CAA0C;IAC1C,uCAAiB,CAAA;IACjB,yCAAyC;IACzC,uCAAiB,CAAA;AACrB,CAAC,EAPW,kBAAkB,KAAlB,kBAAkB,QAO7B;AAeD,kGAAkG;AAClG,MAAM,CAAN,IAAY,aAKX;AALD,WAAY,aAAa;IACrB,6GAA6G;IAC7G,8BAAa,CAAA;IACb,mEAAmE;IACnE,gCAAe,CAAA;AACnB,CAAC,EALW,aAAa,KAAb,aAAa,QAKxB"}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../src/main/base.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,MAAM,CAAN,IAAY,gBAKX;AALD,WAAY,gBAAgB;IACxB,mCAAmC;IACnC,6CAAyB,CAAA;IACzB,mEAAmE;IACnE,iDAA6B,CAAA;AACjC,CAAC,EALW,gBAAgB,KAAhB,gBAAgB,QAK3B;AAED,uDAAuD;AACvD,MAAM,CAAN,IAAY,oBAMX;AAND,WAAY,oBAAoB;IAC5B,oEAAoE;IACpE,mCAAW,CAAA;IACX,+BAA+B;IAC/B,gDAAgD;IAChD,uCAAe,CAAA;AACnB,CAAC,EANW,oBAAoB,KAApB,oBAAoB,QAM/B;AAED,iFAAiF;AACjF,MAAM,CAAN,IAAY,qBAOX;AAPD,WAAY,qBAAqB;IAC7B,kCAAkC;IAClC,gDAAuB,CAAA;IACvB,6BAA6B;IAC7B,wCAAe,CAAA;IACf,iDAAiD;IACjD,0CAAiB,CAAA;AACrB,CAAC,EAPW,qBAAqB,KAArB,qBAAqB,QAOhC;AAED,wFAAwF;AACxF,MAAM,CAAN,IAAY,uBAKX;AALD,WAAY,uBAAuB;IAC/B,wCAAwC;IACxC,kDAAuB,CAAA;IACvB,2CAA2C;IAC3C,gDAAqB,CAAA;AACzB,CAAC,EALW,uBAAuB,KAAvB,uBAAuB,QAKlC;AAED,6DAA6D;AAC7D,MAAM,CAAN,IAAY,mBAKX;AALD,WAAY,mBAAmB;IAC3B,2DAA2D;IAC3D,sDAA+B,CAAA;IAC/B,2DAA2D;IAC3D,8DAAuC,CAAA;AAC3C,CAAC,EALW,mBAAmB,KAAnB,mBAAmB,QAK9B;AAED,kEAAkE;AAClE,MAAM,CAAN,IAAY,qBAOX;AAPD,WAAY,qBAAqB;IAC7B,yBAAyB;IACzB,wCAAe,CAAA;IACf,gCAAgC;IAChC,wCAAe,CAAA;IACf,4CAA4C;IAC5C,0CAAiB,CAAA;AACrB,CAAC,EAPW,qBAAqB,KAArB,qBAAqB,QAOhC;AAyED,4FAA4F;AAC5F,MAAM,CAAN,IAAY,kBAOX;AAPD,WAAY,kBAAkB;IAC1B,uEAAuE;IACvE,iCAAW,CAAA;IACX,0CAA0C;IAC1C,uCAAiB,CAAA;IACjB,yCAAyC;IACzC,uCAAiB,CAAA;AACrB,CAAC,EAPW,kBAAkB,KAAlB,kBAAkB,QAO7B;AAeD,kGAAkG;AAClG,MAAM,CAAN,IAAY,aAKX;AALD,WAAY,aAAa;IACrB,6GAA6G;IAC7G,8BAAa,CAAA;IACb,mEAAmE;IACnE,gCAAe,CAAA;AACnB,CAAC,EALW,aAAa,KAAb,aAAa,QAKxB"}

package/dist/basics.d.ts

@@ -1,9 +1,14 @@
-import type { IODatabase } from "./fileio.js";
+import type { IODatabase, IPreparedWrite } from "./fileio.js";
 import { EBHandlerMode, EBModificationType, IBCollection, IBCollectionConfig, IBDatabase, IBDatabaseConfig, IBFunctionRegistry, IBSnapshotOptions, IBTransaction, IHandlerRegistration, TAddHandler, TDeleteHandler, TGetIDFunction, TSetIDFunction, TUpdateHandler } from "./base.js";
 /** Default {@link TGetIDFunction}: reads `v.id`, `undefined` if absent. */
 export declare const DEFAULT_GET_ID: TGetIDFunction;
 /** Default {@link TSetIDFunction}: assigns to `v.id`. */
 export declare const DEFAULT_SET_ID: TSetIDFunction;
+export interface IPreparedTransactionCommit {
+    readonly write: IPreparedWrite;
+    apply(): void;
+    fire(): Promise<void>;
+}
 /** {@link IBCollectionConfig} used when a collection is created without an explicit one. */
 export declare const DEFAULT_COLLECTION_CONFIG: IBCollectionConfig;
 /** {@link IBDatabaseConfig} used when `getDatabase()` creates a fresh database. */
@@ -13,7 +18,11 @@ export declare class BDatabase implements IBDatabase {
     private collections;
     readonly io: IODatabase;
     readonly functionRegistry?: IBFunctionRegistry;
+    readonly iid: string;
+    private readonly transactionScope;
     constructor(io: IODatabase, config?: IBDatabaseConfig, functionRegistry?: IBFunctionRegistry);
+    runExclusive<R>(fn: () => Promise<R>): Promise<R>;
+    isInTransaction(collectionName: string): boolean;
     addCollection(collection: BCollection): void;
     getCollection<T>(collectionName: string, collectionConfig?: IBCollectionConfig): Promise<IBCollection<T>>;
     createCollection<T = any>(collectionName: string, collectionConfig?: IBCollectionConfig): Promise<BCollection<T>>;
@@ -32,15 +41,19 @@ export declare class BCollection<T = any> implements IBCollection<T> {
     private loaded;
     private dirty;
     private dropped;
+    private transactionClone;
     private addHandlers;
     private updateHandlers;
     private deleteHandlers;
     private indexDefinitions;
     private indexRuntime;
+    private indexedKeys;
+    private txChanges?;
     constructor(database: BDatabase, collectionID: string, collectionName: string, collectionConfig: IBCollectionConfig);
     private checkLoaded;
     private runExclusive;
     private runProtected;
+    private runMutation;
     /**
      * call this only within the protecting mutex
      */
@@ -60,6 +73,8 @@ export declare class BCollection<T = any> implements IBCollection<T> {
     private resolveIndexDefinitions;
     private indexKeysFor;
     private addToIndexes;
+    private indexKeysForAll;
+    private addKeysToIndexes;
     private removeFromIndexes;
     /**
      * full rebuild from currently loaded data; only needed right after (re)load, since every
@@ -70,10 +85,14 @@ export declare class BCollection<T = any> implements IBCollection<T> {
     /**
      * id -> value for every stored item, resolved via the plain id getter (no auto-id assignment - every
      * stored item already has one). Used to diff a transaction's working copy against the pre-transaction
-     * state in {@link commitTransactionClone}.
+     * state in {@link prepareTransactionCommit}.
      */
     private idKeyedSnapshot;
-    private getID;
+    private resolveIDSetter;
+    private resolveIncomingIDs;
+    private assignMissingIDs;
+    private storedArrayIDs;
+    private recordTxChanges;
     add(...vs: T[]): Promise<number>;
     update(predicate: (v: T) => boolean, updater: (v: T) => Promise<T>): Promise<number>;
     private doOnDirty;
@@ -88,12 +107,10 @@ export declare class BCollection<T = any> implements IBCollection<T> {
      */
     cloneForTransaction(): Promise<BCollection<T>>;
     /**
-     * Applies a working copy from {@link cloneForTransaction} back onto this collection: replaces the live
-     * state, flushes once, then fires `ADD`/`UPDATE`/`DELETE` handlers for the net difference between this
-     * collection's state before the transaction and `clone`'s state - not for each intermediate operation the
-     * transaction performed. The before/after diff itself (and the id resolution it needs) only runs when at
-     * least one handler is registered on this collection - a transaction on a collection nobody listens to
-     * skips it entirely. Call only while already holding this collection's mutex for the whole transaction.
+     * Writes `clone`'s state to a temp file (see {@link IPreparedWrite}) and computes the handler events for the
+     * net changes against this collection's current state: one per id the transaction touched, typed by the last
+     * operation on it (`DELETE` if gone, `ADD` if new or last stored via `add()`, `UPDATE` otherwise). Nothing is
+     * applied until `apply()`; call only while already holding this collection's mutex for the whole transaction.
      */
-    commitTransactionClone(clone: BCollection<T>): Promise<void>;
+    prepareTransactionCommit(clone: BCollection<T>): Promise<IPreparedTransactionCommit>;
 }