holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/storage/nostr-client.js

@@ -1,19 +1,37 @@
 /**
- * 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
+/**
+ * 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
+ * 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) {
@@ -25,40 +43,93 @@ function getGlobalPool(config = {}) {
   return globalPool;
 }
 
-// Global pending queries map for deduplication
-// Key: JSON-stringified filter, Value: { promise, timestamp }
+/**
+ * Global pending queries map for deduplication.
+ * Key: JSON-stringified filter, Value: { promise, timestamp }
+ * @private
+ */
 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 }
+/**
+ * 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
+/**
+ * Throttle background refreshes to avoid flooding the relay.
+ * Key: path, Value: timestamp of last refresh
+ * @private
+ */
 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 }
+/**
+ * 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();
-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 }
+/**
+ * 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();
-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
+ * 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;
 
@@ -140,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)) {
@@ -181,8 +270,10 @@ export class NostrClient {
   }
 
   /**
-   * Initialize WebSocket polyfill and pool
+   * Initialize WebSocket polyfill and pool.
+   *
    * @private
+   * @returns {Promise<void>}
    */
   async _initialize() {
     // Ensure WebSocket is available before initializing pool
@@ -422,13 +513,21 @@ export class NostrClient {
   }
 
   /**
-   * Publish event to relays
-   * Supports debouncing for replaceable events (kind 30000-39999) to avoid rapid updates
+   * 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)
+   * @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
@@ -590,14 +689,22 @@ export class NostrClient {
   }
 
   /**
-   * Query events from relays
-   * Uses long-lived subscription for cache updates - avoids polling
+   * 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)
+   * @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
@@ -994,12 +1101,21 @@ export class NostrClient {
   }
 
   /**
-   * Subscribe to events
-   * Uses subscription deduplication to avoid creating multiple identical subscriptions
+   * 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
@@ -1403,9 +1519,11 @@ 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 all connections and subscriptions.
+   *
+   * @param {Object} [options={}] - Close options
+   * @param {boolean} [options.flush=true] - Flush pending writes before closing
+   * @returns {Promise<void>}
    */
   async close(options = {}) {
     const shouldFlush = options.flush !== false;
@@ -1462,9 +1580,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);

package/src/storage/nostr-wrapper.js

@@ -1,7 +1,11 @@
 /**
- * Nostr Storage Wrapper
- * Drop-in replacement for gun-wrapper.js with same API
+ * @fileoverview Nostr Storage Wrapper.
+ *
+ * Drop-in replacement for gun-wrapper.js providing the same API.
  * Handles path construction and CRUD operations using Nostr relays
+ * for distributed P2P storage.
+ *
+ * @module storage/nostr-wrapper
  */
 
 import {

package/src/storage/outbox-queue.js

@@ -1,19 +1,37 @@
 /**
- * OutboxQueue - Persistent queue for reliable relay delivery
+ * @fileoverview OutboxQueue - Persistent queue for reliable relay delivery.
  *
  * Implements guaranteed delivery with exponential backoff retry.
  * Events are persisted to local storage and retried until delivered
  * or max retries exceeded.
+ *
+ * @module storage/outbox-queue
  */
 
+/**
+ * Persistent queue for reliable event delivery to Nostr relays.
+ *
+ * Features:
+ * - Exponential backoff retry with jitter
+ * - Persistent storage across restarts
+ * - Automatic purging of old failed events
+ * - Queue statistics and monitoring
+ *
+ * @class OutboxQueue
+ * @example
+ * const queue = new OutboxQueue(storage, { maxRetries: 5 });
+ * await queue.enqueue(signedEvent, ['wss://relay1.com', 'wss://relay2.com']);
+ */
 export class OutboxQueue {
   /**
+   * Create a new OutboxQueue.
+   *
    * @param {Object} persistentStorage - Storage adapter (IndexedDB/FileSystem)
-   * @param {Object} options - Configuration options
-   * @param {number} options.maxRetries - Max retry attempts (default: 5)
-   * @param {number} options.baseDelay - Base delay in ms (default: 1000)
-   * @param {number} options.maxDelay - Max delay cap in ms (default: 60000)
-   * @param {number} options.failedTTL - TTL for failed events in ms (default: 24 hours)
+   * @param {Object} [options={}] - Configuration options
+   * @param {number} [options.maxRetries=5] - Max retry attempts
+   * @param {number} [options.baseDelay=1000] - Base delay in ms
+   * @param {number} [options.maxDelay=60000] - Max delay cap in ms (1 minute)
+   * @param {number} [options.failedTTL=86400000] - TTL for failed events in ms (24 hours)
    */
   constructor(persistentStorage, options = {}) {
     this.storage = persistentStorage;
@@ -25,10 +43,11 @@ export class OutboxQueue {
   }
 
   /**
-   * Add an event to the outbox queue
+   * Add an event to the outbox queue.
+   *
    * @param {Object} event - Signed Nostr event
    * @param {string[]} relays - Target relay URLs
-   * @returns {Promise<Object>} Queue entry
+   * @returns {Promise<Object>} Queue entry with metadata
    */
   async enqueue(event, relays) {
     const entry = {
@@ -48,9 +67,13 @@ export class OutboxQueue {
   }
 
   /**
-   * Mark an event as sent (removes from queue if successful)
+   * Mark an event as sent.
+   *
+   * Removes from queue if at least one relay accepted, otherwise schedules retry.
+   *
    * @param {string} eventId - Event ID
    * @param {string[]} successfulRelays - Relays that accepted the event
+   * @returns {Promise<void>}
    */
   async markSent(eventId, successfulRelays) {
     const key = `${this.queuePrefix}${eventId}`;
@@ -67,8 +90,14 @@ export class OutboxQueue {
   }
 
   /**
-   * Schedule a retry with exponential backoff
+   * Schedule a retry with exponential backoff.
+   *
+   * Uses exponential backoff with jitter. Marks as failed if max retries exceeded.
+   *
    * @private
+   * @param {string} key - Storage key
+   * @param {Object} entry - Queue entry
+   * @returns {Promise<void>}
    */
   async _scheduleRetry(key, entry) {
     entry.retries++;
@@ -90,7 +119,8 @@ export class OutboxQueue {
   }
 
   /**
-   * Get all pending events ready for retry
+   * Get all pending events ready for retry.
+   *
    * @returns {Promise<Object[]>} Pending queue entries sorted by creation time
    */
   async getPendingEvents() {
@@ -103,7 +133,8 @@ export class OutboxQueue {
   }
 
   /**
-   * Get all failed events (exceeded max retries)
+   * Get all failed events (exceeded max retries).
+   *
    * @returns {Promise<Object[]>} Failed queue entries
    */
   async getFailedEvents() {
@@ -112,8 +143,9 @@ export class OutboxQueue {
   }
 
   /**
-   * Get queue statistics
-   * @returns {Promise<Object>} Stats object
+   * Get queue statistics.
+   *
+   * @returns {Promise<Object>} Stats object with total, pending, failed counts and oldest timestamps
    */
   async getStats() {
     const allEntries = await this.storage.getAll(this.queuePrefix);
@@ -146,8 +178,9 @@ export class OutboxQueue {
   }
 
   /**
-   * Purge failed events older than maxAge
-   * @param {number} maxAge - Max age in ms (default: 24 hours)
+   * Purge failed events older than maxAge.
+   *
+   * @param {number} [maxAge] - Max age in ms (defaults to failedTTL)
    * @returns {Promise<number>} Number of entries purged
    */
   async purgeOldFailed(maxAge = this.failedTTL) {
@@ -166,7 +199,8 @@ export class OutboxQueue {
   }
 
   /**
-   * Clear all entries from the queue
+   * Clear all entries from the queue.
+   *
    * @returns {Promise<number>} Number of entries cleared
    */
   async clear() {
@@ -184,7 +218,10 @@ export class OutboxQueue {
   }
 
   /**
-   * Manually retry a failed event
+   * Manually retry a failed event.
+   *
+   * Resets retry counter and status to allow manual retry of a failed event.
+   *
    * @param {string} eventId - Event ID to retry
    * @returns {Promise<Object|null>} Updated entry or null if not found
    */

package/src/storage/persistent-storage.js

@@ -1,69 +1,102 @@
 /**
- * Persistent Storage Interface
- * Provides a unified API for local persistence across browser and Node.js
+ * @fileoverview Persistent Storage Interface.
+ *
+ * Provides a unified API for local persistence across browser and Node.js.
+ * Automatically selects the appropriate storage backend:
+ * - IndexedDB in browsers
+ * - Filesystem in Node.js
+ * - Memory fallback if neither available
+ *
+ * @module storage/persistent-storage
  */
 
 /**
- * Base class for persistent storage adapters
+ * Base class for persistent storage adapters.
+ *
+ * All storage implementations must extend this class and implement all methods.
+ *
+ * @class PersistentStorage
+ * @abstract
  */
 class PersistentStorage {
   /**
-   * Initialize storage
+   * Initialize storage with namespace.
+   *
+   * @abstract
    * @param {string} namespace - Storage namespace (appName)
    * @returns {Promise<void>}
+   * @throws {Error} Must be implemented by subclass
    */
   async init(namespace) {
     throw new Error('init() must be implemented by subclass');
   }
 
   /**
-   * Store event
+   * Store event.
+   *
+   * @abstract
    * @param {string} key - Event ID or d-tag
    * @param {Object} event - Nostr event
    * @returns {Promise<void>}
+   * @throws {Error} Must be implemented by subclass
    */
   async put(key, event) {
     throw new Error('put() must be implemented by subclass');
   }
 
   /**
-   * Retrieve event
+   * Retrieve event.
+   *
+   * @abstract
    * @param {string} key - Event ID or d-tag
    * @returns {Promise<Object|null>} Event or null
+   * @throws {Error} Must be implemented by subclass
    */
   async get(key) {
     throw new Error('get() must be implemented by subclass');
   }
 
   /**
-   * Get all events matching prefix
+   * Get all events matching prefix.
+   *
+   * @abstract
    * @param {string} prefix - Key prefix
    * @returns {Promise<any[]>} Array of events
+   * @throws {Error} Must be implemented by subclass
    */
   async getAll(prefix) {
     throw new Error('getAll() must be implemented by subclass');
   }
 
   /**
-   * Delete event
+   * Delete event.
+   *
+   * @abstract
    * @param {string} key - Event ID or d-tag
    * @returns {Promise<void>}
+   * @throws {Error} Must be implemented by subclass
    */
   async delete(key) {
     throw new Error('delete() must be implemented by subclass');
   }
 
   /**
-   * Clear all data in namespace
+   * Clear all data in namespace.
+   *
+   * @abstract
    * @returns {Promise<void>}
+   * @throws {Error} Must be implemented by subclass
    */
   async clear() {
     throw new Error('clear() must be implemented by subclass');
   }
 
   /**
-   * Close storage
+   * Close storage connection.
+   *
+   * @abstract
    * @returns {Promise<void>}
+   * @throws {Error} Must be implemented by subclass
    */
   async close() {
     throw new Error('close() must be implemented by subclass');
@@ -71,10 +104,20 @@ class PersistentStorage {
 }
 
 /**
- * Detect environment and return appropriate storage adapter
+ * Detect environment and return appropriate storage adapter.
+ *
+ * Automatically creates:
+ * - IndexedDBStorage in browsers
+ * - FileSystemStorage in Node.js
+ * - MemoryStorage as fallback
+ *
  * @param {string} namespace - Storage namespace
- * @param {Object} options - Storage options
- * @returns {Promise<PersistentStorage>} Storage instance
+ * @param {Object} [options={}] - Storage options
+ * @param {string} [options.dataDir] - Custom data directory (Node.js only)
+ * @returns {Promise<PersistentStorage>} Initialized storage instance
+ * @example
+ * const storage = await createPersistentStorage('myapp');
+ * await storage.put('key1', { id: 'event1', data: 'test' });
  */
 async function createPersistentStorage(namespace, options = {}) {
   // Detect environment