holosphere 2.0.0-alpha8 → 2.0.0-alpha9

package/src/storage/key-storage.js

@@ -1,13 +1,25 @@
 /**
- * Key Storage - Universal API
- * Automatically uses Node.js or Browser implementation
+ * @fileoverview Key Storage - Universal API.
+ *
+ * Automatically uses Node.js or Browser implementation for storing private keys.
+ * In Node.js, keys are stored in the filesystem (~/.config/holosphere/keys).
+ * In browsers, keys are stored in localStorage.
+ *
+ * @module storage/key-storage
  */
 
 /**
- * Lazy-loaded Node.js modules
+ * Lazy-loaded Node.js modules.
+ * @private
  */
 let nodeModules = null;
 
+/**
+ * Get or initialize Node.js modules for filesystem access.
+ *
+ * @private
+ * @returns {Object|null} Node.js modules or null if unavailable
+ */
 function getNodeModules() {
   if (!nodeModules) {
     try {
@@ -36,10 +48,17 @@ function getNodeModules() {
 }
 
 /**
- * Load private key from storage
+ * Load private key from storage.
+ *
+ * Attempts to load from localStorage (browser) or filesystem (Node.js).
+ *
  * @param {string} appName - Application name
- * @param {Object} options - Options
- * @returns {string|null} Private key or null
+ * @param {Object} [options={}] - Options
+ * @param {string} [options.keyDir] - Custom key directory (Node.js only)
+ * @returns {string|null} Private key (hex) or null if not found
+ * @example
+ * const key = loadPrivateKey('myapp');
+ * if (key) console.log('Loaded existing key');
  */
 export function loadPrivateKey(appName, options = {}) {
   // Browser environment
@@ -70,11 +89,18 @@ export function loadPrivateKey(appName, options = {}) {
 }
 
 /**
- * Save private key to storage
+ * Save private key to storage.
+ *
+ * Saves to localStorage (browser) or filesystem (Node.js) with secure permissions.
+ *
  * @param {string} appName - Application name
- * @param {string} privateKey - Private key (hex)
- * @param {Object} options - Options
- * @returns {boolean} Success
+ * @param {string} privateKey - Private key (64-character hex string)
+ * @param {Object} [options={}] - Options
+ * @param {string} [options.keyDir] - Custom key directory (Node.js only)
+ * @returns {boolean} True if saved successfully
+ * @throws {Error} If private key format is invalid
+ * @example
+ * const success = savePrivateKey('myapp', '1a2b3c...');
  */
 export function savePrivateKey(appName, privateKey, options = {}) {
   if (!/^[0-9a-f]{64}$/i.test(privateKey)) {
@@ -113,11 +139,17 @@ export function savePrivateKey(appName, privateKey, options = {}) {
 }
 
 /**
- * Get or create private key for an app
+ * Get or create private key for an app.
+ *
+ * Loads existing key or generates and saves a new one.
+ *
  * @param {string} appName - Application name
- * @param {Function} generateFn - Function to generate new key
- * @param {Object} options - Options
+ * @param {Function} generateFn - Function to generate new key (returns hex string)
+ * @param {Object} [options={}] - Options
+ * @param {string} [options.keyDir] - Custom key directory (Node.js only)
  * @returns {string} Private key (hex)
+ * @example
+ * const key = getOrCreatePrivateKey('myapp', () => generateSecureKey());
  */
 export function getOrCreatePrivateKey(appName, generateFn, options = {}) {
   const existingKey = loadPrivateKey(appName, options);

package/src/storage/memory-storage.js

@@ -1,16 +1,43 @@
 /**
- * Memory-only storage adapter (fallback, no actual persistence)
+ * @fileoverview Memory-only storage adapter (fallback, no actual persistence).
+ *
+ * Provides in-memory storage for testing or when persistent storage is unavailable.
+ * Data is shared across instances with the same namespace but lost on process restart.
+ *
+ * @module storage/memory-storage
  */
 
 import { PersistentStorage } from './persistent-storage.js';
 
+/**
+ * Memory-only storage adapter.
+ *
+ * Stores data in memory with no persistence across restarts.
+ * Uses a global store to share data across instances with same namespace.
+ *
+ * @class MemoryStorage
+ * @extends PersistentStorage
+ * @example
+ * const storage = new MemoryStorage();
+ * await storage.init('myapp');
+ * await storage.put('key1', { id: 'event1' });
+ */
 export class MemoryStorage extends PersistentStorage {
+  /**
+   * Create a new MemoryStorage instance.
+   */
   constructor() {
     super();
     this.data = new Map();
     this.namespace = null;
   }
 
+  /**
+   * Initialize storage with namespace.
+   *
+   * @param {string} namespace - Storage namespace
+   * @returns {Promise<void>}
+   */
   async init(namespace) {
     this.namespace = namespace;
     // Check if there's existing data for this namespace
@@ -23,18 +50,33 @@ export class MemoryStorage extends PersistentStorage {
     this.data = MemoryStorage._globalStore.get(namespace);
   }
 
+  /**
+   * Store an event.
+   *
+   * @param {string} key - Storage key
+   * @param {Object} event - Event data
+   * @returns {Promise<void>}
+   */
   async put(key, event) {
     this.data.set(key, JSON.parse(JSON.stringify(event))); // Deep clone
   }
 
+  /**
+   * Retrieve an event.
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<Object|null>} Event data or null
+   */
   async get(key) {
     const data = this.data.get(key);
     return data ? JSON.parse(JSON.stringify(data)) : null; // Deep clone
   }
 
   /**
-   * @param {string} prefix
-   * @returns {Promise<any[]>}
+   * Retrieve all events matching a prefix.
+   *
+   * @param {string} prefix - Key prefix to match
+   * @returns {Promise<any[]>} Array of matching events
    */
   async getAll(prefix) {
     /** @type {any[]} */
@@ -47,18 +89,37 @@ export class MemoryStorage extends PersistentStorage {
     return results;
   }
 
+  /**
+   * Delete an event.
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<void>}
+   */
   async delete(key) {
     this.data.delete(key);
   }
 
+  /**
+   * Clear all stored events.
+   *
+   * @returns {Promise<void>}
+   */
   async clear() {
     this.data.clear();
   }
 
+  /**
+   * Close storage (no-op for memory storage).
+   *
+   * @returns {Promise<void>}
+   */
   async close() {
     // Nothing to close for memory storage
   }
 }
 
-// Global store shared across instances with same namespace
+/**
+ * Global store shared across instances with same namespace.
+ * @private
+ */
 MemoryStorage._globalStore = null;

package/src/storage/migration.js

@@ -1,11 +1,8 @@
 /**
- * Migration Tool for HoloSphere Storage Backends
- *
- * Enables data migration between different storage backends:
- * - Export data from any backend to a portable format
- * - Import data to any backend from the portable format
- * - Direct migration between backends
- * - Validation of migrated data
+ * @fileoverview Migration tool for HoloSphere storage backends.
+ * Enables data migration between different storage backends (Nostr, GunDB, ActivityPub)
+ * with export/import functionality, direct migration, and validation.
+ * @module storage/migration
  */
 
 import { BackendFactory } from './backend-factory.js';
@@ -38,9 +35,25 @@ import { BackendFactory } from './backend-factory.js';
  * @property {Object[]} errors - Error details
  */
 
+/**
+ * Migration tool for transferring data between HoloSphere storage backends.
+ * Supports export/import to portable format, direct migration, and validation.
+ *
+ * @class MigrationTool
+ * @example
+ * const tool = new MigrationTool();
+ * await tool.setSource('nostr', { relays: ['wss://...'] });
+ * await tool.setTarget('gundb', { peers: ['wss://...'] });
+ * const results = await tool.migrate();
+ */
 export class MigrationTool {
+  /**
+   * Create a new MigrationTool instance.
+   */
   constructor() {
+    /** @type {StorageBackend|null} */
     this.sourceBackend = null;
+    /** @type {StorageBackend|null} */
     this.targetBackend = null;
   }
 

package/src/storage/nostr-async.js

@@ -1,34 +1,52 @@
 /**
- * Nostr Async Utilities
- * Provides Promise-based wrappers and async patterns for Nostr operations
+ * @fileoverview Nostr Async Utilities.
+ *
+ * Provides Promise-based wrappers and async patterns for Nostr operations.
+ * Includes local-first data access, query deduplication, subscription management,
+ * and background refresh capabilities for optimal performance.
+ *
+ * @module storage/nostr-async
  */
 
 /**
- * Global subscription manager to prevent duplicate subscriptions
+ * Global subscription manager to prevent duplicate subscriptions.
  * Maps: subscriptionKey -> subscription object
+ * @private
  */
 const globalSubscriptions = new Map();
 
 /**
- * Single-path subscription manager (for nostrSubscribe)
+ * Single-path subscription manager (for nostrSubscribe).
  * Maps: subscriptionKey -> { subscription, callbacks: [] }
+ * @private
  */
 const singlePathSubscriptions = new Map();
 
 /**
- * Query deduplication for nostrGet - prevents duplicate relay queries
+ * Query deduplication for nostrGet - prevents duplicate relay queries.
  * Maps: queryKey -> { promise, timestamp, callbacks: [] }
+ * @private
  */
 const pendingQueries = new Map();
-const QUERY_DEDUP_WINDOW = 2000; // 2 second window for deduplication
 
 /**
- * Write data as Nostr event (parameterized replaceable event)
+ * Time window for query deduplication (2 seconds).
+ * @private
+ * @constant {number}
+ */
+const QUERY_DEDUP_WINDOW = 2000;
+
+/**
+ * Write data as Nostr event (parameterized replaceable event).
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path identifier (encoded in d-tag)
  * @param {Object} data - Data to store
- * @param {number} kind - Event kind (default: 30000 for parameterized replaceable)
- * @returns {Promise<Object>} Published event result
+ * @param {number} [kind=30000] - Event kind (default: 30000 for parameterized replaceable)
+ * @returns {Promise<Object>} Published event result with relay responses
+ * @example
+ * const result = await nostrPut(client, 'myapp/holon123/items/item1', { name: 'Test' });
+ * console.log(result.event.id); // Event ID
  */
 export async function nostrPut(client, path, data, kind = 30000) {
   const dataEvent = {
@@ -45,17 +63,25 @@ export async function nostrPut(client, path, data, kind = 30000) {
 }
 
 /**
- * Read data from Nostr (query by d-tag)
- * LOCAL-FIRST: Checks persistent storage first, never blocks on network
- * Uses query deduplication to prevent duplicate relay queries within a time window
+ * Read data from Nostr (query by d-tag).
+ *
+ * LOCAL-FIRST: Checks persistent storage first, never blocks on network.
+ * Uses query deduplication to prevent duplicate relay queries within a time window.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path identifier
- * @param {number} kind - Event kind (default: 30000)
- * @param {Object} options - Query options
- * @param {string[]} options.authors - Array of public keys to query (default: [client.publicKey])
- * @param {boolean} options.includeAuthor - If true, adds _author field to returned data
- * @param {boolean} options.skipPersistent - If true, skip persistent storage check (default: false)
+ * @param {number} [kind=30000] - Event kind (default: 30000)
+ * @param {Object} [options={}] - Query options
+ * @param {string[]} [options.authors] - Array of public keys to query (default: [client.publicKey])
+ * @param {boolean} [options.includeAuthor=false] - If true, adds _author field to returned data
+ * @param {boolean} [options.skipPersistent=false] - If true, skip persistent storage check
+ * @param {number} [options.timeout=30000] - Query timeout in milliseconds
  * @returns {Promise<Object|null>} Data or null if not found
+ * @example
+ * const data = await nostrGet(client, 'myapp/holon1/items/item1');
+ * if (data) {
+ *   console.log(data.name);
+ * }
  */
 export async function nostrGet(client, path, kind = 30000, options = {}) {
   const timeout = options.timeout !== undefined ? options.timeout : 30000;
@@ -72,8 +98,8 @@ export async function nostrGet(client, path, kind = 30000, options = {}) {
         try {
           const data = JSON.parse(persistedEvent.content);
 
-          // Skip deleted items
-          if (data._deleted) {
+          // Skip null/undefined or deleted items
+          if (!data || data._deleted) {
             return null;
           }
 
@@ -128,8 +154,16 @@ export async function nostrGet(client, path, kind = 30000, options = {}) {
 }
 
 /**
- * Internal function to execute nostrGet query
+ * Internal function to execute nostrGet query.
+ *
  * @private
+ * @param {Object} client - NostrClient instance
+ * @param {string} path - Path identifier
+ * @param {number} kind - Event kind
+ * @param {string[]} authors - Array of author public keys
+ * @param {number} timeout - Query timeout
+ * @param {Object} options - Query options
+ * @returns {Promise<Object|null>} Data or null
  */
 async function _executeNostrGet(client, path, kind, authors, timeout, options) {
   const filter = {
@@ -153,8 +187,8 @@ async function _executeNostrGet(client, path, kind, authors, timeout, options) {
 
   try {
     const data = JSON.parse(event.content);
-    // Skip deleted items
-    if (data._deleted) {
+    // Skip null/undefined or deleted items
+    if (!data || data._deleted) {
       return null;
     }
     // Optionally include author information
@@ -169,17 +203,24 @@ async function _executeNostrGet(client, path, kind, authors, timeout, options) {
 }
 
 /**
- * Query all events under a path prefix
- * LOCAL-FIRST: Checks persistent storage first, never blocks on network
- * Uses query deduplication to prevent duplicate relay queries within a time window
+ * Query all events under a path prefix.
+ *
+ * LOCAL-FIRST: Checks persistent storage first, never blocks on network.
+ * Uses query deduplication to prevent duplicate relay queries within a time window.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} pathPrefix - Path prefix to match
- * @param {number} kind - Event kind (default: 30000)
- * @param {Object} options - Query options
- * @param {string[]} options.authors - Array of public keys to query (default: [client.publicKey])
- * @param {boolean} options.includeAuthor - If true, adds _author field to returned data
- * @param {boolean} options.skipPersistent - If true, skip persistent storage check (default: false)
+ * @param {number} [kind=30000] - Event kind (default: 30000)
+ * @param {Object} [options={}] - Query options
+ * @param {string[]} [options.authors] - Array of public keys to query (default: [client.publicKey])
+ * @param {boolean} [options.includeAuthor=false] - If true, adds _author field to returned data
+ * @param {boolean} [options.skipPersistent=false] - If true, skip persistent storage check
+ * @param {number} [options.timeout=30000] - Query timeout in milliseconds
+ * @param {number} [options.limit=1000] - Maximum number of events to retrieve
  * @returns {Promise<Array>} Array of data objects
+ * @example
+ * const items = await nostrGetAll(client, 'myapp/holon1/items/');
+ * console.log(`Found ${items.length} items`);
  */
 export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}) {
   const timeout = options.timeout !== undefined ? options.timeout : 30000;
@@ -208,8 +249,8 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
           try {
             const data = JSON.parse(event.content);
 
-            // Handle deleted items - remove from map if this is newer
-            if (data._deleted) {
+            // Handle null/undefined or deleted items - remove from map if this is newer
+            if (!data || data._deleted) {
               byPath.delete(path);
               continue;
             }
@@ -266,8 +307,17 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
 }
 
 /**
- * Internal function to execute nostrGetAll query
+ * Internal function to execute nostrGetAll query.
+ *
  * @private
+ * @param {Object} client - NostrClient instance
+ * @param {string} pathPrefix - Path prefix to match
+ * @param {number} kind - Event kind
+ * @param {string[]} authors - Array of author public keys
+ * @param {number} timeout - Query timeout
+ * @param {number} limit - Maximum results
+ * @param {Object} options - Query options
+ * @returns {Promise<Array>} Array of data objects
  */
 async function _executeNostrGetAll(client, pathPrefix, kind, authors, timeout, limit, options) {
   const filter = {
@@ -296,8 +346,8 @@ async function _executeNostrGetAll(client, pathPrefix, kind, authors, timeout, l
       try {
         const data = JSON.parse(event.content);
 
-        // Handle deleted items - remove from map if this is newer
-        if (data._deleted) {
+        // Handle null/undefined or deleted items - remove from map if this is newer
+        if (!data || data._deleted) {
           byPath.delete(dTag);
           continue;
         }
@@ -318,14 +368,18 @@ async function _executeNostrGetAll(client, pathPrefix, kind, authors, timeout, l
 }
 
 /**
- * Query all events under a path prefix (HYBRID MODE - local + relay)
- * Checks local cache first, then merges with relay data
+ * Query all events under a path prefix (HYBRID MODE - local + relay).
+ *
+ * Checks local cache first, then merges with relay data.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} pathPrefix - Path prefix to match
- * @param {number} kind - Event kind (default: 30000)
- * @param {Object} options - Query options
- * @param {string[]} options.authors - Array of public keys to query (default: [client.publicKey])
- * @param {boolean} options.includeAuthor - If true, adds _author field to returned data
+ * @param {number} [kind=30000] - Event kind (default: 30000)
+ * @param {Object} [options={}] - Query options
+ * @param {string[]} [options.authors] - Array of public keys to query (default: [client.publicKey])
+ * @param {boolean} [options.includeAuthor=false] - If true, adds _author field to returned data
+ * @param {number} [options.timeout=30000] - Query timeout in milliseconds
+ * @param {number} [options.limit=1000] - Maximum number of events to retrieve
  * @returns {Promise<Array>} Array of data objects (merged from local + relay)
  */
 export async function nostrGetAllHybrid(client, pathPrefix, kind = 30000, options = {}) {
@@ -386,11 +440,19 @@ export async function nostrGetAllHybrid(client, pathPrefix, kind = 30000, option
 }
 
 /**
- * Delete data (publish deletion event - NIP-09)
+ * Delete data (publish deletion event - NIP-09).
+ *
+ * Publishes a tombstone event and a NIP-09 deletion event to mark data as deleted.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path identifier
- * @param {number} kind - Original event kind (default: 30000)
- * @returns {Promise<Object>} Deletion event result
+ * @param {number} [kind=30000] - Original event kind (default: 30000)
+ * @returns {Promise<Object>} Deletion event result with status
+ * @example
+ * const result = await nostrDelete(client, 'myapp/holon1/items/item1');
+ * if (result.reason !== 'not_found') {
+ *   console.log('Item deleted successfully');
+ * }
  */
 export async function nostrDelete(client, path, kind = 30000) {
   // Read existing data first
@@ -447,11 +509,15 @@ export async function nostrDelete(client, path, kind = 30000) {
 }
 
 /**
- * Delete all data with path prefix (publish deletion events - NIP-09)
+ * Delete all data with path prefix (publish deletion events - NIP-09).
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} pathPrefix - Path prefix to delete all items under
- * @param {number} kind - Original event kind (default: 30000)
- * @returns {Promise<Object>} Deletion results
+ * @param {number} [kind=30000] - Original event kind (default: 30000)
+ * @returns {Promise<Object>} Deletion results with success count
+ * @example
+ * const result = await nostrDeleteAll(client, 'myapp/holon1/items/');
+ * console.log(`Deleted ${result.count} items`);
  */
 export async function nostrDeleteAll(client, pathPrefix, kind = 30000) {
   // Query events from relay
@@ -566,13 +632,21 @@ export async function nostrDeleteAll(client, pathPrefix, kind = 30000) {
 }
 
 /**
- * Subscribe to path changes
- * Uses subscription deduplication - multiple subscribers to same path share one relay subscription
+ * Subscribe to path changes.
+ *
+ * Uses subscription deduplication - multiple subscribers to same path share one relay subscription.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path to subscribe to
  * @param {Function} callback - Callback function (data, event) => void
- * @param {Object} options - Subscription options
+ * @param {Object} [options={}] - Subscription options
+ * @param {number} [options.kind=30000] - Event kind to subscribe to
  * @returns {Object} Subscription object with unsubscribe method
+ * @example
+ * const sub = nostrSubscribe(client, 'myapp/holon1/items/item1', (data, event) => {
+ *   console.log('Item updated:', data);
+ * });
+ * // Later: sub.unsubscribe();
  */
 export function nostrSubscribe(client, path, callback, options = {}) {
   const kind = options.kind || 30000;
@@ -631,8 +705,8 @@ export function nostrSubscribe(client, path, callback, options = {}) {
       try {
         const data = JSON.parse(event.content);
 
-        // Skip deleted items - don't send tombstones to subscribers
-        if (data._deleted) {
+        // Skip null/undefined or deleted items - don't send tombstones to subscribers
+        if (!data || data._deleted) {
           return;
         }
 
@@ -674,7 +748,7 @@ export function nostrSubscribe(client, path, callback, options = {}) {
 }
 
 /**
- * Subscribe to path prefix (multiple paths)
+ * Subscribe to path prefix (multiple paths).
  *
  * Subscribes to data events and uses Page Visibility API to refresh when tab becomes visible.
  * Note: Nostr relays do not broadcast replaceable event updates to active subscriptions.
@@ -682,8 +756,14 @@ export function nostrSubscribe(client, path, callback, options = {}) {
  * @param {Object} client - NostrClient instance
  * @param {string} pathPrefix - Path prefix to match
  * @param {Function} callback - Callback function (data, path, event) => void
- * @param {Object} options - Subscription options
+ * @param {Object} [options={}] - Subscription options
+ * @param {number} [options.kind=30000] - Event kind to subscribe to
  * @returns {Promise<Object>} Subscription object with unsubscribe method
+ * @example
+ * const sub = await nostrSubscribeMany(client, 'myapp/holon1/items/', (data, path, event) => {
+ *   console.log('Item event:', data);
+ * });
+ * // Later: sub.unsubscribe();
  */
 export async function nostrSubscribeMany(client, pathPrefix, callback, options = {}) {
   const kind = options.kind || 30000;
@@ -758,8 +838,8 @@ export async function nostrSubscribeMany(client, pathPrefix, callback, options =
       try {
         const data = JSON.parse(event.content);
 
-        // Skip deleted items - don't send tombstones to subscribers
-        if (data._deleted) {
+        // Skip null/undefined data or deleted items - don't send tombstones to subscribers
+        if (!data || data._deleted) {
           return;
         }
 
@@ -844,12 +924,16 @@ export async function nostrSubscribeMany(client, pathPrefix, callback, options =
 }
 
 /**
- * Update data (merge with existing)
+ * Update data (merge with existing).
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path identifier
  * @param {Object} updates - Fields to update
- * @param {number} kind - Event kind (default: 30000)
+ * @param {number} [kind=30000] - Event kind (default: 30000)
  * @returns {Promise<Object>} Updated event result
+ * @throws {Error} If no data found at path
+ * @example
+ * await nostrUpdate(client, 'myapp/holon1/items/item1', { status: 'completed' });
  */
 export async function nostrUpdate(client, path, updates, kind = 30000) {
   // Read existing data
@@ -867,10 +951,11 @@ export async function nostrUpdate(client, path, updates, kind = 30000) {
 }
 
 /**
- * Batch read multiple paths
+ * Batch read multiple paths.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string[]} paths - Array of paths
- * @param {number} kind - Event kind (default: 30000)
+ * @param {number} [kind=30000] - Event kind (default: 30000)
  * @returns {Promise<Object>} Object mapping paths to data
  */
 export async function nostrBatchGet(client, paths, kind = 30000) {
@@ -911,10 +996,11 @@ export async function nostrBatchGet(client, paths, kind = 30000) {
 }
 
 /**
- * Batch write multiple paths
+ * Batch write multiple paths.
+ *
  * @param {Object} client - NostrClient instance
  * @param {Object} pathDataMap - Object mapping paths to data
- * @param {number} kind - Event kind (default: 30000)
+ * @param {number} [kind=30000] - Event kind (default: 30000)
  * @returns {Promise<Array>} Array of publish results
  */
 export async function nostrBatchPut(client, pathDataMap, kind = 30000) {
@@ -926,11 +1012,13 @@ export async function nostrBatchPut(client, pathDataMap, kind = 30000) {
 }
 
 /**
- * Retry operation with exponential backoff
+ * Retry operation with exponential backoff.
+ *
  * @param {Function} operation - Async function to retry
- * @param {number} maxRetries - Max retry attempts (default: 3)
- * @param {number} baseDelay - Base delay in ms (default: 100ms)
+ * @param {number} [maxRetries=3] - Max retry attempts
+ * @param {number} [baseDelay=100] - Base delay in ms
  * @returns {Promise<any>} Promise resolving to operation result
+ * @throws {Error} Last error if all retries fail
  */
 export async function nostrRetry(operation, maxRetries = 3, baseDelay = 100) {
   let lastError;
@@ -951,12 +1039,14 @@ export async function nostrRetry(operation, maxRetries = 3, baseDelay = 100) {
 }
 
 /**
- * Wait for specific condition on data
+ * Wait for specific condition on data.
+ *
  * @param {Object} client - NostrClient instance
  * @param {string} path - Path to watch
  * @param {Function} predicate - Condition function (data) => boolean
- * @param {number} timeout - Timeout in ms (default: 5000ms)
+ * @param {number} [timeout=5000] - Timeout in ms
  * @returns {Promise<any>} Promise resolving when condition is met
+ * @throws {Error} If timeout occurs before condition is met
  */
 export async function nostrWaitFor(client, path, predicate, timeout = 5000) {
   return new Promise((resolve, reject) => {