holosphere 2.0.0-alpha1 → 2.0.0-alpha10

package/src/storage/nostr-client.js

@@ -1,12 +1,193 @@
 /**
- * Nostr Client - SimplePool wrapper for relay management
- * Provides connection pooling and relay management
+ * @fileoverview Nostr Client - SimplePool wrapper for relay management.
+ *
+ * Provides connection pooling, relay management, event caching, persistent storage,
+ * outbox queue for guaranteed delivery, and background sync services.
+ *
+ * @module storage/nostr-client
  */
 
 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.
+ * @private
+ */
+let globalPool = null;
+
+/**
+ * Set of relays used by the global pool.
+ * @private
+ */
+let globalPoolRelays = new Set();
+
+/**
+ * Get or create global SimplePool singleton.
+ * This ensures WebSocket connections are reused across all operations.
+ *
+ * @private
+ * @param {Object} [config={}] - Pool configuration
+ * @param {boolean} [config.enableReconnect=true] - Enable auto-reconnect
+ * @param {boolean} [config.enablePing=true] - Enable ping/pong
+ * @returns {SimplePool} The global SimplePool instance
+ */
+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 }
+ * @private
+ */
+const pendingQueries = new Map();
+
+/**
+ * Pending query timeout (5 seconds).
+ * @private
+ * @constant {number}
+ */
+const PENDING_QUERY_TIMEOUT = 5000;
+
+/**
+ * Global active subscriptions map for subscription deduplication.
+ * Key: JSON-stringified filter, Value: { subscription, callbacks: Set, refCount }
+ * @private
+ */
+const activeSubscriptions = new Map();
+
+/**
+ * Throttle background refreshes to avoid flooding the relay.
+ * Key: path, Value: timestamp of last refresh
+ * @private
+ */
+const backgroundRefreshThrottle = new Map();
+
+/**
+ * Background refresh interval (30 seconds).
+ * @private
+ * @constant {number}
+ */
+const BACKGROUND_REFRESH_INTERVAL = 30000;
+
+/**
+ * Write debouncing for rapid updates to the same path.
+ * Key: d-tag path, Value: { event, timer, resolve, reject }
+ * @private
+ */
+const pendingWrites = new Map();
+
+/**
+ * Write debounce window (500ms).
+ * @private
+ * @constant {number}
+ */
+const WRITE_DEBOUNCE_MS = 500;
+
+/**
+ * Long-lived subscription manager - keeps ONE subscription per author for real-time updates.
+ * Key: pubkey, Value: { subscription, lastEventTime, initialized }
+ * @private
+ */
+const authorSubscriptions = new Map();
+
+/**
+ * Author subscription initialization timeout (5 seconds).
+ * @private
+ * @constant {number}
+ */
+const AUTHOR_SUB_INIT_TIMEOUT = 5000;
+
+/**
+ * Simple LRU Cache implementation.
+ * Automatically evicts least recently used entries when max size is reached.
+ *
+ * @private
+ * @class LRUCache
+ */
+class LRUCache {
+  /**
+   * Create a new LRU cache.
+   *
+   * @param {number} [maxSize=500] - Maximum number of entries
+   */
+  constructor(maxSize = 500) {
+    this.maxSize = maxSize;
+    this.cache = new Map();
+  }
+
+  /**
+   * Get an entry from the cache.
+   *
+   * @param {string} key - Cache key
+   * @returns {*} Cached value or undefined
+   */
+  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() {
@@ -30,17 +211,35 @@ function ensureWebSocket() {
 import { createPersistentStorage } from './persistent-storage.js';
 
 /**
- * NostrClient - Manages connections to Nostr relays
+ * NostrClient - Manages connections to Nostr relays.
+ *
+ * Provides event publishing, querying, subscription management, persistent caching,
+ * and guaranteed delivery via outbox queue.
+ *
+ * @class NostrClient
+ * @example
+ * const client = new NostrClient({
+ *   relays: ['wss://relay.example.com'],
+ *   appName: 'myapp',
+ *   persistence: true
+ * });
  */
 export class NostrClient {
   /**
-   * @param {Object} config - Configuration options
-   * @param {string[]} config.relays - Array of relay URLs
-   * @param {string} config.privateKey - Private key for signing (hex format)
-   * @param {boolean} config.enableReconnect - Auto-reconnect on disconnect (default: true)
-   * @param {boolean} config.enablePing - Auto-ping relays (default: true)
-   * @param {string} config.appName - Application name for storage namespace
-   * @param {boolean} config.persistence - Enable persistent storage (default: true)
+   * Create a new NostrClient.
+   *
+   * @param {Object} [config={}] - Configuration options
+   * @param {string[]} [config.relays=[]] - Array of relay URLs
+   * @param {string} [config.privateKey] - Private key for signing (hex format)
+   * @param {boolean} [config.enableReconnect=true] - Auto-reconnect on disconnect
+   * @param {boolean} [config.enablePing=true] - Auto-ping relays
+   * @param {string} [config.appName] - Application name for storage namespace
+   * @param {boolean} [config.persistence=true] - Enable persistent storage
+   * @param {number} [config.cacheSize=500] - Maximum cache size
+   * @param {number} [config.persistBatchMs=100] - Batch persist writes within this window
+   * @param {boolean} [config.backgroundSync=true] - Enable background sync service
+   * @param {string} [config.dataDir] - Data directory for persistent storage
+   * @throws {Error} If relays is not an array
    */
   constructor(config = {}) {
     if (config.relays && !Array.isArray(config.relays)) {
@@ -57,16 +256,24 @@ 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();
   }
 
   /**
-   * Initialize WebSocket polyfill and pool
+   * Initialize WebSocket polyfill and pool.
+   *
    * @private
+   * @returns {Promise<void>}
    */
   async _initialize() {
     // Ensure WebSocket is available before initializing pool
@@ -74,10 +281,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 +298,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;
+    }
   }
 
   /**
@@ -169,6 +461,23 @@ export class NostrClient {
     }
   }
 
+  /**
+   * Get event from LRU cache by d-tag path (for local-first reads).
+   * This is always up-to-date because writes update the LRU cache synchronously,
+   * unlike persistent storage which uses batched writes.
+   * @param {string} path - The d-tag path
+   * @param {number} [kind=30000] - Event kind
+   * @returns {Object|null} The cached event or null
+   */
+  getCachedByPath(path, kind = 30000) {
+    const dTagKey = `d:${kind}:${path}`;
+    const cached = this._eventCache.get(dTagKey);
+    if (cached && cached.events && cached.events[0]) {
+      return cached.events[0];
+    }
+    return null;
+  }
+
   /**
    * Get all events from persistent storage matching a prefix
    * @param {string} prefix - The path prefix to match
@@ -221,11 +530,21 @@ export class NostrClient {
   }
 
   /**
-   * Publish event to relays
+   * 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 {Object} [options={}] - Publish options
+   * @param {boolean} [options.waitForRelays=false] - Wait for relay confirmation
+   * @param {boolean} [options.debounce=true] - Debounce rapid writes to same d-tag
    * @returns {Promise<Object>} Signed event with relay publish results
+   * @example
+   * const result = await client.publish({
+   *   kind: 30000,
+   *   tags: [['d', 'mypath']],
+   *   content: JSON.stringify({ name: 'Test' })
+   * });
    */
   async publish(event, options = {}) {
     // Ensure initialization is complete
@@ -233,8 +552,71 @@ export class NostrClient {
 
     const waitForRelays = options.waitForRelays || false;
 
-    // Sign the event
-    const signedEvent = finalizeEvent(event, this.privateKey);
+    // 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;
+
+    // Check if event is already signed (has id and sig)
+    // If so, use it as-is; otherwise sign it
+    const signedEvent = (event.id && event.sig)
+      ? event
+      : finalizeEvent(event, this.privateKey);
 
     // 1. Cache the event locally first (this makes reads instant)
     await this._cacheEvent(signedEvent);
@@ -256,8 +638,8 @@ export class NostrClient {
       };
     } else {
       // Fire and forget - publish in background, return immediately
-      this._attemptDelivery(signedEvent, this.relays).catch(err => {
-        console.warn('[nostr] Immediate delivery failed, queued for retry:', err.message);
+      this._attemptDelivery(signedEvent, this.relays).catch(() => {
+        // Silent - event is cached locally and queued for retry
       });
 
       // Return immediately (data is in local cache and queued for delivery)
@@ -305,25 +687,41 @@ export class NostrClient {
       await this.outboxQueue.markSent(event.id, successful);
     }
 
-    // Log failures for debugging
-    if (failed.length > 0) {
+    // Log failures only at debug level (common during network issues)
+    if (failed.length > 0 && successful.length === 0) {
+      // Only warn if ALL relays failed (likely a real issue)
       const reasons = results
         .filter(r => r.status === 'rejected')
         .map(f => f.reason?.message || f.reason || 'unknown')
         .join(', ');
-      console.warn(`[nostr] ${failed.length}/${relays.length} relays failed for ${event.id.slice(0, 8)}: ${reasons}`);
+      // Use debug level for timeout issues (very common)
+      if (reasons.includes('timed out')) {
+        // Silent - event is queued for retry anyway
+      } else {
+        console.warn(`[nostr] All relays failed for ${event.id.slice(0, 8)}: ${reasons}`);
+      }
     }
 
     return { successful, failed, results: formattedResults };
   }
 
   /**
-   * Query events from relays
+   * 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 {Object} [options={}] - Query options
+   * @param {number} [options.timeout=30000] - Query timeout in ms (set to 0 for no timeout)
+   * @param {boolean} [options.localFirst=true] - Return local cache immediately, refresh in background
+   * @param {boolean} [options.forceRelay=false] - Force relay query even if subscription cache is available
    * @returns {Promise<Array>} Array of events
+   * @example
+   * const events = await client.query({
+   *   kinds: [30000],
+   *   authors: [client.publicKey],
+   *   '#d': ['mypath']
+   * });
    */
   async query(filter, options = {}) {
     // Ensure initialization is complete
@@ -331,6 +729,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) {
@@ -338,6 +737,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) {
@@ -370,29 +798,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);
+      }
     }
+  }
+
+  /**
+   * 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;
 
-    return events;
+    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
+    }
   }
 
   /**
@@ -421,20 +921,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 =>
@@ -462,22 +984,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)
     );
@@ -583,17 +1118,28 @@ export class NostrClient {
   }
 
   /**
-   * Subscribe to events
+   * 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
-   * @returns {Object} Subscription object with unsubscribe method
+   * @param {Object} [options={}] - Subscription options
+   * @param {Function} [options.onEOSE] - Callback when End Of Stored Events is received
+   * @returns {Promise<Object>} Subscription object with unsubscribe method and id
+   * @example
+   * const sub = await client.subscribe(
+   *   { kinds: [30000], authors: [client.publicKey] },
+   *   (event) => console.log('Event:', event)
+   * );
+   * // Later: sub.unsubscribe();
    */
   async subscribe(filter, onEvent, options = {}) {
     // 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) {
@@ -630,6 +1176,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],
@@ -645,7 +1228,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();
@@ -653,12 +1247,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);
       },
     };
@@ -708,16 +1311,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);
@@ -726,38 +1339,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);
       }
     }
 
@@ -776,6 +1393,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
@@ -891,14 +1536,35 @@ export class NostrClient {
   }
 
   /**
-   * Close all connections and subscriptions
+   * Close all connections and subscriptions.
+   *
+   * @param {Object} [options={}] - Close options
+   * @param {boolean} [options.flush=true] - Flush pending writes before closing
+   * @returns {Promise<void>}
    */
-  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) {
@@ -913,8 +1579,9 @@ export class NostrClient {
     // Close pool
     this.pool.close(this.relays);
 
-    // Clear cache
+    // Clear cache and index
     this._eventCache.clear();
+    this._cacheIndex.clear();
   }
 
   /**
@@ -930,9 +1597,15 @@ export class NostrClient {
 }
 
 /**
- * Create NostrClient instance
+ * Create NostrClient instance.
+ *
  * @param {Object} config - Configuration options
  * @returns {NostrClient} Client instance
+ * @example
+ * const client = createClient({
+ *   relays: ['wss://relay.example.com'],
+ *   appName: 'myapp'
+ * });
  */
 export function createClient(config) {
   return new NostrClient(config);