keri-ts 2.0.1 → 2.2.0

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

@@ -0,0 +1,252 @@
+/**
+ * Browser-capable `DBer`: a `MemStore` mirror with write-behind persistence.
+ *
+ * ADR-0015 owns the durability model. Reads and writes are synchronous against
+ * the mirror; each outermost commit enqueues one batch holding its net effect,
+ * and a queue shared by a composition applies batches one at a time in global
+ * commit order. Nothing here may reach `lmdb`, `node:` or the `Deno` global.
+ *
+ * Invariant: once the queue is joined with no failure, the mirror and the
+ * persisted rows are byte-identical, which is why `reopen` joins before it loads.
+ */
+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 __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 _PersistenceQueue_instances, _PersistenceQueue_tail, _PersistenceQueue_failure, _PersistenceQueue_append, _PersistenceQueue_settled, _WebDBer_instances, _WebDBer_persistence, _WebDBer_queue, _WebDBer_pendingTables, _WebDBer_connected, _WebDBer_enqueue, _WebDBer_takePendingTables, _WebDBer_carryPendingTables;
+import { bytesEqual, bytesHex } from "cesr-ts";
+import { call, ensure } from "effection";
+import { DatabaseOperationError } from "../../core/errors.js";
+import { MemStore } from "./memstore.js";
+/**
+ * The persistence order of one composition. Tasks run strictly one at a time,
+ * outside any Effection scope, so cancelling a waiter never cancels a write.
+ *
+ * The first failure latches: every later task is skipped, because applying a
+ * later batch over a lost earlier one would break prefix durability.
+ */
+export class PersistenceQueue {
+    constructor() {
+        _PersistenceQueue_instances.add(this);
+        _PersistenceQueue_tail.set(this, Promise.resolve());
+        _PersistenceQueue_failure.set(this, null);
+    }
+    /** Append a task, which is skipped if an earlier one failed. */
+    enqueue(task) {
+        __classPrivateFieldGet(this, _PersistenceQueue_instances, "m", _PersistenceQueue_append).call(this, task, false);
+    }
+    /** Append connection teardown, which still runs after a failure so a handle is not left open. */
+    release(task) {
+        __classPrivateFieldGet(this, _PersistenceQueue_instances, "m", _PersistenceQueue_append).call(this, task, true);
+    }
+    /** Refuse new work once latched. The original failure is the cause. */
+    assertHealthy() {
+        if (__classPrivateFieldGet(this, _PersistenceQueue_failure, "f")) {
+            throw new DatabaseOperationError("Persistence failed; this composition accepts no more commits", {
+                cause: __classPrivateFieldGet(this, _PersistenceQueue_failure, "f").error,
+            });
+        }
+    }
+    /** Wait until everything enqueued before this call is durable. Halting cancels only the wait. */
+    *flushed() {
+        const settled = __classPrivateFieldGet(this, _PersistenceQueue_instances, "m", _PersistenceQueue_settled).call(this);
+        yield* call(() => settled);
+    }
+    /** Like `flushed`, but a halted caller still waits for the queue and still reports its failure. */
+    *joined() {
+        const settled = __classPrivateFieldGet(this, _PersistenceQueue_instances, "m", _PersistenceQueue_settled).call(this);
+        yield* call(function* () {
+            yield* ensure(() => call(() => settled));
+            yield* call(() => settled);
+        });
+    }
+}
+_PersistenceQueue_tail = new WeakMap(), _PersistenceQueue_failure = new WeakMap(), _PersistenceQueue_instances = new WeakSet(), _PersistenceQueue_append = function _PersistenceQueue_append(task, always) {
+    __classPrivateFieldSet(this, _PersistenceQueue_tail, __classPrivateFieldGet(this, _PersistenceQueue_tail, "f").then(async () => {
+        if (__classPrivateFieldGet(this, _PersistenceQueue_failure, "f") && !always)
+            return;
+        try {
+            await task();
+        }
+        catch (error) {
+            __classPrivateFieldSet(this, _PersistenceQueue_failure, __classPrivateFieldGet(this, _PersistenceQueue_failure, "f") ?? { error }, "f");
+        }
+    }), "f");
+}, _PersistenceQueue_settled = function _PersistenceQueue_settled() {
+    return __classPrivateFieldGet(this, _PersistenceQueue_tail, "f").then(() => {
+        if (__classPrivateFieldGet(this, _PersistenceQueue_failure, "f"))
+            throw __classPrivateFieldGet(this, _PersistenceQueue_failure, "f").error;
+    });
+};
+function sameValue(a, c) {
+    return a === null || c === null ? a === c : bytesEqual(a, c);
+}
+/** Collapse a commit's writes to the first prior and latest state of each row identity. */
+function netRows(changes) {
+    const net = new Map();
+    for (const change of changes) {
+        if (change.kind !== "row")
+            continue;
+        const duplicate = change.dupsort ? bytesHex((change.before ?? change.after)) : "";
+        const identity = `${bytesHex(change.key)}/${duplicate}/${change.table}`;
+        const seen = net.get(identity);
+        if (seen) {
+            seen.after = change.after;
+        }
+        else {
+            net.set(identity, { ...change });
+        }
+    }
+    return [...net.values()].filter((row) => !sameValue(row.before, row.after));
+}
+/** The version a commit leaves behind, or `undefined` when it ends where it began. */
+function netVersion(changes) {
+    const versions = changes.filter((change) => change.kind === "version");
+    const first = versions.at(0);
+    const last = versions.at(-1);
+    return first && last && first.before !== last.after ? last.after : undefined;
+}
+/**
+ * `MemStore` mirror whose commits persist through a `Persistence` adapter.
+ *
+ * After the queue latches, a commit already in the mirror stays there and stays
+ * readable even though it was never persisted, and every later transaction
+ * throws before touching the mirror, so the mirror stops changing. The durable
+ * state is a prefix of the commit sequence. Recovery is a new composition, with
+ * a new queue, loading that prefix; there is no retry.
+ */
+export class WebDBer extends MemStore {
+    constructor(options, persistence, queue) {
+        super(options);
+        _WebDBer_instances.add(this);
+        _WebDBer_persistence.set(this, void 0);
+        _WebDBer_queue.set(this, void 0);
+        /** Tables not yet carried by a batch, so an unwritten table still persists its dupsort flag. */
+        _WebDBer_pendingTables.set(this, new Map());
+        _WebDBer_connected.set(this, false);
+        __classPrivateFieldSet(this, _WebDBer_persistence, persistence, "f");
+        __classPrivateFieldSet(this, _WebDBer_queue, queue, "f");
+    }
+    /**
+     * Join the queue, then bulk-load every persisted table before returning, so
+     * reads never suspend. A latched queue refuses, reporting its failure.
+     */
+    *reopen(options = {}) {
+        yield* this.close(options.clear ?? false);
+        const persistence = __classPrivateFieldGet(this, _WebDBer_persistence, "f");
+        __classPrivateFieldSet(this, _WebDBer_connected, true, "f");
+        const meta = yield* call(() => persistence.meta());
+        const tables = [];
+        for (const { name, dupsort } of meta.tables) {
+            tables.push({ name, dupsort, rows: yield* call(() => persistence.load(name)) });
+        }
+        this.loadContents(tables, meta.version);
+        return yield* super.reopen(options);
+    }
+    /**
+     * Stop accepting work, drain and join the queue even when cancelled, and
+     * report any failure. A latched store is neither cleared nor reusable, and
+     * every later close reports the same failure.
+     */
+    *close(clear = false) {
+        if (clear) {
+            __classPrivateFieldGet(this, _WebDBer_pendingTables, "f").clear();
+        }
+        else if (this.opened && !this.readonly) {
+            __classPrivateFieldGet(this, _WebDBer_instances, "m", _WebDBer_carryPendingTables).call(this);
+        }
+        yield* super.close();
+        const persistence = __classPrivateFieldGet(this, _WebDBer_persistence, "f");
+        if (__classPrivateFieldGet(this, _WebDBer_connected, "f")) {
+            __classPrivateFieldSet(this, _WebDBer_connected, false, "f");
+            __classPrivateFieldGet(this, _WebDBer_queue, "f").release(() => persistence.close());
+        }
+        if (clear)
+            __classPrivateFieldGet(this, _WebDBer_queue, "f").enqueue(() => persistence.clear());
+        yield* __classPrivateFieldGet(this, _WebDBer_queue, "f").joined();
+        if (clear)
+            yield* super.close(true);
+        return true;
+    }
+    /** Bind a table; a new one is physically created by the batch that first carries it. */
+    openTable(name, options = {}) {
+        if (this.readonly || !this.opened || !name || this.hasTable(name))
+            return super.openTable(name, options);
+        __classPrivateFieldGet(this, _WebDBer_queue, "f").assertHealthy();
+        const table = super.openTable(name, options);
+        __classPrivateFieldGet(this, _WebDBer_pendingTables, "f").set(name, options.dupsort ?? false);
+        return table;
+    }
+    transaction(fn) {
+        this.assertOpen();
+        __classPrivateFieldGet(this, _WebDBer_queue, "f").assertHealthy();
+        return super.transaction(fn);
+    }
+    /** Completes when every earlier commit in this composition is durable, or fails with its recorded failure. */
+    *flushed() {
+        this.assertOpen();
+        if (!this.readonly)
+            __classPrivateFieldGet(this, _WebDBer_instances, "m", _WebDBer_carryPendingTables).call(this);
+        yield* __classPrivateFieldGet(this, _WebDBer_queue, "f").flushed();
+    }
+    committed(changes) {
+        const rows = netRows(changes);
+        const version = netVersion(changes);
+        if (rows.length === 0 && version === undefined)
+            return;
+        const copy = (bytes) => new Uint8Array(bytes);
+        __classPrivateFieldGet(this, _WebDBer_instances, "m", _WebDBer_enqueue).call(this, {
+            tables: __classPrivateFieldGet(this, _WebDBer_instances, "m", _WebDBer_takePendingTables).call(this),
+            ...(version === undefined ? {} : { version }),
+            puts: rows.filter(({ after }) => after !== null).map(({ table, key, after }) => ({
+                table,
+                key: copy(key),
+                value: copy(after),
+            })),
+            deletes: rows.filter(({ after }) => after === null).map(({ table, dupsort, key, before }) => ({
+                table,
+                key: copy(key),
+                ...(dupsort ? { value: copy(before) } : {}),
+            })),
+        });
+    }
+}
+_WebDBer_persistence = new WeakMap(), _WebDBer_queue = new WeakMap(), _WebDBer_pendingTables = new WeakMap(), _WebDBer_connected = new WeakMap(), _WebDBer_instances = new WeakSet(), _WebDBer_enqueue = function _WebDBer_enqueue(batch) {
+    const persistence = __classPrivateFieldGet(this, _WebDBer_persistence, "f");
+    __classPrivateFieldGet(this, _WebDBer_queue, "f").enqueue(() => persistence.write(batch));
+}, _WebDBer_takePendingTables = function _WebDBer_takePendingTables() {
+    const tables = [...__classPrivateFieldGet(this, _WebDBer_pendingTables, "f")].filter(([name]) => this.hasTable(name));
+    __classPrivateFieldGet(this, _WebDBer_pendingTables, "f").clear();
+    return tables.map(([name, dupsort]) => ({ name, dupsort }));
+}, _WebDBer_carryPendingTables = function _WebDBer_carryPendingTables() {
+    const tables = __classPrivateFieldGet(this, _WebDBer_instances, "m", _WebDBer_takePendingTables).call(this);
+    if (tables.length > 0)
+        __classPrivateFieldGet(this, _WebDBer_instances, "m", _WebDBer_enqueue).call(this, { tables, puts: [], deletes: [] });
+};
+/** A `StoreOpener` of `WebDBer`s bound to one queue, which is what makes a composition one commit order. */
+export class WebStoreOpener {
+    constructor(persistenceFor) {
+        Object.defineProperty(this, "persistenceFor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: persistenceFor
+        });
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new PersistenceQueue()
+        });
+    }
+    create(family, identity) {
+        return new WebDBer(identity, this.persistenceFor(family, identity), this.queue);
+    }
+}

package/esm/keri/npm/src/db/escrowing.js

@@ -155,7 +155,7 @@ export class Broker {
             if (!scan) {
                 const start = encode(`${typ}.`), ceiling = encode(`${typ}/`);
                 let tail;
-                for (const key of this.escrowdb.sdb.getKeys({ start: ceiling, end: start, reverse: true, limit: 1 })) {
+                for (const key of this.db.scanKeys(this.escrowdb.sdb, { start: ceiling, end: start, reverse: true, limit: 1 })) {
                     tail = key.slice();
                 }
                 if (!tail)
@@ -164,7 +164,7 @@ export class Broker {
                 this.retryScans.set(typ, scan);
             }
             const rows = [];
-            for (const key of this.escrowdb.sdb.getKeys({ start: scan.start, end: scan.end, limit: maxRows })) {
+            for (const key of this.db.scanKeys(this.escrowdb.sdb, { start: scan.start, end: scan.end, limit: maxRows })) {
                 rows.push(key.slice());
             }
             for (const key of rows) {

package/esm/keri/npm/src/db/exchange/exchange-nests.js

@@ -3,7 +3,7 @@ import { b, collectPayload, concatBytes, Counter, nestedPayload, parseBytes, t,
 import { suffix, unsuffix } from "../core/keys.js";
 /** Read one physical row and close the LMDB key cursor before any caller suspension. */
 function nextRow(db, table, said, ordinal) {
-    for (const key of table.sdb.getKeys({ start: suffix(b(said), ordinal) })) {
+    for (const key of db.scanKeys(table.sdb, { start: suffix(b(said), ordinal) })) {
         const [owner, index] = unsuffix(key);
         if (t(owner) !== said)
             return null;
@@ -16,8 +16,9 @@ function nextRow(db, table, said, ordinal) {
 }
 /** Test row presence without hydrating a potentially large wire value. */
 export function hasNests(db, said, ordinal = 0) {
-    for (const key of db.enst.sdb.getKeys({ start: suffix(b(said), ordinal) }))
+    for (const key of db.scanKeys(db.enst.sdb, { start: suffix(b(said), ordinal) })) {
         return t(unsuffix(key)[0]) === said;
+    }
     return false;
 }
 /** Serialize resident children before the caller enters its synchronous evidence writer. */

package/esm/keri/npm/src/db/indexeddb.js

@@ -0,0 +1,98 @@
+/**
+ * Browser IndexedDB backend surface for `keri-ts/db/indexeddb`.
+ *
+ * Kept off `keri-ts/db` because `IndexedDbPersistence` names DOM types
+ * (`IDBFactory`, `IDBKeyRange`) that Node consumers should not have to type-check.
+ */
+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 _LockedWebDBer_instances, _LockedWebDBer_group, _LockedWebDBer_identity, _LockedWebDBer_ref, _LockedWebDBer_reopening, _LockedWebDBer_letGo, _LockedStoreOpener_group;
+import { call } from "effection";
+import { IndexedDbPersistence } from "./core/indexeddb-persistence.js";
+import { WebDBer, WebStoreOpener } from "./core/webdber.js";
+import { acquireStoreLock, StoreLockGroup, StoreLockHeldError, storeLockKey, StoreLockUnsupportedError, } from "./store-lock.js";
+export { acquireStoreLock, IndexedDbPersistence, StoreLockHeldError, storeLockKey, StoreLockUnsupportedError, };
+/** A `WebDBer` that holds a reference on its opener's lock for as long as it is open. */
+class LockedWebDBer extends WebDBer {
+    constructor(identity, persistence, queue, group) {
+        super(identity, persistence, queue);
+        _LockedWebDBer_instances.add(this);
+        _LockedWebDBer_group.set(this, void 0);
+        _LockedWebDBer_identity.set(this, void 0);
+        _LockedWebDBer_ref.set(this, void 0);
+        _LockedWebDBer_reopening.set(this, false);
+        __classPrivateFieldSet(this, _LockedWebDBer_group, group, "f");
+        __classPrivateFieldSet(this, _LockedWebDBer_identity, identity, "f");
+    }
+    /** Take the lock before `WebDBer.reopen` loads anything; any failure or refusal to open lets it go. */
+    *reopen(options = {}) {
+        // Assigned inside the promise so a halt while waiting cannot orphan the reference.
+        yield* call(async () => {
+            __classPrivateFieldSet(this, _LockedWebDBer_ref, __classPrivateFieldGet(this, _LockedWebDBer_ref, "f") ?? await __classPrivateFieldGet(this, _LockedWebDBer_group, "f").acquire(__classPrivateFieldGet(this, _LockedWebDBer_identity, "f")), "f");
+        });
+        __classPrivateFieldSet(this, _LockedWebDBer_reopening, true, "f");
+        let opened = false;
+        try {
+            opened = yield* super.reopen(options);
+            return opened;
+        }
+        finally {
+            __classPrivateFieldSet(this, _LockedWebDBer_reopening, false, "f");
+            if (!opened)
+                yield* __classPrivateFieldGet(this, _LockedWebDBer_instances, "m", _LockedWebDBer_letGo).call(this);
+        }
+    }
+    /** Close, then release the lock even when closing fails. `reopen`'s own inner close keeps it. */
+    *close(clear = false) {
+        try {
+            return yield* super.close(clear);
+        }
+        finally {
+            if (!__classPrivateFieldGet(this, _LockedWebDBer_reopening, "f"))
+                yield* __classPrivateFieldGet(this, _LockedWebDBer_instances, "m", _LockedWebDBer_letGo).call(this);
+        }
+    }
+}
+_LockedWebDBer_group = new WeakMap(), _LockedWebDBer_identity = new WeakMap(), _LockedWebDBer_ref = new WeakMap(), _LockedWebDBer_reopening = new WeakMap(), _LockedWebDBer_instances = new WeakSet(), _LockedWebDBer_letGo = function* _LockedWebDBer_letGo() {
+    const ref = __classPrivateFieldGet(this, _LockedWebDBer_ref, "f");
+    __classPrivateFieldSet(this, _LockedWebDBer_ref, undefined, "f");
+    if (ref)
+        yield* call(() => ref.release());
+};
+/** `WebStoreOpener` whose stores share one reference-counted lock per store identity. */
+class LockedStoreOpener extends WebStoreOpener {
+    constructor(persistenceFor, locks) {
+        super(persistenceFor);
+        _LockedStoreOpener_group.set(this, void 0);
+        __classPrivateFieldSet(this, _LockedStoreOpener_group, new StoreLockGroup(locks), "f");
+    }
+    create(family, identity) {
+        return new LockedWebDBer(identity, this.persistenceFor(family, identity), this.queue, __classPrivateFieldGet(this, _LockedStoreOpener_group, "f"));
+    }
+}
+_LockedStoreOpener_group = new WeakMap();
+/**
+ * A `WebStoreOpener` whose stores persist to IndexedDB, one database per store
+ * family and identity. Inject `factory` and `keyRange` together outside a browser.
+ *
+ * Single-writer by default: the first store to open an identity (`base`, `name`, `temp`) takes a
+ * Web Locks lock, shared by every family the opener creates for it and released when the last of
+ * them closes. A second opener, tab or window on that identity is refused with
+ * `StoreLockHeldError`, and an engine without `navigator.locks` with `StoreLockUnsupportedError`;
+ * nothing runs unlocked unless `unsafeSkipStoreLock` says so.
+ */
+export function indexedDbOpener(options = {}) {
+    const persistenceFor = (family, identity) => new IndexedDbPersistence(family, identity, options.factory, options.keyRange);
+    return options.unsafeSkipStoreLock
+        ? new WebStoreOpener(persistenceFor)
+        : new LockedStoreOpener(persistenceFor, options.locks === undefined ? {} : { locks: options.locks });
+}