holosphere 2.0.0-alpha7 → 2.0.0-alpha9

package/src/storage/sync-service.js

@@ -1,16 +1,34 @@
 /**
- * SyncService - Background service for reliable sync
+ * @fileoverview SyncService - Background service for reliable sync.
  *
  * Periodically processes the outbox queue to retry failed deliveries
  * and purge old failed events.
+ *
+ * @module storage/sync-service
  */
 
+/**
+ * Background service for reliable event synchronization.
+ *
+ * Runs on a periodic interval to:
+ * - Retry pending events in the outbox queue
+ * - Purge old failed events (24 hour TTL)
+ * - Provide sync statistics
+ *
+ * @class SyncService
+ * @example
+ * const sync = new SyncService(client, { interval: 10000, autoStart: true });
+ * const stats = await sync.getStats();
+ * console.log('Pending events:', stats.queue.pending);
+ */
 export class SyncService {
   /**
-   * @param {Object} client - NostrClient instance
-   * @param {Object} options - Configuration options
-   * @param {number} options.interval - Sync interval in ms (default: 10000)
-   * @param {boolean} options.autoStart - Start automatically (default: false)
+   * Create a new SyncService.
+   *
+   * @param {Object} client - NostrClient instance with outboxQueue
+   * @param {Object} [options={}] - Configuration options
+   * @param {number} [options.interval=10000] - Sync interval in ms (10 seconds)
+   * @param {boolean} [options.autoStart=false] - Start automatically
    */
   constructor(client, options = {}) {
     this.client = client;
@@ -25,7 +43,9 @@ export class SyncService {
   }
 
   /**
-   * Start the background sync service
+   * Start the background sync service.
+   *
+   * @returns {void}
    */
   start() {
     if (this.running) return;
@@ -34,7 +54,9 @@ export class SyncService {
   }
 
   /**
-   * Stop the background sync service
+   * Stop the background sync service.
+   *
+   * @returns {void}
    */
   stop() {
     this.running = false;
@@ -45,24 +67,30 @@ export class SyncService {
   }
 
   /**
-   * Check if the service is running
-   * @returns {boolean}
+   * Check if the service is running.
+   *
+   * @returns {boolean} True if service is running
    */
   isRunning() {
     return this.running;
   }
 
   /**
-   * Force an immediate sync (useful for testing or manual trigger)
-   * @returns {Promise<Object>} Sync result
+   * Force an immediate sync.
+   *
+   * Useful for testing or manual trigger.
+   *
+   * @returns {Promise<Object>} Sync result with processed, succeeded, failed, purged counts
    */
   async syncNow() {
     return this._processOutbox();
   }
 
   /**
-   * Schedule the next run
+   * Schedule the next run.
+   *
    * @private
+   * @returns {void}
    */
   _scheduleNextRun() {
     if (!this.running) return;
@@ -73,8 +101,10 @@ export class SyncService {
   }
 
   /**
-   * Main loop iteration
+   * Main loop iteration.
+   *
    * @private
+   * @returns {Promise<void>}
    */
   async _runLoop() {
     if (!this.running) return;
@@ -90,9 +120,12 @@ export class SyncService {
   }
 
   /**
-   * Process pending events in the outbox
+   * Process pending events in the outbox.
+   *
+   * Retries pending events and purges old failed events.
+   *
    * @private
-   * @returns {Promise<Object>} Processing result
+   * @returns {Promise<Object>} Processing result with counts
    */
   async _processOutbox() {
     // Prevent concurrent processing
@@ -145,8 +178,9 @@ export class SyncService {
   }
 
   /**
-   * Get sync service statistics
-   * @returns {Promise<Object>} Stats including queue status
+   * Get sync service statistics.
+   *
+   * @returns {Promise<Object>} Stats including running status, interval, and queue status
    */
   async getStats() {
     const stats = {

package/src/storage/unified-storage.js

@@ -1,6 +1,11 @@
 /**
- * Unified Storage Adapter
- * Routes storage operations to the correct backend (nostr or gundb)
+ * @fileoverview Unified Storage Adapter.
+ *
+ * Routes storage operations to the correct backend (Nostr or GunDB).
+ * Provides a consistent API for reading, writing, updating, and deleting
+ * data across different storage backends.
+ *
+ * @module storage/unified-storage
  */
 
 import * as nostrWrapper from './nostr-wrapper.js';
@@ -27,7 +32,11 @@ export function buildPath(appName, holonId, lensName, key = null) {
  * @returns {Promise<boolean>} Success indicator
  */
 export async function write(client, path, data) {
-  // Check if this is a GunDB client
+  // Check if this is a GunDB client with backend methods (preferred - has write cache)
+  if (client.write && client.gun) {
+    return client.write(path, data);
+  }
+  // Fallback to direct gunWrapper (no write cache)
   if (client.gun) {
     return gunWrapper.write(client.gun, path, data);
   }
@@ -43,6 +52,11 @@ export async function write(client, path, data) {
  * @returns {Promise<Object|null>} Data or null
  */
 export async function read(client, path, options = {}) {
+  // Check if this is a GunDB client with backend methods (preferred - has write cache)
+  if (client.read && client.gun) {
+    return client.read(path, options);
+  }
+  // Fallback to direct gunWrapper
   if (client.gun) {
     return gunWrapper.read(client.gun, path);
   }
@@ -57,6 +71,11 @@ export async function read(client, path, options = {}) {
  * @returns {Promise<Object[]>} Array of data objects
  */
 export async function readAll(client, path, options = {}) {
+  // Check if this is a GunDB client with backend methods (preferred - has write cache)
+  if (client.readAll && client.gun) {
+    return client.readAll(path, options);
+  }
+  // Fallback to direct gunWrapper
   if (client.gun) {
     return gunWrapper.readAll(client.gun, path);
   }
@@ -71,6 +90,11 @@ export async function readAll(client, path, options = {}) {
  * @returns {Promise<boolean>} Success indicator
  */
 export async function update(client, path, updates) {
+  // Check if this is a GunDB client with backend methods (preferred - has write cache)
+  if (client.update && client.gun) {
+    return client.update(path, updates);
+  }
+  // Fallback to direct gunWrapper
   if (client.gun) {
     return gunWrapper.update(client.gun, path, updates);
   }
@@ -84,6 +108,11 @@ export async function update(client, path, updates) {
  * @returns {Promise<boolean>} Success indicator
  */
 export async function deleteData(client, path) {
+  // Check if this is a GunDB client with backend methods (preferred - has write cache)
+  if (client.delete && client.gun) {
+    return client.delete(path);
+  }
+  // Fallback to direct gunWrapper
   if (client.gun) {
     return gunWrapper.deleteData(client.gun, path);
   }
@@ -97,6 +126,7 @@ export async function deleteData(client, path) {
  * @returns {Promise<Object>} Deletion results
  */
 export async function deleteAll(client, path) {
+  // Fallback to direct gunWrapper (deleteAll not typically in client interface)
   if (client.gun) {
     return gunWrapper.deleteAll(client.gun, path);
   }
@@ -112,6 +142,11 @@ export async function deleteAll(client, path) {
  * @returns {Object} Subscription with unsubscribe method
  */
 export function subscribe(client, path, callback, options = {}) {
+  // Check if this is a GunDB client with backend methods
+  if (client.subscribe && client.gun) {
+    return client.subscribe(path, callback, options);
+  }
+  // Fallback to direct gunWrapper
   if (client.gun) {
     return gunWrapper.subscribe(client.gun, path, callback, options);
   }

package/src/subscriptions/manager.js

@@ -1,22 +1,26 @@
 /**
- * Real-time Subscription Management
+ * @fileoverview Real-time subscription management with throttling, filtering, and hologram resolution.
+ * Provides subscription utilities for real-time data updates from the unified storage layer.
+ * @module subscriptions/manager
  */
 
 import { subscribe } from '../storage/unified-storage.js';
 import { resolveHologram } from '../federation/hologram.js';
 
 /**
- * Create subscription with throttle and filter
+ * Create subscription with throttle and filter support.
+ * Manages real-time data updates with deduplication, hologram resolution, and filtering capabilities.
  * @param {Object} client - Nostr client instance
- * @param {string} path - Path to subscribe to
- * @param {Function} callback - Callback function
- * @param {Object} options - Subscription options
- * @param {number} options.throttle - Throttle interval in ms
- * @param {Function} options.filter - Filter predicate
- * @param {boolean} options.includeFederated - Include federated data
- * @param {boolean} options.triggerInitial - Trigger callback with initial data (default: false)
- * @param {boolean} options.resolveHolograms - Resolve holograms before callback (default: true)
- * @returns {Object} Subscription object with unsubscribe method
+ * @param {string} path - Path to subscribe to (app/holon/lens/data)
+ * @param {Function} callback - Callback function invoked with (data, key)
+ * @param {Object} [options={}] - Subscription options
+ * @param {number} [options.throttle=0] - Throttle interval in milliseconds
+ * @param {Function} [options.filter=null] - Filter predicate function (data, key) => boolean
+ * @param {boolean} [options.includeFederated=false] - Include federated data
+ * @param {boolean} [options.triggerInitial=false] - Trigger callback with initial data
+ * @param {boolean} [options.realtimeOnly=true] - Only subscribe to new events
+ * @param {boolean} [options.resolveHolograms=true] - Resolve holograms before callback
+ * @returns {Promise<Object>} Subscription object with path and unsubscribe method
  */
 export async function createSubscription(client, path, callback, options = {}) {
   const { throttle = 0, filter = null, includeFederated = false, triggerInitial = false, realtimeOnly = true, resolveHolograms = true } = options;
@@ -98,22 +102,34 @@ export async function createSubscription(client, path, callback, options = {}) {
 }
 
 /**
- * Subscription registry for tracking active subscriptions
+ * Registry for tracking and managing multiple active subscriptions.
+ * Provides centralized subscription lifecycle management with batch operations.
  */
 export class SubscriptionRegistry {
+  /**
+   * Create a new subscription registry.
+   */
   constructor() {
+    /**
+     * Map of subscription ID to subscription object
+     * @type {Map<string, Object>}
+     * @private
+     */
     this.subscriptions = new Map();
   }
 
   /**
-   * Register a subscription
+   * Register a subscription by ID.
+   * @param {string} id - Unique subscription identifier
+   * @param {Object} subscription - Subscription object with unsubscribe method
    */
   register(id, subscription) {
     this.subscriptions.set(id, subscription);
   }
 
   /**
-   * Unregister a subscription
+   * Unregister and unsubscribe a subscription by ID.
+   * @param {string} id - Subscription identifier to remove
    */
   unregister(id) {
     const subscription = this.subscriptions.get(id);
@@ -124,7 +140,7 @@ export class SubscriptionRegistry {
   }
 
   /**
-   * Unsubscribe all
+   * Unsubscribe all registered subscriptions and clear the registry.
    */
   unsubscribeAll() {
     for (const [id, subscription] of this.subscriptions) {
@@ -134,7 +150,8 @@ export class SubscriptionRegistry {
   }
 
   /**
-   * Get active subscription count
+   * Get the count of active subscriptions.
+   * @returns {number} Number of active subscriptions
    */
   count() {
     return this.subscriptions.size;

package/vite.config.cdn.js

@@ -0,0 +1,60 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+
+/**
+ * CDN Build Configuration
+ * Creates a self-contained bundle for browser usage via CDN
+ * All dependencies are bundled (no externals)
+ */
+export default defineConfig({
+  build: {
+    target: 'es2020',
+    outDir: 'dist/cdn',
+    lib: {
+      entry: resolve(__dirname, 'src/cdn-entry.js'),
+      name: 'HoloSphere',
+      formats: ['iife'],
+      fileName: () => 'holosphere.min.js',
+    },
+    rollupOptions: {
+      // Bundle all dependencies for CDN
+      external: [],
+      output: {
+        // Use default export so HoloSphere is directly accessible
+        exports: 'default',
+        // Extend window with all exports
+        extend: true,
+        // Provide globals for any remaining externals
+        globals: {},
+        // Inline dynamic imports
+        inlineDynamicImports: true,
+      },
+    },
+    sourcemap: true,
+    minify: 'terser',
+    terserOptions: {
+      compress: {
+        drop_console: false,
+        passes: 2,
+      },
+      mangle: {
+        safari10: true,
+      },
+    },
+    // Increase chunk size warning limit for CDN bundle
+    chunkSizeWarningLimit: 2000,
+  },
+  resolve: {
+    alias: [
+      {
+        find: './filesystem-storage.js',
+        replacement: resolve(__dirname, 'src/storage/filesystem-storage-browser.js'),
+      },
+    ],
+  },
+  define: {
+    'process.versions.node': JSON.stringify(undefined),
+    'process.env.NODE_ENV': JSON.stringify('production'),
+    'global': 'globalThis',
+  },
+});