webspresso 0.0.100 → 0.0.102

package/core/events/dispatcher.js

@@ -0,0 +1,552 @@
+/**
+ * Webspresso Events - Decoupled Event & Signals Dispatcher (AdonisJS Events & Django Signals-inspired)
+ * Zero-dependency event dispatcher supporting sync, async parallel, serial, waterfall,
+ * wildcard pattern matching, Django-style sender filtering, and background queue bridging.
+ * @module core/events/dispatcher
+ */
+
+const EventEmitter = require('events');
+
+/**
+ * Convert a glob/wildcard pattern (e.g. 'order.*', 'order.**', '*') into a RegExp
+ * @param {string} pattern
+ * @returns {RegExp}
+ */
+function patternToRegExp(pattern) {
+  if (pattern === '*' || pattern === '**') {
+    return /^.*$/;
+  }
+
+  const escaped = pattern
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars except *
+    .replace(/\*\*/g, '___DOUBLE_STAR___')
+    .replace(/\*/g, '[^.]+')
+    .replace(/___DOUBLE_STAR___/g, '.*');
+
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * Match sender against filter
+ * @param {any} expectedSender
+ * @param {any} actualSender
+ * @returns {boolean}
+ */
+function matchesSender(expectedSender, actualSender) {
+  if (expectedSender === undefined || expectedSender === null) {
+    return true; // No sender filter applied
+  }
+  if (actualSender === undefined || actualSender === null) {
+    return false; // Filter requested but no sender provided
+  }
+  if (expectedSender === actualSender) {
+    return true;
+  }
+  // If sender is string or object with name (e.g. Model class or name)
+  const expName = typeof expectedSender === 'function' ? expectedSender.name : (expectedSender.name || String(expectedSender));
+  const actName = typeof actualSender === 'function' ? actualSender.name : (actualSender.name || String(actualSender));
+  return expName.toLowerCase() === actName.toLowerCase();
+}
+
+/**
+ * EventDispatcher - Enterprise Event & Signal Dispatcher
+ */
+class EventDispatcher extends EventEmitter {
+  /**
+   * @param {Object} [options]
+   * @param {any} [options.queue] - Optional Webspresso QueueManager instance for bridging
+   * @param {number} [options.maxListeners=50]
+   * @param {any} [options.logger=console]
+   */
+  constructor(options = {}) {
+    super();
+    this.maxListeners = options.maxListeners || 50;
+    this.setMaxListeners(this.maxListeners);
+
+    this.queue = options.queue || null;
+    this.logger = options.logger || console;
+
+    /** @type {Map<string, Array<{ id: number, handler: Function, once: boolean, sender?: any, priority: number }>>} */
+    this.exactListeners = new Map();
+
+    /** @type {Array<{ id: number, pattern: string, regex: RegExp, handler: Function, once: boolean, sender?: any, priority: number }>} */
+    this.wildcardListeners = [];
+
+    /** @type {Array<{ id: number, handler: Function, once: boolean, priority: number }>} */
+    this.anyListeners = [];
+
+    this._idCounter = 0;
+  }
+
+  /**
+   * Register an event listener
+   * @param {string} event - Event name or wildcard pattern (e.g. 'order.created', 'order.*')
+   * @param {Function} handler - Listener function (data, meta) => any
+   * @param {Object} [options]
+   * @param {any} [options.sender] - Django-style sender filter
+   * @param {number} [options.priority=0] - Execution priority (higher runs first)
+   * @param {boolean} [options.once=false] - Whether to fire only once
+   * @returns {Function} Unsubscribe function
+   */
+  on(event, handler, options = {}) {
+    if (typeof event !== 'string' || !event) {
+      throw new TypeError('Event name must be a non-empty string');
+    }
+    if (typeof handler !== 'function') {
+      throw new TypeError('Handler must be a function');
+    }
+
+    const id = ++this._idCounter;
+    const priority = typeof options.priority === 'number' ? options.priority : 0;
+    const once = Boolean(options.once);
+    const sender = options.sender ?? null;
+
+    const listenerRecord = { id, handler, once, sender, priority };
+
+    if (event.includes('*') || event.includes('?')) {
+      this.wildcardListeners.push({
+        ...listenerRecord,
+        pattern: event,
+        regex: patternToRegExp(event),
+      });
+    } else {
+      if (!this.exactListeners.has(event)) {
+        this.exactListeners.set(event, []);
+      }
+      this.exactListeners.get(event).push(listenerRecord);
+    }
+
+    // Return unsubscribe function
+    return () => this.off(event, handler);
+  }
+
+  /**
+   * Register a one-time event listener
+   * @param {string} event
+   * @param {Function} handler
+   * @param {Object} [options]
+   * @returns {Function} Unsubscribe function
+   */
+  once(event, handler, options = {}) {
+    return this.on(event, handler, { ...options, once: true });
+  }
+
+  /**
+   * Remove an event listener
+   * @param {string} event
+   * @param {Function} handler
+   * @returns {this}
+   */
+  off(event, handler) {
+    if (typeof event !== 'string' || typeof handler !== 'function') {
+      return this;
+    }
+
+    if (event.includes('*') || event.includes('?')) {
+      this.wildcardListeners = this.wildcardListeners.filter(
+        (l) => !(l.pattern === event && l.handler === handler)
+      );
+    } else if (this.exactListeners.has(event)) {
+      const list = this.exactListeners.get(event).filter((l) => l.handler !== handler);
+      if (list.length === 0) {
+        this.exactListeners.delete(event);
+      } else {
+        this.exactListeners.set(event, list);
+      }
+    }
+
+    return this;
+  }
+
+  /**
+   * Catch-all listener for every event
+   * @param {Function} handler - (eventName, data, meta) => any
+   * @param {Object} [options]
+   * @returns {Function} Unsubscribe function
+   */
+  onAny(handler, options = {}) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('Handler must be a function');
+    }
+    const id = ++this._idCounter;
+    const priority = typeof options.priority === 'number' ? options.priority : 0;
+    const once = Boolean(options.once);
+
+    const record = { id, handler, once, priority };
+    this.anyListeners.push(record);
+
+    return () => {
+      this.anyListeners = this.anyListeners.filter((l) => l.id !== id);
+    };
+  }
+
+  /**
+   * Collect matched listeners sorted by priority
+   * @protected
+   * @param {string} event
+   * @param {any} [sender]
+   * @returns {Array<{ handler: Function, isAny: boolean, remove: Function }>}
+   */
+  _getMatchedListeners(event, sender = null) {
+    const matched = [];
+
+    // 1. Exact listeners
+    if (this.exactListeners.has(event)) {
+      const list = this.exactListeners.get(event);
+      const toKeep = [];
+      for (const item of list) {
+        if (matchesSender(item.sender, sender)) {
+          matched.push({
+            priority: item.priority,
+            handler: item.handler,
+            isAny: false,
+            remove: () => {
+              const current = this.exactListeners.get(event) || [];
+              this.exactListeners.set(event, current.filter((l) => l.id !== item.id));
+            },
+            once: item.once,
+          });
+        }
+        if (!item.once) {
+          toKeep.push(item);
+        }
+      }
+      this.exactListeners.set(event, toKeep);
+    }
+
+    // 2. Wildcard listeners
+    const remainingWildcards = [];
+    for (const item of this.wildcardListeners) {
+      if (item.regex.test(event) && matchesSender(item.sender, sender)) {
+        matched.push({
+          priority: item.priority,
+          handler: item.handler,
+          isAny: false,
+          remove: () => {
+            this.wildcardListeners = this.wildcardListeners.filter((l) => l.id !== item.id);
+          },
+          once: item.once,
+        });
+      }
+      if (!item.once) {
+        remainingWildcards.push(item);
+      }
+    }
+    this.wildcardListeners = remainingWildcards;
+
+    // 3. Any listeners
+    const remainingAny = [];
+    for (const item of this.anyListeners) {
+      matched.push({
+        priority: item.priority,
+        handler: item.handler,
+        isAny: true,
+        remove: () => {
+          this.anyListeners = this.anyListeners.filter((l) => l.id !== item.id);
+        },
+        once: item.once,
+      });
+      if (!item.once) {
+        remainingAny.push(item);
+      }
+    }
+    this.anyListeners = remainingAny;
+
+    // Sort by priority descending (higher numbers first)
+    matched.sort((a, b) => b.priority - a.priority);
+
+    return matched;
+  }
+
+  /**
+   * Parse event argument (supports event class instance)
+   * @protected
+   */
+  _parseEmitArgs(eventOrInstance, data, options) {
+    if (eventOrInstance && typeof eventOrInstance === 'object' && eventOrInstance.eventName) {
+      return {
+        event: eventOrInstance.eventName,
+        data: eventOrInstance,
+        options: data || {},
+      };
+    }
+    return {
+      event: String(eventOrInstance),
+      data,
+      options: options || {},
+    };
+  }
+
+  /**
+   * Synchronous / fire-and-forget emit
+   * @param {string|Object} eventOrInstance - Event name or Event class instance
+   * @param {any} [data] - Event payload
+   * @param {Object} [options] - Options ({ sender })
+   * @returns {boolean} Whether any listeners were invoked
+   */
+  emit(eventOrInstance, data, options = {}) {
+    const parsed = this._parseEmitArgs(eventOrInstance, data, options);
+    const { event, data: payload, options: opts } = parsed;
+    const sender = opts.sender ?? null;
+
+    const listeners = this._getMatchedListeners(event, sender);
+    if (listeners.length === 0) {
+      return false;
+    }
+
+    const meta = { event, sender, timestamp: Date.now() };
+
+    for (const listener of listeners) {
+      try {
+        if (listener.isAny) {
+          listener.handler(event, payload, meta);
+        } else {
+          listener.handler(payload, meta);
+        }
+      } catch (err) {
+        // Emit error on dispatcher or log
+        if (this.listenerCount('error') > 0) {
+          super.emit('error', err);
+        } else if (this.logger && typeof this.logger.error === 'function') {
+          this.logger.error(`[EventDispatcher] Error in listener for event "${event}":`, err);
+        }
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Asynchronous parallel emit (AdonisJS-style)
+   * Invokes all matching listeners concurrently with Promise.allSettled
+   * @param {string|Object} eventOrInstance
+   * @param {any} [data]
+   * @param {Object} [options]
+   * @returns {Promise<Array<{ status: 'fulfilled'|'rejected', value?: any, reason?: any }>>}
+   */
+  async emitAsync(eventOrInstance, data, options = {}) {
+    const parsed = this._parseEmitArgs(eventOrInstance, data, options);
+    const { event, data: payload, options: opts } = parsed;
+    const sender = opts.sender ?? null;
+
+    const listeners = this._getMatchedListeners(event, sender);
+    if (listeners.length === 0) {
+      return [];
+    }
+
+    const meta = { event, sender, timestamp: Date.now() };
+
+    const promises = listeners.map(async (listener) => {
+      if (listener.isAny) {
+        return listener.handler(event, payload, meta);
+      }
+      return listener.handler(payload, meta);
+    });
+
+    return Promise.allSettled(promises);
+  }
+
+  /**
+   * Alias for emitAsync
+   */
+  async emitParallel(eventOrInstance, data, options = {}) {
+    return this.emitAsync(eventOrInstance, data, options);
+  }
+
+  /**
+   * Asynchronous sequential emit (one after another in priority order)
+   * @param {string|Object} eventOrInstance
+   * @param {any} [data]
+   * @param {Object} [options]
+   * @returns {Promise<any[]>} Array of return values
+   */
+  async emitSerial(eventOrInstance, data, options = {}) {
+    const parsed = this._parseEmitArgs(eventOrInstance, data, options);
+    const { event, data: payload, options: opts } = parsed;
+    const sender = opts.sender ?? null;
+
+    const listeners = this._getMatchedListeners(event, sender);
+    if (listeners.length === 0) {
+      return [];
+    }
+
+    const meta = { event, sender, timestamp: Date.now() };
+    const results = [];
+
+    for (const listener of listeners) {
+      const res = listener.isAny
+        ? await listener.handler(event, payload, meta)
+        : await listener.handler(payload, meta);
+      results.push(res);
+    }
+
+    return results;
+  }
+
+  /**
+   * Waterfall sequential emit: Each listener receives the output of the previous listener
+   * @param {string|Object} eventOrInstance
+   * @param {any} initialData
+   * @param {Object} [options]
+   * @returns {Promise<any>} Final transformed data
+   */
+  async emitWaterfall(eventOrInstance, initialData, options = {}) {
+    const parsed = this._parseEmitArgs(eventOrInstance, initialData, options);
+    const { event, data: payload, options: opts } = parsed;
+    const sender = opts.sender ?? null;
+
+    const listeners = this._getMatchedListeners(event, sender);
+    if (listeners.length === 0) {
+      return payload;
+    }
+
+    const meta = { event, sender, timestamp: Date.now() };
+    let currentData = payload;
+
+    for (const listener of listeners) {
+      const res = listener.isAny
+        ? await listener.handler(event, currentData, meta)
+        : await listener.handler(currentData, meta);
+
+      if (res !== undefined) {
+        currentData = res;
+      }
+    }
+
+    return currentData;
+  }
+
+  /**
+   * Set or update background queue manager for job dispatching
+   * @param {any} queueManager
+   * @returns {this}
+   */
+  setQueue(queueManager) {
+    this.queue = queueManager;
+    return this;
+  }
+
+  /**
+   * Bridge an event to a background queue job (Adonis / Laravel style)
+   * When event is fired, automatically dispatches to `queue.dispatch(jobName, data, queueOptions)`
+   * @param {string} event - Event name
+   * @param {string} jobName - Queue job name
+   * @param {Object} [queueOptions] - Dispatch options (delay, priority, retries, etc.)
+   * @returns {Function} Unsubscribe function
+   */
+  listenAndQueue(event, jobName, queueOptions = {}) {
+    return this.on(event, (data) => {
+      if (!this.queue || typeof this.queue.dispatch !== 'function') {
+        throw new Error(
+          `[EventDispatcher] Cannot queue job '${jobName}' for event '${event}'. No QueueManager is attached.`
+        );
+      }
+      return this.queue.dispatch(jobName, data, queueOptions);
+    });
+  }
+
+  /**
+   * Bridge Django-style ORM lifecycle events (ModelEvents) into application dispatcher
+   * Emits 'model:created', 'model:updated', 'model:deleted'
+   * @param {import('../orm/events').ModelEventsClass} [modelEvents]
+   * @returns {Function} Detach function
+   */
+  bridgeOrm(modelEvents) {
+    if (!modelEvents || typeof modelEvents.on !== 'function') {
+      return () => {};
+    }
+
+    const unsubs = [
+      modelEvents.on('*.afterCreate', (record, ctx) => {
+        this.emit('model:created', record, { sender: ctx.model, trx: ctx.trx });
+        this.emit(`${ctx.model.toLowerCase()}:created`, record, { sender: ctx.model, trx: ctx.trx });
+      }),
+      modelEvents.on('*.afterUpdate', (record, ctx) => {
+        this.emit('model:updated', record, { sender: ctx.model, trx: ctx.trx });
+        this.emit(`${ctx.model.toLowerCase()}:updated`, record, { sender: ctx.model, trx: ctx.trx });
+      }),
+      modelEvents.on('*.afterDelete', (record, ctx) => {
+        this.emit('model:deleted', record, { sender: ctx.model, trx: ctx.trx });
+        this.emit(`${ctx.model.toLowerCase()}:deleted`, record, { sender: ctx.model, trx: ctx.trx });
+      }),
+    ];
+
+    return () => {
+      for (const unsub of unsubs) {
+        if (typeof unsub === 'function') unsub();
+      }
+    };
+  }
+
+  /**
+   * Get all registered event names and wildcard patterns
+   * @returns {string[]}
+   */
+  eventNames() {
+    const exact = Array.from(this.exactListeners.keys());
+    const wildcards = this.wildcardListeners.map((w) => w.pattern);
+    return Array.from(new Set([...exact, ...wildcards]));
+  }
+
+  /**
+   * Get count of listeners for a given event name
+   * @param {string} [event]
+   * @returns {number}
+   */
+  listenerCount(event) {
+    if (!event) {
+      let count = 0;
+      for (const list of this.exactListeners.values()) count += list.length;
+      count += this.wildcardListeners.length;
+      count += this.anyListeners.length;
+      return count;
+    }
+
+    let count = (this.exactListeners.get(event) || []).length;
+    for (const w of this.wildcardListeners) {
+      if (w.regex.test(event)) count++;
+    }
+    count += this.anyListeners.length;
+    return count;
+  }
+
+  /**
+   * Remove all listeners
+   * @param {string} [event]
+   * @returns {this}
+   */
+  removeAllListeners(event) {
+    if (event) {
+      this.exactListeners.delete(event);
+      this.wildcardListeners = this.wildcardListeners.filter((w) => w.pattern !== event);
+    } else {
+      this.exactListeners.clear();
+      this.wildcardListeners = [];
+      this.anyListeners = [];
+    }
+    return this;
+  }
+
+  /**
+   * Reset / clear dispatcher state
+   */
+  clear() {
+    this.removeAllListeners();
+  }
+}
+
+/**
+ * Factory to create a new EventDispatcher
+ * @param {Object} [options]
+ * @returns {EventDispatcher}
+ */
+function createEventDispatcher(options = {}) {
+  return new EventDispatcher(options);
+}
+
+module.exports = {
+  EventDispatcher,
+  createEventDispatcher,
+  patternToRegExp,
+  matchesSender,
+};

package/core/events/index.js

@@ -0,0 +1,23 @@
+/**
+ * Webspresso Events Subsystem - Decoupled Event & Signals Architecture
+ * (AdonisJS Events & Django Signals-inspired)
+ * @module core/events
+ */
+
+const { EventDispatcher, createEventDispatcher } = require('./dispatcher');
+const { Signal, defineSignal } = require('./signal');
+const { defineListener, loadListeners } = require('./discovery');
+
+// Global default event dispatcher instance
+const defaultDispatcher = createEventDispatcher();
+
+module.exports = {
+  EventDispatcher,
+  createEventDispatcher,
+  defaultDispatcher,
+  events: defaultDispatcher,
+  Signal,
+  defineSignal,
+  defineListener,
+  loadListeners,
+};

package/core/events/signal.js

@@ -0,0 +1,92 @@
+/**
+ * Webspresso Events - Django-Style Signals Subsystem
+ * Declarative Signal objects with sender filtering, connect, disconnect, and send methods.
+ * @module core/events/signal
+ */
+
+/**
+ * Signal class representing a named event channel (Django-inspired)
+ */
+class Signal {
+  /**
+   * @param {string} name - Signal identifier name (e.g. 'order_placed', 'user_registered')
+   * @param {import('./dispatcher').EventDispatcher} dispatcher
+   */
+  constructor(name, dispatcher) {
+    if (!name || typeof name !== 'string') {
+      throw new TypeError('Signal name must be a non-empty string');
+    }
+    this.name = name;
+    this.dispatcher = dispatcher;
+  }
+
+  /**
+   * Connect a receiver/listener to this signal
+   * @param {Function} receiver - (data, meta) => any
+   * @param {Object} [options]
+   * @param {any} [options.sender] - Filter by specific sender (class, object, or string)
+   * @param {number} [options.priority=0] - Priority order
+   * @param {boolean} [options.once=false] - Fire only once
+   * @returns {Function} Disconnect function
+   */
+  connect(receiver, options = {}) {
+    return this.dispatcher.on(this.name, receiver, options);
+  }
+
+  /**
+   * Disconnect a receiver from this signal
+   * @param {Function} receiver
+   * @returns {this}
+   */
+  disconnect(receiver) {
+    this.dispatcher.off(this.name, receiver);
+    return this;
+  }
+
+  /**
+   * Send the signal (synchronous / fire-and-forget)
+   * @param {any} [data] - Signal payload
+   * @param {Object} [options] - Options ({ sender })
+   * @returns {boolean} Whether any receivers were invoked
+   */
+  send(data, options = {}) {
+    return this.dispatcher.emit(this.name, data, options);
+  }
+
+  /**
+   * Send the signal asynchronously in parallel
+   * @param {any} [data]
+   * @param {Object} [options]
+   * @returns {Promise<Array<{ status: 'fulfilled'|'rejected', value?: any, reason?: any }>>}
+   */
+  async sendAsync(data, options = {}) {
+    return this.dispatcher.emitAsync(this.name, data, options);
+  }
+
+  /**
+   * Send the signal asynchronously in series (one receiver at a time)
+   * @param {any} [data]
+   * @param {Object} [options]
+   * @returns {Promise<any[]>}
+   */
+  async sendSerial(data, options = {}) {
+    return this.dispatcher.emitSerial(this.name, data, options);
+  }
+}
+
+/**
+ * Define a named Signal
+ * @param {string} name
+ * @param {import('./dispatcher').EventDispatcher} [dispatcher]
+ * @returns {Signal}
+ */
+function defineSignal(name, dispatcher) {
+  const { defaultDispatcher } = require('./index');
+  const targetDispatcher = dispatcher || defaultDispatcher;
+  return new Signal(name, targetDispatcher);
+}
+
+module.exports = {
+  Signal,
+  defineSignal,
+};