holosphere 2.0.0-alpha7 → 2.0.0-alpha9

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,6 +1,11 @@
 /**
- * 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, subscribe } from './unified-storage.js';

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,10 +70,12 @@ export function gunPut(gunChain, data, timeout = 1000) {
 }
 
 /**
- * Get all items from a Gun map
- * First gets count of items, then collects until count is reached
+ * 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 (fallback, default 5000ms)
+ * @param {number} [timeout=5000] - Timeout in ms (fallback)
  * @returns {Promise<Object>} Promise resolving to map of items
  */
 export async function gunMap(gunChain, timeout = 5000) {

package/src/storage/gun-auth.js

@@ -1,19 +1,30 @@
 /**
- * GunDB Authentication Handler
- * Handles user authentication and private data storage using Gun's user system
+ * @fileoverview GunDB Authentication Handler.
  *
+ * Handles user authentication and private data storage using Gun's user system.
  * Private data is stored under: user.get('private').get(lens).get(key)
  * Usernames are namespaced: ${appname}:${holonId}
+ *
+ * @module storage/gun-auth
  */
 
 import { gunPromise, gunPut } from './gun-async.js';
 
 /**
- * Authentication handler for GunDB backend
+ * Authentication handler for GunDB backend.
+ *
+ * Manages user creation, authentication, and private data access.
+ *
+ * @class GunAuth
+ * @example
+ * const auth = new GunAuth(gun, 'myapp');
+ * await auth.createUser('holon123', 'password');
+ * await auth.authenticate('holon123', 'password');
  */
 export class GunAuth {
   /**
-   * Create a new authentication handler
+   * Create a new authentication handler.
+   *
    * @param {Object} gun - Gun instance
    * @param {string} appname - Application namespace
    */

package/src/storage/gun-federation.js

@@ -1,19 +1,28 @@
 /**
- * GunDB Federation Module
- * Provides methods for creating, managing, and using federated spaces
+ * @fileoverview GunDB Federation Module.
  *
- * Ported from holosphere/federation.js to work with the GunDBBackend
+ * Provides methods for creating, managing, and using federated spaces.
+ * Supports data propagation with references for lightweight federation,
+ * aggregation across federated sources, and subscription to federated changes.
+ *
+ * Ported from holosphere/federation.js to work with the GunDBBackend.
+ *
+ * @module storage/gun-federation
  */
 
 /**
- * Creates a federation relationship between two spaces
+ * Creates a federation relationship between two spaces.
+ *
  * Federation is bidirectional by default, and data propagation uses soul references by default.
  *
  * @param {Object} backend - The GunDBBackend instance
  * @param {string} spaceId1 - The first space ID
  * @param {string} spaceId2 - The second space ID
- * @param {boolean} bidirectional - Whether to set up bidirectional notifications (default: true)
+ * @param {boolean} [bidirectional=true] - Whether to set up bidirectional notifications
  * @returns {Promise<boolean>} True if federation was created successfully
+ * @throws {Error} If space IDs are missing or identical
+ * @example
+ * await federate(backend, 'space1', 'space2');
  */
 export async function federate(backend, spaceId1, spaceId2, bidirectional = true) {
   if (!spaceId1 || !spaceId2) {

package/src/storage/gun-references.js

@@ -1,19 +1,30 @@
 /**
- * GunDB Reference Handler
- * Handles creation and resolution of data references for federation
+ * @fileoverview GunDB Reference Handler.
  *
+ * Handles creation and resolution of data references for federation.
  * References use a "soul" pattern: appname/holon/lens/key
- * This allows lightweight propagation without data duplication
+ * This allows lightweight propagation without data duplication.
+ *
+ * @module storage/gun-references
  */
 
 import { read } from './gun-wrapper.js';
 
 /**
- * Reference handler for GunDB backend
+ * Reference handler for GunDB backend.
+ *
+ * Manages creation, detection, and resolution of data references.
+ *
+ * @class GunReferenceHandler
+ * @example
+ * const handler = new GunReferenceHandler('myapp');
+ * const ref = handler.createReference('holon1', 'items', { id: '123', name: 'Test' });
+ * const resolved = await handler.resolveReference(gun, ref);
  */
 export class GunReferenceHandler {
   /**
-   * Create a new reference handler
+   * Create a new reference handler.
+   *
    * @param {string} appname - Application namespace
    */
   constructor(appname) {

package/src/storage/gun-schema.js

@@ -1,14 +1,20 @@
 /**
- * GunDB Schema Validator
- * Handles JSON Schema validation for data stored in GunDB
+ * @fileoverview GunDB Schema Validator.
  *
- * Schemas are stored in the global 'schemas' table
- * Validation uses AJV (Another JSON Schema Validator) with JSON Schema 2019
+ * Handles JSON Schema validation for data stored in GunDB.
+ * Schemas are stored in the global 'schemas' table.
+ * Validation uses AJV (Another JSON Schema Validator) with JSON Schema 2019.
+ *
+ * @module storage/gun-schema
  */
 
 import { writeGlobal, readGlobal, readAllGlobal, deleteGlobal } from './gun-wrapper.js';
 
-// Default meta-schema for validating schema definitions
+/**
+ * Default meta-schema for validating schema definitions.
+ * @private
+ * @constant {Object}
+ */
 const META_SCHEMA = {
   type: 'object',
   required: ['type'],
@@ -23,14 +29,23 @@ const META_SCHEMA = {
 };
 
 /**
- * Schema validator for GunDB backend
+ * Schema validator for GunDB backend.
+ *
+ * Provides JSON Schema validation with caching and lazy-loaded AJV.
+ *
+ * @class GunSchemaValidator
+ * @example
+ * const validator = new GunSchemaValidator({ strict: true });
+ * await validator.init();
+ * await validator.setSchema(gun, 'myapp', 'user', { type: 'object', properties: { name: { type: 'string' } } });
  */
 export class GunSchemaValidator {
   /**
-   * Create a new schema validator
-   * @param {Object} options - Validator options
-   * @param {boolean} options.strict - Whether to enforce strict validation (default: false)
-   * @param {number} options.cacheMaxAge - Schema cache TTL in ms (default: 3600000 = 1 hour)
+   * Create a new schema validator.
+   *
+   * @param {Object} [options={}] - Validator options
+   * @param {boolean} [options.strict=false] - Whether to enforce strict validation
+   * @param {number} [options.cacheMaxAge=3600000] - Schema cache TTL in ms (1 hour)
    */
   constructor(options = {}) {
     this.strict = options.strict || false;