@incoqnito.io/bajadab 1.1.0

package/LICENSE

@@ -0,0 +1 @@
+(c) Copyright 2026 incoqnito GmbH, all rights reserved.

package/README.md

@@ -0,0 +1,101 @@
+# 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.
+- 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.
+
+## 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. |
+
+## 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.
+
+## 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.
+
+## License
+
+See [LICENSE](./LICENSE).

package/dist/bajadab.d.ts

@@ -0,0 +1,3 @@
+export * from "./base.js";
+export { getDatabase } from "./fileio.js";
+export { DEFAULT_COLLECTION_CONFIG, DEFAULT_DATABASE_CONFIG, DEFAULT_GET_ID, DEFAULT_SET_ID, } from "./basics.js";

package/dist/bajadab.js

@@ -0,0 +1,4 @@
+export * from "./base.js";
+export { getDatabase } from "./fileio.js";
+export { DEFAULT_COLLECTION_CONFIG, DEFAULT_DATABASE_CONFIG, DEFAULT_GET_ID, DEFAULT_SET_ID, } from "./basics.js";
+//# sourceMappingURL=bajadab.js.map

package/dist/bajadab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bajadab.js","sourceRoot":"","sources":["../src/main/bajadab.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,cAAc,EAAE,cAAc,GAAG,MAAM,aAAa,CAAC"}

package/dist/base.d.ts

@@ -0,0 +1,110 @@
+/** How a missing id is handled on {@link IBCollection.add}. */
+export declare 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 declare enum EBMemStorageStrategy {
+    /** Keyed by id; `add()` looks up existing entries by id in O(1). */
+    MAP = "MAP",
+    /** Plain list; insertion order is preserved. */
+    ARRAY = "ARRAY"
+}
+/** What happens on {@link IBCollection.add} when a value's id already exists. */
+export declare 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 declare 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 declare 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 declare 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>;
+/** 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;
+}
+/** Database-wide configuration. */
+export interface IBDatabaseConfig {
+    /** Used for any collection created without an explicit config. */
+    readonly defaultCollectionConfig: IBCollectionConfig;
+}
+/** 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>;
+}
+/** 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>;
+    /** 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;
+}

package/dist/base.js

@@ -0,0 +1,54 @@
+/** How a missing id is handled on {@link IBCollection.add}. */
+export var EBAutoIDStrategy;
+(function (EBAutoIDStrategy) {
+    /** Reject values without an id. */
+    EBAutoIDStrategy["NO_AUTO_ID"] = "NO_AUTO_ID";
+    /** Generate a `uuidv7` and assign it via the configured setter. */
+    EBAutoIDStrategy["AUTO_ID_UUID"] = "AUTO_ID_UUID";
+})(EBAutoIDStrategy || (EBAutoIDStrategy = {}));
+/** In-memory representation of a collection's data. */
+export var EBMemStorageStrategy;
+(function (EBMemStorageStrategy) {
+    /** Keyed by id; `add()` looks up existing entries by id in O(1). */
+    EBMemStorageStrategy["MAP"] = "MAP";
+    // LINKED_LIST = "LINKED_LIST",
+    /** Plain list; insertion order is preserved. */
+    EBMemStorageStrategy["ARRAY"] = "ARRAY";
+})(EBMemStorageStrategy || (EBMemStorageStrategy = {}));
+/** What happens on {@link IBCollection.add} when a value's id already exists. */
+export var EBDuplicateIDStrategy;
+(function (EBDuplicateIDStrategy) {
+    /** Replace the existing value. */
+    EBDuplicateIDStrategy["OVERWRITE"] = "OVERWRITE";
+    /** Reject the whole call. */
+    EBDuplicateIDStrategy["ERROR"] = "ERROR";
+    /** Keep the existing value, drop the new one. */
+    EBDuplicateIDStrategy["IGNORE"] = "IGNORE";
+})(EBDuplicateIDStrategy || (EBDuplicateIDStrategy = {}));
+/** How {@link IBCollection.delete} removes matched items from an `ARRAY` collection. */
+export var EBArrayDeletionStrategy;
+(function (EBArrayDeletionStrategy) {
+    /** Build a new array via `filter()`. */
+    EBArrayDeletionStrategy["NEW_ARRAY"] = "NEW_ARRAY";
+    /** Compact the existing array in place. */
+    EBArrayDeletionStrategy["IN_PLACE"] = "IN_PLACE";
+})(EBArrayDeletionStrategy || (EBArrayDeletionStrategy = {}));
+/** When a collection is written to disk after a mutation. */
+export var EBAutoFlushStrategy;
+(function (EBAutoFlushStrategy) {
+    /** Only on an explicit {@link IBCollection.flush} call. */
+    EBAutoFlushStrategy["NO_AUTO_FLUSH"] = "NO_AUTO_FLUSH";
+    /** After every mutating call (`add`/`update`/`delete`). */
+    EBAutoFlushStrategy["ALWAYS_AUTO_FLUSH"] = "ALWAYS_AUTO_FLUSH";
+})(EBAutoFlushStrategy || (EBAutoFlushStrategy = {}));
+/** What {@link IBCollection.unload} does with unsaved changes. */
+export var EBDirtyUnloadStrategy;
+(function (EBDirtyUnloadStrategy) {
+    /** Reject the unload. */
+    EBDirtyUnloadStrategy["ERROR"] = "ERROR";
+    /** Flush first, then unload. */
+    EBDirtyUnloadStrategy["FLUSH"] = "FLUSH";
+    /** Discard the unsaved changes silently. */
+    EBDirtyUnloadStrategy["IGNORE"] = "IGNORE";
+})(EBDirtyUnloadStrategy || (EBDirtyUnloadStrategy = {}));
+//# sourceMappingURL=base.js.map

package/dist/base.js.map

@@ -0,0 +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"}

package/dist/basics.d.ts

@@ -0,0 +1,50 @@
+import type { IODatabase } from "./fileio.js";
+import { IBCollection, IBCollectionConfig, IBDatabase, IBDatabaseConfig, IBFunctionRegistry, TGetIDFunction, TSetIDFunction } 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;
+/** {@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. */
+export declare const DEFAULT_DATABASE_CONFIG: IBDatabaseConfig;
+export declare class BDatabase implements IBDatabase {
+    readonly config: IBDatabaseConfig;
+    private collections;
+    readonly io: IODatabase;
+    readonly functionRegistry?: IBFunctionRegistry;
+    constructor(io: IODatabase, config?: IBDatabaseConfig, functionRegistry?: IBFunctionRegistry);
+    addCollection(collection: BCollection): void;
+    getCollection<T>(collectionName: string, collectionConfig?: IBCollectionConfig): Promise<IBCollection<T>>;
+    createCollection<T = any>(collectionName: string, collectionConfig?: IBCollectionConfig): Promise<BCollection<T>>;
+    hasCollection(collectionName: string): Promise<boolean>;
+    dropCollection(collectionName: string): Promise<void>;
+}
+export declare class BCollection<T = any> implements IBCollection<T> {
+    readonly database: BDatabase;
+    readonly collectionConfig: IBCollectionConfig;
+    readonly collectionName: string;
+    readonly collectionID: string;
+    private mapData;
+    private arrayData;
+    private loaded;
+    private dirty;
+    private dropped;
+    constructor(database: BDatabase, collectionID: string, collectionName: string, collectionConfig: IBCollectionConfig);
+    private checkLoaded;
+    private runProtected;
+    /**
+     * call this only within the proteing mutex
+     */
+    markDropped(): void;
+    get(predicate?: (v: T) => boolean): Promise<T[]>;
+    delete(predicate: (v: T) => boolean): Promise<number>;
+    has(predicate: (v: T) => boolean): Promise<boolean>;
+    private getID;
+    add(...vs: T[]): Promise<number>;
+    update(predicate: (v: T) => boolean, updater: (v: T) => Promise<T>): Promise<number>;
+    private doOnDirty;
+    flush(): Promise<void>;
+    reload(): Promise<void>;
+    unload(): Promise<void>;
+}