@saulwade/swl-ses 2.3.0 → 2.4.1

package/gateway/lib/event-channel.js

@@ -1,191 +1,191 @@
-'use strict';
-
-/**
- * event-channel.js
- *
- * Pub/sub event channel para CommandRelay y otros componentes del gateway.
- *
- * Patrón adaptado de `temp/obsidian-agent-client-master/src/acp/acp-handler.ts`
- * (Set<listeners> con callback unsubscribe). Diferencias:
- *   - Zero-deps Node.js (sin RxJS, sin EventEmitter de node — Set nativo).
- *   - Backward compat: si no hay listeners, comportamiento idéntico al actual.
- *   - Tipos de evento explícitos para evitar typos.
- *
- * Casos de uso en SWL:
- *   - CommandRelay emite eventos al recibir/aceptar/rechazar/procesar comandos.
- *   - Múltiples adaptadores (Telegram, Discord) pueden suscribirse simultáneamente.
- *   - El consumidor /swl:inbox puede mostrar progreso sin polling.
- *
- * Uso:
- *   const channel = new EventChannel();
- *   const off = channel.on('cmd:queued', (event) => console.log(event));
- *   channel.emit({ type: 'cmd:queued', commandId: 'cmd-abc', userId: '123' });
- *   off();  // unsubscribe
- *
- * @module gateway/lib/event-channel
- */
-
-// ── tipos de evento ──────────────────────────────────────────────────────────
-
-/**
- * Tipos válidos de evento. Se usan strings para serializar fácilmente
- * a JSONL si se requiere persistencia (no obligatorio).
- */
-const EVENTS = Object.freeze({
-  // Lifecycle de comandos en CommandRelay
-  CMD_RECEIVED:  'cmd:received',   // mensaje llegó al relay
-  CMD_REJECTED:  'cmd:rejected',   // rechazado por validación (auth/rate/dedup)
-  CMD_QUEUED:    'cmd:queued',     // encolado en .planning/inbox/
-  CMD_PROCESSED: 'cmd:processed',  // marcado como procesado por consumidor
-
-  // Lifecycle de notificaciones
-  NOTIFICATION_SENT:   'notification:sent',
-  NOTIFICATION_FAILED: 'notification:failed',
-});
-
-// ── implementación ────────────────────────────────────────────────────────────
-
-/**
- * Canal de eventos pub/sub con escucha por tipo o wildcard.
- *
- * Mantiene dos estructuras:
- *   - listenersByType: Map<eventType, Set<callback>>
- *   - wildcardListeners: Set<callback>  (escuchan TODOS los eventos)
- *
- * Una excepción en un listener NO interrumpe la propagación a los demás —
- * patrón de aislamiento del mismo origen (acp-handler.ts:47-50).
- */
-class EventChannel {
-  constructor() {
-    this.listenersByType = new Map();
-    this.wildcardListeners = new Set();
-    this.errorHandler = null;  // opcional: callback para errores en listeners
-  }
-
-  /**
-   * Suscribe un listener a un tipo de evento (o '*' para todos).
-   *
-   * @param {string} eventType - tipo de evento o '*'
-   * @param {function} callback - recibe el objeto event
-   * @returns {function} función de unsubscribe (idempotente)
-   */
-  on(eventType, callback) {
-    if (typeof callback !== 'function') {
-      throw new TypeError('callback debe ser función');
-    }
-    if (typeof eventType !== 'string' || !eventType) {
-      throw new TypeError('eventType debe ser string no vacío');
-    }
-
-    if (eventType === '*') {
-      this.wildcardListeners.add(callback);
-      return () => this.wildcardListeners.delete(callback);
-    }
-
-    if (!this.listenersByType.has(eventType)) {
-      this.listenersByType.set(eventType, new Set());
-    }
-    const set = this.listenersByType.get(eventType);
-    set.add(callback);
-    return () => set.delete(callback);
-  }
-
-  /**
-   * Suscribe un listener que se invoca UNA sola vez y luego se desuscribe.
-   */
-  once(eventType, callback) {
-    const off = this.on(eventType, (event) => {
-      off();
-      callback(event);
-    });
-    return off;
-  }
-
-  /**
-   * Emite un evento a todos los listeners suscriptos al tipo + wildcards.
-   * El evento debe tener al menos `type`. Se enriquece con `ts` (ISO).
-   *
-   * @param {object} event - objeto con `type` y datos arbitrarios
-   * @returns {number} cantidad de listeners notificados
-   */
-  emit(event) {
-    if (!event || typeof event !== 'object') {
-      throw new TypeError('event debe ser objeto');
-    }
-    if (typeof event.type !== 'string' || !event.type) {
-      throw new TypeError('event.type es obligatorio');
-    }
-
-    const enriched = { ts: new Date().toISOString(), ...event };
-    let notified = 0;
-
-    // Listeners específicos del tipo
-    const typedSet = this.listenersByType.get(enriched.type);
-    if (typedSet) {
-      for (const cb of typedSet) {
-        notified++;
-        this._safeInvoke(cb, enriched);
-      }
-    }
-
-    // Listeners wildcard
-    for (const cb of this.wildcardListeners) {
-      notified++;
-      this._safeInvoke(cb, enriched);
-    }
-
-    return notified;
-  }
-
-  /**
-   * Cuenta de listeners para un tipo (o total si no se pasa tipo).
-   */
-  listenerCount(eventType) {
-    if (eventType == null) {
-      let total = this.wildcardListeners.size;
-      for (const set of this.listenersByType.values()) total += set.size;
-      return total;
-    }
-    if (eventType === '*') return this.wildcardListeners.size;
-    const set = this.listenersByType.get(eventType);
-    return (set ? set.size : 0) + this.wildcardListeners.size;
-  }
-
-  /**
-   * Limpia todos los listeners. Útil para tests.
-   */
-  clear() {
-    this.listenersByType.clear();
-    this.wildcardListeners.clear();
-  }
-
-  /**
-   * Asigna un handler para errores en listeners.
-   * Si no se asigna, los errores se silencian (no rompen la propagación).
-   */
-  onError(handler) {
-    if (typeof handler !== 'function') {
-      throw new TypeError('handler debe ser función');
-    }
-    this.errorHandler = handler;
-  }
-
-  // ── internos ────────────────────────────────────────────────────────────────
-
-  _safeInvoke(cb, event) {
-    try {
-      cb(event);
-    } catch (err) {
-      if (this.errorHandler) {
-        try { this.errorHandler(err, event); } catch (_) { /* silencioso */ }
-      }
-    }
-  }
-}
-
-// ── exports ───────────────────────────────────────────────────────────────────
-
-module.exports = {
-  EventChannel,
-  EVENTS,
-};
+'use strict';
+
+/**
+ * event-channel.js
+ *
+ * Pub/sub event channel para CommandRelay y otros componentes del gateway.
+ *
+ * Patrón adaptado de `temp/obsidian-agent-client-master/src/acp/acp-handler.ts`
+ * (Set<listeners> con callback unsubscribe). Diferencias:
+ *   - Zero-deps Node.js (sin RxJS, sin EventEmitter de node — Set nativo).
+ *   - Backward compat: si no hay listeners, comportamiento idéntico al actual.
+ *   - Tipos de evento explícitos para evitar typos.
+ *
+ * Casos de uso en SWL:
+ *   - CommandRelay emite eventos al recibir/aceptar/rechazar/procesar comandos.
+ *   - Múltiples adaptadores (Telegram, Discord) pueden suscribirse simultáneamente.
+ *   - El consumidor /swl:inbox puede mostrar progreso sin polling.
+ *
+ * Uso:
+ *   const channel = new EventChannel();
+ *   const off = channel.on('cmd:queued', (event) => console.log(event));
+ *   channel.emit({ type: 'cmd:queued', commandId: 'cmd-abc', userId: '123' });
+ *   off();  // unsubscribe
+ *
+ * @module gateway/lib/event-channel
+ */
+
+// ── tipos de evento ──────────────────────────────────────────────────────────
+
+/**
+ * Tipos válidos de evento. Se usan strings para serializar fácilmente
+ * a JSONL si se requiere persistencia (no obligatorio).
+ */
+const EVENTS = Object.freeze({
+  // Lifecycle de comandos en CommandRelay
+  CMD_RECEIVED:  'cmd:received',   // mensaje llegó al relay
+  CMD_REJECTED:  'cmd:rejected',   // rechazado por validación (auth/rate/dedup)
+  CMD_QUEUED:    'cmd:queued',     // encolado en .planning/inbox/
+  CMD_PROCESSED: 'cmd:processed',  // marcado como procesado por consumidor
+
+  // Lifecycle de notificaciones
+  NOTIFICATION_SENT:   'notification:sent',
+  NOTIFICATION_FAILED: 'notification:failed',
+});
+
+// ── implementación ────────────────────────────────────────────────────────────
+
+/**
+ * Canal de eventos pub/sub con escucha por tipo o wildcard.
+ *
+ * Mantiene dos estructuras:
+ *   - listenersByType: Map<eventType, Set<callback>>
+ *   - wildcardListeners: Set<callback>  (escuchan TODOS los eventos)
+ *
+ * Una excepción en un listener NO interrumpe la propagación a los demás —
+ * patrón de aislamiento del mismo origen (acp-handler.ts:47-50).
+ */
+class EventChannel {
+  constructor() {
+    this.listenersByType = new Map();
+    this.wildcardListeners = new Set();
+    this.errorHandler = null;  // opcional: callback para errores en listeners
+  }
+
+  /**
+   * Suscribe un listener a un tipo de evento (o '*' para todos).
+   *
+   * @param {string} eventType - tipo de evento o '*'
+   * @param {function} callback - recibe el objeto event
+   * @returns {function} función de unsubscribe (idempotente)
+   */
+  on(eventType, callback) {
+    if (typeof callback !== 'function') {
+      throw new TypeError('callback debe ser función');
+    }
+    if (typeof eventType !== 'string' || !eventType) {
+      throw new TypeError('eventType debe ser string no vacío');
+    }
+
+    if (eventType === '*') {
+      this.wildcardListeners.add(callback);
+      return () => this.wildcardListeners.delete(callback);
+    }
+
+    if (!this.listenersByType.has(eventType)) {
+      this.listenersByType.set(eventType, new Set());
+    }
+    const set = this.listenersByType.get(eventType);
+    set.add(callback);
+    return () => set.delete(callback);
+  }
+
+  /**
+   * Suscribe un listener que se invoca UNA sola vez y luego se desuscribe.
+   */
+  once(eventType, callback) {
+    const off = this.on(eventType, (event) => {
+      off();
+      callback(event);
+    });
+    return off;
+  }
+
+  /**
+   * Emite un evento a todos los listeners suscriptos al tipo + wildcards.
+   * El evento debe tener al menos `type`. Se enriquece con `ts` (ISO).
+   *
+   * @param {object} event - objeto con `type` y datos arbitrarios
+   * @returns {number} cantidad de listeners notificados
+   */
+  emit(event) {
+    if (!event || typeof event !== 'object') {
+      throw new TypeError('event debe ser objeto');
+    }
+    if (typeof event.type !== 'string' || !event.type) {
+      throw new TypeError('event.type es obligatorio');
+    }
+
+    const enriched = { ts: new Date().toISOString(), ...event };
+    let notified = 0;
+
+    // Listeners específicos del tipo
+    const typedSet = this.listenersByType.get(enriched.type);
+    if (typedSet) {
+      for (const cb of typedSet) {
+        notified++;
+        this._safeInvoke(cb, enriched);
+      }
+    }
+
+    // Listeners wildcard
+    for (const cb of this.wildcardListeners) {
+      notified++;
+      this._safeInvoke(cb, enriched);
+    }
+
+    return notified;
+  }
+
+  /**
+   * Cuenta de listeners para un tipo (o total si no se pasa tipo).
+   */
+  listenerCount(eventType) {
+    if (eventType == null) {
+      let total = this.wildcardListeners.size;
+      for (const set of this.listenersByType.values()) total += set.size;
+      return total;
+    }
+    if (eventType === '*') return this.wildcardListeners.size;
+    const set = this.listenersByType.get(eventType);
+    return (set ? set.size : 0) + this.wildcardListeners.size;
+  }
+
+  /**
+   * Limpia todos los listeners. Útil para tests.
+   */
+  clear() {
+    this.listenersByType.clear();
+    this.wildcardListeners.clear();
+  }
+
+  /**
+   * Asigna un handler para errores en listeners.
+   * Si no se asigna, los errores se silencian (no rompen la propagación).
+   */
+  onError(handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('handler debe ser función');
+    }
+    this.errorHandler = handler;
+  }
+
+  // ── internos ────────────────────────────────────────────────────────────────
+
+  _safeInvoke(cb, event) {
+    try {
+      cb(event);
+    } catch (err) {
+      if (this.errorHandler) {
+        try { this.errorHandler(err, event); } catch (_) { /* silencioso */ }
+      }
+    }
+  }
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  EventChannel,
+  EVENTS,
+};