holosphere 2.0.0-alpha0 → 2.0.0-alpha10

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,64 +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<Object[]>} Array of events
+   * @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');
@@ -66,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

package/src/storage/sync-service.js

@@ -1,16 +1,34 @@
 /**
- * SyncService - Background service for reliable sync
+ * @fileoverview SyncService - Background service for reliable sync.
  *
  * Periodically processes the outbox queue to retry failed deliveries
  * and purge old failed events.
+ *
+ * @module storage/sync-service
  */
 
+/**
+ * Background service for reliable event synchronization.
+ *
+ * Runs on a periodic interval to:
+ * - Retry pending events in the outbox queue
+ * - Purge old failed events (24 hour TTL)
+ * - Provide sync statistics
+ *
+ * @class SyncService
+ * @example
+ * const sync = new SyncService(client, { interval: 10000, autoStart: true });
+ * const stats = await sync.getStats();
+ * console.log('Pending events:', stats.queue.pending);
+ */
 export class SyncService {
   /**
-   * @param {Object} client - NostrClient instance
-   * @param {Object} options - Configuration options
-   * @param {number} options.interval - Sync interval in ms (default: 10000)
-   * @param {boolean} options.autoStart - Start automatically (default: false)
+   * Create a new SyncService.
+   *
+   * @param {Object} client - NostrClient instance with outboxQueue
+   * @param {Object} [options={}] - Configuration options
+   * @param {number} [options.interval=10000] - Sync interval in ms (10 seconds)
+   * @param {boolean} [options.autoStart=false] - Start automatically
    */
   constructor(client, options = {}) {
     this.client = client;
@@ -25,7 +43,9 @@ export class SyncService {
   }
 
   /**
-   * Start the background sync service
+   * Start the background sync service.
+   *
+   * @returns {void}
    */
   start() {
     if (this.running) return;
@@ -34,7 +54,9 @@ export class SyncService {
   }
 
   /**
-   * Stop the background sync service
+   * Stop the background sync service.
+   *
+   * @returns {void}
    */
   stop() {
     this.running = false;
@@ -45,24 +67,30 @@ export class SyncService {
   }
 
   /**
-   * Check if the service is running
-   * @returns {boolean}
+   * Check if the service is running.
+   *
+   * @returns {boolean} True if service is running
    */
   isRunning() {
     return this.running;
   }
 
   /**
-   * Force an immediate sync (useful for testing or manual trigger)
-   * @returns {Promise<Object>} Sync result
+   * Force an immediate sync.
+   *
+   * Useful for testing or manual trigger.
+   *
+   * @returns {Promise<Object>} Sync result with processed, succeeded, failed, purged counts
    */
   async syncNow() {
     return this._processOutbox();
   }
 
   /**
-   * Schedule the next run
+   * Schedule the next run.
+   *
    * @private
+   * @returns {void}
    */
   _scheduleNextRun() {
     if (!this.running) return;
@@ -73,8 +101,10 @@ export class SyncService {
   }
 
   /**
-   * Main loop iteration
+   * Main loop iteration.
+   *
    * @private
+   * @returns {Promise<void>}
    */
   async _runLoop() {
     if (!this.running) return;
@@ -90,9 +120,12 @@ export class SyncService {
   }
 
   /**
-   * Process pending events in the outbox
+   * Process pending events in the outbox.
+   *
+   * Retries pending events and purges old failed events.
+   *
    * @private
-   * @returns {Promise<Object>} Processing result
+   * @returns {Promise<Object>} Processing result with counts
    */
   async _processOutbox() {
     // Prevent concurrent processing
@@ -145,8 +178,9 @@ export class SyncService {
   }
 
   /**
-   * Get sync service statistics
-   * @returns {Promise<Object>} Stats including queue status
+   * Get sync service statistics.
+   *
+   * @returns {Promise<Object>} Stats including running status, interval, and queue status
    */
   async getStats() {
     const stats = {

package/src/storage/unified-storage.js

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview Unified Storage Adapter.
+ *
+ * Routes storage operations to the correct backend (Nostr or GunDB).
+ * Provides a consistent API for reading, writing, updating, and deleting
+ * data across different storage backends.
+ *
+ * @module storage/unified-storage
+ */
+
+import * as nostrWrapper from './nostr-wrapper.js';
+import * as gunWrapper from './gun-wrapper.js';
+
+/**
+ * Build path from components
+ * @param {string} appName - Application namespace
+ * @param {string} holonId - Holon identifier
+ * @param {string} lensName - Lens name
+ * @param {string} [key] - Optional data key
+ * @returns {string} Constructed path
+ */
+export function buildPath(appName, holonId, lensName, key = null) {
+  // Both backends use the same path format
+  return nostrWrapper.buildPath(appName, holonId, lensName, key);
+}
+
+/**
+ * Write data to storage
+ * @param {Object} client - Client instance (nostr client or gun-compatible client)
+ * @param {string} path - Storage path
+ * @param {Object} data - Data to write
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function write(client, path, data) {
+  // Check if this is a GunDB client with backend methods (preferred - has write cache)
+  if (client.write && client.gun) {
+    return client.write(path, data);
+  }
+  // Fallback to direct gunWrapper (no write cache)
+  if (client.gun) {
+    return gunWrapper.write(client.gun, path, data);
+  }
+  // Default to Nostr
+  return nostrWrapper.write(client, path, data);
+}
+
+/**
+ * Read data from storage
+ * @param {Object} client - Client instance
+ * @param {string} path - Storage path
+ * @param {Object} [options] - Read options
+ * @returns {Promise<Object|null>} Data or null
+ */
+export async function read(client, path, options = {}) {
+  // Check if this is a GunDB client with backend methods (preferred - has write cache)
+  if (client.read && client.gun) {
+    return client.read(path, options);
+  }
+  // Fallback to direct gunWrapper
+  if (client.gun) {
+    return gunWrapper.read(client.gun, path);
+  }
+  return nostrWrapper.read(client, path, options);
+}
+
+/**
+ * Read all data under a path prefix
+ * @param {Object} client - Client instance
+ * @param {string} path - Path prefix
+ * @param {Object} [options] - Query options
+ * @returns {Promise<Object[]>} Array of data objects
+ */
+export async function readAll(client, path, options = {}) {
+  // Check if this is a GunDB client with backend methods (preferred - has write cache)
+  if (client.readAll && client.gun) {
+    return client.readAll(path, options);
+  }
+  // Fallback to direct gunWrapper
+  if (client.gun) {
+    return gunWrapper.readAll(client.gun, path);
+  }
+  return nostrWrapper.readAll(client, path, options);
+}
+
+/**
+ * Update data (merge fields)
+ * @param {Object} client - Client instance
+ * @param {string} path - Storage path
+ * @param {Object} updates - Fields to update
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function update(client, path, updates) {
+  // Check if this is a GunDB client with backend methods (preferred - has write cache)
+  if (client.update && client.gun) {
+    return client.update(path, updates);
+  }
+  // Fallback to direct gunWrapper
+  if (client.gun) {
+    return gunWrapper.update(client.gun, path, updates);
+  }
+  return nostrWrapper.update(client, path, updates);
+}
+
+/**
+ * Delete data at path
+ * @param {Object} client - Client instance
+ * @param {string} path - Storage path
+ * @returns {Promise<boolean>} Success indicator
+ */
+export async function deleteData(client, path) {
+  // Check if this is a GunDB client with backend methods (preferred - has write cache)
+  if (client.delete && client.gun) {
+    return client.delete(path);
+  }
+  // Fallback to direct gunWrapper
+  if (client.gun) {
+    return gunWrapper.deleteData(client.gun, path);
+  }
+  return nostrWrapper.deleteData(client, path);
+}
+
+/**
+ * Delete all data under path prefix
+ * @param {Object} client - Client instance
+ * @param {string} path - Path prefix
+ * @returns {Promise<Object>} Deletion results
+ */
+export async function deleteAll(client, path) {
+  // Fallback to direct gunWrapper (deleteAll not typically in client interface)
+  if (client.gun) {
+    return gunWrapper.deleteAll(client.gun, path);
+  }
+  return nostrWrapper.deleteAll(client, path);
+}
+
+/**
+ * Subscribe to data changes
+ * @param {Object} client - Client instance
+ * @param {string} path - Path or path prefix
+ * @param {Function} callback - Called on changes
+ * @param {Object} [options] - Subscription options
+ * @returns {Object} Subscription with unsubscribe method
+ */
+export function subscribe(client, path, callback, options = {}) {
+  // Check if this is a GunDB client with backend methods
+  if (client.subscribe && client.gun) {
+    return client.subscribe(path, callback, options);
+  }
+  // Fallback to direct gunWrapper
+  if (client.gun) {
+    return gunWrapper.subscribe(client.gun, path, callback, options);
+  }
+  return nostrWrapper.subscribe(client, path, callback, options);
+}

package/src/subscriptions/manager.js

@@ -1,22 +1,26 @@
 /**
- * Real-time Subscription Management
+ * @fileoverview Real-time subscription management with throttling, filtering, and hologram resolution.
+ * Provides subscription utilities for real-time data updates from the unified storage layer.
+ * @module subscriptions/manager
  */
 
-import { subscribe } from '../storage/nostr-wrapper.js';
+import { subscribe } from '../storage/unified-storage.js';
 import { resolveHologram } from '../federation/hologram.js';
 
 /**
- * Create subscription with throttle and filter
+ * Create subscription with throttle and filter support.
+ * Manages real-time data updates with deduplication, hologram resolution, and filtering capabilities.
  * @param {Object} client - Nostr client instance
- * @param {string} path - Path to subscribe to
- * @param {Function} callback - Callback function
- * @param {Object} options - Subscription options
- * @param {number} options.throttle - Throttle interval in ms
- * @param {Function} options.filter - Filter predicate
- * @param {boolean} options.includeFederated - Include federated data
- * @param {boolean} options.triggerInitial - Trigger callback with initial data (default: false)
- * @param {boolean} options.resolveHolograms - Resolve holograms before callback (default: true)
- * @returns {Object} Subscription object with unsubscribe method
+ * @param {string} path - Path to subscribe to (app/holon/lens/data)
+ * @param {Function} callback - Callback function invoked with (data, key)
+ * @param {Object} [options={}] - Subscription options
+ * @param {number} [options.throttle=0] - Throttle interval in milliseconds
+ * @param {Function} [options.filter=null] - Filter predicate function (data, key) => boolean
+ * @param {boolean} [options.includeFederated=false] - Include federated data
+ * @param {boolean} [options.triggerInitial=false] - Trigger callback with initial data
+ * @param {boolean} [options.realtimeOnly=true] - Only subscribe to new events
+ * @param {boolean} [options.resolveHolograms=true] - Resolve holograms before callback
+ * @returns {Promise<Object>} Subscription object with path and unsubscribe method
  */
 export async function createSubscription(client, path, callback, options = {}) {
   const { throttle = 0, filter = null, includeFederated = false, triggerInitial = false, realtimeOnly = true, resolveHolograms = true } = options;
@@ -98,22 +102,34 @@ export async function createSubscription(client, path, callback, options = {}) {
 }
 
 /**
- * Subscription registry for tracking active subscriptions
+ * Registry for tracking and managing multiple active subscriptions.
+ * Provides centralized subscription lifecycle management with batch operations.
  */
 export class SubscriptionRegistry {
+  /**
+   * Create a new subscription registry.
+   */
   constructor() {
+    /**
+     * Map of subscription ID to subscription object
+     * @type {Map<string, Object>}
+     * @private
+     */
     this.subscriptions = new Map();
   }
 
   /**
-   * Register a subscription
+   * Register a subscription by ID.
+   * @param {string} id - Unique subscription identifier
+   * @param {Object} subscription - Subscription object with unsubscribe method
    */
   register(id, subscription) {
     this.subscriptions.set(id, subscription);
   }
 
   /**
-   * Unregister a subscription
+   * Unregister and unsubscribe a subscription by ID.
+   * @param {string} id - Subscription identifier to remove
    */
   unregister(id) {
     const subscription = this.subscriptions.get(id);
@@ -124,7 +140,7 @@ export class SubscriptionRegistry {
   }
 
   /**
-   * Unsubscribe all
+   * Unsubscribe all registered subscriptions and clear the registry.
    */
   unsubscribeAll() {
     for (const [id, subscription] of this.subscriptions) {
@@ -134,7 +150,8 @@ export class SubscriptionRegistry {
   }
 
   /**
-   * Get active subscription count
+   * Get the count of active subscriptions.
+   * @returns {number} Number of active subscriptions
    */
   count() {
     return this.subscriptions.size;