holosphere 2.0.0-alpha1 → 2.0.0-alpha10

package/src/storage/indexeddb-storage.js

@@ -1,18 +1,48 @@
 /**
- * IndexedDB storage adapter for browsers
- * Provides persistent storage with good performance
+ * @fileoverview IndexedDB storage adapter for browsers.
+ *
+ * Provides persistent storage with good performance using browser IndexedDB.
+ * Uses B-tree indexes for efficient prefix queries.
+ *
+ * @module storage/indexeddb-storage
  */
 
 import { PersistentStorage } from './persistent-storage.js';
 
+/**
+ * IndexedDB storage adapter for browsers.
+ *
+ * Provides high-performance persistent storage using IndexedDB with efficient prefix queries.
+ *
+ * @class IndexedDBStorage
+ * @extends PersistentStorage
+ * @example
+ * const storage = new IndexedDBStorage();
+ * await storage.init('myapp');
+ * await storage.put('key1', { id: 'event1', content: 'test' });
+ */
 export class IndexedDBStorage extends PersistentStorage {
+  /**
+   * Create a new IndexedDBStorage instance.
+   */
   constructor() {
     super();
+    /** @type {IDBDatabase|null} */
     this.db = null;
-    this.dbName = null;
+    /** @type {string} */
+    this.dbName = '';
+    /** @type {string} */
     this.storeName = 'events';
   }
 
+  /**
+   * Initialize storage with namespace.
+   *
+   * Creates or opens the IndexedDB database and object store.
+   *
+   * @param {string} namespace - Storage namespace
+   * @returns {Promise<void>}
+   */
   async init(namespace) {
     this.dbName = `holosphere_${namespace}`;
 
@@ -22,11 +52,12 @@ export class IndexedDBStorage extends PersistentStorage {
       request.onerror = () => reject(request.error);
       request.onsuccess = () => {
         this.db = request.result;
-        resolve();
+        resolve(undefined);
       };
 
       request.onupgradeneeded = (event) => {
-        const db = event.target.result;
+        const target = /** @type {IDBOpenDBRequest} */ (event.target);
+        const db = target.result;
 
         // Create object store if it doesn't exist
         if (!db.objectStoreNames.contains(this.storeName)) {
@@ -38,20 +69,41 @@ export class IndexedDBStorage extends PersistentStorage {
     });
   }
 
+  /**
+   * Store an event.
+   *
+   * @param {string} key - Storage key
+   * @param {Object} event - Event data
+   * @returns {Promise<void>}
+   */
   async put(key, event) {
     return new Promise((resolve, reject) => {
+      if (!this.db) {
+        reject(new Error('Database not initialized'));
+        return;
+      }
       const transaction = this.db.transaction([this.storeName], 'readwrite');
       const objectStore = transaction.objectStore(this.storeName);
 
       const request = objectStore.put({ key, event, timestamp: Date.now() });
 
-      request.onsuccess = () => resolve();
+      request.onsuccess = () => resolve(undefined);
       request.onerror = () => reject(request.error);
     });
   }
 
+  /**
+   * Retrieve an event.
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<Object|null>} Event data or null
+   */
   async get(key) {
     return new Promise((resolve, reject) => {
+      if (!this.db) {
+        reject(new Error('Database not initialized'));
+        return;
+      }
       const transaction = this.db.transaction([this.storeName], 'readonly');
       const objectStore = transaction.objectStore(this.storeName);
 
@@ -65,20 +117,43 @@ export class IndexedDBStorage extends PersistentStorage {
     });
   }
 
+  /**
+   * Retrieve all events matching a prefix.
+   *
+   * Uses IDBKeyRange for efficient B-tree index queries.
+   *
+   * @param {string} prefix - Key prefix to match
+   * @returns {Promise<any[]>} Array of matching events
+   */
   async getAll(prefix) {
     return new Promise((resolve, reject) => {
+      if (!this.db) {
+        reject(new Error('Database not initialized'));
+        return;
+      }
       const transaction = this.db.transaction([this.storeName], 'readonly');
       const objectStore = transaction.objectStore(this.storeName);
 
+      /** @type {any[]} */
       const results = [];
-      const request = objectStore.openCursor();
+
+      // Use IDBKeyRange for efficient prefix query instead of full table scan
+      // This creates a range from "prefix" to "prefix\uffff" (highest unicode char)
+      // which efficiently uses the B-tree index
+      let request;
+      if (prefix) {
+        const range = IDBKeyRange.bound(prefix, prefix + '\uffff', false, false);
+        request = objectStore.openCursor(range);
+      } else {
+        // No prefix = get all
+        request = objectStore.openCursor();
+      }
 
       request.onsuccess = (event) => {
-        const cursor = event.target.result;
+        const target = /** @type {IDBRequest} */ (event.target);
+        const cursor = target.result;
         if (cursor) {
-          if (cursor.value.key.startsWith(prefix)) {
-            results.push(cursor.value.event);
-          }
+          results.push(cursor.value.event);
           cursor.continue();
         } else {
           resolve(results);
@@ -89,30 +164,54 @@ export class IndexedDBStorage extends PersistentStorage {
     });
   }
 
+  /**
+   * Delete an event.
+   *
+   * @param {string} key - Storage key
+   * @returns {Promise<void>}
+   */
   async delete(key) {
     return new Promise((resolve, reject) => {
+      if (!this.db) {
+        reject(new Error('Database not initialized'));
+        return;
+      }
       const transaction = this.db.transaction([this.storeName], 'readwrite');
       const objectStore = transaction.objectStore(this.storeName);
 
       const request = objectStore.delete(key);
 
-      request.onsuccess = () => resolve();
+      request.onsuccess = () => resolve(undefined);
       request.onerror = () => reject(request.error);
     });
   }
 
+  /**
+   * Clear all stored events.
+   *
+   * @returns {Promise<void>}
+   */
   async clear() {
     return new Promise((resolve, reject) => {
+      if (!this.db) {
+        reject(new Error('Database not initialized'));
+        return;
+      }
       const transaction = this.db.transaction([this.storeName], 'readwrite');
       const objectStore = transaction.objectStore(this.storeName);
 
       const request = objectStore.clear();
 
-      request.onsuccess = () => resolve();
+      request.onsuccess = () => resolve(undefined);
       request.onerror = () => reject(request.error);
     });
   }
 
+  /**
+   * Close the database connection.
+   *
+   * @returns {Promise<void>}
+   */
   async close() {
     if (this.db) {
       this.db.close();

package/src/storage/key-storage-simple.js

@@ -1,9 +1,11 @@
 /**
- * Simple Key Storage for Node.js
- * Basic filesystem-based key management
+ * @fileoverview Simple Key Storage for Node.js.
  *
- * NOTE: This only works in Node.js, not browsers
- * For browsers, keys are managed in localStorage
+ * Basic filesystem-based key management.
+ * NOTE: This only works in Node.js, not browsers.
+ * For browsers, keys are managed in localStorage.
+ *
+ * @module storage/key-storage-simple
  */
 
 import fs from 'fs';
@@ -11,7 +13,10 @@ import path from 'path';
 import os from 'os';
 
 /**
- * Get key storage directory
+ * Get key storage directory.
+ *
+ * @private
+ * @returns {string} Key storage directory path
  */
 function getKeyDir() {
   const configDir = process.env.XDG_CONFIG_HOME ||
@@ -23,7 +28,11 @@ function getKeyDir() {
 }
 
 /**
- * Get key file path for an app
+ * Get key file path for an app.
+ *
+ * @private
+ * @param {string} appName - Application name
+ * @returns {string} Full path to key file
  */
 function getKeyPath(appName) {
   const safeName = appName.replace(/[^a-zA-Z0-9-_]/g, '_');
@@ -31,7 +40,10 @@ function getKeyPath(appName) {
 }
 
 /**
- * Load private key
+ * Load private key from filesystem.
+ *
+ * @param {string} appName - Application name
+ * @returns {string|null} Private key (hex) or null if not found
  */
 export function loadKey(appName) {
   const keyPath = getKeyPath(appName);
@@ -45,7 +57,12 @@ export function loadKey(appName) {
 }
 
 /**
- * Save private key
+ * Save private key to filesystem with secure permissions.
+ *
+ * @param {string} appName - Application name
+ * @param {string} privateKey - Private key (64-character hex string)
+ * @returns {string} Path where key was saved
+ * @throws {Error} If private key format is invalid
  */
 export function saveKey(appName, privateKey) {
   if (!/^[0-9a-f]{64}$/i.test(privateKey)) {
@@ -64,7 +81,13 @@ export function saveKey(appName, privateKey) {
 }
 
 /**
- * Get or create key
+ * Get or create private key.
+ *
+ * Loads existing key or generates and saves a new one.
+ *
+ * @param {string} appName - Application name
+ * @param {Function} generateFn - Function to generate new key (returns hex string)
+ * @returns {string} Private key (hex)
  */
 export function getOrCreateKey(appName, generateFn) {
   const existing = loadKey(appName);

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,16 +50,36 @@ 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
   }
 
+  /**
+   * 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[]} */
     const results = [];
     for (const [key, value] of this.data.entries()) {
       if (key.startsWith(prefix)) {
@@ -42,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;
   }