holosphere 2.0.0-alpha7 → 2.0.0-alpha9

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;
@@ -65,28 +91,33 @@ export async function nostrGet(client, path, kind = 30000, options = {}) {
   if (!options.skipPersistent && client.persistentGet) {
     const persistedEvent = await client.persistentGet(path);
     if (persistedEvent && persistedEvent.content) {
-      try {
-        const data = JSON.parse(persistedEvent.content);
+      // Verify author is in requested authors list (persistent storage may have cached events from other authors)
+      if (!authors.includes(persistedEvent.pubkey)) {
+        // Author mismatch - fall through to relay query
+      } else {
+        try {
+          const data = JSON.parse(persistedEvent.content);
 
-        // Skip deleted items
-        if (data._deleted) {
-          return null;
-        }
+          // Skip null/undefined or deleted items
+          if (!data || data._deleted) {
+            return null;
+          }
 
-        // Optionally include author information
-        if (options.includeAuthor) {
-          data._author = persistedEvent.pubkey;
-        }
+          // Optionally include author information
+          if (options.includeAuthor) {
+            data._author = persistedEvent.pubkey;
+          }
 
-        // Trigger background refresh from relays (fire-and-forget)
-        if (client.refreshPathInBackground) {
-          client.refreshPathInBackground(path, kind, { authors, timeout });
-        }
+          // Trigger background refresh from relays (fire-and-forget)
+          if (client.refreshPathInBackground) {
+            client.refreshPathInBackground(path, kind, { authors, timeout });
+          }
 
-        return data;
-      } catch (error) {
-        // Fall through to relay query if parsing fails
-        console.warn('[nostrGet] Failed to parse persisted event:', error);
+          return data;
+        } catch (error) {
+          // Fall through to relay query if parsing fails
+          console.warn('[nostrGet] Failed to parse persisted event:', error);
+        }
       }
     }
   }
@@ -123,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 = {
@@ -136,17 +175,20 @@ async function _executeNostrGet(client, path, kind, authors, timeout, options) {
 
   const events = await client.query(filter, { timeout });
 
-  if (events.length === 0) {
+  // Filter by author (relays may not respect authors filter)
+  const authoredEvents = events.filter(event => authors.includes(event.pubkey));
+
+  if (authoredEvents.length === 0) {
     return null;
   }
 
-  // Get most recent event (across all authors)
-  const event = events.sort((a, b) => b.created_at - a.created_at)[0];
+  // Get most recent event (across allowed authors)
+  const event = authoredEvents.sort((a, b) => b.created_at - a.created_at)[0];
 
   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
@@ -161,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;
@@ -187,6 +236,9 @@ export async function nostrGetAll(client, pathPrefix, kind = 30000, options = {}
       for (const event of persistedEvents) {
         if (!event || !event.tags) continue;
 
+        // Verify author is in requested authors list (persistent storage may have cached events from other authors)
+        if (!authors.includes(event.pubkey)) continue;
+
         const dTag = event.tags.find(t => t[0] === 'd');
         if (!dTag || !dTag[1] || !dTag[1].startsWith(pathPrefix)) continue;
 
@@ -197,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;
             }
@@ -255,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 = {
@@ -267,10 +328,12 @@ async function _executeNostrGetAll(client, pathPrefix, kind, authors, timeout, l
 
   const events = await client.query(filter, { timeout });
 
-  // Filter by path prefix in application layer
+  // Filter by path prefix AND verify author (relays may not respect authors filter)
   const matching = events.filter(event => {
     const dTag = event.tags.find(t => t[0] === 'd');
-    return dTag && dTag[1] && dTag[1].startsWith(pathPrefix);
+    const pathMatches = dTag && dTag[1] && dTag[1].startsWith(pathPrefix);
+    const authorAllowed = authors.includes(event.pubkey);
+    return pathMatches && authorAllowed;
   });
 
   // Parse content and group by d-tag (keep latest only, across all authors)
@@ -283,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;
         }
@@ -305,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 = {}) {
@@ -331,10 +398,12 @@ export async function nostrGetAllHybrid(client, pathPrefix, kind = 30000, option
 
   const events = await queryMethod.call(client, filter, { timeout });
 
-  // Filter by path prefix in application layer
+  // Filter by path prefix AND verify author (relays may not respect authors filter)
   const matching = events.filter(event => {
     const dTag = event.tags.find(t => t[0] === 'd');
-    return dTag && dTag[1] && dTag[1].startsWith(pathPrefix);
+    const pathMatches = dTag && dTag[1] && dTag[1].startsWith(pathPrefix);
+    const authorAllowed = authors.includes(event.pubkey);
+    return pathMatches && authorAllowed;
   });
 
   // Parse content and group by d-tag (keep latest only)
@@ -371,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
@@ -432,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
@@ -551,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;
@@ -616,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;
         }
 
@@ -659,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.
@@ -667,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;
@@ -743,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;
         }
 
@@ -829,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
@@ -852,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) {
@@ -896,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) {
@@ -911,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;
@@ -936,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) => {