@incoqnito.io/bajadab 1.1.0 → 1.2.1

package/README.md

@@ -8,8 +8,10 @@ A lightweight JSON-file-backed database for small, single-machine setups. No ser
 - `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.
 
 ## Install
 
@@ -54,6 +56,7 @@ Every collection has an `IBCollectionConfig`. `db.config.defaultCollectionConfig
 | `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
 
@@ -82,6 +85,34 @@ const users = await db.createCollection("users", {
 
 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:
@@ -96,6 +127,27 @@ Collections are addressed by a stable id, not by name, so a handle to a since-re
 
 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.
+
 ## License
 
 See [LICENSE](./LICENSE).

package/dist/base.d.ts

@@ -48,6 +48,8 @@ export declare enum EBDirtyUnloadStrategy {
 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;
@@ -60,12 +62,23 @@ export interface IBCollectionConfig {
     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;
@@ -77,6 +90,39 @@ export interface IBDatabase {
     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 declare 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 declare 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> {
@@ -96,6 +142,16 @@ export interface IBCollection<T = any> {
     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. */

package/dist/base.js

@@ -51,4 +51,22 @@ export var EBDirtyUnloadStrategy;
     /** Discard the unsaved changes silently. */
     EBDirtyUnloadStrategy["IGNORE"] = "IGNORE";
 })(EBDirtyUnloadStrategy || (EBDirtyUnloadStrategy = {}));
+/** What kind of collection mutation a handler subscribes to via {@link IBCollection.on}. */
+export var EBModificationType;
+(function (EBModificationType) {
+    /** A value was stored by `add()` (including an id-based overwrite). */
+    EBModificationType["ADD"] = "ADD";
+    /** A value was replaced by `update()`. */
+    EBModificationType["UPDATE"] = "UPDATE";
+    /** A value was removed by `delete()`. */
+    EBModificationType["DELETE"] = "DELETE";
+})(EBModificationType || (EBModificationType = {}));
+/** Whether a handler registered via {@link IBCollection.on} blocks the call that triggered it. */
+export var EBHandlerMode;
+(function (EBHandlerMode) {
+    /** The triggering `add()`/`update()`/`delete()` call doesn't resolve until this handler has run. Default. */
+    EBHandlerMode["SYNC"] = "SYNC";
+    /** The handler runs without the triggering call waiting for it. */
+    EBHandlerMode["ASYNC"] = "ASYNC";
+})(EBHandlerMode || (EBHandlerMode = {}));
 //# sourceMappingURL=base.js.map

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"}
+{"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;AA4DD,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,5 +1,5 @@
 import type { IODatabase } from "./fileio.js";
-import { IBCollection, IBCollectionConfig, IBDatabase, IBDatabaseConfig, IBFunctionRegistry, TGetIDFunction, TSetIDFunction } from "./base.js";
+import { EBHandlerMode, EBModificationType, IBCollection, IBCollectionConfig, IBDatabase, IBDatabaseConfig, IBFunctionRegistry, IBSnapshotOptions, 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`. */
@@ -19,6 +19,7 @@ export declare class BDatabase implements IBDatabase {
     createCollection<T = any>(collectionName: string, collectionConfig?: IBCollectionConfig): Promise<BCollection<T>>;
     hasCollection(collectionName: string): Promise<boolean>;
     dropCollection(collectionName: string): Promise<void>;
+    snapshot(targetDir: string, options?: IBSnapshotOptions): Promise<string>;
 }
 export declare class BCollection<T = any> implements IBCollection<T> {
     readonly database: BDatabase;
@@ -30,16 +31,40 @@ export declare class BCollection<T = any> implements IBCollection<T> {
     private loaded;
     private dirty;
     private dropped;
+    private addHandlers;
+    private updateHandlers;
+    private deleteHandlers;
+    private indexDefinitions;
+    private indexRuntime;
     constructor(database: BDatabase, collectionID: string, collectionName: string, collectionConfig: IBCollectionConfig);
     private checkLoaded;
+    private runExclusive;
     private runProtected;
     /**
-     * call this only within the proteing mutex
+     * call this only within the protecting mutex
      */
     markDropped(): void;
     get(predicate?: (v: T) => boolean): Promise<T[]>;
+    count(predicate?: (v: T) => boolean): Promise<number>;
+    getByIndex(indexKey: string, key: string): Promise<T[]>;
+    private invokeHandler;
+    private fireAdd;
+    private fireUpdate;
+    private fireDelete;
+    on(modificationType: EBModificationType.ADD, handler: TAddHandler<T>, mode?: EBHandlerMode): Promise<IHandlerRegistration>;
+    on(modificationType: EBModificationType.UPDATE, handler: TUpdateHandler<T>, mode?: EBHandlerMode): Promise<IHandlerRegistration>;
+    on(modificationType: EBModificationType.DELETE, handler: TDeleteHandler<T>, mode?: EBHandlerMode): Promise<IHandlerRegistration>;
     delete(predicate: (v: T) => boolean): Promise<number>;
     has(predicate: (v: T) => boolean): Promise<boolean>;
+    private resolveIndexDefinitions;
+    private indexKeysFor;
+    private addToIndexes;
+    private removeFromIndexes;
+    /**
+     * full rebuild from currently loaded data; only needed right after (re)load, since every
+     * value then is a freshly deserialized object the incremental add/update/delete hooks never saw
+     */
+    private rebuildIndexRuntime;
     private getID;
     add(...vs: T[]): Promise<number>;
     update(predicate: (v: T) => boolean, updater: (v: T) => Promise<T>): Promise<number>;