zapo-js 1.6.1 → 1.6.2

package/dist/esm/store/createStore.js

@@ -34,6 +34,7 @@ import { WaSignalMemoryStore } from './memory/signal.store.js';
 import { WaThreadMemoryStore } from './memory/thread.store.js';
 import { NOOP_CONTACT_STORE, NOOP_DEVICE_LIST_STORE, NOOP_GROUP_METADATA_STORE, NOOP_MESSAGE_SECRET_STORE, NOOP_MESSAGE_STORE, NOOP_RETRY_STORE, NOOP_THREAD_STORE } from './noop.store.js';
 import { resolvePositive } from '../util/coercion.js';
+import { toError } from '../util/primitives.js';
 const DEFAULT_CACHE_TTLS_MS = Object.freeze({
     retryMs: 60 * 1000,
     groupMetadataMs: 5 * 60 * 1000,
@@ -109,6 +110,7 @@ export function createStore(options) {
         messageSecret: resolvePositive(options.memory?.cacheTtlMs?.messageSecretMs, DEFAULT_CACHE_TTLS_MS.messageSecretMs, 'memory.cacheTtlMs.messageSecretMs')
     });
     const sessions = new Map();
+    const pendingSessionDestroys = new Set();
     let storeDestroyed = false;
     return {
         session(sessionId) {
@@ -148,37 +150,48 @@ export function createStore(options) {
                 ? new WaContactMemoryStore({ maxContacts: ml.contacts })
                 : NOOP_CONTACT_STORE);
             const rawPrivacyToken = resolveStore(id, backends, providers.privacyToken ?? 'memory', 'privacyToken', 'stores', () => new WaPrivacyTokenMemoryStore(ml.privacyTokens));
-            const rawRetry = resolveStore(id, backends, cacheProviders.retry ?? 'memory', 'retry', 'caches', () => cacheProviders.retry === 'memory' || !cacheProviders.retry
-                ? new WaRetryMemoryStore(cacheTtlsMs.retry, {
-                    maxOutboundMessages: ml.retryOutboundMessages,
-                    maxInboundCounters: ml.retryInboundCounters,
-                    logger: memoryLogger?.child({ domain: 'retry', sessionId: id })
-                })
-                : NOOP_RETRY_STORE);
-            const rawGroupMetadata = resolveStore(id, backends, cacheProviders.groupMetadata ?? 'memory', 'groupMetadata', 'caches', () => cacheProviders.groupMetadata === 'memory' || !cacheProviders.groupMetadata
-                ? new WaGroupMetadataMemoryStore(cacheTtlsMs.groupMetadata, {
-                    maxGroups: ml.groupMetadataGroups,
-                    logger: memoryLogger?.child({
-                        domain: 'groupMetadata',
-                        sessionId: id
+            const buildCaches = () => ({
+                retry: withRetryLock(resolveStore(id, backends, cacheProviders.retry ?? 'memory', 'retry', 'caches', () => cacheProviders.retry === 'memory' || !cacheProviders.retry
+                    ? new WaRetryMemoryStore(cacheTtlsMs.retry, {
+                        maxOutboundMessages: ml.retryOutboundMessages,
+                        maxInboundCounters: ml.retryInboundCounters,
+                        logger: memoryLogger?.child({
+                            domain: 'retry',
+                            sessionId: id
+                        })
                     })
-                })
-                : NOOP_GROUP_METADATA_STORE);
-            const rawDeviceList = resolveStore(id, backends, cacheProviders.deviceList ?? 'memory', 'deviceList', 'caches', () => cacheProviders.deviceList === 'memory'
-                ? new WaDeviceListMemoryStore(cacheTtlsMs.deviceList, {
-                    maxUsers: ml.deviceListUsers,
-                    logger: memoryLogger?.child({ domain: 'deviceList', sessionId: id })
-                })
-                : NOOP_DEVICE_LIST_STORE);
-            const rawMessageSecret = resolveStore(id, backends, cacheProviders.messageSecret ?? 'memory', 'messageSecret', 'caches', () => cacheProviders.messageSecret === 'memory' || !cacheProviders.messageSecret
-                ? new WaMessageSecretMemoryStore(cacheTtlsMs.messageSecret, {
-                    maxSecrets: ml.messageSecrets,
-                    logger: memoryLogger?.child({
-                        domain: 'messageSecret',
-                        sessionId: id
+                    : NOOP_RETRY_STORE)),
+                groupMetadata: withGroupMetadataLock(resolveStore(id, backends, cacheProviders.groupMetadata ?? 'memory', 'groupMetadata', 'caches', () => cacheProviders.groupMetadata === 'memory' ||
+                    !cacheProviders.groupMetadata
+                    ? new WaGroupMetadataMemoryStore(cacheTtlsMs.groupMetadata, {
+                        maxGroups: ml.groupMetadataGroups,
+                        logger: memoryLogger?.child({
+                            domain: 'groupMetadata',
+                            sessionId: id
+                        })
                     })
-                })
-                : NOOP_MESSAGE_SECRET_STORE);
+                    : NOOP_GROUP_METADATA_STORE)),
+                deviceList: withDeviceListLock(resolveStore(id, backends, cacheProviders.deviceList ?? 'memory', 'deviceList', 'caches', () => cacheProviders.deviceList === 'memory' || !cacheProviders.deviceList
+                    ? new WaDeviceListMemoryStore(cacheTtlsMs.deviceList, {
+                        maxUsers: ml.deviceListUsers,
+                        logger: memoryLogger?.child({
+                            domain: 'deviceList',
+                            sessionId: id
+                        })
+                    })
+                    : NOOP_DEVICE_LIST_STORE)),
+                messageSecret: withMessageSecretLock(resolveStore(id, backends, cacheProviders.messageSecret ?? 'memory', 'messageSecret', 'caches', () => cacheProviders.messageSecret === 'memory' ||
+                    !cacheProviders.messageSecret
+                    ? new WaMessageSecretMemoryStore(cacheTtlsMs.messageSecret, {
+                        maxSecrets: ml.messageSecrets,
+                        logger: memoryLogger?.child({
+                            domain: 'messageSecret',
+                            sessionId: id
+                        })
+                    })
+                    : NOOP_MESSAGE_SECRET_STORE))
+            });
+            let caches = buildCaches();
             const authStore = withAuthLock(rawAuth);
             const signalStore = withSignalLock(rawSignal);
             const preKeyStore = withPreKeyLock(rawPreKey);
@@ -192,41 +205,72 @@ export function createStore(options) {
                 ? withSenderKeyCache(rawSenderKey, cacheLayer.limits?.senderKey)
                 : rawSenderKey);
             const appStateStore = withAppStateLock(rawAppState);
-            const retryStore = withRetryLock(rawRetry);
-            const groupMetadataStore = withGroupMetadataLock(rawGroupMetadata);
-            const deviceListStore = withDeviceListLock(rawDeviceList);
             const messageStore = withMessageLock(rawMessages);
-            const messageSecretStore = withMessageSecretLock(rawMessageSecret);
             const threadStore = withThreadLock(rawThreads);
             const contactStore = withContactLock(rawContacts);
             const privacyTokenStore = withPrivacyTokenLock(cacheLayer.privacyToken && usesBackend(providers.privacyToken)
                 ? withPrivacyTokenCache(rawPrivacyToken, cacheLayer.limits?.privacyToken)
                 : rawPrivacyToken);
-            let cachesDestroyed = false;
             let sessionDestroyed = false;
-            const destroyCaches = async () => {
-                if (cachesDestroyed)
-                    return;
-                cachesDestroyed = true;
-                await Promise.all([
-                    retryStore.clear(),
-                    groupMetadataStore.clear(),
-                    deviceListStore.clear(),
-                    messageSecretStore.clear()
+            let destroyPromise = null;
+            let cacheLifecycle = Promise.resolve();
+            const teardownCaches = async (target) => {
+                const cleared = await Promise.allSettled([
+                    target.retry.clear(),
+                    target.groupMetadata.clear(),
+                    target.deviceList.clear(),
+                    target.messageSecret.clear()
                 ]);
-                await Promise.all([
-                    destroyIfSupported(retryStore),
-                    destroyIfSupported(groupMetadataStore),
-                    destroyIfSupported(deviceListStore),
-                    destroyIfSupported(messageSecretStore)
+                const destroyed = await Promise.allSettled([
+                    destroyIfSupported(target.retry),
+                    destroyIfSupported(target.groupMetadata),
+                    destroyIfSupported(target.deviceList),
+                    destroyIfSupported(target.messageSecret)
                 ]);
+                const failures = [...cleared, ...destroyed].filter((result) => result.status === 'rejected');
+                if (failures.length > 0) {
+                    storeLogger?.warn('cache teardown had failures', {
+                        sessionId: id,
+                        droppedCount: failures.length,
+                        totalExpected: cleared.length + destroyed.length,
+                        sample: toError(failures[0].reason).message
+                    });
+                }
+                return failures.length;
+            };
+            const destroyCaches = () => {
+                const run = cacheLifecycle.then(async () => {
+                    if (sessionDestroyed)
+                        return;
+                    const failureCount = await teardownCaches(caches);
+                    caches = buildCaches();
+                    if (failureCount > 0) {
+                        throw new Error(`cache reset finished with ${failureCount} teardown failure(s); ` +
+                            'fresh caches are in place but old persistent entries may remain');
+                    }
+                });
+                cacheLifecycle = run.then(() => undefined, () => undefined);
+                return run;
             };
-            const destroy = async () => {
-                if (sessionDestroyed)
-                    return;
+            const destroy = () => {
+                if (!destroyPromise) {
+                    const pending = destroyInternal().finally(() => pendingSessionDestroys.delete(pending));
+                    destroyPromise = pending;
+                    pendingSessionDestroys.add(pending);
+                }
+                return destroyPromise;
+            };
+            const destroyInternal = async () => {
                 sessionDestroyed = true;
-                await destroyCaches();
-                await Promise.all([
+                if (sessions.get(id) === storeSession) {
+                    sessions.delete(id);
+                }
+                await cacheLifecycle;
+                await teardownCaches(caches);
+                await destroyPersistentStores();
+            };
+            const destroyPersistentStores = async () => {
+                const results = await Promise.allSettled([
                     destroyIfSupported(authStore),
                     destroyIfSupported(signalStore),
                     destroyIfSupported(preKeyStore),
@@ -239,6 +283,15 @@ export function createStore(options) {
                     destroyIfSupported(contactStore),
                     destroyIfSupported(privacyTokenStore)
                 ]);
+                const failures = results.filter((result) => result.status === 'rejected');
+                if (failures.length > 0) {
+                    storeLogger?.warn('persistent store teardown had failures', {
+                        sessionId: id,
+                        droppedCount: failures.length,
+                        totalExpected: results.length,
+                        sample: toError(failures[0].reason).message
+                    });
+                }
             };
             const storeSession = {
                 auth: authStore,
@@ -248,11 +301,19 @@ export function createStore(options) {
                 identity: identityStore,
                 senderKey: senderKeyStore,
                 appState: appStateStore,
-                retry: retryStore,
-                groupMetadata: groupMetadataStore,
-                deviceList: deviceListStore,
+                get retry() {
+                    return caches.retry;
+                },
+                get groupMetadata() {
+                    return caches.groupMetadata;
+                },
+                get deviceList() {
+                    return caches.deviceList;
+                },
                 messages: messageStore,
-                messageSecret: messageSecretStore,
+                get messageSecret() {
+                    return caches.messageSecret;
+                },
                 threads: threadStore,
                 contacts: contactStore,
                 privacyToken: privacyTokenStore,
@@ -273,6 +334,7 @@ export function createStore(options) {
             const list = Array.from(sessions.values());
             sessions.clear();
             await Promise.all(list.map((s) => s.destroy()));
+            await Promise.all(Array.from(pendingSessionDestroys));
             const uniqueBackends = new Set(Object.values(backends));
             await Promise.all(Array.from(uniqueBackends, (backend) => destroyIfSupported(backend)));
         }

package/dist/store/createStore.js

@@ -37,6 +37,7 @@ const signal_store_1 = require("./memory/signal.store");
 const thread_store_1 = require("./memory/thread.store");
 const noop_store_1 = require("./noop.store");
 const coercion_1 = require("../util/coercion");
+const primitives_1 = require("../util/primitives");
 const DEFAULT_CACHE_TTLS_MS = Object.freeze({
     retryMs: 60 * 1000,
     groupMetadataMs: 5 * 60 * 1000,
@@ -112,6 +113,7 @@ function createStore(options) {
         messageSecret: (0, coercion_1.resolvePositive)(options.memory?.cacheTtlMs?.messageSecretMs, DEFAULT_CACHE_TTLS_MS.messageSecretMs, 'memory.cacheTtlMs.messageSecretMs')
     });
     const sessions = new Map();
+    const pendingSessionDestroys = new Set();
     let storeDestroyed = false;
     return {
         session(sessionId) {
@@ -151,37 +153,48 @@ function createStore(options) {
                 ? new contact_store_1.WaContactMemoryStore({ maxContacts: ml.contacts })
                 : noop_store_1.NOOP_CONTACT_STORE);
             const rawPrivacyToken = resolveStore(id, backends, providers.privacyToken ?? 'memory', 'privacyToken', 'stores', () => new privacy_token_store_1.WaPrivacyTokenMemoryStore(ml.privacyTokens));
-            const rawRetry = resolveStore(id, backends, cacheProviders.retry ?? 'memory', 'retry', 'caches', () => cacheProviders.retry === 'memory' || !cacheProviders.retry
-                ? new retry_store_1.WaRetryMemoryStore(cacheTtlsMs.retry, {
-                    maxOutboundMessages: ml.retryOutboundMessages,
-                    maxInboundCounters: ml.retryInboundCounters,
-                    logger: memoryLogger?.child({ domain: 'retry', sessionId: id })
-                })
-                : noop_store_1.NOOP_RETRY_STORE);
-            const rawGroupMetadata = resolveStore(id, backends, cacheProviders.groupMetadata ?? 'memory', 'groupMetadata', 'caches', () => cacheProviders.groupMetadata === 'memory' || !cacheProviders.groupMetadata
-                ? new group_metadata_store_1.WaGroupMetadataMemoryStore(cacheTtlsMs.groupMetadata, {
-                    maxGroups: ml.groupMetadataGroups,
-                    logger: memoryLogger?.child({
-                        domain: 'groupMetadata',
-                        sessionId: id
+            const buildCaches = () => ({
+                retry: (0, retry_lock_1.withRetryLock)(resolveStore(id, backends, cacheProviders.retry ?? 'memory', 'retry', 'caches', () => cacheProviders.retry === 'memory' || !cacheProviders.retry
+                    ? new retry_store_1.WaRetryMemoryStore(cacheTtlsMs.retry, {
+                        maxOutboundMessages: ml.retryOutboundMessages,
+                        maxInboundCounters: ml.retryInboundCounters,
+                        logger: memoryLogger?.child({
+                            domain: 'retry',
+                            sessionId: id
+                        })
                     })
-                })
-                : noop_store_1.NOOP_GROUP_METADATA_STORE);
-            const rawDeviceList = resolveStore(id, backends, cacheProviders.deviceList ?? 'memory', 'deviceList', 'caches', () => cacheProviders.deviceList === 'memory'
-                ? new device_list_store_1.WaDeviceListMemoryStore(cacheTtlsMs.deviceList, {
-                    maxUsers: ml.deviceListUsers,
-                    logger: memoryLogger?.child({ domain: 'deviceList', sessionId: id })
-                })
-                : noop_store_1.NOOP_DEVICE_LIST_STORE);
-            const rawMessageSecret = resolveStore(id, backends, cacheProviders.messageSecret ?? 'memory', 'messageSecret', 'caches', () => cacheProviders.messageSecret === 'memory' || !cacheProviders.messageSecret
-                ? new message_secret_store_1.WaMessageSecretMemoryStore(cacheTtlsMs.messageSecret, {
-                    maxSecrets: ml.messageSecrets,
-                    logger: memoryLogger?.child({
-                        domain: 'messageSecret',
-                        sessionId: id
+                    : noop_store_1.NOOP_RETRY_STORE)),
+                groupMetadata: (0, group_metadata_lock_1.withGroupMetadataLock)(resolveStore(id, backends, cacheProviders.groupMetadata ?? 'memory', 'groupMetadata', 'caches', () => cacheProviders.groupMetadata === 'memory' ||
+                    !cacheProviders.groupMetadata
+                    ? new group_metadata_store_1.WaGroupMetadataMemoryStore(cacheTtlsMs.groupMetadata, {
+                        maxGroups: ml.groupMetadataGroups,
+                        logger: memoryLogger?.child({
+                            domain: 'groupMetadata',
+                            sessionId: id
+                        })
                     })
-                })
-                : noop_store_1.NOOP_MESSAGE_SECRET_STORE);
+                    : noop_store_1.NOOP_GROUP_METADATA_STORE)),
+                deviceList: (0, device_list_lock_1.withDeviceListLock)(resolveStore(id, backends, cacheProviders.deviceList ?? 'memory', 'deviceList', 'caches', () => cacheProviders.deviceList === 'memory' || !cacheProviders.deviceList
+                    ? new device_list_store_1.WaDeviceListMemoryStore(cacheTtlsMs.deviceList, {
+                        maxUsers: ml.deviceListUsers,
+                        logger: memoryLogger?.child({
+                            domain: 'deviceList',
+                            sessionId: id
+                        })
+                    })
+                    : noop_store_1.NOOP_DEVICE_LIST_STORE)),
+                messageSecret: (0, message_secret_lock_1.withMessageSecretLock)(resolveStore(id, backends, cacheProviders.messageSecret ?? 'memory', 'messageSecret', 'caches', () => cacheProviders.messageSecret === 'memory' ||
+                    !cacheProviders.messageSecret
+                    ? new message_secret_store_1.WaMessageSecretMemoryStore(cacheTtlsMs.messageSecret, {
+                        maxSecrets: ml.messageSecrets,
+                        logger: memoryLogger?.child({
+                            domain: 'messageSecret',
+                            sessionId: id
+                        })
+                    })
+                    : noop_store_1.NOOP_MESSAGE_SECRET_STORE))
+            });
+            let caches = buildCaches();
             const authStore = (0, auth_lock_1.withAuthLock)(rawAuth);
             const signalStore = (0, signal_lock_1.withSignalLock)(rawSignal);
             const preKeyStore = (0, pre_key_lock_1.withPreKeyLock)(rawPreKey);
@@ -195,41 +208,72 @@ function createStore(options) {
                 ? (0, sender_key_cache_1.withSenderKeyCache)(rawSenderKey, cacheLayer.limits?.senderKey)
                 : rawSenderKey);
             const appStateStore = (0, appstate_lock_1.withAppStateLock)(rawAppState);
-            const retryStore = (0, retry_lock_1.withRetryLock)(rawRetry);
-            const groupMetadataStore = (0, group_metadata_lock_1.withGroupMetadataLock)(rawGroupMetadata);
-            const deviceListStore = (0, device_list_lock_1.withDeviceListLock)(rawDeviceList);
             const messageStore = (0, message_lock_1.withMessageLock)(rawMessages);
-            const messageSecretStore = (0, message_secret_lock_1.withMessageSecretLock)(rawMessageSecret);
             const threadStore = (0, thread_lock_1.withThreadLock)(rawThreads);
             const contactStore = (0, contact_lock_1.withContactLock)(rawContacts);
             const privacyTokenStore = (0, privacy_token_lock_1.withPrivacyTokenLock)(cacheLayer.privacyToken && usesBackend(providers.privacyToken)
                 ? (0, privacy_token_cache_1.withPrivacyTokenCache)(rawPrivacyToken, cacheLayer.limits?.privacyToken)
                 : rawPrivacyToken);
-            let cachesDestroyed = false;
             let sessionDestroyed = false;
-            const destroyCaches = async () => {
-                if (cachesDestroyed)
-                    return;
-                cachesDestroyed = true;
-                await Promise.all([
-                    retryStore.clear(),
-                    groupMetadataStore.clear(),
-                    deviceListStore.clear(),
-                    messageSecretStore.clear()
+            let destroyPromise = null;
+            let cacheLifecycle = Promise.resolve();
+            const teardownCaches = async (target) => {
+                const cleared = await Promise.allSettled([
+                    target.retry.clear(),
+                    target.groupMetadata.clear(),
+                    target.deviceList.clear(),
+                    target.messageSecret.clear()
                 ]);
-                await Promise.all([
-                    destroyIfSupported(retryStore),
-                    destroyIfSupported(groupMetadataStore),
-                    destroyIfSupported(deviceListStore),
-                    destroyIfSupported(messageSecretStore)
+                const destroyed = await Promise.allSettled([
+                    destroyIfSupported(target.retry),
+                    destroyIfSupported(target.groupMetadata),
+                    destroyIfSupported(target.deviceList),
+                    destroyIfSupported(target.messageSecret)
                 ]);
+                const failures = [...cleared, ...destroyed].filter((result) => result.status === 'rejected');
+                if (failures.length > 0) {
+                    storeLogger?.warn('cache teardown had failures', {
+                        sessionId: id,
+                        droppedCount: failures.length,
+                        totalExpected: cleared.length + destroyed.length,
+                        sample: (0, primitives_1.toError)(failures[0].reason).message
+                    });
+                }
+                return failures.length;
+            };
+            const destroyCaches = () => {
+                const run = cacheLifecycle.then(async () => {
+                    if (sessionDestroyed)
+                        return;
+                    const failureCount = await teardownCaches(caches);
+                    caches = buildCaches();
+                    if (failureCount > 0) {
+                        throw new Error(`cache reset finished with ${failureCount} teardown failure(s); ` +
+                            'fresh caches are in place but old persistent entries may remain');
+                    }
+                });
+                cacheLifecycle = run.then(() => undefined, () => undefined);
+                return run;
             };
-            const destroy = async () => {
-                if (sessionDestroyed)
-                    return;
+            const destroy = () => {
+                if (!destroyPromise) {
+                    const pending = destroyInternal().finally(() => pendingSessionDestroys.delete(pending));
+                    destroyPromise = pending;
+                    pendingSessionDestroys.add(pending);
+                }
+                return destroyPromise;
+            };
+            const destroyInternal = async () => {
                 sessionDestroyed = true;
-                await destroyCaches();
-                await Promise.all([
+                if (sessions.get(id) === storeSession) {
+                    sessions.delete(id);
+                }
+                await cacheLifecycle;
+                await teardownCaches(caches);
+                await destroyPersistentStores();
+            };
+            const destroyPersistentStores = async () => {
+                const results = await Promise.allSettled([
                     destroyIfSupported(authStore),
                     destroyIfSupported(signalStore),
                     destroyIfSupported(preKeyStore),
@@ -242,6 +286,15 @@ function createStore(options) {
                     destroyIfSupported(contactStore),
                     destroyIfSupported(privacyTokenStore)
                 ]);
+                const failures = results.filter((result) => result.status === 'rejected');
+                if (failures.length > 0) {
+                    storeLogger?.warn('persistent store teardown had failures', {
+                        sessionId: id,
+                        droppedCount: failures.length,
+                        totalExpected: results.length,
+                        sample: (0, primitives_1.toError)(failures[0].reason).message
+                    });
+                }
             };
             const storeSession = {
                 auth: authStore,
@@ -251,11 +304,19 @@ function createStore(options) {
                 identity: identityStore,
                 senderKey: senderKeyStore,
                 appState: appStateStore,
-                retry: retryStore,
-                groupMetadata: groupMetadataStore,
-                deviceList: deviceListStore,
+                get retry() {
+                    return caches.retry;
+                },
+                get groupMetadata() {
+                    return caches.groupMetadata;
+                },
+                get deviceList() {
+                    return caches.deviceList;
+                },
                 messages: messageStore,
-                messageSecret: messageSecretStore,
+                get messageSecret() {
+                    return caches.messageSecret;
+                },
                 threads: threadStore,
                 contacts: contactStore,
                 privacyToken: privacyTokenStore,
@@ -276,6 +337,7 @@ function createStore(options) {
             const list = Array.from(sessions.values());
             sessions.clear();
             await Promise.all(list.map((s) => s.destroy()));
+            await Promise.all(Array.from(pendingSessionDestroys));
             const uniqueBackends = new Set(Object.values(backends));
             await Promise.all(Array.from(uniqueBackends, (backend) => destroyIfSupported(backend)));
         }

package/dist/store/types.d.ts

@@ -33,12 +33,43 @@ export interface WaStoreSession {
     readonly threads: WaThreadStore;
     readonly contacts: WaContactStore;
     readonly privacyToken: WaPrivacyTokenStore;
+    /**
+     * Tears down the cache domains (retry/groupMetadata/deviceList/
+     * messageSecret) and swaps fresh, empty ones into this bundle. The
+     * session stays usable; the caches rebuild on demand. The swap happens
+     * after the old stores finish tearing down (so a persistent cache
+     * backend is never cleared under the fresh stores), which means cache
+     * operations issued while the reset is in flight may reject. References
+     * to the old cache stores captured before the call (e.g. by a live
+     * client) reject afterwards - recreate the client to pick up the fresh
+     * stores. Rejects when the old generation's teardown had failures - the
+     * fresh caches are still in place, but stale entries may remain in a
+     * persistent cache backend.
+     */
     destroyCaches(): Promise<void>;
+    /**
+     * Final teardown of every domain store in this bundle. The bundle is
+     * single-shot: every operation on it rejects afterwards. The sessionId
+     * is released as soon as destruction starts, so a concurrent
+     * `store.session(id)` builds a fresh bundle instead of returning this
+     * one. Repeat calls return the same in-flight promise. Teardown
+     * failures are logged (warn), never thrown.
+     */
     destroy(): Promise<void>;
 }
 export interface WaStore {
+    /**
+     * Returns the lock-wrapped per-domain store bundle for `sessionId`,
+     * building it on first use and caching it until its `destroy()` (or the
+     * store-wide `destroy()`) releases it.
+     */
     session(sessionId: string): WaStoreSession;
+    /** Runs {@link WaStoreSession.destroyCaches} on every live session. */
     destroyCaches(): Promise<void>;
+    /**
+     * Destroys every live session bundle and the registered backends. The
+     * store is single-shot: `session()` throws afterwards.
+     */
     destroy(): Promise<void>;
 }
 export interface WaStoreBackend {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "zapo-js",
-    "version": "1.6.1",
+    "version": "1.6.2",
     "description": "High-performance WhatsApp Web TypeScript library",
     "license": "MIT",
     "author": "vinikjkkj <contact@vinicius.email> (https://github.com/vinikjkkj)",