holosphere 2.0.0-alpha7 → 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;
   }