@incoqnito.io/bajadab 1.2.1 → 1.3.0

package/src/main/base.ts

@@ -1,186 +1,235 @@
-/** How a missing id is handled on {@link IBCollection.add}. */
-export enum EBAutoIDStrategy {
-    /** Reject values without an id. */
-    NO_AUTO_ID = "NO_AUTO_ID",
-    /** Generate a `uuidv7` and assign it via the configured setter. */
-    AUTO_ID_UUID = "AUTO_ID_UUID",
-}
-
-/** In-memory representation of a collection's data. */
-export enum EBMemStorageStrategy {
-    /** Keyed by id; `add()` looks up existing entries by id in O(1). */
-    MAP = "MAP",
-    // LINKED_LIST = "LINKED_LIST",
-    /** Plain list; insertion order is preserved. */
-    ARRAY = "ARRAY",
-}
-
-/** What happens on {@link IBCollection.add} when a value's id already exists. */
-export enum EBDuplicateIDStrategy {
-    /** Replace the existing value. */
-    OVERWRITE = "OVERWRITE",
-    /** Reject the whole call. */
-    ERROR = "ERROR",
-    /** Keep the existing value, drop the new one. */
-    IGNORE = "IGNORE",
-}
-
-/** How {@link IBCollection.delete} removes matched items from an `ARRAY` collection. */
-export enum EBArrayDeletionStrategy {
-    /** Build a new array via `filter()`. */
-    NEW_ARRAY = "NEW_ARRAY",
-    /** Compact the existing array in place. */
-    IN_PLACE = "IN_PLACE",
-}
-
-/** When a collection is written to disk after a mutation. */
-export enum EBAutoFlushStrategy {
-    /** Only on an explicit {@link IBCollection.flush} call. */
-    NO_AUTO_FLUSH = "NO_AUTO_FLUSH",
-    /** After every mutating call (`add`/`update`/`delete`). */
-    ALWAYS_AUTO_FLUSH = "ALWAYS_AUTO_FLUSH",
-}
-
-/** What {@link IBCollection.unload} does with unsaved changes. */
-export enum EBDirtyUnloadStrategy {
-    /** Reject the unload. */
-    ERROR = "ERROR",
-    /** Flush first, then unload. */
-    FLUSH = "FLUSH",
-    /** Discard the unsaved changes silently. */
-    IGNORE = "IGNORE",
-}
-
-/** Resolves the id of a value; `undefined` means "no id yet". */
-export type TGetIDFunction = (v: any) => Promise<string | undefined>;
-
-/** Assigns an id onto a value. */
-export type TSetIDFunction = (v: any, id: string) => Promise<void>;
-
-/** Extracts an index key (or several, for a multi-valued index) from a value; `undefined` means "not indexed". */
-export type TIndexKeyFunction<T = any> = (v: T) => Promise<string | string[] | undefined>;
-
-/** Per-collection behavior. Passed to {@link IBDatabase.createCollection}/{@link IBDatabase.getCollection}. */
-export interface IBCollectionConfig {
-    autoIDStrategy: EBAutoIDStrategy;
-    duplicateIDStrategy: EBDuplicateIDStrategy;
-    memStorageStrategy: EBMemStorageStrategy;
-    arrayDeletionStrategy: EBArrayDeletionStrategy;
-    dirtyUnloadStrategy: EBDirtyUnloadStrategy;
-    autoFlushStrategy: EBAutoFlushStrategy;
-    /** Registry key for a custom {@link TGetIDFunction}. Omit to use the default (reads `.id`). */
-    getID?: string;
-    /** Registry key for a custom {@link TSetIDFunction}. Omit to use the default (sets `.id`). */
-    setID?: string;
-    /** Index name → registry key of a {@link TIndexKeyFunction} for that index. Omit for no indexes. */
-    indexes?: { [indexKey: string]: string };
-}
-
-/** Database-wide configuration. */
-export interface IBDatabaseConfig {
-    /** Used for any collection created without an explicit config. */
-    readonly defaultCollectionConfig: IBCollectionConfig;
-}
-
-/** Options for {@link IBDatabase.snapshot}. */
-export interface IBSnapshotOptions {
-    /** Appended to the version folder's timestamp. Letters, digits, `-` and `_` only. */
-    label?: string;
-    /** Older version folders under `targetDir` to keep besides the one just created. `0` keeps only the new one. Negative values reject. */
-    keepLast?: number;
-}
-
-/** A JSON-file-backed database. Obtain one via `getDatabase()`. */
-export interface IBDatabase {
-    readonly config: IBDatabaseConfig;
-    /** Creates a new collection. Rejects if one with the same (canonicalized) name already exists. */
-    createCollection<T>(collectionName: string, collectionConfig?: IBCollectionConfig): Promise<IBCollection<T>>;
-    /** Returns the named collection, creating it with `collectionConfig` (or the database default) if it doesn't exist yet. */
-    getCollection<T>(collectionName: string, collectionConfig?: IBCollectionConfig): Promise<IBCollection<T>>;
-    /** Whether a collection with this (canonicalized) name exists. */
-    hasCollection(collectionName: string): Promise<boolean>;
-    /** Deletes a collection and invalidates any handle still held on it. Rejects if it doesn't exist. */
-    dropCollection(collectionName: string): Promise<void>;
-    /**
-     * Flushes every loaded collection, then copies the whole database directory into a new, timestamped
-     * version folder under `targetDir` (created if needed). Blocks all other database operations for the
-     * duration. See {@link IBSnapshotOptions} for pruning older versions. Returns the new version folder's path.
-     */
-    snapshot(targetDir: string, options?: IBSnapshotOptions): Promise<string>;
-}
-
-/** What kind of collection mutation a handler subscribes to via {@link IBCollection.on}. */
-export enum EBModificationType {
-    /** A value was stored by `add()` (including an id-based overwrite). */
-    ADD = "ADD",
-    /** A value was replaced by `update()`. */
-    UPDATE = "UPDATE",
-    /** A value was removed by `delete()`. */
-    DELETE = "DELETE",
-}
-
-/** Handler for {@link EBModificationType.ADD}: called with each value stored by `add()`. */
-export type TAddHandler<T> = (added: T) => void | Promise<void>;
-/** Handler for {@link EBModificationType.UPDATE}: called with the previous and the replacement value. */
-export type TUpdateHandler<T> = (previous: T, updated: T) => void | Promise<void>;
-/** Handler for {@link EBModificationType.DELETE}: called with each value removed by `delete()`. */
-export type TDeleteHandler<T> = (deleted: T) => void | Promise<void>;
-
-/** Handle returned by {@link IBCollection.on}. */
-export interface IHandlerRegistration {
-    /** Unsubscribes the handler. Idempotent. */
-    cancel(): Promise<void>;
-}
-
-/** Whether a handler registered via {@link IBCollection.on} blocks the call that triggered it. */
-export enum EBHandlerMode {
-    /** The triggering `add()`/`update()`/`delete()` call doesn't resolve until this handler has run. Default. */
-    SYNC = "SYNC",
-    /** The handler runs without the triggering call waiting for it. */
-    ASYNC = "ASYNC",
-}
-
-/** A single collection of values of type `T`. Obtain one via {@link IBDatabase}. */
-export interface IBCollection<T = any> {
-    readonly database: IBDatabase;
-    readonly collectionConfig: IBCollectionConfig;
-    /** Canonicalized (trimmed, lowercased) name. */
-    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. */
-    get(predicate?: (v: T) => boolean): Promise<T[]>;
-    /** Deletes matching items. Returns the number removed. */
-    delete(predicate: (v: T) => boolean): Promise<number>;
-    /** Whether any item matches `predicate`. */
-    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. */
-    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. */
-    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>;
-    /** Subscribes to `update()` mutations. Fires after the value is replaced, 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.UPDATE, handler: TUpdateHandler<T>, mode?: EBHandlerMode): Promise<IHandlerRegistration>;
-    /** Subscribes to `delete()` mutations. Fires after the value is removed, 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.DELETE, handler: TDeleteHandler<T>, mode?: EBHandlerMode): Promise<IHandlerRegistration>;
-
-    /** Writes the current in-memory state to disk. */
-    flush(): Promise<void>;
-    /** Discards in-memory state and re-reads it from disk. */
-    reload(): Promise<void>;
-    /** Evicts the in-memory state (per the dirty-unload strategy if there are unsaved changes). */
-    unload(): Promise<void>;
-
-}
-
-/** Resolves the custom id functions referenced by {@link IBCollectionConfig.getID}/`setID`. */
-export interface IBFunctionRegistry {
-    /** Returns the function registered under `key`, or `undefined` if there is none. */
-    fetch(key?: string): Function | undefined;
-}
+/** How a missing id is handled on {@link IBCollection.add}. */
+export enum EBAutoIDStrategy {
+    /** Reject values without an id. */
+    NO_AUTO_ID = "NO_AUTO_ID",
+    /** Generate a `uuidv7` and assign it via the configured setter. */
+    AUTO_ID_UUID = "AUTO_ID_UUID",
+}
+
+/** In-memory representation of a collection's data. */
+export enum EBMemStorageStrategy {
+    /** Keyed by id; `add()` looks up existing entries by id in O(1). */
+    MAP = "MAP",
+    // LINKED_LIST = "LINKED_LIST",
+    /** Plain list; insertion order is preserved. */
+    ARRAY = "ARRAY",
+}
+
+/** What happens on {@link IBCollection.add} when a value's id already exists. */
+export enum EBDuplicateIDStrategy {
+    /** Replace the existing value. */
+    OVERWRITE = "OVERWRITE",
+    /** Reject the whole call. */
+    ERROR = "ERROR",
+    /** Keep the existing value, drop the new one. */
+    IGNORE = "IGNORE",
+}
+
+/** How {@link IBCollection.delete} removes matched items from an `ARRAY` collection. */
+export enum EBArrayDeletionStrategy {
+    /** Build a new array via `filter()`. */
+    NEW_ARRAY = "NEW_ARRAY",
+    /** Compact the existing array in place. */
+    IN_PLACE = "IN_PLACE",
+}
+
+/** When a collection is written to disk after a mutation. */
+export enum EBAutoFlushStrategy {
+    /** Only on an explicit {@link IBCollection.flush} call. */
+    NO_AUTO_FLUSH = "NO_AUTO_FLUSH",
+    /** After every mutating call (`add`/`update`/`delete`). */
+    ALWAYS_AUTO_FLUSH = "ALWAYS_AUTO_FLUSH",
+}
+
+/** What {@link IBCollection.unload} does with unsaved changes. */
+export enum EBDirtyUnloadStrategy {
+    /** Reject the unload. */
+    ERROR = "ERROR",
+    /** Flush first, then unload. */
+    FLUSH = "FLUSH",
+    /** Discard the unsaved changes silently. */
+    IGNORE = "IGNORE",
+}
+
+/** Resolves the id of a value; `undefined` means "no id yet". */
+export type TGetIDFunction = (v: any) => Promise<string | undefined>;
+
+/** Assigns an id onto a value. */
+export type TSetIDFunction = (v: any, id: string) => Promise<void>;
+
+/** Extracts an index key (or several, for a multi-valued index) from a value; `undefined` means "not indexed". */
+export type TIndexKeyFunction<T = any> = (v: T) => Promise<string | string[] | undefined>;
+
+/** Per-collection behavior. Passed to {@link IBDatabase.createCollection}/{@link IBDatabase.getCollection}. */
+export interface IBCollectionConfig {
+    autoIDStrategy: EBAutoIDStrategy;
+    duplicateIDStrategy: EBDuplicateIDStrategy;
+    memStorageStrategy: EBMemStorageStrategy;
+    arrayDeletionStrategy: EBArrayDeletionStrategy;
+    dirtyUnloadStrategy: EBDirtyUnloadStrategy;
+    autoFlushStrategy: EBAutoFlushStrategy;
+    /** Registry key for a custom {@link TGetIDFunction}. Omit to use the default (reads `.id`). */
+    getID?: string;
+    /** Registry key for a custom {@link TSetIDFunction}. Omit to use the default (sets `.id`). */
+    setID?: string;
+    /** Index name → registry key of a {@link TIndexKeyFunction} for that index. Omit for no indexes. */
+    indexes?: { [indexKey: string]: string };
+}
+
+/** Database-wide configuration. */
+export interface IBDatabaseConfig {
+    /** Used for any collection created without an explicit config. */
+    readonly defaultCollectionConfig: IBCollectionConfig;
+}
+
+/** Options for {@link IBDatabase.snapshot}. */
+export interface IBSnapshotOptions {
+    /** Appended to the version folder's timestamp. Letters, digits, `-` and `_` only. */
+    label?: string;
+    /** Older version folders under `targetDir` to keep besides the one just created. `0` keeps only the new one. Negative values reject. */
+    keepLast?: number;
+}
+
+/** A JSON-file-backed database. Obtain one via `getDatabase()`. */
+export interface IBDatabase {
+    readonly config: IBDatabaseConfig;
+    /** Creates a new collection. Rejects if one with the same (canonicalized) name already exists. */
+    createCollection<T>(collectionName: string, collectionConfig?: IBCollectionConfig): Promise<IBCollection<T>>;
+    /** Returns the named collection, creating it with `collectionConfig` (or the database default) if it doesn't exist yet. */
+    getCollection<T>(collectionName: string, collectionConfig?: IBCollectionConfig): Promise<IBCollection<T>>;
+    /** Whether a collection with this (canonicalized) name exists. */
+    hasCollection(collectionName: string): Promise<boolean>;
+    /** Deletes a collection and invalidates any handle still held on it. Rejects if it doesn't exist. */
+    dropCollection(collectionName: string): Promise<void>;
+    /**
+     * Flushes every loaded collection, then copies the whole database directory into a new, timestamped
+     * version folder under `targetDir` (created if needed). Blocks all other database operations for the
+     * duration. See {@link IBSnapshotOptions} for pruning older versions. Returns the new version folder's path.
+     */
+    snapshot(targetDir: string, options?: IBSnapshotOptions): Promise<string>;
+    /**
+     * 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>;
+}
+
+/** What kind of collection mutation a handler subscribes to via {@link IBCollection.on}. */
+export enum EBModificationType {
+    /** A value was stored by `add()` (including an id-based overwrite). */
+    ADD = "ADD",
+    /** A value was replaced by `update()`. */
+    UPDATE = "UPDATE",
+    /** A value was removed by `delete()`. */
+    DELETE = "DELETE",
+}
+
+/** Handler for {@link EBModificationType.ADD}: called with each value stored by `add()`. */
+export type TAddHandler<T> = (added: T) => void | Promise<void>;
+/** Handler for {@link EBModificationType.UPDATE}: called with the previous and the replacement value. */
+export type TUpdateHandler<T> = (previous: T, updated: T) => void | Promise<void>;
+/** Handler for {@link EBModificationType.DELETE}: called with each value removed by `delete()`. */
+export type TDeleteHandler<T> = (deleted: T) => void | Promise<void>;
+
+/** Handle returned by {@link IBCollection.on}. */
+export interface IHandlerRegistration {
+    /** Unsubscribes the handler. Idempotent. */
+    cancel(): Promise<void>;
+}
+
+/** Whether a handler registered via {@link IBCollection.on} blocks the call that triggered it. */
+export enum EBHandlerMode {
+    /** The triggering `add()`/`update()`/`delete()` call doesn't resolve until this handler has run. Default. */
+    SYNC = "SYNC",
+    /** The handler runs without the triggering call waiting for it. */
+    ASYNC = "ASYNC",
+}
+
+/** A single collection of values of type `T`. Obtain one via {@link IBDatabase}. */
+export interface IBCollection<T = any> {
+    readonly database: IBDatabase;
+    readonly collectionConfig: IBCollectionConfig;
+    /** Canonicalized (trimmed, lowercased) name. */
+    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`. 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>;
+    /** Whether any item matches `predicate`. */
+    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`; 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`. 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>;
+    /** Subscribes to `update()` mutations. Fires after the value is replaced, 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.UPDATE, handler: TUpdateHandler<T>, mode?: EBHandlerMode): Promise<IHandlerRegistration>;
+    /** Subscribes to `delete()` mutations. Fires after the value is removed, 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.DELETE, handler: TDeleteHandler<T>, mode?: EBHandlerMode): Promise<IHandlerRegistration>;
+
+    /** Writes the current in-memory state to disk. */
+    flush(): Promise<void>;
+    /** Discards in-memory state and re-reads it from disk. */
+    reload(): Promise<void>;
+    /** Evicts the in-memory state (per the dirty-unload strategy if there are unsaved changes). */
+    unload(): Promise<void>;
+
+}
+
+/**
+ * Transaction-scoped view of a collection, returned by {@link IBTransaction.getCollection}. Deliberately
+ * narrower than {@link IBCollection}: no `flush`/`reload`/`unload`/`on` here - flushing would write the
+ * transaction's not-yet-committed state to disk, and `on()` would register a handler against a working copy
+ * that either gets discarded (rolled back) or replaced (committed), neither of which is what a caller means
+ * by "subscribe to this collection".
+ */
+export interface IBTransactionCollection<T = any> {
+    readonly collectionName: string;
+    readonly collectionID: string;
+    /** Same as {@link IBCollection.get}, scoped to this transaction's in-progress state. */
+    get(predicate?: (v: T) => boolean): Promise<T[]>;
+    /** Same as {@link IBCollection.has}, scoped to this transaction's in-progress state. */
+    has(predicate: (v: T) => boolean): Promise<boolean>;
+    /** Same as {@link IBCollection.count}, scoped to this transaction's in-progress state. */
+    count(predicate?: (v: T) => boolean): Promise<number>;
+    /** Same as {@link IBCollection.getByIndex}, scoped to this transaction's in-progress state. */
+    getByIndex(indexKey: string, key: string): Promise<T[]>;
+    /** Same as {@link IBCollection.add}, applied only within this transaction until it commits. */
+    add(...v: T[]): Promise<number>;
+    /** Same as {@link IBCollection.update}, applied only within this transaction until it commits. */
+    update(predicate: (v: T) => boolean, updater: (v: T) => Promise<T>): Promise<number>;
+    /** Same as {@link IBCollection.delete}, applied only within this transaction until it commits. */
+    delete(predicate: (v: T) => boolean): Promise<number>;
+}
+
+/** Passed into {@link IBDatabase.transaction}'s callback; the only way to reach the collections it declared. */
+export interface IBTransaction {
+    /**
+     * The transaction-scoped view of `collectionName`. Returns the same instance on repeat calls with the
+     * same (canonicalized) name within one transaction. Throws if `collectionName` wasn't declared to
+     * {@link IBDatabase.transaction}.
+     */
+    getCollection<T = any>(collectionName: string): Promise<IBTransactionCollection<T>>;
+}
+
+/** Resolves the custom id functions referenced by {@link IBCollectionConfig.getID}/`setID`. */
+export interface IBFunctionRegistry {
+    /** Returns the function registered under `key`, or `undefined` if there is none. */
+    fetch(key?: string): Function | undefined;
+}