holosphere 2.0.0-alpha1 → 2.0.0-alpha11

package/src/storage/backends/nostr-backend.js

@@ -1,18 +1,52 @@
 /**
- * Nostr Storage Backend
+ * @fileoverview Nostr Storage Backend.
+ *
  * Wraps existing nostr-wrapper.js and nostr-client.js as a StorageBackend
+ * implementation. Provides Nostr-based distributed storage with relay support.
+ *
+ * @module storage/backends/nostr-backend
  */
 
 import { StorageBackend } from '../backend-interface.js';
 import { createClient } from '../nostr-client.js';
 import * as wrapper from '../nostr-wrapper.js';
 
+/**
+ * Nostr storage backend implementation.
+ *
+ * Provides distributed storage using Nostr relays with event-based data storage.
+ *
+ * @class NostrBackend
+ * @extends StorageBackend
+ * @example
+ * const backend = new NostrBackend({
+ *   relays: ['wss://relay.example.com'],
+ *   appName: 'myapp',
+ *   persistence: true
+ * });
+ * await backend.init();
+ */
 export class NostrBackend extends StorageBackend {
+  /**
+   * Create a new NostrBackend.
+   *
+   * @param {Object} config - Backend configuration
+   * @param {string[]} [config.relays] - Relay URLs
+   * @param {string} [config.privateKey] - Private key for signing
+   * @param {string} [config.appName] - Application name
+   * @param {boolean} [config.persistence=true] - Enable persistent storage
+   * @param {boolean} [config.backgroundSync] - Enable background sync
+   */
   constructor(config) {
     super(config);
     this.client = null;
   }
 
+  /**
+   * Initialize the backend.
+   *
+   * @returns {Promise<void>}
+   */
   async init() {
     this.client = createClient({
       relays: this.config.relays || ['wss://relay.holons.io'],
@@ -32,38 +66,102 @@ export class NostrBackend extends StorageBackend {
     this.publicKey = this.client.publicKey;
   }
 
+  /**
+   * Build path from components.
+   *
+   * @param {string} appName - Application name
+   * @param {string} holonId - Holon ID
+   * @param {string} lensName - Lens name
+   * @param {string} [key=null] - Optional key
+   * @returns {string} Built path
+   */
   buildPath(appName, holonId, lensName, key = null) {
     return wrapper.buildPath(appName, holonId, lensName, key);
   }
 
+  /**
+   * Write data to path.
+   *
+   * @param {string} path - Storage path
+   * @param {Object} data - Data to write
+   * @param {Object} [options={}] - Write options
+   * @returns {Promise<Object>} Write result
+   */
   async write(path, data, options = {}) {
     return wrapper.write(this.client, path, data);
   }
 
+  /**
+   * Read data from path.
+   *
+   * @param {string} path - Storage path
+   * @param {Object} [options={}] - Read options
+   * @returns {Promise<Object|null>} Data or null
+   */
   async read(path, options = {}) {
     return wrapper.read(this.client, path, options);
   }
 
+  /**
+   * Read all data under path.
+   *
+   * @param {string} path - Storage path prefix
+   * @param {Object} [options={}] - Read options
+   * @returns {Promise<Object[]>} Array of data objects
+   */
   async readAll(path, options = {}) {
     return wrapper.readAll(this.client, path, options);
   }
 
+  /**
+   * Update data at path.
+   *
+   * @param {string} path - Storage path
+   * @param {Object} updates - Fields to update
+   * @returns {Promise<Object>} Update result
+   */
   async update(path, updates) {
     return wrapper.update(this.client, path, updates);
   }
 
+  /**
+   * Delete data at path.
+   *
+   * @param {string} path - Storage path
+   * @returns {Promise<boolean>} Success indicator
+   */
   async delete(path) {
     return wrapper.deleteData(this.client, path);
   }
 
+  /**
+   * Delete all data under path.
+   *
+   * @param {string} path - Storage path prefix
+   * @returns {Promise<Object>} Deletion results
+   */
   async deleteAll(path) {
     return wrapper.deleteAll(this.client, path);
   }
 
+  /**
+   * Subscribe to changes at path.
+   *
+   * @param {string} path - Storage path
+   * @param {Function} callback - Callback function
+   * @param {Object} [options={}] - Subscribe options
+   * @returns {Promise<Object>} Subscription object with unsubscribe method
+   */
   async subscribe(path, callback, options = {}) {
     return wrapper.subscribe(this.client, path, callback, options);
   }
 
+  /**
+   * Export all data for this user.
+   *
+   * @param {string} [pathPrefix=''] - Optional path prefix filter
+   * @returns {Promise<Object[]>} Array of exported records
+   */
   async exportData(pathPrefix = '') {
     // Wait for client to be ready
     await this.client._initReady;
@@ -101,6 +199,13 @@ export class NostrBackend extends StorageBackend {
       .filter(record => !record.data._deleted); // Filter out deleted items
   }
 
+  /**
+   * Import data records.
+   *
+   * @param {Object[]} records - Array of records to import
+   * @param {Object} [options={}] - Import options
+   * @returns {Promise<Object>} Import results with success/failed counts
+   */
   async importData(records, options = {}) {
     const results = { success: 0, failed: 0, errors: [] };
 
@@ -117,12 +222,22 @@ export class NostrBackend extends StorageBackend {
     return results;
   }
 
+  /**
+   * Close the backend and cleanup resources.
+   *
+   * @returns {void}
+   */
   close() {
     if (this.client) {
       this.client.close();
     }
   }
 
+  /**
+   * Get backend status.
+   *
+   * @returns {Object} Status object with type, publicKey, relays, connected
+   */
   getStatus() {
     return {
       type: 'nostr',

package/src/storage/filesystem-storage-browser.js

@@ -1,40 +1,80 @@
 /**
- * Browser stub for FileSystemStorage
- * Throws an error if used in browser environment
+ * @fileoverview Browser stub for FileSystemStorage.
+ *
+ * This stub throws errors if FileSystemStorage is used in browser environments.
+ * Browsers should use IndexedDBStorage or MemoryStorage instead.
+ *
+ * @module storage/filesystem-storage-browser
  */
 
 import { PersistentStorage } from './persistent-storage.js';
 
+/**
+ * Browser stub for FileSystemStorage.
+ *
+ * All methods throw errors indicating filesystem storage is unavailable in browsers.
+ *
+ * @class FileSystemStorage
+ * @extends PersistentStorage
+ * @throws {Error} Always throws - not available in browser environments
+ */
 export class FileSystemStorage extends PersistentStorage {
+  /**
+   * Constructor throws error in browser.
+   *
+   * @param {string} [baseDir=null] - Ignored in browser
+   * @throws {Error} Always throws - not available in browser
+   */
   constructor(baseDir = null) {
     super();
     throw new Error('FileSystemStorage is not available in browser environments. Use IndexedDBStorage or MemoryStorage instead.');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async init(namespace) {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async put(key, event) {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async get(key) {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async getAll(prefix) {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async delete(key) {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async clear() {
     throw new Error('FileSystemStorage is not available in browser environments');
   }
 
+  /**
+   * @throws {Error} Always throws - not available in browser
+   */
   async close() {
     throw new Error('FileSystemStorage is not available in browser environments');
   }

package/src/storage/filesystem-storage.js

@@ -1,7 +1,10 @@
 /**
- * File system storage adapter for Node.js
- * Stores events as JSON files in a directory structure
- * This module is only loaded in Node.js environments
+ * @fileoverview File system storage adapter for Node.js.
+ *
+ * Stores events as JSON files in a directory structure.
+ * This module is only loaded in Node.js environments.
+ *
+ * @module storage/filesystem-storage
  */
 
 // Guard against browser environments
@@ -14,7 +17,24 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 
+/**
+ * File system storage adapter for Node.js.
+ *
+ * Stores events as JSON files in a directory structure for persistent storage.
+ *
+ * @class FileSystemStorage
+ * @extends PersistentStorage
+ * @example
+ * const storage = new FileSystemStorage('/custom/path');
+ * await storage.init('myapp');
+ * await storage.put('key1', { id: 'event1', data: 'test' });
+ */
 export class FileSystemStorage extends PersistentStorage {
+  /**
+   * Create a new FileSystemStorage instance.
+   *
+   * @param {string} [baseDir=null] - Base directory for storage (defaults to ~/.holosphere)
+   */
   constructor(baseDir = null) {
     super();
     this.baseDir = baseDir || path.join(os.homedir(), '.holosphere');
@@ -22,6 +42,12 @@ export class FileSystemStorage extends PersistentStorage {
     this.storageDir = null;
   }
 
+  /**
+   * Initialize storage with namespace.
+   *
+   * @param {string} namespace - Storage namespace (app name)
+   * @returns {Promise<void>}
+   */
   async init(namespace) {
     this.namespace = namespace;
     this.storageDir = path.join(this.baseDir, namespace);
@@ -37,8 +63,11 @@ export class FileSystemStorage extends PersistentStorage {
   }
 
   /**
-   * Convert key to safe filename
+   * Convert key to safe filename.
+   *
    * @private
+   * @param {string} key - Storage key
+   * @returns {string} Safe filename
    */
   _keyToFilename(key) {
     // Replace unsafe characters
@@ -46,19 +75,35 @@ export class FileSystemStorage extends PersistentStorage {
   }
 
   /**
-   * Get full file path for key
+   * Get full file path for key.
+   *
    * @private
+   * @param {string} key - Storage key
+   * @returns {string} Full file path
    */
   _getFilePath(key) {
     return path.join(this.storageDir, this._keyToFilename(key));
   }
 
+  /**
+   * Store an event.
+   *
+   * @param {string} key - Storage key
+   * @param {Object} event - Event data to store
+   * @returns {Promise<void>}
+   */
   async put(key, event) {
     const filePath = this._getFilePath(key);
     const data = JSON.stringify(event, null, 2);
     await fs.writeFile(filePath, data, 'utf8');
   }
 
+  /**
+   * Retrieve an event.
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<Object|null>} Event data or null if not found
+   */
   async get(key) {
     const filePath = this._getFilePath(key);
     try {
@@ -72,6 +117,12 @@ export class FileSystemStorage extends PersistentStorage {
     }
   }
 
+  /**
+   * Retrieve all events matching a prefix.
+   *
+   * @param {string} prefix - Key prefix to match
+   * @returns {Promise<Object[]>} Array of matching events
+   */
   async getAll(prefix) {
     const results = [];
 
@@ -108,6 +159,12 @@ export class FileSystemStorage extends PersistentStorage {
     return results;
   }
 
+  /**
+   * Delete an event.
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<void>}
+   */
   async delete(key) {
     const filePath = this._getFilePath(key);
     try {
@@ -119,6 +176,11 @@ export class FileSystemStorage extends PersistentStorage {
     }
   }
 
+  /**
+   * Clear all stored events.
+   *
+   * @returns {Promise<void>}
+   */
   async clear() {
     try {
       const files = await fs.readdir(this.storageDir);
@@ -132,6 +194,11 @@ export class FileSystemStorage extends PersistentStorage {
     }
   }
 
+  /**
+   * Close storage (no-op for filesystem).
+   *
+   * @returns {Promise<void>}
+   */
   async close() {
     // Nothing to close for file system storage
   }

package/src/storage/global-tables.js

@@ -1,9 +1,14 @@
 /**
- * Global Data Operations
- * Non-location-specific storage (FR-044, FR-045)
+ * @fileoverview Global Data Operations.
+ *
+ * Provides non-location-specific (non-holon) data storage operations.
+ * Used for storing application-wide data like federation configs, schemas,
+ * and user preferences that aren't tied to specific H3 cells.
+ *
+ * @module storage/global-tables
  */
 
-import { write, read, readAll, update, deleteData, deleteAll } from './nostr-wrapper.js';
+import { write, read, readAll, update, deleteData, deleteAll, subscribe } from './unified-storage.js';
 
 /**
  * Write data to global table
@@ -79,3 +84,30 @@ export async function deleteAllGlobal(client, appname, table) {
   const path = `${appname}/${table}`;
   return deleteAll(client, path);
 }
+
+/**
+ * Get all data from global table
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} table - Global table name
+ * @returns {Promise<Object[]>} Array of data objects
+ */
+export async function getAllGlobal(client, appname, table) {
+  const path = `${appname}/${table}`;
+  return readAll(client, path);
+}
+
+/**
+ * Subscribe to global table changes
+ * @param {Object} client - Nostr client instance
+ * @param {string} appname - Application namespace
+ * @param {string} table - Global table name
+ * @param {string} key - Data key (optional, if not provided subscribes to all)
+ * @param {Function} callback - Called on data changes
+ * @param {Object} options - Subscription options
+ * @returns {Promise<Object>} Subscription object with unsubscribe method
+ */
+export async function subscribeGlobal(client, appname, table, key, callback, options = {}) {
+  const path = key ? `${appname}/${table}/${key}` : `${appname}/${table}`;
+  return subscribe(client, path, callback, options);
+}

package/src/storage/gun-async.js

@@ -1,13 +1,18 @@
 /**
- * Gun Async Utilities
- * Provides Promise-based wrappers and async patterns for Gun operations
+ * @fileoverview Gun Async Utilities.
+ *
+ * Provides Promise-based wrappers and async patterns for Gun operations.
+ * Includes utilities for promises, batch operations, retries, streams, and async iteration.
+ *
+ * @module storage/gun-async
  */
 
 /**
- * Get data from Gun using native .then() support
+ * Get data from Gun using native .then() support.
+ *
  * @param {Object} gunChain - Gun chain reference
- * @param {number} timeout - Timeout in ms (default 1000ms)
- * @returns {Promise<any>} Promise resolving to data
+ * @param {number} [timeout=1000] - Timeout in ms
+ * @returns {Promise<any>} Promise resolving to data or null on timeout
  */
 export function gunPromise(gunChain, timeout = 1000) {
   return new Promise((resolve, reject) => {
@@ -31,11 +36,13 @@ export function gunPromise(gunChain, timeout = 1000) {
 }
 
 /**
- * Wait for Gun write acknowledgement
+ * Wait for Gun write acknowledgement.
+ *
  * @param {Object} gunChain - Gun chain reference
  * @param {any} data - Data to write
- * @param {number} timeout - Timeout in ms (default 1000ms)
- * @returns {Promise<Object>} Promise resolving to ack object
+ * @param {number} [timeout=1000] - Timeout in ms
+ * @returns {Promise<Object>} Promise resolving to ack object { ok, timeout? }
+ * @throws {Error} If write fails with error
  */
 export function gunPut(gunChain, data, timeout = 1000) {
   return new Promise((resolve, reject) => {
@@ -63,23 +70,76 @@ export function gunPut(gunChain, data, timeout = 1000) {
 }
 
 /**
- * Get all items from a Gun map
+ * Get all items from a Gun map.
+ *
+ * First gets count of items, then collects until count is reached.
+ *
  * @param {Object} gunChain - Gun chain reference
- * @param {number} timeout - Timeout in ms (default 300ms)
+ * @param {number} [timeout=5000] - Timeout in ms (fallback)
  * @returns {Promise<Object>} Promise resolving to map of items
  */
-export async function gunMap(gunChain, timeout = 300) {
+export async function gunMap(gunChain, timeout = 5000) {
   return new Promise((resolve) => {
     const items = {};
+    let settled = false;
+    let expectedCount = 0;
+    let receivedCount = 0;
 
-    gunChain.map().once((data, key) => {
-      if (data && !key.startsWith('_')) {
-        items[key] = data;
+    const tryResolve = () => {
+      if (settled) return;
+      if (expectedCount > 0 && receivedCount >= expectedCount) {
+        settled = true;
+        resolve(items);
+      }
+    };
+
+    // Step 1: Get parent to count expected items
+    gunChain.once((parentData) => {
+      if (settled) return;
+
+      if (!parentData) {
+        settled = true;
+        resolve({});
+        return;
+      }
+
+      const keys = Object.keys(parentData).filter(k => k !== '_');
+      if (keys.length === 0) {
+        settled = true;
+        resolve({});
+        return;
       }
+
+      // Pre-collect inline items (not Gun references)
+      for (const key of keys) {
+        const rawItem = parentData[key];
+        if (!rawItem) continue;
+
+        // Skip Gun references - will be fetched via map().once()
+        if (typeof rawItem === 'object' && rawItem['#']) continue;
+
+        items[key] = rawItem;
+      }
+
+      // Expected count is ALL keys (map().once() fires for all)
+      expectedCount = keys.length;
+
+      // Step 2: Collect items via map().once(), counting as we go
+      gunChain.map().once((data, key) => {
+        if (settled || !data || key.startsWith('_')) return;
+        // Add/update the item (inline items may be updated by map().once())
+        items[key] = data;
+        receivedCount++;
+        tryResolve();
+      });
     });
 
+    // Fallback timeout
     setTimeout(() => {
-      resolve(items);
+      if (!settled) {
+        settled = true;
+        resolve(items);
+      }
     }, timeout);
   });
 }