mycelia-kernel-plugin 1.0.0

package/src/hooks/listeners/listener-registry.js

@@ -0,0 +1,176 @@
+/**
+ * ListenerRegistry Class
+ * 
+ * Manages listener storage and basic registration/unregistration operations.
+ * Handles exact path matching only (no pattern matching).
+ * 
+ * @example
+ * const registry = new ListenerRegistry();
+ * registry.register('layers/create', handler);
+ * const handlers = registry.get('layers/create');
+ */
+export class ListenerRegistry {
+  /**
+   * Create a new ListenerRegistry instance
+   * 
+   * @param {Object} [options={}] - Configuration options
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(options = {}) {
+    this.debug = options.debug || false;
+    
+    // Listener storage: path -> [handler1, handler2, ...]
+    this.listeners = new Map();
+  }
+
+  /**
+   * Register a listener for a specific path
+   * @param {string} path - Message path to listen for
+   * @param {Function} handler - Handler function to call when message is received
+   * @param {Array<Function>} existingListeners - Existing listeners for this path (from policy)
+   * @returns {void}
+   */
+  register(path, handler, existingListeners = []) {
+    this.listeners.set(path, existingListeners);
+    
+    if (this.debug) {
+      console.log(`ListenerRegistry: Registered listener for '${path}' (${existingListeners.length} total)`);
+    }
+  }
+
+  /**
+   * Unregister a specific listener for a path
+   * @param {string} path - Message path
+   * @param {Function} handler - Handler function to remove
+   * @returns {boolean} Success status
+   */
+  unregister(path, handler) {
+    if (!this.listeners.has(path)) {
+      return false;
+    }
+
+    const existingListeners = this.listeners.get(path);
+    const index = existingListeners.indexOf(handler);
+    
+    if (index === -1) {
+      return false;
+    }
+
+    existingListeners.splice(index, 1);
+
+    // Clean up empty arrays
+    if (existingListeners.length === 0) {
+      this.listeners.delete(path);
+    }
+
+    if (this.debug) {
+      console.log(`ListenerRegistry: Unregistered listener for '${path}' (${existingListeners.length} remaining)`);
+    }
+
+    return true;
+  }
+
+  /**
+   * Unregister all listeners for a specific path
+   * @param {string} path - Message path
+   * @returns {number} Number of listeners removed
+   */
+  unregisterAll(path) {
+    if (!this.listeners.has(path)) {
+      return 0;
+    }
+
+    const count = this.listeners.get(path).length;
+    this.listeners.delete(path);
+
+    if (this.debug) {
+      console.log(`ListenerRegistry: Removed ${count} listeners for '${path}'`);
+    }
+
+    return count;
+  }
+
+  /**
+   * Clear all listeners
+   * @returns {number} Total number of listeners removed
+   */
+  clear() {
+    let totalRemoved = 0;
+    
+    for (const [_path, handlers] of this.listeners) {
+      totalRemoved += handlers.length;
+    }
+
+    this.listeners.clear();
+
+    if (this.debug) {
+      console.log(`ListenerRegistry: Cleared ${totalRemoved} listeners`);
+    }
+
+    return totalRemoved;
+  }
+
+  /**
+   * Check if there are listeners for a specific path
+   * @param {string} path - Message path
+   * @returns {boolean} True if listeners exist
+   */
+  has(path) {
+    return this.listeners.has(path) && this.listeners.get(path).length > 0;
+  }
+
+  /**
+   * Get the number of listeners for a specific path
+   * @param {string} path - Message path
+   * @returns {number} Number of listeners
+   */
+  getCount(path) {
+    return this.listeners.has(path) ? this.listeners.get(path).length : 0;
+  }
+
+  /**
+   * Get all listeners for a specific path
+   * @param {string} path - Message path
+   * @returns {Array<Function>} Array of handler functions
+   */
+  get(path) {
+    return this.listeners.has(path) ? [...this.listeners.get(path)] : [];
+  }
+
+  /**
+   * Get all listeners (for debugging)
+   * @returns {Object} Object with paths as keys and handler arrays as values
+   */
+  getAll() {
+    const result = {};
+    for (const [path, handlers] of this.listeners) {
+      result[path] = [...handlers];
+    }
+    return result;
+  }
+
+  /**
+   * Get all registered paths
+   * @returns {Array<string>} Array of path strings
+   */
+  getPaths() {
+    return Array.from(this.listeners.keys());
+  }
+
+  /**
+   * Get total listener count across all paths
+   * @returns {number} Total number of listeners
+   */
+  getTotalCount() {
+    return Array.from(this.listeners.values()).reduce((sum, handlers) => sum + handlers.length, 0);
+  }
+
+  /**
+   * Get number of paths with listeners
+   * @returns {number} Number of paths
+   */
+  getPathCount() {
+    return this.listeners.size;
+  }
+}
+

package/src/hooks/listeners/listener-statistics.js

@@ -0,0 +1,106 @@
+/**
+ * ListenerStatistics Class
+ * 
+ * Tracks statistics for listener operations.
+ * 
+ * @example
+ * const stats = new ListenerStatistics();
+ * stats.recordRegistration();
+ * stats.recordNotification(5);
+ */
+export class ListenerStatistics {
+  /**
+   * Create a new ListenerStatistics instance
+   */
+  constructor() {
+    this.stats = {
+      listenersRegistered: 0,
+      listenersUnregistered: 0,
+      notificationsSent: 0,
+      notificationErrors: 0,
+      patternListenersRegistered: 0,
+      patternListenersUnregistered: 0,
+      patternMatches: 0
+    };
+  }
+
+  /**
+   * Record a listener registration
+   */
+  recordRegistration() {
+    this.stats.listenersRegistered++;
+  }
+
+  /**
+   * Record a listener unregistration
+   */
+  recordUnregistration() {
+    this.stats.listenersUnregistered++;
+  }
+
+  /**
+   * Record notifications sent
+   * @param {number} count - Number of notifications sent
+   */
+  recordNotifications(count) {
+    this.stats.notificationsSent += count;
+  }
+
+  /**
+   * Record a notification error
+   */
+  recordError() {
+    this.stats.notificationErrors++;
+  }
+
+  /**
+   * Record a pattern listener registration
+   */
+  recordPatternRegistration() {
+    this.stats.patternListenersRegistered++;
+    this.stats.listenersRegistered++; // Also count as regular registration
+  }
+
+  /**
+   * Record a pattern listener unregistration
+   */
+  recordPatternUnregistration() {
+    this.stats.patternListenersUnregistered++;
+    this.stats.listenersUnregistered++; // Also count as regular unregistration
+  }
+
+  /**
+   * Record a pattern match
+   */
+  recordPatternMatch() {
+    this.stats.patternMatches++;
+  }
+
+  /**
+   * Get current statistics
+   * @param {Object} additionalData - Additional data to include in stats
+   * @returns {Object} Statistics object
+   */
+  get(additionalData = {}) {
+    return {
+      ...this.stats,
+      ...additionalData
+    };
+  }
+
+  /**
+   * Clear statistics and reset state
+   */
+  clear() {
+    this.stats = {
+      listenersRegistered: 0,
+      listenersUnregistered: 0,
+      notificationsSent: 0,
+      notificationErrors: 0,
+      patternListenersRegistered: 0,
+      patternListenersUnregistered: 0,
+      patternMatches: 0
+    };
+  }
+}
+

package/src/hooks/listeners/pattern-matcher.js

@@ -0,0 +1,283 @@
+/**
+ * PatternMatcher Class
+ * 
+ * Handles pattern-based listener registration and matching.
+ * Supports {param} syntax in paths (e.g., 'command/completed/id/{id}').
+ * 
+ * @example
+ * const matcher = new PatternMatcher({ debug: false });
+ * matcher.register('command/completed/id/{id}', handler);
+ * const matches = matcher.findMatches('command/completed/id/123');
+ */
+export class PatternMatcher {
+  /**
+   * Create a new PatternMatcher instance
+   * 
+   * @param {Object} [options={}] - Configuration options
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(options = {}) {
+    this.debug = options.debug || false;
+    
+    // Pattern listener storage: pattern -> [{ handlers, paramNames, regex }, ...]
+    // Each entry contains handlers for that pattern and compiled regex for matching
+    this.patternListeners = new Map();
+  }
+
+  /**
+   * Check if a path contains pattern syntax (e.g., {param})
+   * @param {string} path - Path to check
+   * @returns {boolean} True if path contains pattern syntax
+   */
+  isPattern(path) {
+    return /\{[a-zA-Z_][a-zA-Z0-9_]*\}/.test(path);
+  }
+
+  /**
+   * Parse pattern to extract parameter names
+   * @param {string} pattern - Pattern string (e.g., 'command/completed/id/{id}')
+   * @returns {Array<string>} Array of parameter names (e.g., ['id'])
+   */
+  parsePattern(pattern) {
+    const paramNames = [];
+    const paramRegex = /\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g;
+    let match;
+    
+    while ((match = paramRegex.exec(pattern)) !== null) {
+      const paramName = match[1];
+      if (!paramNames.includes(paramName)) {
+        paramNames.push(paramName);
+      }
+    }
+    
+    return paramNames;
+  }
+
+  /**
+   * Convert pattern to regex with capture groups
+   * @param {string} pattern - Pattern string (e.g., 'command/completed/id/{id}')
+   * @returns {RegExp} Regex with capture groups
+   */
+  patternToRegex(pattern) {
+    // Escape special regex characters except the pattern syntax
+    let regexStr = pattern
+      .replace(/[.*+?^${}()|[\]\\]/g, (char) => {
+        // Don't escape { and } as they're used for pattern syntax
+        if (char === '{' || char === '}') {
+          return char;
+        }
+        return '\\' + char;
+      });
+    
+    // Replace {param} with capture groups
+    // Each {param} becomes (.+) to capture any value
+    regexStr = regexStr.replace(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g, '(.+)');
+    
+    // Anchor to start and end
+    regexStr = '^' + regexStr + '$';
+    
+    return new RegExp(regexStr);
+  }
+
+  /**
+   * Extract parameter values from a pattern match
+   * @param {string} pattern - Original pattern
+   * @param {Array<string>} paramNames - Parameter names in order
+   * @param {Array} matchResult - Regex match result array
+   * @returns {Object} Parameters object (e.g., { id: 'msg_123' })
+   */
+  extractParams(pattern, paramNames, matchResult) {
+    if (!matchResult || matchResult.length === 0) {
+      return {};
+    }
+
+    // matchResult[0] is the full match
+    // matchResult[1], matchResult[2], ... are capture groups
+    const params = {};
+    const captureGroups = matchResult.slice(1);
+    
+    if (paramNames.length !== captureGroups.length) {
+      if (this.debug) {
+        console.warn(`PatternMatcher: Parameter count mismatch for pattern '${pattern}'. Expected ${paramNames.length}, got ${captureGroups.length}`);
+      }
+      return {};
+    }
+    
+    for (let i = 0; i < paramNames.length; i++) {
+      params[paramNames[i]] = captureGroups[i];
+    }
+    
+    return params;
+  }
+
+  /**
+   * Register a listener for a pattern path
+   * @param {string} pattern - Pattern path with {param} placeholders
+   * @param {Function} handler - Handler function to call when pattern matches
+   * @param {Array<Function>} existingHandlers - Existing handlers for this pattern (from policy)
+   * @returns {void}
+   */
+  register(pattern, handler, existingHandlers = []) {
+    if (!this.isPattern(pattern)) {
+      throw new Error(`Path '${pattern}' does not contain pattern syntax. Use exact path matching or onPattern() with {param} syntax.`);
+    }
+
+    // Parse pattern to extract parameter names
+    const paramNames = this.parsePattern(pattern);
+    
+    if (paramNames.length === 0) {
+      throw new Error(`Pattern '${pattern}' contains no valid parameters. Use {paramName} syntax.`);
+    }
+
+    // Convert pattern to regex
+    const regex = this.patternToRegex(pattern);
+
+    // Get existing pattern entries or create new array
+    const existingEntries = this.patternListeners.get(pattern) || [];
+    
+    // Check if this pattern already has entries
+    let patternEntry = existingEntries.find(entry => 
+      entry.paramNames.join(',') === paramNames.join(',') &&
+      entry.regex.source === regex.source
+    );
+
+    if (!patternEntry) {
+      // Create new pattern entry
+      patternEntry = {
+        pattern: pattern,
+        paramNames: paramNames,
+        regex: regex,
+        handlers: []
+      };
+      existingEntries.push(patternEntry);
+    }
+
+    // Update handlers
+    patternEntry.handlers = existingHandlers;
+    this.patternListeners.set(pattern, existingEntries);
+    
+    if (this.debug) {
+      console.log(`PatternMatcher: Registered pattern listener for '${pattern}' (${patternEntry.handlers.length} total handlers for this pattern)`);
+    }
+  }
+
+  /**
+   * Unregister a pattern listener
+   * @param {string} pattern - Pattern path
+   * @param {Function} handler - Handler function to remove
+   * @returns {boolean} Success status
+   */
+  unregister(pattern, handler) {
+    if (!this.patternListeners.has(pattern)) {
+      return false;
+    }
+
+    const patternEntries = this.patternListeners.get(pattern);
+    let removed = false;
+
+    for (const patternEntry of patternEntries) {
+      const index = patternEntry.handlers.indexOf(handler);
+      if (index !== -1) {
+        patternEntry.handlers.splice(index, 1);
+        removed = true;
+      }
+    }
+
+    // Clean up empty pattern entries
+    const filteredEntries = patternEntries.filter(entry => entry.handlers.length > 0);
+    if (filteredEntries.length === 0) {
+      this.patternListeners.delete(pattern);
+    } else {
+      this.patternListeners.set(pattern, filteredEntries);
+    }
+
+    if (removed && this.debug) {
+      console.log(`PatternMatcher: Unregistered pattern listener for '${pattern}'`);
+    }
+
+    return removed;
+  }
+
+  /**
+   * Find all pattern matches for a given path
+   * @param {string} path - Actual path to match against
+   * @returns {Array<Object>} Array of { patternEntry, params } objects
+   */
+  findMatches(path) {
+    const matches = [];
+    
+    for (const [pattern, patternEntries] of this.patternListeners) {
+      for (const patternEntry of patternEntries) {
+        const matchResult = patternEntry.regex.exec(path);
+        if (matchResult) {
+          const params = this.extractParams(pattern, patternEntry.paramNames, matchResult);
+          matches.push({ patternEntry, params });
+        }
+      }
+    }
+    
+    return matches;
+  }
+
+  /**
+   * Check if pattern listeners exist for a pattern
+   * @param {string} pattern - Pattern path
+   * @returns {boolean} True if pattern listeners exist
+   */
+  has(pattern) {
+    return this.patternListeners.has(pattern) && 
+           this.patternListeners.get(pattern).some(entry => entry.handlers.length > 0);
+  }
+
+  /**
+   * Get pattern listener count for a specific pattern
+   * @param {string} pattern - Pattern path
+   * @returns {number} Total number of handlers for this pattern
+   */
+  getCount(pattern) {
+    if (!this.patternListeners.has(pattern)) {
+      return 0;
+    }
+    
+    return this.patternListeners.get(pattern).reduce((sum, entry) => sum + entry.handlers.length, 0);
+  }
+
+  /**
+   * Get all registered patterns
+   * @returns {Array<string>} Array of pattern strings
+   */
+  getPatterns() {
+    return Array.from(this.patternListeners.keys());
+  }
+
+  /**
+   * Get total pattern listener count across all patterns
+   * @returns {number} Total number of pattern listeners
+   */
+  getTotalCount() {
+    return Array.from(this.patternListeners.values()).reduce((sum, entries) => {
+      return sum + entries.reduce((entrySum, entry) => entrySum + entry.handlers.length, 0);
+    }, 0);
+  }
+
+  /**
+   * Get number of registered patterns
+   * @returns {number} Number of patterns
+   */
+  getPatternCount() {
+    return this.patternListeners.size;
+  }
+
+  /**
+   * Clear all pattern listeners
+   * @returns {void}
+   */
+  clear() {
+    this.patternListeners.clear();
+    
+    if (this.debug) {
+      console.log(`PatternMatcher: Cleared all pattern listeners`);
+    }
+  }
+}
+