@parsrun/service 0.1.0

package/dist/events/index.js

@@ -0,0 +1,853 @@
+// src/events/format.ts
+import { generateId } from "@parsrun/core";
+function createEvent(options) {
+  const event = {
+    specversion: "1.0",
+    type: options.type,
+    source: options.source,
+    id: options.id ?? generateId(),
+    time: (/* @__PURE__ */ new Date()).toISOString(),
+    datacontenttype: "application/json",
+    data: options.data
+  };
+  if (options.subject) event.subject = options.subject;
+  if (options.tenantId) event.parstenantid = options.tenantId;
+  if (options.requestId) event.parsrequestid = options.requestId;
+  if (options.traceContext) event.parstracecontext = formatTraceContext(options.traceContext);
+  if (options.delivery) event.parsdelivery = options.delivery;
+  return event;
+}
+function toCloudEvent(event) {
+  return { ...event };
+}
+function toCompactEvent(event) {
+  const compact = {
+    e: event.type,
+    s: event.source,
+    i: event.id,
+    t: new Date(event.time).getTime(),
+    d: event.data
+  };
+  if (event.parstracecontext) compact.ctx = event.parstracecontext;
+  if (event.parstenantid) compact.tid = event.parstenantid;
+  return compact;
+}
+function fromCompactEvent(compact, source) {
+  const event = {
+    specversion: "1.0",
+    type: compact.e,
+    source: source ?? compact.s,
+    id: compact.i,
+    time: new Date(compact.t).toISOString(),
+    datacontenttype: "application/json",
+    data: compact.d
+  };
+  if (compact.ctx) event.parstracecontext = compact.ctx;
+  if (compact.tid) event.parstenantid = compact.tid;
+  return event;
+}
+function formatEventType(source, type) {
+  return `com.pars.${source}.${type}`;
+}
+function parseEventType(fullType) {
+  const prefix = "com.pars.";
+  if (!fullType.startsWith(prefix)) {
+    const parts = fullType.split(".");
+    if (parts.length >= 2) {
+      const [source, ...rest] = parts;
+      return { source, type: rest.join(".") };
+    }
+    return null;
+  }
+  const withoutPrefix = fullType.slice(prefix.length);
+  const dotIndex = withoutPrefix.indexOf(".");
+  if (dotIndex === -1) {
+    return null;
+  }
+  return {
+    source: withoutPrefix.slice(0, dotIndex),
+    type: withoutPrefix.slice(dotIndex + 1)
+  };
+}
+function matchEventType(type, pattern) {
+  if (pattern === "*" || pattern === "**") {
+    return true;
+  }
+  const typeParts = type.split(".");
+  const patternParts = pattern.split(".");
+  let ti = 0;
+  let pi = 0;
+  while (ti < typeParts.length && pi < patternParts.length) {
+    const pp = patternParts[pi];
+    if (pp === "**") {
+      if (pi === patternParts.length - 1) {
+        return true;
+      }
+      for (let i = ti; i <= typeParts.length; i++) {
+        const remaining = typeParts.slice(i).join(".");
+        const remainingPattern = patternParts.slice(pi + 1).join(".");
+        if (matchEventType(remaining, remainingPattern)) {
+          return true;
+        }
+      }
+      return false;
+    }
+    if (pp === "*") {
+      ti++;
+      pi++;
+      continue;
+    }
+    if (pp !== typeParts[ti]) {
+      return false;
+    }
+    ti++;
+    pi++;
+  }
+  return ti === typeParts.length && pi === patternParts.length;
+}
+function formatTraceContext(ctx) {
+  const flags = ctx.traceFlags.toString(16).padStart(2, "0");
+  return `00-${ctx.traceId}-${ctx.spanId}-${flags}`;
+}
+function validateEvent(event) {
+  if (!event || typeof event !== "object") {
+    return false;
+  }
+  const e = event;
+  if (e["specversion"] !== "1.0") return false;
+  if (typeof e["type"] !== "string" || e["type"].length === 0) return false;
+  if (typeof e["source"] !== "string" || e["source"].length === 0) return false;
+  if (typeof e["id"] !== "string" || e["id"].length === 0) return false;
+  if (typeof e["time"] !== "string") return false;
+  return true;
+}
+function validateCompactEvent(event) {
+  if (!event || typeof event !== "object") {
+    return false;
+  }
+  const e = event;
+  if (typeof e["e"] !== "string" || e["e"].length === 0) return false;
+  if (typeof e["s"] !== "string" || e["s"].length === 0) return false;
+  if (typeof e["i"] !== "string" || e["i"].length === 0) return false;
+  if (typeof e["t"] !== "number") return false;
+  return true;
+}
+
+// src/events/emitter.ts
+import { createLogger } from "@parsrun/core";
+var EventEmitter = class {
+  service;
+  definition;
+  transport;
+  logger;
+  defaultTenantId;
+  validateEvents;
+  constructor(options) {
+    this.service = options.service;
+    if (options.definition) {
+      this.definition = options.definition;
+    }
+    this.transport = options.transport;
+    this.logger = options.logger ?? createLogger({ name: `events:${options.service}` });
+    if (options.defaultTenantId) {
+      this.defaultTenantId = options.defaultTenantId;
+    }
+    this.validateEvents = options.validateEvents ?? true;
+  }
+  /**
+   * Emit an event
+   */
+  async emit(type, data, options) {
+    if (this.validateEvents && this.definition?.events?.emits) {
+      const emits = this.definition.events.emits;
+      if (!(type in emits)) {
+        this.logger.warn(`Event type not declared in service definition: ${type}`);
+      }
+    }
+    let delivery;
+    if (this.definition?.events?.emits?.[type]) {
+      delivery = this.definition.events.emits[type].delivery;
+    }
+    const eventOptions = {
+      type,
+      source: this.service,
+      data
+    };
+    if (options?.eventId) eventOptions.id = options.eventId;
+    if (options?.subject) eventOptions.subject = options.subject;
+    const tenantId = options?.tenantId ?? this.defaultTenantId;
+    if (tenantId) eventOptions.tenantId = tenantId;
+    if (options?.requestId) eventOptions.requestId = options.requestId;
+    if (options?.traceContext) eventOptions.traceContext = options.traceContext;
+    const eventDelivery = options?.delivery ?? delivery;
+    if (eventDelivery) eventOptions.delivery = eventDelivery;
+    const event = createEvent(eventOptions);
+    try {
+      await this.transport.emit(event);
+      this.logger.debug(`Event emitted: ${type}`, {
+        eventId: event.id,
+        tenantId: event.parstenantid
+      });
+      return event.id;
+    } catch (error) {
+      this.logger.error(`Failed to emit event: ${type}`, error, {
+        eventId: event.id
+      });
+      throw error;
+    }
+  }
+  /**
+   * Emit multiple events
+   */
+  async emitBatch(events) {
+    const results = [];
+    for (const { type, data, options } of events) {
+      const eventId = await this.emit(type, data, options);
+      results.push(eventId);
+    }
+    return results;
+  }
+  /**
+   * Create a scoped emitter with preset options
+   */
+  scoped(options) {
+    return new ScopedEmitter(this, options);
+  }
+  /**
+   * Get service name
+   */
+  get serviceName() {
+    return this.service;
+  }
+};
+var ScopedEmitter = class {
+  emitter;
+  defaultOptions;
+  constructor(emitter, defaultOptions) {
+    this.emitter = emitter;
+    this.defaultOptions = defaultOptions;
+  }
+  async emit(type, data, options) {
+    return this.emitter.emit(type, data, {
+      ...this.defaultOptions,
+      ...options
+    });
+  }
+};
+function createEventEmitter(options) {
+  return new EventEmitter(options);
+}
+function createTypedEmitter(definition, options) {
+  const emitter = new EventEmitter({
+    ...options,
+    service: definition.name,
+    definition
+  });
+  return emitter;
+}
+
+// src/events/handler.ts
+import { createLogger as createLogger2 } from "@parsrun/core";
+var EventHandlerRegistry = class {
+  handlers = /* @__PURE__ */ new Map();
+  logger;
+  deadLetterQueue;
+  defaultOptions;
+  constructor(options = {}) {
+    this.logger = options.logger ?? createLogger2({ name: "event-handler" });
+    if (options.deadLetterQueue) {
+      this.deadLetterQueue = options.deadLetterQueue;
+    }
+    const defaultOpts = {
+      retries: options.defaultOptions?.retries ?? 3,
+      backoff: options.defaultOptions?.backoff ?? "exponential",
+      maxDelay: options.defaultOptions?.maxDelay ?? 3e4,
+      onExhausted: options.defaultOptions?.onExhausted ?? "log"
+    };
+    if (options.defaultOptions?.deadLetter) {
+      defaultOpts.deadLetter = options.defaultOptions.deadLetter;
+    }
+    this.defaultOptions = defaultOpts;
+  }
+  /**
+   * Register an event handler
+   */
+  register(pattern, handler, options) {
+    const registration = {
+      pattern,
+      handler,
+      options: {
+        ...this.defaultOptions,
+        ...options
+      }
+    };
+    const handlers = this.handlers.get(pattern) ?? [];
+    handlers.push(registration);
+    this.handlers.set(pattern, handlers);
+    this.logger.debug(`Handler registered for pattern: ${pattern}`);
+    return () => {
+      const currentHandlers = this.handlers.get(pattern);
+      if (currentHandlers) {
+        const index = currentHandlers.indexOf(registration);
+        if (index !== -1) {
+          currentHandlers.splice(index, 1);
+          if (currentHandlers.length === 0) {
+            this.handlers.delete(pattern);
+          }
+          this.logger.debug(`Handler unregistered for pattern: ${pattern}`);
+        }
+      }
+    };
+  }
+  /**
+   * Handle an event
+   */
+  async handle(event) {
+    const matchingHandlers = this.getMatchingHandlers(event.type);
+    if (matchingHandlers.length === 0) {
+      this.logger.debug(`No handlers for event type: ${event.type}`, {
+        eventId: event.id
+      });
+      return;
+    }
+    this.logger.debug(`Handling event: ${event.type}`, {
+      eventId: event.id,
+      handlerCount: matchingHandlers.length
+    });
+    const results = await Promise.allSettled(
+      matchingHandlers.map((reg) => this.executeHandler(event, reg))
+    );
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i];
+      if (result?.status === "rejected") {
+        this.logger.error(
+          `Handler failed for ${event.type}`,
+          result.reason,
+          { eventId: event.id, pattern: matchingHandlers[i]?.pattern }
+        );
+      }
+    }
+  }
+  /**
+   * Execute a single handler with retry logic
+   */
+  async executeHandler(event, registration) {
+    const { handler, options } = registration;
+    const maxAttempts = options.retries + 1;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const context = {
+          logger: this.logger.child({
+            eventId: event.id,
+            pattern: registration.pattern,
+            attempt
+          }),
+          attempt,
+          maxAttempts,
+          isRetry: attempt > 1
+        };
+        if (event.parstracecontext) {
+          const traceCtx = parseTraceContext(event.parstracecontext);
+          if (traceCtx) {
+            context.traceContext = traceCtx;
+          }
+        }
+        await handler(event, context);
+        return;
+      } catch (error) {
+        lastError = error;
+        if (attempt < maxAttempts) {
+          const delay = this.calculateBackoff(attempt, options);
+          this.logger.warn(
+            `Handler failed, retrying in ${delay}ms`,
+            { eventId: event.id, attempt, maxAttempts }
+          );
+          await sleep(delay);
+        }
+      }
+    }
+    await this.handleExhausted(event, registration, lastError);
+  }
+  /**
+   * Calculate backoff delay
+   */
+  calculateBackoff(attempt, options) {
+    const baseDelay = 100;
+    if (options.backoff === "exponential") {
+      return Math.min(baseDelay * Math.pow(2, attempt - 1), options.maxDelay);
+    }
+    return Math.min(baseDelay * attempt, options.maxDelay);
+  }
+  /**
+   * Handle exhausted retries
+   */
+  async handleExhausted(event, registration, error) {
+    const { options } = registration;
+    if (options.deadLetter && this.deadLetterQueue) {
+      await this.deadLetterQueue.add({
+        event,
+        error: error.message,
+        pattern: registration.pattern,
+        attempts: options.retries + 1
+      });
+    }
+    switch (options.onExhausted) {
+      case "alert":
+        this.logger.error(
+          `[ALERT] Event handler exhausted all retries`,
+          error,
+          {
+            eventId: event.id,
+            eventType: event.type,
+            pattern: registration.pattern
+          }
+        );
+        break;
+      case "discard":
+        this.logger.debug(`Event discarded after exhausted retries`, {
+          eventId: event.id
+        });
+        break;
+      case "log":
+      default:
+        this.logger.warn(`Event handler exhausted all retries`, {
+          eventId: event.id,
+          error: error.message
+        });
+    }
+  }
+  /**
+   * Get handlers matching an event type
+   */
+  getMatchingHandlers(eventType) {
+    const matching = [];
+    for (const [pattern, handlers] of this.handlers) {
+      if (matchEventType(eventType, pattern)) {
+        matching.push(...handlers);
+      }
+    }
+    return matching;
+  }
+  /**
+   * Get all registered patterns
+   */
+  getPatterns() {
+    return Array.from(this.handlers.keys());
+  }
+  /**
+   * Check if a pattern has handlers
+   */
+  hasHandlers(pattern) {
+    return this.handlers.has(pattern);
+  }
+  /**
+   * Clear all handlers
+   */
+  clear() {
+    this.handlers.clear();
+  }
+};
+function createEventHandlerRegistry(options) {
+  return new EventHandlerRegistry(options);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function parseTraceContext(traceparent) {
+  const parts = traceparent.split("-");
+  if (parts.length !== 4) return void 0;
+  const [, traceId, spanId, flags] = parts;
+  if (!traceId || !spanId || !flags) return void 0;
+  return {
+    traceId,
+    spanId,
+    traceFlags: parseInt(flags, 16)
+  };
+}
+
+// src/events/transports/memory.ts
+import { createLogger as createLogger3 } from "@parsrun/core";
+var MemoryEventTransport = class {
+  name = "memory";
+  registry;
+  logger;
+  sync;
+  pendingEvents = [];
+  processing = false;
+  constructor(options = {}) {
+    this.logger = options.logger ?? createLogger3({ name: "memory-transport" });
+    this.sync = options.sync ?? false;
+    const registryOptions = {
+      logger: this.logger
+    };
+    if (options.defaultHandlerOptions) {
+      registryOptions.defaultOptions = options.defaultHandlerOptions;
+    }
+    this.registry = new EventHandlerRegistry(registryOptions);
+  }
+  /**
+   * Emit an event
+   */
+  async emit(event) {
+    this.logger.debug(`Event emitted: ${event.type}`, {
+      eventId: event.id,
+      tenantId: event.parstenantid
+    });
+    if (this.sync) {
+      await this.registry.handle(event);
+    } else {
+      this.pendingEvents.push(event);
+      this.processQueue();
+    }
+  }
+  /**
+   * Subscribe to events
+   */
+  subscribe(eventType, handler, options) {
+    return this.registry.register(eventType, handler, options);
+  }
+  /**
+   * Process pending events asynchronously
+   */
+  async processQueue() {
+    if (this.processing) return;
+    this.processing = true;
+    try {
+      while (this.pendingEvents.length > 0) {
+        const event = this.pendingEvents.shift();
+        if (event) {
+          await this.registry.handle(event);
+        }
+      }
+    } finally {
+      this.processing = false;
+    }
+  }
+  /**
+   * Wait for all pending events to be processed
+   */
+  async flush() {
+    while (this.pendingEvents.length > 0 || this.processing) {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+  /**
+   * Get pending event count
+   */
+  get pendingCount() {
+    return this.pendingEvents.length;
+  }
+  /**
+   * Get registered patterns
+   */
+  getPatterns() {
+    return this.registry.getPatterns();
+  }
+  /**
+   * Clear all subscriptions
+   */
+  clear() {
+    this.registry.clear();
+    this.pendingEvents.length = 0;
+  }
+  /**
+   * Close the transport
+   */
+  async close() {
+    await this.flush();
+    this.clear();
+  }
+};
+function createMemoryEventTransport(options) {
+  return new MemoryEventTransport(options);
+}
+var GlobalEventBus = class _GlobalEventBus {
+  static instance = null;
+  transports = /* @__PURE__ */ new Map();
+  logger;
+  constructor() {
+    this.logger = createLogger3({ name: "global-event-bus" });
+  }
+  static getInstance() {
+    if (!_GlobalEventBus.instance) {
+      _GlobalEventBus.instance = new _GlobalEventBus();
+    }
+    return _GlobalEventBus.instance;
+  }
+  /**
+   * Register a service's event transport
+   */
+  register(serviceName, transport) {
+    if (this.transports.has(serviceName)) {
+      throw new Error(`Service already registered: ${serviceName}`);
+    }
+    this.transports.set(serviceName, transport);
+    this.logger.debug(`Service registered: ${serviceName}`);
+  }
+  /**
+   * Unregister a service
+   */
+  unregister(serviceName) {
+    const deleted = this.transports.delete(serviceName);
+    if (deleted) {
+      this.logger.debug(`Service unregistered: ${serviceName}`);
+    }
+    return deleted;
+  }
+  /**
+   * Broadcast an event to all services (except source)
+   */
+  async broadcast(event, excludeSource) {
+    const promises = [];
+    for (const [name, transport] of this.transports) {
+      if (name !== excludeSource) {
+        promises.push(transport.emit(event));
+      }
+    }
+    await Promise.allSettled(promises);
+  }
+  /**
+   * Send an event to a specific service
+   */
+  async send(serviceName, event) {
+    const transport = this.transports.get(serviceName);
+    if (!transport) {
+      this.logger.warn(`Target service not found: ${serviceName}`, {
+        eventId: event.id
+      });
+      return;
+    }
+    await transport.emit(event);
+  }
+  /**
+   * Get all registered service names
+   */
+  getServices() {
+    return Array.from(this.transports.keys());
+  }
+  /**
+   * Clear all registrations
+   */
+  clear() {
+    this.transports.clear();
+  }
+  /**
+   * Reset singleton (for testing)
+   */
+  static reset() {
+    _GlobalEventBus.instance = null;
+  }
+};
+function getGlobalEventBus() {
+  return GlobalEventBus.getInstance();
+}
+
+// src/events/dead-letter.ts
+import { createLogger as createLogger4, generateId as generateId2 } from "@parsrun/core";
+var DeadLetterQueue = class {
+  entries = /* @__PURE__ */ new Map();
+  resolvedOptions;
+  logger;
+  cleanupTimer = null;
+  constructor(options = {}) {
+    this.resolvedOptions = {
+      maxSize: options.maxSize ?? 1e3,
+      retentionMs: options.retentionMs ?? 30 * 24 * 60 * 60 * 1e3,
+      // 30 days
+      alertThreshold: options.alertThreshold ?? 10
+    };
+    if (options.onAdd) this.resolvedOptions.onAdd = options.onAdd;
+    if (options.onThreshold) this.resolvedOptions.onThreshold = options.onThreshold;
+    if (options.logger) this.resolvedOptions.logger = options.logger;
+    this.logger = options.logger ?? createLogger4({ name: "dlq" });
+    this.cleanupTimer = setInterval(() => this.cleanup(), 60 * 60 * 1e3);
+  }
+  /**
+   * Add an entry to the DLQ
+   */
+  async add(options) {
+    const entry = {
+      id: generateId2(),
+      event: options.event,
+      error: options.error,
+      pattern: options.pattern,
+      attempts: options.attempts,
+      addedAt: /* @__PURE__ */ new Date()
+    };
+    if (options.metadata) {
+      entry.metadata = options.metadata;
+    }
+    if (this.entries.size >= this.resolvedOptions.maxSize) {
+      const oldest = this.getOldest();
+      if (oldest) {
+        this.entries.delete(oldest.id);
+        this.logger.debug(`DLQ: Removed oldest entry to make room`, {
+          removedId: oldest.id
+        });
+      }
+    }
+    this.entries.set(entry.id, entry);
+    this.logger.warn(`DLQ: Entry added`, {
+      id: entry.id,
+      eventId: entry.event.id,
+      eventType: entry.event.type,
+      error: entry.error
+    });
+    this.resolvedOptions.onAdd?.(entry);
+    if (this.entries.size >= this.resolvedOptions.alertThreshold) {
+      this.resolvedOptions.onThreshold?.(this.entries.size);
+    }
+    return entry.id;
+  }
+  /**
+   * Get an entry by ID
+   */
+  get(id) {
+    return this.entries.get(id);
+  }
+  /**
+   * Get all entries
+   */
+  getAll() {
+    return Array.from(this.entries.values());
+  }
+  /**
+   * Get entries by event type
+   */
+  getByEventType(eventType) {
+    return Array.from(this.entries.values()).filter(
+      (e) => e.event.type === eventType
+    );
+  }
+  /**
+   * Get entries by pattern
+   */
+  getByPattern(pattern) {
+    return Array.from(this.entries.values()).filter(
+      (e) => e.pattern === pattern
+    );
+  }
+  /**
+   * Remove an entry
+   */
+  remove(id) {
+    const deleted = this.entries.delete(id);
+    if (deleted) {
+      this.logger.debug(`DLQ: Entry removed`, { id });
+    }
+    return deleted;
+  }
+  /**
+   * Retry an entry (remove from DLQ and return event)
+   */
+  retry(id) {
+    const entry = this.entries.get(id);
+    if (!entry) return void 0;
+    this.entries.delete(id);
+    this.logger.info(`DLQ: Entry removed for retry`, {
+      id,
+      eventId: entry.event.id
+    });
+    return entry.event;
+  }
+  /**
+   * Get count
+   */
+  get size() {
+    return this.entries.size;
+  }
+  /**
+   * Clear all entries
+   */
+  clear() {
+    this.entries.clear();
+    this.logger.info(`DLQ: Cleared all entries`);
+  }
+  /**
+   * Cleanup expired entries
+   */
+  cleanup() {
+    const now = Date.now();
+    let removed = 0;
+    for (const [id, entry] of this.entries) {
+      const age = now - entry.addedAt.getTime();
+      if (age > this.resolvedOptions.retentionMs) {
+        this.entries.delete(id);
+        removed++;
+      }
+    }
+    if (removed > 0) {
+      this.logger.debug(`DLQ: Cleaned up ${removed} expired entries`);
+    }
+  }
+  /**
+   * Get oldest entry
+   */
+  getOldest() {
+    let oldest;
+    for (const entry of this.entries.values()) {
+      if (!oldest || entry.addedAt < oldest.addedAt) {
+        oldest = entry;
+      }
+    }
+    return oldest;
+  }
+  /**
+   * Stop cleanup timer
+   */
+  close() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+  /**
+   * Export entries for persistence
+   */
+  export() {
+    return Array.from(this.entries.values()).map((e) => ({
+      ...e,
+      addedAt: e.addedAt
+    }));
+  }
+  /**
+   * Import entries from persistence
+   */
+  import(entries) {
+    for (const entry of entries) {
+      this.entries.set(entry.id, {
+        ...entry,
+        addedAt: new Date(entry.addedAt)
+      });
+    }
+    this.logger.info(`DLQ: Imported ${entries.length} entries`);
+  }
+};
+function createDeadLetterQueue(options) {
+  return new DeadLetterQueue(options);
+}
+export {
+  DeadLetterQueue,
+  EventEmitter,
+  EventHandlerRegistry,
+  GlobalEventBus,
+  MemoryEventTransport,
+  ScopedEmitter,
+  createDeadLetterQueue,
+  createEvent,
+  createEventEmitter,
+  createEventHandlerRegistry,
+  createMemoryEventTransport,
+  createTypedEmitter,
+  formatEventType,
+  fromCompactEvent,
+  getGlobalEventBus,
+  matchEventType,
+  parseEventType,
+  toCloudEvent,
+  toCompactEvent,
+  validateCompactEvent,
+  validateEvent
+};
+//# sourceMappingURL=index.js.map