holosphere 2.0.0-alpha4 → 2.0.0-alpha5

package/src/storage/nostr-client.js

@@ -7,6 +7,116 @@ import { SimplePool, finalizeEvent, getPublicKey } from 'nostr-tools';
 import { OutboxQueue } from './outbox-queue.js';
 import { SyncService } from './sync-service.js';
 
+// Global pool singleton - reuse connections across NostrClient instances
+let globalPool = null;
+let globalPoolRelays = new Set();
+
+/**
+ * Get or create global SimplePool singleton
+ * This ensures WebSocket connections are reused across all operations
+ */
+function getGlobalPool(config = {}) {
+  if (!globalPool) {
+    globalPool = new SimplePool({
+      enableReconnect: config.enableReconnect !== false,
+      enablePing: config.enablePing !== false,
+    });
+  }
+  return globalPool;
+}
+
+// Global pending queries map for deduplication
+// Key: JSON-stringified filter, Value: { promise, timestamp }
+const pendingQueries = new Map();
+const PENDING_QUERY_TIMEOUT = 5000; // 5 seconds
+
+// Global active subscriptions map for subscription deduplication
+// Key: JSON-stringified filter, Value: { subscription, callbacks: Set, refCount }
+const activeSubscriptions = new Map();
+
+// Throttle background refreshes to avoid flooding the relay
+// Key: path, Value: timestamp of last refresh
+const backgroundRefreshThrottle = new Map();
+const BACKGROUND_REFRESH_INTERVAL = 30000; // Only refresh same path every 30 seconds
+
+// Write debouncing for rapid updates to the same path
+// Key: d-tag path, Value: { event, timer, resolve, reject }
+const pendingWrites = new Map();
+const WRITE_DEBOUNCE_MS = 500; // Debounce writes within 500ms window
+
+// Long-lived subscription manager - keeps ONE subscription per author for real-time updates
+// Key: pubkey, Value: { subscription, lastEventTime, initialized }
+const authorSubscriptions = new Map();
+const AUTHOR_SUB_INIT_TIMEOUT = 5000; // Wait up to 5s for initial data load
+
+/**
+ * Simple LRU Cache implementation
+ * Automatically evicts least recently used entries when max size is reached
+ */
+class LRUCache {
+  constructor(maxSize = 500) {
+    this.maxSize = maxSize;
+    this.cache = new Map();
+  }
+
+  get(key) {
+    if (!this.cache.has(key)) return undefined;
+
+    // Move to end (most recently used)
+    const value = this.cache.get(key);
+    this.cache.delete(key);
+    this.cache.set(key, value);
+    return value;
+  }
+
+  set(key, value) {
+    // If key exists, delete it first to update position
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    this.cache.set(key, value);
+
+    // Evict oldest entries if over capacity
+    while (this.cache.size > this.maxSize) {
+      const oldestKey = this.cache.keys().next().value;
+      this.cache.delete(oldestKey);
+    }
+  }
+
+  has(key) {
+    return this.cache.has(key);
+  }
+
+  delete(key) {
+    return this.cache.delete(key);
+  }
+
+  clear() {
+    this.cache.clear();
+  }
+
+  get size() {
+    return this.cache.size;
+  }
+
+  keys() {
+    return this.cache.keys();
+  }
+
+  values() {
+    return this.cache.values();
+  }
+
+  entries() {
+    return this.cache.entries();
+  }
+
+  forEach(callback) {
+    this.cache.forEach(callback);
+  }
+}
+
 // Lazy-load WebSocket polyfill for Node.js environment
 let webSocketPolyfillPromise = null;
 function ensureWebSocket() {
@@ -57,9 +167,15 @@ export class NostrClient {
     this.config = config;
 
     this._subscriptions = new Map();
-    this._eventCache = new Map(); // In-memory cache for recent events
+    this._eventCache = new LRUCache(config.cacheSize || 500); // LRU cache for recent events
+    this._cacheIndex = new Map(); // Reverse index: kind -> Set of cache keys affected by that kind
     this.persistentStorage = null;
 
+    // Batched persistent writes for better I/O performance
+    this._persistQueue = new Map(); // path -> event
+    this._persistTimer = null;
+    this._persistBatchMs = config.persistBatchMs || 100; // Batch writes within 100ms window
+
     // Initialize pool and storage asynchronously
     this._initReady = this._initialize();
   }
@@ -74,10 +190,11 @@ export class NostrClient {
 
     // Initialize SimplePool with options (only if relays exist)
     if (this.relays.length > 0) {
-      this.pool = new SimplePool({
-        enableReconnect: this.config.enableReconnect !== false,
-        enablePing: this.config.enablePing !== false,
-      });
+      // Use global pool singleton to reuse WebSocket connections
+      this.pool = getGlobalPool(this.config);
+
+      // Track relays used by this client
+      this.relays.forEach(r => globalPoolRelays.add(r));
     } else {
       // Mock pool for testing - returns mock promise that resolves immediately
       this.pool = {
@@ -90,6 +207,90 @@ export class NostrClient {
 
     // Initialize persistent storage
     await this._initPersistentStorage();
+
+    // Start long-lived subscription for real-time cache updates
+    if (this.relays.length > 0) {
+      this._initLongLivedSubscription();
+    }
+  }
+
+  /**
+   * Initialize a long-lived subscription to keep cache fresh
+   * This replaces polling with a single persistent subscription
+   * @private
+   */
+  _initLongLivedSubscription() {
+    const subKey = this.publicKey;
+
+    // Check if subscription already exists for this author
+    if (authorSubscriptions.has(subKey)) {
+      return;
+    }
+
+    const subInfo = {
+      subscription: null,
+      initialized: false,
+      initPromise: null,
+      initResolve: null,
+    };
+
+    // Create promise for initial load completion
+    subInfo.initPromise = new Promise(resolve => {
+      subInfo.initResolve = resolve;
+    });
+
+    authorSubscriptions.set(subKey, subInfo);
+
+    // Subscribe to ALL events for this author (kind 30000)
+    // This single subscription replaces all the polling queries
+    const filter = {
+      kinds: [30000],
+      authors: [this.publicKey],
+    };
+
+    const sub = this.pool.subscribeMany(
+      this.relays,
+      [filter],
+      {
+        onevent: (event) => {
+          // Verify author (relay may not respect filter)
+          if (event.pubkey !== this.publicKey) {
+            return;
+          }
+
+          // Cache the event - this keeps our local cache in sync
+          this._cacheEvent(event);
+        },
+        oneose: () => {
+          // End of stored events - initial load complete
+          if (!subInfo.initialized) {
+            subInfo.initialized = true;
+            subInfo.initResolve();
+          }
+        },
+      }
+    );
+
+    subInfo.subscription = sub;
+
+    // Set timeout for initial load in case EOSE never arrives
+    setTimeout(() => {
+      if (!subInfo.initialized) {
+        subInfo.initialized = true;
+        subInfo.initResolve();
+      }
+    }, AUTHOR_SUB_INIT_TIMEOUT);
+  }
+
+  /**
+   * Wait for long-lived subscription to complete initial load
+   * @private
+   */
+  async _waitForSubscriptionInit() {
+    const subInfo = authorSubscriptions.get(this.publicKey);
+    if (subInfo && subInfo.initPromise) {
+      await subInfo.initPromise;
+    }
   }
 
   /**
@@ -222,9 +423,11 @@ export class NostrClient {
 
   /**
    * Publish event to relays
+   * Supports debouncing for replaceable events (kind 30000-39999) to avoid rapid updates
    * @param {Object} event - Unsigned event object
    * @param {Object} options - Publish options
    * @param {boolean} options.waitForRelays - Wait for relay confirmation (default: false for speed)
+   * @param {boolean} options.debounce - Debounce rapid writes to same d-tag (default: true for replaceable events)
    * @returns {Promise<Object>} Signed event with relay publish results
    */
   async publish(event, options = {}) {
@@ -233,6 +436,66 @@ export class NostrClient {
 
     const waitForRelays = options.waitForRelays || false;
 
+    // For replaceable events, check if we should debounce
+    const isReplaceable = event.kind >= 30000 && event.kind < 40000;
+    const shouldDebounce = isReplaceable && options.debounce !== false && !waitForRelays;
+
+    if (shouldDebounce) {
+      const dTag = event.tags?.find(t => t[0] === 'd');
+      if (dTag && dTag[1]) {
+        return this._debouncedPublish(event, dTag[1], options);
+      }
+    }
+
+    return this._doPublish(event, options);
+  }
+
+  /**
+   * Debounced publish - coalesces rapid writes to the same d-tag
+   * @private
+   */
+  _debouncedPublish(event, dTagPath, options) {
+    return new Promise((resolve, reject) => {
+      const existing = pendingWrites.get(dTagPath);
+
+      if (existing) {
+        // Cancel previous pending write and use the new one
+        clearTimeout(existing.timer);
+        // Resolve the previous promise with the new event (it will be superseded)
+        existing.resolve({
+          event: null,
+          results: [],
+          debounced: true,
+          supersededBy: event,
+        });
+      }
+
+      // Set up debounced write
+      const timer = setTimeout(async () => {
+        pendingWrites.delete(dTagPath);
+        try {
+          const result = await this._doPublish(event, options);
+          resolve(result);
+        } catch (err) {
+          reject(err);
+        }
+      }, WRITE_DEBOUNCE_MS);
+
+      pendingWrites.set(dTagPath, { event, timer, resolve, reject });
+
+      // Cache immediately for local-first reads (even before relay publish)
+      const signedEvent = finalizeEvent(event, this.privateKey);
+      this._cacheEvent(signedEvent);
+    });
+  }
+
+  /**
+   * Internal publish implementation
+   * @private
+   */
+  async _doPublish(event, options = {}) {
+    const waitForRelays = options.waitForRelays || false;
+
     // Sign the event
     const signedEvent = finalizeEvent(event, this.privateKey);
 
@@ -325,10 +588,12 @@ export class NostrClient {
 
   /**
    * Query events from relays
+   * Uses long-lived subscription for cache updates - avoids polling
    * @param {Object} filter - Nostr filter object
    * @param {Object} options - Query options
    * @param {number} options.timeout - Query timeout in ms (default: 30000, set to 0 for no timeout)
    * @param {boolean} options.localFirst - Return local cache immediately, refresh in background (default: true)
+   * @param {boolean} options.forceRelay - Force relay query even if subscription cache is available (default: false)
    * @returns {Promise<Array>} Array of events
    */
   async query(filter, options = {}) {
@@ -337,6 +602,7 @@ export class NostrClient {
 
     const timeout = options.timeout !== undefined ? options.timeout : 30000;
     const localFirst = options.localFirst !== false; // Default to true for speed
+    const forceRelay = options.forceRelay === true;
 
     // If no relays, query from cache only
     if (this.relays.length === 0) {
@@ -344,6 +610,35 @@ export class NostrClient {
       return matchingEvents;
     }
 
+    // Check if this query can be served from the long-lived subscription cache
+    // The subscription keeps ALL events for this author in cache, updated in real-time
+    const subInfo = authorSubscriptions.get(this.publicKey);
+    const isOwnDataQuery = filter.authors &&
+                           filter.authors.length === 1 &&
+                           filter.authors[0] === this.publicKey;
+
+    // If we have an initialized subscription for our own data, use cache
+    if (!forceRelay && isOwnDataQuery && subInfo && subInfo.initialized) {
+      // Return matching events from cache - no relay query needed!
+      const matchingEvents = this._getMatchingCachedEvents(filter);
+      return matchingEvents;
+    }
+
+    // For first query before subscription initializes, wait briefly
+    if (isOwnDataQuery && subInfo && !subInfo.initialized) {
+      // Wait for subscription to initialize (up to timeout)
+      await Promise.race([
+        subInfo.initPromise,
+        new Promise(resolve => setTimeout(resolve, Math.min(timeout, AUTHOR_SUB_INIT_TIMEOUT)))
+      ]);
+
+      // Now try cache again
+      if (subInfo.initialized) {
+        const matchingEvents = this._getMatchingCachedEvents(filter);
+        return matchingEvents;
+      }
+    }
+
     // Check d-tag cache first for single-item queries (most common case)
     // This ensures recently written data is returned immediately
     if (filter['#d'] && filter['#d'].length === 1 && filter.kinds && filter.kinds.length === 1) {
@@ -376,29 +671,101 @@ export class NostrClient {
 
   /**
    * Query relays and update cache
+   * Uses global pending queries map to deduplicate identical concurrent queries
    * @private
    */
   async _queryRelaysAndCache(filter, cacheKey, timeout) {
-    let events = await this.pool.querySync(this.relays, filter, { timeout });
-
-    // CRITICAL: Filter out events from other authors (relay may not respect filter)
-    if (filter.authors && filter.authors.length > 0) {
-      events = events.filter(event => filter.authors.includes(event.pubkey));
+    // Check if there's already a pending query for this exact filter
+    const pending = pendingQueries.get(cacheKey);
+    if (pending && Date.now() - pending.timestamp < PENDING_QUERY_TIMEOUT) {
+      // Reuse the pending query promise instead of creating a new one
+      return pending.promise;
     }
 
-    // Cache results
-    this._eventCache.set(cacheKey, {
-      events,
+    // Create the query promise
+    const queryPromise = (async () => {
+      try {
+        let events = await this.pool.querySync(this.relays, filter, { timeout });
+
+        // CRITICAL: Filter out events from other authors (relay may not respect filter)
+        if (filter.authors && filter.authors.length > 0) {
+          events = events.filter(event => filter.authors.includes(event.pubkey));
+        }
+
+        // Cache results
+        this._eventCache.set(cacheKey, {
+          events,
+          timestamp: Date.now(),
+        });
+
+        // Update reverse index for fast invalidation
+        this._indexCacheEntry(cacheKey, filter);
+
+        return events;
+      } finally {
+        // Clean up pending query after completion
+        pendingQueries.delete(cacheKey);
+      }
+    })();
+
+    // Store the pending query
+    pendingQueries.set(cacheKey, {
+      promise: queryPromise,
       timestamp: Date.now(),
     });
 
-    // Limit cache size
-    if (this._eventCache.size > 100) {
-      const firstKey = this._eventCache.keys().next().value;
-      this._eventCache.delete(firstKey);
+    return queryPromise;
+  }
+
+  /**
+   * Limit cache size (called after cache operations)
+   * Note: LRU cache handles this automatically, kept for API compatibility
+   * @private
+   */
+  _limitCacheSize() {
+    // LRU cache handles size limiting automatically
+  }
+
+  /**
+   * Add cache entry to reverse index for fast invalidation
+   * @private
+   */
+  _indexCacheEntry(cacheKey, filter) {
+    // Index by kinds for fast lookup during invalidation
+    if (filter.kinds) {
+      for (const kind of filter.kinds) {
+        if (!this._cacheIndex.has(kind)) {
+          this._cacheIndex.set(kind, new Set());
+        }
+        this._cacheIndex.get(kind).add(cacheKey);
+      }
     }
+  }
 
-    return events;
+  /**
+   * Remove cache entry from reverse index
+   * @private
+   */
+  _unindexCacheEntry(cacheKey) {
+    // Try to parse the filter from the cache key to remove from index
+    if (!cacheKey.startsWith('{')) return;
+
+    try {
+      const filter = JSON.parse(cacheKey);
+      if (filter.kinds) {
+        for (const kind of filter.kinds) {
+          const indexSet = this._cacheIndex.get(kind);
+          if (indexSet) {
+            indexSet.delete(cacheKey);
+            if (indexSet.size === 0) {
+              this._cacheIndex.delete(kind);
+            }
+          }
+        }
+      }
+    } catch {
+      // Not a valid filter key, skip
+    }
   }
 
   /**
@@ -427,20 +794,42 @@ export class NostrClient {
 
   /**
    * Internal method to refresh a path from relays
+   * Throttled to avoid flooding the relay with repeated requests
    * @private
    */
   async _doBackgroundPathRefresh(path, kind, options) {
     if (this.relays.length === 0) return;
 
+    // Throttle: Skip if we've refreshed this path recently
+    const lastRefresh = backgroundRefreshThrottle.get(path);
+    if (lastRefresh && Date.now() - lastRefresh < BACKGROUND_REFRESH_INTERVAL) {
+      return; // Skip - recently refreshed
+    }
+
+    // Mark as refreshed
+    backgroundRefreshThrottle.set(path, Date.now());
+
+    // Clean up old throttle entries periodically (keep map from growing)
+    if (backgroundRefreshThrottle.size > 1000) {
+      const cutoff = Date.now() - BACKGROUND_REFRESH_INTERVAL;
+      for (const [key, timestamp] of backgroundRefreshThrottle) {
+        if (timestamp < cutoff) {
+          backgroundRefreshThrottle.delete(key);
+        }
+      }
+    }
+
     const filter = {
       kinds: [kind],
       authors: options.authors || [this.publicKey],
       '#d': [path],
       limit: 1,
     };
+    const cacheKey = JSON.stringify(filter);
 
+    // Use our query deduplication by calling query() instead of pool.querySync() directly
     const timeout = options.timeout || 30000;
-    const events = await this.pool.querySync(this.relays, filter, { timeout });
+    const events = await this._queryRelaysAndCache(filter, cacheKey, timeout);
 
     // Filter by author (relays may not respect filter)
     const authorFiltered = events.filter(e =>
@@ -468,22 +857,35 @@ export class NostrClient {
 
   /**
    * Internal method to refresh a prefix from relays
+   * Throttled to avoid flooding the relay with repeated requests
    * @private
    */
   async _doBackgroundPrefixRefresh(prefix, kind, options) {
     if (this.relays.length === 0) return;
 
+    // Throttle: Skip if we've refreshed this prefix recently
+    const throttleKey = `prefix:${prefix}`;
+    const lastRefresh = backgroundRefreshThrottle.get(throttleKey);
+    if (lastRefresh && Date.now() - lastRefresh < BACKGROUND_REFRESH_INTERVAL) {
+      return; // Skip - recently refreshed
+    }
+
+    // Mark as refreshed
+    backgroundRefreshThrottle.set(throttleKey, Date.now());
+
     // Query with wildcard-ish filter (relays handle d-tag prefix matching)
     const filter = {
       kinds: [kind],
       authors: options.authors || [this.publicKey],
       limit: options.limit || 1000,
     };
+    const cacheKey = JSON.stringify(filter);
 
+    // Use our query deduplication
     const timeout = options.timeout || 30000;
-    let events = await this.pool.querySync(this.relays, filter, { timeout });
+    let events = await this._queryRelaysAndCache(filter, cacheKey, timeout);
 
-    // Filter by author
+    // Filter by author (already done by _queryRelaysAndCache, but double-check)
     events = events.filter(e =>
       (options.authors || [this.publicKey]).includes(e.pubkey)
     );
@@ -590,6 +992,7 @@ export class NostrClient {
 
   /**
    * Subscribe to events
+   * Uses subscription deduplication to avoid creating multiple identical subscriptions
    * @param {Object} filter - Nostr filter object
    * @param {Function} onEvent - Callback for each event
    * @param {Object} options - Subscription options
@@ -599,7 +1002,8 @@ export class NostrClient {
     // Ensure initialization is complete
     await this._initReady;
 
-    const subId = `sub-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    const subId = `sub-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+    const filterKey = JSON.stringify(filter);
 
     // If no relays, check cache for matching events and trigger callbacks
     if (this.relays.length === 0) {
@@ -636,6 +1040,43 @@ export class NostrClient {
       };
     }
 
+    // Check if we already have an active subscription for this filter
+    const existing = activeSubscriptions.get(filterKey);
+    if (existing) {
+      // Add callback to existing subscription
+      existing.callbacks.add(onEvent);
+      existing.refCount++;
+
+      // Return wrapper that removes this specific callback on unsubscribe
+      return {
+        id: subId,
+        unsubscribe: () => {
+          existing.callbacks.delete(onEvent);
+          existing.refCount--;
+
+          // Only close actual subscription when no more callbacks
+          if (existing.refCount === 0) {
+            if (existing.subscription && existing.subscription.close) {
+              existing.subscription.close();
+            }
+            activeSubscriptions.delete(filterKey);
+          }
+          this._subscriptions.delete(subId);
+        },
+      };
+    }
+
+    // Create new subscription with shared callback dispatcher
+    const callbacks = new Set([onEvent]);
+    const subscriptionInfo = {
+      callbacks,
+      refCount: 1,
+      subscription: null,
+    };
+
+    // Store before creating subscription to handle race conditions
+    activeSubscriptions.set(filterKey, subscriptionInfo);
+
     const sub = this.pool.subscribeMany(
       this.relays,
       [filter],
@@ -651,7 +1092,18 @@ export class NostrClient {
           }
 
           this._cacheEvent(event);
-          onEvent(event);
+
+          // Dispatch to ALL registered callbacks for this subscription
+          const subInfo = activeSubscriptions.get(filterKey);
+          if (subInfo) {
+            for (const cb of subInfo.callbacks) {
+              try {
+                cb(event);
+              } catch (err) {
+                console.warn('[nostr] Subscription callback error:', err.message);
+              }
+            }
+          }
         },
         oneose: () => {
           if (options.onEOSE) options.onEOSE();
@@ -659,12 +1111,21 @@ export class NostrClient {
       }
     );
 
+    // Store the actual subscription object
+    subscriptionInfo.subscription = sub;
     this._subscriptions.set(subId, sub);
 
     return {
       id: subId,
       unsubscribe: () => {
-        if (sub.close) sub.close();
+        callbacks.delete(onEvent);
+        subscriptionInfo.refCount--;
+
+        // Only close actual subscription when no more callbacks
+        if (subscriptionInfo.refCount === 0) {
+          if (sub.close) sub.close();
+          activeSubscriptions.delete(filterKey);
+        }
         this._subscriptions.delete(subId);
       },
     };
@@ -714,16 +1175,26 @@ export class NostrClient {
 
   /**
    * Invalidate query caches that might be affected by a new event
+   * Uses reverse index for O(1) lookup instead of O(n) scan
    * @private
    */
   _invalidateQueryCachesForEvent(event) {
-    // Find and remove query cache entries that could match this event
-    // Query cache keys are JSON-stringified filters
+    // Use reverse index for fast lookup - only check caches that could match this event's kind
+    const indexedKeys = this._cacheIndex.get(event.kind);
+    if (!indexedKeys || indexedKeys.size === 0) {
+      return; // No cached queries for this kind
+    }
+
     const keysToDelete = [];
 
-    for (const [cacheKey, cached] of this._eventCache.entries()) {
-      // Skip non-query caches (event IDs and d-tag keys)
-      if (!cacheKey.startsWith('{')) continue;
+    // Only iterate over cache entries that match the event's kind
+    for (const cacheKey of indexedKeys) {
+      const cached = this._eventCache.get(cacheKey);
+      if (!cached) {
+        // Cache entry was evicted, clean up index
+        indexedKeys.delete(cacheKey);
+        continue;
+      }
 
       try {
         const filter = JSON.parse(cacheKey);
@@ -732,38 +1203,42 @@ export class NostrClient {
           keysToDelete.push(cacheKey);
         }
       } catch {
-        // Not a JSON key, skip
+        // Not a valid JSON key, clean up index
+        indexedKeys.delete(cacheKey);
       }
     }
 
     for (const key of keysToDelete) {
       this._eventCache.delete(key);
+      this._unindexCacheEntry(key);
     }
   }
 
   /**
-   * Cache event in memory and persist
+   * Cache event in memory and persist (batched)
    * @private
    */
   async _cacheEvent(event) {
-    // Cache in memory
+    // Cache in memory (synchronous - immediate for local-first reads)
     this._cacheEventSync(event);
 
-    // Persist to storage
+    // Queue for batched persistence (async - batches writes for I/O efficiency)
     if (this.persistentStorage) {
-      try {
-        // For replaceable events, use d-tag as key
-        let storageKey = event.id;
-        if (event.kind >= 30000 && event.kind < 40000) {
-          const dTag = event.tags.find(t => t[0] === 'd');
-          if (dTag && dTag[1]) {
-            storageKey = dTag[1]; // Use d-tag as key for replaceable events
-          }
+      // For replaceable events, use d-tag as key
+      let storageKey = event.id;
+      if (event.kind >= 30000 && event.kind < 40000) {
+        const dTag = event.tags.find(t => t[0] === 'd');
+        if (dTag && dTag[1]) {
+          storageKey = dTag[1]; // Use d-tag as key for replaceable events
         }
+      }
 
-        await this.persistentStorage.put(storageKey, event);
-      } catch (error) {
-        console.warn('Failed to persist event:', error);
+      // Queue for batched write (overwrites previous if same key)
+      this._persistQueue.set(storageKey, event);
+
+      // Schedule batch flush if not already scheduled
+      if (!this._persistTimer) {
+        this._persistTimer = setTimeout(() => this._flushPersistQueue(), this._persistBatchMs);
       }
     }
 
@@ -782,6 +1257,34 @@ export class NostrClient {
     }
   }
 
+  /**
+   * Flush batched persistent writes
+   * @private
+   */
+  async _flushPersistQueue() {
+    this._persistTimer = null;
+
+    if (!this.persistentStorage || this._persistQueue.size === 0) {
+      return;
+    }
+
+    // Take snapshot of current queue and clear it
+    const toWrite = Array.from(this._persistQueue.entries());
+    this._persistQueue.clear();
+
+    // Write all queued events
+    const writePromises = toWrite.map(async ([key, event]) => {
+      try {
+        await this.persistentStorage.put(key, event);
+      } catch (error) {
+        console.warn(`Failed to persist event ${key}:`, error.message);
+      }
+    });
+
+    // Wait for all writes to complete
+    await Promise.all(writePromises);
+  }
+
   /**
    * Get cached events matching a filter
    * @private
@@ -898,13 +1401,32 @@ export class NostrClient {
 
   /**
    * Close all connections and subscriptions
+   * @param {Object} options - Close options
+   * @param {boolean} options.flush - Flush pending writes before closing (default: true)
    */
-  close() {
+  async close(options = {}) {
+    const shouldFlush = options.flush !== false;
+
+    // Flush pending persistent writes before closing
+    if (shouldFlush && this._persistTimer) {
+      clearTimeout(this._persistTimer);
+      await this._flushPersistQueue();
+    }
+
     // Stop background sync service
     if (this.syncService) {
       this.syncService.stop();
     }
 
+    // Close long-lived author subscription
+    const authorSub = authorSubscriptions.get(this.publicKey);
+    if (authorSub && authorSub.subscription) {
+      if (authorSub.subscription.close) {
+        authorSub.subscription.close();
+      }
+      authorSubscriptions.delete(this.publicKey);
+    }
+
     // Close all subscriptions
     for (const sub of this._subscriptions.values()) {
       if (sub.close) {
@@ -919,8 +1441,9 @@ export class NostrClient {
     // Close pool
     this.pool.close(this.relays);
 
-    // Clear cache
+    // Clear cache and index
     this._eventCache.clear();
+    this._cacheIndex.clear();
   }
 
   /**