mycelia-kernel-plugin 1.0.0

package/src/hooks/listeners/use-listeners.js

@@ -0,0 +1,164 @@
+/**
+ * useListeners Hook
+ * 
+ * Provides listener management functionality to subsystems.
+ * Wraps ListenerManager and exposes on(), off(), hasListeners() methods.
+ * 
+ * @param {Object} ctx - Context object containing config.listeners for listener configuration
+ * @param {Object} api - Subsystem API being built
+ * @param {BaseSubsystem} subsystem - Subsystem instance
+ * @returns {Facet} Facet object with listener methods
+ */
+import { ListenerManager } from './listener-manager.js';
+import { Facet } from '../../core/facet.js';
+import { createHook } from '../../core/create-hook.js';
+import { getDebugFlag } from '../../utils/debug-flag.js';
+import { createLogger } from '../../utils/logger.js';
+
+export const useListeners = createHook({
+  kind: 'listeners',
+  version: '1.0.0',
+  overwrite: false,
+  required: [],
+  attach: true,
+  source: import.meta.url,
+  contract: 'listeners',
+  // eslint-disable-next-line no-unused-vars
+  fn: (ctx, api, _subsystem) => {
+    const { name } = api;
+    const config = ctx.config?.listeners || {};
+    const debug = getDebugFlag(config, ctx);
+    
+    // Listeners are optional - can be enabled/disabled
+    let listeners = null;
+    let listenersEnabled = false;
+    
+    return new Facet('listeners', { attach: true, source: import.meta.url, contract: 'listeners' })
+      .add({
+      
+      /**
+       * Check if listeners are enabled
+       * @returns {boolean} True if listeners are enabled
+       */
+      hasListeners() {
+        return listenersEnabled && listeners !== null;
+      },
+      
+      /**
+       * Enable listeners
+       * @param {Object} [listenerOptions={}] - ListenerManager options (overrides config)
+       */
+      enableListeners(listenerOptions = {}) {
+        if (listeners === null) {
+          listeners = new ListenerManager({
+            registrationPolicy: listenerOptions.registrationPolicy || config.registrationPolicy || 'multiple',
+            debug: listenerOptions.debug !== undefined ? listenerOptions.debug : getDebugFlag(config, ctx),
+            policyOptions: listenerOptions.policyOptions || config.policyOptions || {}
+          });
+        }
+        listenersEnabled = true;
+      },
+      
+      /**
+       * Disable listeners
+       */
+      disableListeners() {
+        listenersEnabled = false;
+      },
+      
+      /**
+       * Register a listener for a specific path
+       * @param {string} path - Message path to listen for
+       * @param {Function|Object} handlers - Handler function or handler group object
+       * @param {Object} [options={}] - Registration options
+       * @param {boolean} [options.isHandlerGroup=false] - Whether handlers is a handler group object
+       * @returns {boolean} Success status
+       */
+      on(path, handlers, options = {}) {
+        // Check if listeners are enabled
+        if (!listenersEnabled || listeners === null) {
+          // Use runtime debug flag from options, fallback to hook debug
+          const runtimeDebug = options.debug !== undefined ? options.debug : debug;
+          if (runtimeDebug) {
+            const runtimeLogger = createLogger(runtimeDebug, `useListeners ${name}`);
+            runtimeLogger.warn('Cannot register listener - listeners not enabled');
+          }
+          return false;
+        }
+        
+        // If it's a handler group, delegate to ListenerManager's handler group method
+        if (options.isHandlerGroup && typeof handlers === 'object') {
+          return listeners.registerHandlerGroup(path, handlers, options);
+        }
+        
+        // Delegate to ListenerManager for regular handlers
+        return listeners.on(path, handlers);
+      },
+      
+      /**
+       * Unregister a listener for a specific path
+       * @param {string} path - Message path
+       * @param {Function|Object} handlers - Handler function or handler group object to remove
+       * @param {Object} [options={}] - Unregistration options
+       * @param {boolean} [options.isHandlerGroup=false] - Whether handlers is a handler group object
+       * @returns {boolean} Success status
+       */
+      off(path, handlers, options = {}) {
+        // Check if listeners are enabled
+        if (!listenersEnabled || listeners === null) {
+          // Use runtime debug flag from options, fallback to hook debug
+          const runtimeDebug = options.debug !== undefined ? options.debug : debug;
+          if (runtimeDebug) {
+            const runtimeLogger = createLogger(runtimeDebug, `useListeners ${name}`);
+            runtimeLogger.warn('Cannot unregister listener - listeners not enabled');
+          }
+          return false;
+        }
+        
+        // If it's a handler group, delegate to ListenerManager's handler group unregistration
+        if (options.isHandlerGroup && typeof handlers === 'object') {
+          return listeners.unregisterHandlerGroup(path, handlers, options);
+        }
+        
+        // Delegate to ListenerManager for regular handlers
+        return listeners.off(path, handlers);
+      },
+      
+      /**
+       * Emit an event to listeners for a specific path
+       * @param {string} path - Message path to emit to
+       * @param {Message} message - Message to send to listeners
+       * @returns {number} Number of listeners notified, or 0 if listeners not enabled
+       * 
+       * @example
+       * // Emit event to listeners
+       * const notified = subsystem.listeners.emit('layers/create', message);
+       */
+      emit(path, message) {
+        // Check if listeners are enabled
+        if (!listenersEnabled || listeners === null) {
+          if (debug) {
+            const runtimeLogger = createLogger(debug, `useListeners ${name}`);
+            runtimeLogger.warn('Cannot emit event - listeners not enabled');
+          }
+          return 0;
+        }
+        
+        // Delegate to ListenerManager
+        return listeners.emit(path, message);
+      },
+      
+      /**
+       * Expose listeners property for direct access
+       * Returns null if listeners are not enabled
+       */
+      get listeners() {
+        return listeners;
+      },
+      
+      // Expose listener manager for internal use
+      _listenerManager: () => listeners
+      });
+  }
+});
+

package/src/hooks/queue/bounded-queue.js

@@ -0,0 +1,341 @@
+import { CircularBuffer } from './circular-buffer.js';
+
+/**
+ * BoundedQueue Class
+ * 
+ * A queue with a maximum capacity and configurable overflow policy for handling backpressure
+ * and memory management in message-driven systems. Provides event-driven notifications and
+ * comprehensive statistics for monitoring queue behavior.
+ * 
+ * Performance: Uses CircularBuffer internally for O(1) enqueue/dequeue operations (16x faster
+ * than array-based implementation for large queues).
+ * 
+ * @example
+ * // Create a queue with capacity 100 and drop-oldest policy
+ * const queue = new BoundedQueue(100, 'drop-oldest');
+ * 
+ * @example
+ * // Create a queue with error policy for critical data
+ * const criticalQueue = new BoundedQueue(50, 'error');
+ * 
+ * @example
+ * // Monitor queue events
+ * queue.on('full', () => console.log('Queue is full!'));
+ * queue.on('dropped', (data) => console.log('Item dropped:', data.reason));
+ */
+export class BoundedQueue {
+  /**
+   * Create a new BoundedQueue instance
+   * 
+   * @param {number} capacity - Maximum number of items the queue can hold
+   * @param {string} [policy='drop-oldest'] - Overflow policy when queue is full
+   *   - 'drop-oldest': Remove oldest item and add new one (FIFO with replacement)
+   *   - 'drop-newest': Reject new item when full (strict capacity)
+   *   - 'block': Wait for space (simplified implementation)
+   *   - 'error': Throw error when full (fail-fast)
+   * 
+   * @example
+   * // Basic queue with default policy
+   * const queue = new BoundedQueue(100);
+   * 
+   * @example
+   * // Queue with error policy for critical data
+   * const criticalQueue = new BoundedQueue(50, 'error');
+   * 
+   * @example
+   * // Queue with drop-newest for real-time data
+   * const realtimeQueue = new BoundedQueue(200, 'drop-newest');
+   */
+  constructor(capacity, policy = 'drop-oldest') {
+    this.capacity = capacity;
+    this.policy = policy;
+    this.queue = new CircularBuffer(capacity);
+    this.stats = {
+      itemsEnqueued: 0,
+      itemsDequeued: 0,
+      itemsDropped: 0,
+      queueFullEvents: 0,
+      errors: 0
+    };
+    
+    // Event emitters for queue events
+    this.eventHandlers = {
+      full: [],
+      empty: [],
+      dropped: [],
+      error: []
+    };
+  }
+
+  /**
+   * Add an item to the queue
+   * @param {any} item - Item to enqueue
+   * @returns {boolean} Success status
+   */
+  enqueue(item) {
+    try {
+      if (this.isFull()) {
+        this.stats.queueFullEvents++;
+        this.emit('full');
+        return this.handleFullQueue(item);
+      }
+      
+      const success = this.queue.enqueue(item);
+      if (success) {
+        this.stats.itemsEnqueued++;
+        
+        if (this.debug) {
+          console.log(`BoundedQueue: Enqueued item, queue size: ${this.size()}`);
+        }
+      }
+      
+      return success;
+    } catch (error) {
+      // Only catch errors that aren't from the error policy
+      if (this.policy !== 'error') {
+        this.stats.errors++;
+        this.emit('error', { error, item });
+        return false;
+      }
+      // Re-throw error for error policy
+      throw error;
+    }
+  }
+
+  /**
+   * Remove and return the next item from the queue
+   * @returns {any|null} Next item or null if empty
+   */
+  dequeue() {
+    try {
+      if (this.isEmpty()) {
+        return null;
+      }
+      
+      const item = this.queue.dequeue();
+      this.stats.itemsDequeued++;
+      
+      if (this.isEmpty()) {
+        this.emit('empty');
+      }
+      
+      if (this.debug) {
+        console.log(`BoundedQueue: Dequeued item, queue size: ${this.size()}`);
+      }
+      
+      return item;
+    } catch (error) {
+      this.stats.errors++;
+      this.emit('error', { error });
+      return null;
+    }
+  }
+
+  /**
+   * Look at the next item without removing it
+   * @returns {any|null} Next item or null if empty
+   */
+  peek() {
+    return this.queue.peek();
+  }
+
+  /**
+   * Get all items in the queue without removing them
+   * @returns {Array} Copy of all items in the queue
+   */
+  peekAll() {
+    return this.queue.toArray();
+  }
+
+  /**
+   * Remove a specific item from the queue
+   * @param {any} item - Item to remove (matched by reference)
+   * @returns {boolean} True if item was found and removed
+   * 
+   * Note: This operation is O(n) and requires converting to array temporarily.
+   * For high-performance use cases, avoid using this method.
+   */
+  remove(item) {
+    try {
+      // Get all items, find and remove the target, then rebuild queue
+      const items = this.queue.toArray();
+      const index = items.indexOf(item);
+      
+      if (index === -1) {
+        return false;
+      }
+      
+      // Remove the item
+      items.splice(index, 1);
+      
+      // Rebuild queue
+      this.queue.clear();
+      items.forEach(i => this.queue.enqueue(i));
+      
+      this.stats.itemsDequeued++;
+      
+      if (this.isEmpty()) {
+        this.emit('empty');
+      }
+      
+      if (this.debug) {
+        console.log(`BoundedQueue: Removed item, queue size: ${this.size()}`);
+      }
+      
+      return true;
+    } catch (error) {
+      this.stats.errors++;
+      this.emit('error', { error });
+      return false;
+    }
+  }
+
+  /**
+   * Check if queue is empty
+   * @returns {boolean} True if empty
+   */
+  isEmpty() {
+    return this.queue.isEmpty();
+  }
+
+  /**
+   * Check if queue is at capacity
+   * @returns {boolean} True if full
+   */
+  isFull() {
+    return this.queue.isFull();
+  }
+
+  /**
+   * Get current queue size
+   * @returns {number} Current size
+   */
+  size() {
+    return this.queue.size();
+  }
+
+  /**
+   * Get queue capacity
+   * @returns {number} Maximum capacity
+   */
+  getCapacity() {
+    return this.capacity;
+  }
+
+  /**
+   * Clear all items from the queue
+   */
+  clear() {
+    this.queue.clear();
+    if (this.debug) {
+      console.log('BoundedQueue: Cleared all items');
+    }
+  }
+
+  /**
+   * Handle queue overflow based on policy
+   * @param {any} item - Item that couldn't be enqueued
+   * @returns {boolean} Success status
+   */
+  handleFullQueue(item) {
+    switch (this.policy) {
+      case 'drop-oldest':
+        // Remove oldest item and add new one
+        this.queue.dropOldest();
+        const success = this.queue.enqueue(item);
+        this.stats.itemsDropped++;
+        this.emit('dropped', { item, reason: 'drop-oldest' });
+        return success;
+        
+      case 'drop-newest':
+        // Reject new item
+        this.stats.itemsDropped++;
+        this.emit('dropped', { item, reason: 'drop-newest' });
+        return false;
+        
+      case 'block':
+        // Wait for space (simplified - in real implementation would be async)
+        this.emit('dropped', { item, reason: 'block-timeout' });
+        return false;
+        
+      case 'error': {
+        // Throw error
+        const error = new Error(`Queue is full (capacity: ${this.capacity})`);
+        this.stats.errors++;
+        this.emit('error', { error, item });
+        throw error;
+      }
+        
+      default:
+        // Unknown policy, default to drop-newest
+        this.stats.itemsDropped++;
+        this.emit('dropped', { item, reason: 'unknown-policy' });
+        return false;
+    }
+  }
+
+  /**
+   * Add event listener
+   * @param {string} event - Event name
+   * @param {function} handler - Event handler
+   */
+  on(event, handler) {
+    if (this.eventHandlers[event]) {
+      this.eventHandlers[event].push(handler);
+    }
+  }
+
+  /**
+   * Remove event listener
+   * @param {string} event - Event name
+   * @param {function} handler - Event handler
+   */
+  off(event, handler) {
+    if (this.eventHandlers[event]) {
+      const index = this.eventHandlers[event].indexOf(handler);
+      if (index > -1) {
+        this.eventHandlers[event].splice(index, 1);
+      }
+    }
+  }
+
+  /**
+   * Emit event to all listeners
+   * @param {string} event - Event name
+   * @param {any} data - Event data
+   */
+  emit(event, data) {
+    if (this.eventHandlers[event]) {
+      this.eventHandlers[event].forEach(handler => {
+        try {
+          handler(data);
+        } catch (error) {
+          console.error('BoundedQueue: Event handler error:', error);
+        }
+      });
+    }
+  }
+
+  /**
+   * Get queue statistics
+   * @returns {Object} Statistics object
+   */
+  getStatistics() {
+    return {
+      ...this.stats,
+      capacity: this.capacity,
+      currentSize: this.size(),
+      policy: this.policy,
+      utilization: this.size() / this.capacity
+    };
+  }
+
+  /**
+   * Set debug mode
+   * @param {boolean} debug - Debug mode
+   */
+  setDebug(debug) {
+    this.debug = debug;
+  }
+}
+