@interop/was-react 0.19.0 → 0.20.1

package/dist/storage/storageContext.js

@@ -0,0 +1,331 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The session-scoped storage context: everything a session's storage layer
+ * shares across its async consumers, bound to one store registry and owned by
+ * one session auth store. It holds the open {@link LocalStore} replica, the
+ * connected session's {@link WasRemoteStore}, the per-install writer id the
+ * write verbs stamp with, the sync status store, and the debounced re-hydrate
+ * timers -- the values that used to be module globals, so that two providers
+ * in one process no longer clobber each other and a consumer never has to
+ * invent its own "did the holder change under me" guard.
+ *
+ * Staleness is one mechanism, a generation counter: every attach and detach of
+ * the replica bumps it. {@link StorageContext.whileAttached} runs an async
+ * operation against the replica attached at its start and reports the result
+ * only if the same replica is still attached when it settles; the scheduled
+ * re-hydrates and the per-doc change patches are built on it. A consumer that
+ * outlives its replica therefore ends as a silent no-op rather than as an
+ * unhandled rejection or -- worse -- a write into the NEXT session's replica.
+ */
+import { uuidv7 } from 'uuidv7';
+import { activateStorageContext, deactivateStorageContext } from './storageManager.js';
+import { createSyncStatusStore } from './syncStatusStore.js';
+/**
+ * The debounce window coalescing a pull burst into one re-hydrate.
+ */
+const REHYDRATE_DEBOUNCE_MS = 50;
+export class StorageContext {
+    /**
+     * The app's per-collection hydrate/patch handlers; the change patches and the
+     * scheduled re-hydrates route on it.
+     */
+    registry;
+    /**
+     * This session's per-collection replication statuses.
+     */
+    syncStatus = createSyncStatusStore();
+    #writerId;
+    #localStore = null;
+    #remoteStore = null;
+    #generation = 0;
+    /**
+     * Per-collection debounce timers coalescing a pull burst into one hydrate.
+     */
+    #rehydrateTimers = new Map();
+    /**
+     * @param options {object}
+     * @param options.registry {StoreRegistry}
+     * @param options.writerId {string}   the resolved per-install writer id (see
+     *   `getWriterId`), the value every stamp of this session carries
+     */
+    constructor({ registry, writerId }) {
+        this.registry = registry;
+        this.#writerId = writerId;
+    }
+    /**
+     * The writer id this session stamps with: an unkeyed, clearable attribution
+     * label, never an identity.
+     *
+     * @returns {string}
+     */
+    get writerId() {
+        return this.#writerId;
+    }
+    /**
+     * Replaces the in-memory writer id with a fresh one (the clear-data wipe,
+     * after `clearPersistedWriterId` removed the persisted one). The session
+     * keeps running over its new anonymous replica and its write verbs still
+     * have to stamp; nothing persists the new id, so the next run resolves and
+     * stores an id of its own.
+     *
+     * @returns {string}   the new id
+     */
+    resetWriterId() {
+        this.#writerId = uuidv7();
+        return this.#writerId;
+    }
+    /**
+     * Stamps a payload with fresh last-write-wins fields: the current instant as
+     * `updatedAt` and this session's writer id. Any values the caller supplied
+     * are overwritten -- a stamp must describe THIS write, or a hydrated doc's
+     * older `updatedAt` would ride a later edit and lose the conflict.
+     *
+     * @param payload {object}
+     * @returns {object}   the payload with the LWW fields set
+     */
+    stampLww(payload) {
+        return {
+            ...payload,
+            updatedAt: new Date().toISOString(),
+            writerId: this.#writerId
+        };
+    }
+    /**
+     * Installs the opened replica and makes this the process's active context
+     * (the one the app-facing facades and the entity-store verbs resolve to).
+     * Throws if ANOTHER context still has a replica attached: two live sessions
+     * in one process would write into each other's entity stores.
+     *
+     * @param store {LocalStore}
+     * @returns {void}
+     */
+    attachStore(store) {
+        activateStorageContext(this);
+        this.#localStore = store;
+        this.#generation += 1;
+    }
+    /**
+     * Releases the replica (the caller closes or deletes it), cancels every
+     * pending re-hydrate, and releases the process-wide active pointer when this
+     * context holds it -- the mirror of {@link attachStore}'s claim. Anything
+     * still in flight against the old replica sees the generation change and
+     * ends as a no-op; the facades throw until the next attach claims a live
+     * context, rather than resolving a retired one.
+     *
+     * @returns {LocalStore | null}   the replica that was attached, if any
+     */
+    detachStore() {
+        for (const timer of this.#rehydrateTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.#rehydrateTimers.clear();
+        const store = this.#localStore;
+        this.#localStore = null;
+        this.#generation += 1;
+        deactivateStorageContext(this);
+        return store;
+    }
+    /**
+     * Whether a replica is attached.
+     *
+     * @returns {boolean}
+     */
+    hasStore() {
+        return this.#localStore !== null;
+    }
+    /**
+     * The attached replica, or throws if none is open.
+     *
+     * @returns {LocalStore}
+     */
+    requireStore() {
+        if (!this.#localStore) {
+            throw new Error('LocalStore is not initialized; open it first.');
+        }
+        return this.#localStore;
+    }
+    /**
+     * Runs `op` against the replica attached now and resolves with its result
+     * only if that same replica is still attached when `op` settles. Resolves
+     * `undefined` when no replica is attached, or when it was detached or
+     * swapped meanwhile -- including when `op` rejected after the swap, since a
+     * read torn by its own teardown is expected noise, not an error. A rejection
+     * against a replica that is still attached propagates.
+     *
+     * @param op {(store: LocalStore) => Promise<T>}
+     * @returns {Promise<T | undefined>}
+     */
+    async whileAttached(op) {
+        const store = this.#localStore;
+        if (!store) {
+            return undefined;
+        }
+        const generation = this.#generation;
+        let result;
+        try {
+            result = await op(store);
+        }
+        catch (err) {
+            if (this.#generation !== generation) {
+                return undefined;
+            }
+            throw err;
+        }
+        return this.#generation === generation ? result : undefined;
+    }
+    /**
+     * Installs the connected session's delegated remote store (once background
+     * sync has bootstrapped it from the granted zcaps).
+     *
+     * @param store {WasRemoteStore}
+     * @returns {void}
+     */
+    attachRemoteStore(store) {
+        this.#remoteStore = store;
+    }
+    /**
+     * Releases the remote store (logout / sync teardown).
+     *
+     * @returns {void}
+     */
+    detachRemoteStore() {
+        this.#remoteStore = null;
+    }
+    /**
+     * Whether a connected session's remote store is available.
+     *
+     * @returns {boolean}
+     */
+    hasRemoteStore() {
+        return this.#remoteStore !== null;
+    }
+    /**
+     * The connected session's remote store, or throws while no wallet-connected
+     * session is active (local-only mode, or sync has not bootstrapped yet).
+     *
+     * @returns {WasRemoteStore}
+     */
+    requireRemoteStore() {
+        if (!this.#remoteStore) {
+            throw new Error('No WAS remote store is available; connect a wallet session first.');
+        }
+        return this.#remoteStore;
+    }
+    /**
+     * Hydrates every registered store from the attached replica.
+     *
+     * @returns {Promise<void>}
+     */
+    async hydrateAll() {
+        await Promise.all(Object.values(this.registry).map(entry => entry.hydrate()));
+    }
+    /**
+     * Empties every registered store (logout).
+     *
+     * @returns {void}
+     */
+    clearEntityStores() {
+        for (const entry of Object.values(this.registry)) {
+            entry.clear();
+        }
+    }
+    /**
+     * Patches ONE store from a single RxDB change event (per-doc, no
+     * whole-collection re-hydrate): decrypt the changed envelope, then upsert the
+     * payload (INSERT / UPDATE, including conflict-resolved rows) or drop it
+     * (DELETE / tombstone). The `uuid -> envelopeId` index is kept in step so a
+     * later local edit of a remotely-created doc still finds its envelope. Falls
+     * back to a debounced whole-collection re-hydrate if the envelope is missing
+     * or fails to decrypt.
+     *
+     * Fired floating off the RxDB change stream, so a logout/login teardown can
+     * detach or swap the replica while the decrypt is in flight; the decrypt runs
+     * under {@link StorageContext.whileAttached}, so an event that outlives its
+     * replica is dropped rather than patched into the next session's stores.
+     *
+     * @param collectionKey {string}
+     * @param event {object}   an RxDB change event (operation + documentData)
+     * @returns {Promise<void>}
+     */
+    async patchFromChange(collectionKey, event) {
+        const entry = this.registry[collectionKey];
+        if (!entry) {
+            return;
+        }
+        const row = event.documentData;
+        const envelope = row?.data;
+        const deleted = event.operation === 'DELETE' || row?._deleted === true;
+        if (!row || envelope === undefined) {
+            this.scheduleRehydrate(collectionKey);
+            return;
+        }
+        // `null` marks a decrypt failure against a still-attached replica (fall
+        // back to a re-hydrate); `undefined` marks a replica gone meanwhile (drop).
+        const decrypted = await this.whileAttached(async (store) => {
+            try {
+                return {
+                    store,
+                    payload: await store.decryptEnvelope(collectionKey, envelope)
+                };
+            }
+            catch {
+                return null;
+            }
+        });
+        if (decrypted === undefined) {
+            return;
+        }
+        if (decrypted === null) {
+            this.scheduleRehydrate(collectionKey);
+            return;
+        }
+        const { store, payload } = decrypted;
+        if (deleted) {
+            // Only honor a tombstone for the envelope the entity currently lives in.
+            // A delete of a DIFFERENT envelope that decrypts to the same logical id
+            // is a stale duplicate being cleaned up (a reconciled singleton loser,
+            // or the pre-resurrection row of a locally re-created doc) -- dropping
+            // the live doc for it would undo the reconciliation/resurrection.
+            const mapped = store.envelopeIdFor(collectionKey, payload.id);
+            if (mapped !== undefined && mapped !== row.id) {
+                return;
+            }
+            store.forgetEnvelope(collectionKey, payload.id);
+            entry.drop(payload.id);
+        }
+        else {
+            store.rememberEnvelope(collectionKey, payload.id, row.id);
+            entry.upsert(payload);
+        }
+    }
+    /**
+     * Schedules a debounced re-hydrate of one collection's store after a pull.
+     * A no-op without an attached replica, and the timer itself is bound to the
+     * replica attached now: a detach cancels it, and one that still fires after
+     * a swap finds the generation changed and does nothing.
+     *
+     * @param collectionKey {string}
+     * @returns {void}
+     */
+    scheduleRehydrate(collectionKey) {
+        const entry = this.registry[collectionKey];
+        if (!entry || !this.#localStore) {
+            return;
+        }
+        const generation = this.#generation;
+        const existing = this.#rehydrateTimers.get(collectionKey);
+        if (existing) {
+            clearTimeout(existing);
+        }
+        this.#rehydrateTimers.set(collectionKey, setTimeout(() => {
+            this.#rehydrateTimers.delete(collectionKey);
+            if (this.#generation !== generation) {
+                return;
+            }
+            void entry.hydrate();
+        }, REHYDRATE_DEBOUNCE_MS));
+    }
+}
+//# sourceMappingURL=storageContext.js.map

package/dist/storage/storageContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageContext.js","sourceRoot":"","sources":["../../src/storage/storageContext.ts"],"names":[],"mappings":"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"}

package/dist/storage/storageManager.d.ts

@@ -1,115 +1,100 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The storage manager: the one remaining process-wide pointer, to the ACTIVE
+ * {@link StorageContext}, plus the app-facing facades over it. Entity stores
+ * are created at module level, before any session exists, so their verbs
+ * cannot hold a context of their own; they reach the live session through
+ * {@link requireStore} / {@link requireRemoteStore} / {@link stampLww} here,
+ * which resolve to whichever context is active. Keeping the facade free of
+ * store imports (no cycle) also lets the session store own the init/hydrate
+ * ordering.
+ *
+ * Activation is deliberate about the two-providers case: a context with a
+ * replica attached is live, and a live context is never replaced -- a second
+ * session attaching a replica of its own throws instead of silently taking the
+ * facades over. A context without a replica (created but not booted, or torn
+ * down) is inert and is replaced without complaint, which is what a React
+ * dev-mode double `useState` initializer or a test's sequence of stores needs.
+ */
 import type { LwwFields } from '../sync/lww.js';
 import type { LocalStore } from './localStore.js';
+import type { StorageContext } from './storageContext.js';
 import type { WasRemoteStore } from './wasRemoteStore.js';
 /**
- * Installs the opened store (called once by the app bootstrap).
+ * Makes `context` the active one (called by the session store at creation, so
+ * the facades resolve before any replica opens, again right before it opens a
+ * replica, and by {@link StorageContext.attachStore}). Idempotent for the
+ * context already active; throws while a DIFFERENT context still has a replica
+ * attached.
  *
- * @param store {LocalStore}
+ * @param context {StorageContext}
  * @returns {void}
  */
-export declare function setLocalStore(store: LocalStore): void;
+export declare function activateStorageContext(context: StorageContext): void;
 /**
- * The opened store, or throws if the app has not bootstrapped yet.
+ * Releases the active pointer if `context` holds it (called by
+ * `StorageContext.detachStore`, so every path that detaches a replica --
+ * `destroy`, logout, clear-data, the connected activation's fallback to
+ * `local` -- releases it and re-claims on re-attach); a no-op for any other
+ * context. Until the next claim the facades throw rather than resolve a
+ * retired session.
  *
- * @returns {LocalStore}
+ * @param context {StorageContext}
+ * @returns {void}
  */
-export declare function requireStore(): LocalStore;
+export declare function deactivateStorageContext(context: StorageContext): void;
 /**
- * Whether the store has been opened.
+ * Whether a storage context is active.
  *
  * @returns {boolean}
  */
-export declare function hasStore(): boolean;
+export declare function hasStorageContext(): boolean;
 /**
- * Releases the held store reference (logout; the caller closes the db).
+ * The active storage context, or throws if no session store has been created.
  *
- * @returns {void}
+ * @returns {StorageContext}
  */
-export declare function clearLocalStore(): void;
+export declare function requireStorageContext(): StorageContext;
 /**
- * Installs the per-session delegated remote store (set once background sync
- * has bootstrapped it from the granted zcaps).
+ * The active session's opened replica, or throws if none is open.
  *
- * @param store {WasRemoteStore}
- * @returns {void}
- */
-export declare function setRemoteStore(store: WasRemoteStore): void;
-/**
- * The connected session's remote store, or throws while no wallet-connected
- * session is active (local-only mode, or sync has not bootstrapped yet).
- *
- * @returns {WasRemoteStore}
+ * @returns {LocalStore}
  */
-export declare function requireRemoteStore(): WasRemoteStore;
+export declare function requireStore(): LocalStore;
 /**
- * Whether a connected session's remote store is available.
+ * Whether the active session has a replica open.
  *
  * @returns {boolean}
  */
-export declare function hasRemoteStore(): boolean;
-/**
- * Releases the held remote store reference (logout / sync teardown).
- *
- * @returns {void}
- */
-export declare function clearRemoteStore(): void;
+export declare function hasStore(): boolean;
 /**
- * A stable per-install writer id (the last-write-wins tiebreak stamped into
- * every payload), persisted in localStorage under `<prefix>writerId`. In an
- * environment without `localStorage` it falls back to a process-stable
- * unpersisted id instead of throwing.
- *
- * The id is an unkeyed, clearable attribution label -- never an identity. On a
- * miss it adopts a value left under the pre-rename `<prefix>clientId` key and
- * removes the old one, so an existing install keeps stamping the same id
- * across the rename rather than looking like a second writer.
+ * The active session's remote store, or throws while no wallet-connected
+ * session is active.
  *
- * @param [options] {object}
- * @param [options.storageKeyPrefix] {string}   the localStorage key prefix
- *   (defaults to {@link DEFAULT_STORAGE_KEY_PREFIX})
- * @returns {string}
+ * @returns {WasRemoteStore}
  */
-export declare function getWriterId({ storageKeyPrefix }?: {
-    storageKeyPrefix?: string;
-}): string;
+export declare function requireRemoteStore(): WasRemoteStore;
 /**
- * Installs the session's resolved writer id (called once by the session store,
- * under the app's configured `storageKeyPrefix`, before any replica opens).
+ * Whether the active session has a remote store available.
  *
- * @param id {string}
- * @returns {void}
+ * @returns {boolean}
  */
-export declare function setWriterId(id: string): void;
+export declare function hasRemoteStore(): boolean;
 /**
- * The session's resolved writer id, or throws if it has not been installed
- * yet. Deliberately never falls back to {@link getWriterId}: that would resolve
- * under the DEFAULT key prefix, so an app with a custom `storageKeyPrefix`
- * would silently stamp a second writer id.
+ * The active session's writer id, or throws if no session store exists yet.
+ * Deliberately never falls back to `getWriterId`: that would resolve under the
+ * DEFAULT key prefix, so an app with a custom `storageKeyPrefix` would silently
+ * stamp a second writer id.
  *
  * @returns {string}
  */
 export declare function requireWriterId(): string;
 /**
- * Clears the persisted writer id (the clear-data grade of the wipe): removes
- * both the current key and the pre-rename one, so nothing this library wrote
- * survives in localStorage. A fresh id is installed in memory rather than the
- * resolved one being dropped, because the session keeps running over its new
- * anonymous replica and its write verbs still have to stamp; nothing persists
- * it, so the next run resolves and stores an id of its own.
- *
- * @param [options] {object}
- * @param [options.storageKeyPrefix] {string}   the localStorage key prefix
- *   (defaults to {@link DEFAULT_STORAGE_KEY_PREFIX})
- * @returns {void}
- */
-export declare function clearWriterId({ storageKeyPrefix }?: {
-    storageKeyPrefix?: string;
-}): void;
-/**
- * Stamps a payload with fresh last-write-wins fields: the current instant as
- * `updatedAt` and the session's resolved writer id. Any values the caller
- * supplied are overwritten -- a stamp must describe THIS write, or a hydrated
- * doc's older `updatedAt` would ride a later edit and lose the conflict.
+ * Stamps a payload with fresh last-write-wins fields under the active session
+ * (see {@link StorageContext.stampLww}); the entity-store write verbs call it
+ * on every write, and an app writing through `LocalStore` directly does too.
  *
  * @param payload {object}
  * @returns {object}   the payload with the LWW fields set

package/dist/storage/storageManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storageManager.d.ts","sourceRoot":"","sources":["../../src/storage/storageManager.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAKzD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAErD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,UAAU,CAKzC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,cAAc,CAOnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AASD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,EAC1B,gBAA6C,EAC9C,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAe7C;AAID;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAOxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,EAC5B,gBAA6C,EAC9C,GAAE;IAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAS3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAM5E"}
+{"version":3,"file":"storageManager.d.ts","sourceRoot":"","sources":["../../src/storage/storageManager.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAIzD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAQpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAItE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,cAAc,CAOtD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,UAAU,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,cAAc,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAE5E"}