keri-ts 2.0.1 → 2.2.0

package/esm/keri/npm/src/db/core/index.js

@@ -1,6 +1,8 @@
 /**
  * Core database module exports
  */
+export * from "./dber.js";
 export * from "./keys.js";
-export * from "./lmdber.js";
-export * from "./path-manager.js";
+export * from "./memstore.js";
+export * from "./store-owner.js";
+export * from "./webdber.js";

package/esm/keri/npm/src/db/core/indexeddb-persistence.js

@@ -0,0 +1,221 @@
+/**
+ * IndexedDB `Persistence` for `WebDBer`.
+ *
+ * One database per store family and identity holds every logical table in a
+ * single `rows` object store, plus a `meta` store for the version marker and each table's
+ * dupsort flag. Tables are not object stores. Adding a table is therefore a
+ * plain write, never a schema `versionchange`, which another open connection
+ * could block indefinitely. This departs from the plan's "one object store per
+ * table", which ADR-0015 permits as the alternative to handling `versionchange`.
+ *
+ * Rows have out-of-line array keys `[table, keyBytes, valueOrEmpty]`. On a
+ * dupsort table the third part is the duplicate value, so each duplicate is its
+ * own row. On a plain table it is empty and the record holds the value. Empty
+ * dupsort values are rejected upstream, so an empty third part always means
+ * "plain". Binary parts are `ArrayBuffer`s. IndexedDB's key order is never
+ * relied on, because `WebDBer` sorts what it loads.
+ *
+ * The family is part of the database name because a composition's stores share
+ * one `name` and `base`; without it a Baser and Keeper would share a database,
+ * a version marker and a `clear`. A temp store is named apart from a durable one
+ * so clearing it cannot delete durable data of the same name.
+ *
+ * `write` is one `readwrite` transaction with strict durability and settles on
+ * the transaction's `complete` event, never on a request's `success`.
+ *
+ * Another tab's upgrade or delete fires `versionchange` here. The connection
+ * closes at once so that tab is never blocked, and this adapter is then lost:
+ * its next `load` or `write` rejects, which latches the queue, because writing
+ * on after another context deleted the database would break prefix durability.
+ * Recovery is a new open, whose `meta` reconnects. Single-writer exclusion is
+ * the composition's job, not this adapter's.
+ *
+ * A blocked `clear` rejects. Our own connection is already closed, and ours
+ * close on `versionchange`, so only a foreign connection can block. Reads settle on
+ * their transaction's `complete`, like writes: WebKit reports `blocked` for a
+ * connection whose close is still waiting on a finishing read transaction. The browser
+ * keeps the delete request pending and performs it once that connection closes,
+ * which is what `clear` asked for.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _IndexedDbPersistence_instances, _IndexedDbPersistence_databaseName, _IndexedDbPersistence_factory, _IndexedDbPersistence_keyRange, _IndexedDbPersistence_dupsort, _IndexedDbPersistence_db, _IndexedDbPersistence_lost, _IndexedDbPersistence_connect, _IndexedDbPersistence_connection;
+import { DatabaseOperationError } from "../../core/errors.js";
+const ROWS = "rows";
+const META = "meta";
+const VERSION_KEY = "version";
+const TABLE_PREFIX = "table:";
+const EMPTY = new ArrayBuffer(0);
+/** An exact-length `ArrayBuffer` copy, since `.buffer` of a view may span more bytes. */
+const buffer = (bytes) => bytes.slice().buffer;
+/** Settle with a request's result. Only valid inside a transaction that is still open. */
+function result(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+/** Settle on `complete` or fail with the real cause on `abort` or `error`. */
+function completion(transaction) {
+    return new Promise((resolve, reject) => {
+        let cause;
+        transaction.oncomplete = () => resolve();
+        transaction.onerror = (event) => cause ??= event.target?.error;
+        transaction.onabort = () => reject(new DatabaseOperationError("IndexedDB transaction aborted", {
+            cause: transaction.error ?? cause,
+        }));
+    });
+}
+/** `Persistence` over IndexedDB. Methods are called one at a time by `WebDBer`. */
+export class IndexedDbPersistence {
+    /**
+     * @param family Store family; with `identity` it chooses the database.
+     * @param identity Store identity; `name`, `base` and `temp` choose the database.
+     * @param factory Defaults to the global `indexedDB`.
+     * @param keyRange Defaults to the global `IDBKeyRange`; inject it with `factory` outside a browser.
+     */
+    constructor(family, identity, factory = globalThis.indexedDB, keyRange = globalThis.IDBKeyRange) {
+        _IndexedDbPersistence_instances.add(this);
+        _IndexedDbPersistence_databaseName.set(this, void 0);
+        _IndexedDbPersistence_factory.set(this, void 0);
+        _IndexedDbPersistence_keyRange.set(this, void 0);
+        /** Dupsort flag per table, learned from `meta` and from each batch that creates one. */
+        _IndexedDbPersistence_dupsort.set(this, new Map());
+        _IndexedDbPersistence_db.set(this, null);
+        _IndexedDbPersistence_lost.set(this, null);
+        const place = [identity.base ?? "", identity.name ?? "", family.tail, identity.temp ? "temp" : "durable"];
+        __classPrivateFieldSet(this, _IndexedDbPersistence_databaseName, `keri-ts:${JSON.stringify(place)}`, "f");
+        __classPrivateFieldSet(this, _IndexedDbPersistence_factory, factory, "f");
+        __classPrivateFieldSet(this, _IndexedDbPersistence_keyRange, keyRange, "f");
+    }
+    async meta() {
+        const db = await __classPrivateFieldGet(this, _IndexedDbPersistence_instances, "m", _IndexedDbPersistence_connect).call(this);
+        const transaction = db.transaction(META, "readonly");
+        const store = transaction.objectStore(META);
+        const range = __classPrivateFieldGet(this, _IndexedDbPersistence_keyRange, "f").bound(TABLE_PREFIX, `${TABLE_PREFIX}￿`);
+        // Settle on `complete`: a connection with a transaction still finishing is not yet closed.
+        const [, version, names, flags] = await Promise.all([
+            completion(transaction),
+            result(store.get(VERSION_KEY)),
+            result(store.getAllKeys(range)),
+            result(store.getAll(range)),
+        ]);
+        __classPrivateFieldGet(this, _IndexedDbPersistence_dupsort, "f").clear();
+        const tables = names.map((key, index) => {
+            const name = String(key).slice(TABLE_PREFIX.length);
+            const dupsort = flags[index] === true;
+            __classPrivateFieldGet(this, _IndexedDbPersistence_dupsort, "f").set(name, dupsort);
+            return { name, dupsort };
+        });
+        return { version: typeof version === "string" ? version : null, tables };
+    }
+    async load(table) {
+        const transaction = __classPrivateFieldGet(this, _IndexedDbPersistence_instances, "m", _IndexedDbPersistence_connection).call(this).transaction(ROWS, "readonly");
+        const store = transaction.objectStore(ROWS);
+        // Binary sorts below array, so `[table, []]` bounds every `[table, key, value]`.
+        const range = __classPrivateFieldGet(this, _IndexedDbPersistence_keyRange, "f").bound([table], [table, []]);
+        const [, keys, records] = await Promise.all([
+            completion(transaction),
+            result(store.getAllKeys(range)),
+            result(store.getAll(range)),
+        ]);
+        return keys.map((row, index) => {
+            const [, key, duplicate] = row;
+            const value = duplicate.byteLength > 0 ? duplicate : records[index];
+            return { key: new Uint8Array(key), value: new Uint8Array(value) };
+        });
+    }
+    write(batch) {
+        let transaction;
+        try {
+            transaction = __classPrivateFieldGet(this, _IndexedDbPersistence_instances, "m", _IndexedDbPersistence_connection).call(this).transaction([ROWS, META], "readwrite", { durability: "strict" });
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const done = completion(transaction);
+        try {
+            const meta = transaction.objectStore(META);
+            const rows = transaction.objectStore(ROWS);
+            for (const { name, dupsort } of batch.tables) {
+                __classPrivateFieldGet(this, _IndexedDbPersistence_dupsort, "f").set(name, dupsort);
+                meta.put(dupsort, `${TABLE_PREFIX}${name}`);
+            }
+            if (batch.version !== undefined)
+                meta.put(batch.version, VERSION_KEY);
+            for (const { table, key, value } of batch.puts) {
+                const dupsort = __classPrivateFieldGet(this, _IndexedDbPersistence_dupsort, "f").get(table);
+                if (dupsort === undefined)
+                    throw new DatabaseOperationError(`Unknown table ${table}`);
+                rows.put(dupsort ? null : buffer(value), [table, buffer(key), dupsort ? buffer(value) : EMPTY]);
+            }
+            for (const { table, key, value } of batch.deletes) {
+                rows.delete([table, buffer(key), value ? buffer(value) : EMPTY]);
+            }
+        }
+        catch (error) {
+            transaction.abort();
+            return done.catch(() => {
+                throw error;
+            });
+        }
+        return done;
+    }
+    async clear() {
+        await this.close();
+        await new Promise((resolve, reject) => {
+            const request = __classPrivateFieldGet(this, _IndexedDbPersistence_factory, "f").deleteDatabase(__classPrivateFieldGet(this, _IndexedDbPersistence_databaseName, "f"));
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+            request.onblocked = () => reject(new DatabaseOperationError(`Cannot clear ${__classPrivateFieldGet(this, _IndexedDbPersistence_databaseName, "f")}: another connection holds it open; the delete stays pending until it closes`));
+        });
+        __classPrivateFieldGet(this, _IndexedDbPersistence_dupsort, "f").clear();
+    }
+    close() {
+        __classPrivateFieldGet(this, _IndexedDbPersistence_db, "f")?.close();
+        __classPrivateFieldSet(this, _IndexedDbPersistence_db, null, "f");
+        __classPrivateFieldSet(this, _IndexedDbPersistence_lost, null, "f");
+        return Promise.resolve();
+    }
+}
+_IndexedDbPersistence_databaseName = new WeakMap(), _IndexedDbPersistence_factory = new WeakMap(), _IndexedDbPersistence_keyRange = new WeakMap(), _IndexedDbPersistence_dupsort = new WeakMap(), _IndexedDbPersistence_db = new WeakMap(), _IndexedDbPersistence_lost = new WeakMap(), _IndexedDbPersistence_instances = new WeakSet(), _IndexedDbPersistence_connect = function _IndexedDbPersistence_connect() {
+    if (__classPrivateFieldGet(this, _IndexedDbPersistence_db, "f"))
+        return Promise.resolve(__classPrivateFieldGet(this, _IndexedDbPersistence_db, "f"));
+    if (!__classPrivateFieldGet(this, _IndexedDbPersistence_factory, "f"))
+        throw new DatabaseOperationError("IndexedDB is not available in this environment");
+    return new Promise((resolve, reject) => {
+        const request = __classPrivateFieldGet(this, _IndexedDbPersistence_factory, "f").open(__classPrivateFieldGet(this, _IndexedDbPersistence_databaseName, "f"), 1);
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            db.createObjectStore(ROWS);
+            db.createObjectStore(META);
+        };
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => {
+            const db = request.result;
+            db.onversionchange = () => {
+                db.close();
+                if (__classPrivateFieldGet(this, _IndexedDbPersistence_db, "f") === db) {
+                    __classPrivateFieldSet(this, _IndexedDbPersistence_db, null, "f");
+                    __classPrivateFieldSet(this, _IndexedDbPersistence_lost, new DatabaseOperationError("IndexedDB connection closed by another context's versionchange"), "f");
+                }
+            };
+            __classPrivateFieldSet(this, _IndexedDbPersistence_lost, null, "f");
+            __classPrivateFieldSet(this, _IndexedDbPersistence_db, db, "f");
+            resolve(db);
+        };
+    });
+}, _IndexedDbPersistence_connection = function _IndexedDbPersistence_connection() {
+    if (__classPrivateFieldGet(this, _IndexedDbPersistence_db, "f"))
+        return __classPrivateFieldGet(this, _IndexedDbPersistence_db, "f");
+    throw __classPrivateFieldGet(this, _IndexedDbPersistence_lost, "f") ?? new DatabaseOperationError("IndexedDB persistence is not connected");
+};

package/esm/keri/npm/src/db/core/lmdb-opener.js

@@ -0,0 +1,30 @@
+/** LMDB placement of store families, reproducing each family's established paths. */
+import { LMDBer } from "./lmdber.js";
+/** Derive the LMDB path defaults for one family. */
+export function lmdbDefaultsFor(family, compat = false) {
+    const altRoot = compat && !family.noCompat ? ".keri" : ".tufa";
+    return {
+        tailDirPath: `keri/${family.tail}`,
+        cleanTailDirPath: `keri/clean/${family.tail}`,
+        altTailDirPath: `${altRoot}/${family.tail}`,
+        altCleanTailDirPath: `${altRoot}/clean/${family.tail}`,
+        // As in KERIpy, Baser keeps the base LMDBer temp prefix.
+        tempPrefix: family.tail === "db" ? "keri_lmdb_" : `keri_${family.tail.replaceAll("/", "_")}_`,
+        ...(family.maxTables === undefined ? {} : { maxNamedDBs: family.maxTables }),
+    };
+}
+/** The default `StoreOpener`: closed LMDB stores at the family's established paths. */
+export class LmdbStoreOpener {
+    constructor(location = {}) {
+        Object.defineProperty(this, "location", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: location
+        });
+    }
+    create(family, identity) {
+        const { compat, ...place } = this.location;
+        return new LMDBer({ ...identity, ...place }, lmdbDefaultsFor(family, compat));
+    }
+}