@arvo-tools/postgres 1.0.0 → 1.2.0

package/dist/broker/index.d.ts

@@ -0,0 +1,287 @@
+import { type ArvoEvent } from 'arvo-core';
+import type { IArvoEventHandler } from 'arvo-event-handler';
+import { PgBoss, type Queue } from 'pg-boss';
+import type { HandlerRegistrationOptions, ILogger } from './types';
+type PromiseLike<T> = Promise<T> | T;
+/**
+ * Queue-based event broker for ArvoEvent handlers with automatic routing,
+ * retry logic, and OpenTelemetry tracing support.
+ *
+ * PostgresEventBroker extends PgBoss to provide event-driven workflow management
+ * through persistent PostgreSQL-backed queues. It automatically routes events between
+ * registered handlers, ensures reliable delivery with configurable retry policies,
+ * and maintains distributed tracing context across the entire workflow.
+ *
+ * Key capabilities include handler registration with dedicated queues, automatic
+ * event routing based on the 'to' field, workflow completion handling, support for
+ * domained events, and comprehensive queue statistics for monitoring.
+ *
+ * @example
+ * ```typescript
+ * const broker = new PostgresEventBroker({ connectionString: 'postgres://...' });
+ * await broker.start();
+ *
+ * // Register handlers with retry configuration
+ * await broker.register(calculatorHandler, {
+ *   recreateQueue: true,
+ *   worker: {
+ *     concurrency: 5,
+ *     retryLimit: 3,
+ *     retryBackoff: true
+ *   }
+ * });
+ *
+ * // Set up workflow completion handler
+ * await broker.onWorkflowComplete({
+ *   source: 'my.workflow',
+ *   listener: async (event) => {
+ *     this.logger.log('Workflow completed:', event.data);
+ *   }
+ * });
+ *
+ * // Handle domained events (e.g., human approval requests)
+ * broker.onDomainedEvent(async (event) => {
+ *   if (event.domain === 'human.interaction') {
+ *     await handleHumanApproval(event);
+ *   }
+ * });
+ *
+ * // Dispatch events using ArvoEventFactory
+ * const event = createArvoEventFactory(contract.version('1.0.0')).accepts({
+ *   source: 'my.workflow',
+ *   data: { numbers: [1, 2, 3] }
+ * });
+ * await broker.dispatch(event);
+ *
+ * // Monitor queue health
+ * const stats = await broker.getStats();
+ * ```
+ */
+export declare class PostgresEventBroker extends PgBoss {
+    /**
+     * Internal registry of handler configurations keyed by handler source.
+     */
+    private handlers;
+    /**
+     * Internal list of all registered queue names.
+     */
+    private _queues;
+    /**
+     * List of all registered queue names in the broker.
+     */
+    get queues(): string[];
+    /**
+     * Logger instance used for all broker operational logging.
+     * Defaults to console but can be replaced via setLogger().
+     */
+    private logger;
+    /**
+     * Sets a custom logger for broker operations.
+     *
+     * Allows integration with existing logging infrastructure (Winston, Pino, etc.)
+     * by providing a logger that implements the ILogger interface.
+     *
+     * @param logger - Logger instance implementing ILogger interface
+     *
+     * @example
+     * ```typescript
+     * import winston from 'winston';
+     *
+     * const logger = winston.createLogger({
+     *   level: 'info',
+     *   format: winston.format.json(),
+     *   transports: [new winston.transports.Console()]
+     * });
+     *
+     * broker.setLogger(logger);
+     * ```
+     */
+    setLogger(logger: ILogger): void;
+    /**
+     * The configured event source for workflow completion.
+     */
+    private injectionEventSource;
+    /**
+     * Default callback invoked when an event has no registered destination handler.
+     */
+    private _onHandlerNotFound;
+    /**
+     * Callback invoked when a domained event is encountered during routing.
+     */
+    private _onDomainedEvent;
+    /**
+     * Registers a handler for workflow completion events.
+     *
+     * This sets up the terminal point where events return after flowing through
+     * the handler chain. The handler receives events whose 'to' field matches
+     * the configured source, typically indicating workflow completion.
+     *
+     * Sets the injection event source that must match the source of events
+     * dispatched via the dispatch() method.
+     *
+     * **Note:** The listener must handle its own errors. Exceptions are caught
+     * and logged but do not cause job failures. This is by design.
+     *
+     * @param param - Configuration object
+     * @param param.source - Event source identifier for completion events
+     * @param param.listener - Callback invoked when completion events are received
+     * @param param.options - Optional queue and worker configuration
+     *
+     * @example
+     * ```typescript
+     * await broker.onWorkflowComplete({
+     *   source: 'test.test.test',
+     *   listener: async (event) => {
+     *     try {
+     *       this.logger.log('Final result:', event.data);
+     *     } catch (error) {
+     *       logger.error('Completion handler failed', error);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    onWorkflowComplete(param: {
+        source: string;
+        listener: (event: ArvoEvent) => PromiseLike<void>;
+        options?: HandlerRegistrationOptions;
+    }): Promise<void>;
+    /**
+     * Sets a custom handler for events with no registered destination.
+     *
+     * When a handler emits an event whose 'to' field doesn't match any
+     * registered handler, this callback is invoked. Useful for logging
+     * routing errors or implementing fallback behavior.
+     *
+     * **Note:** The listener must handle its own errors. Exceptions are
+     * suppressed by design to prevent routing failures from cascading.
+     *
+     * @param listner - Callback invoked with unroutable events
+     *
+     * @example
+     * ```typescript
+     * broker.onHandlerNotFound(async (event) => {
+     *   try {
+     *     logger.error('No handler for', event.to);
+     *   } catch (error) {
+     *     this.logger.error('Failed to log missing handler', error);
+     *   }
+     * });
+     * ```
+     */
+    onHandlerNotFound(listner: (event: ArvoEvent) => PromiseLike<void>): void;
+    /**
+     * Sets a custom handler for domained events.
+     *
+     * Domained events are intercepted during routing and passed to this handler
+     * instead of being sent to a queue. Useful for handling external system
+     * interactions like human approvals or notifications.
+     *
+     * **Note:** The listener must handle its own errors. Exceptions are
+     * suppressed by design to prevent domained event failures from breaking workflows.
+     *
+     * @param listner - Callback invoked when domained events are encountered
+     *
+     * @example
+     * ```typescript
+     * broker.onDomainedEvent(async (event) => {
+     *   try {
+     *     if (event.domain === 'notification') {
+     *       await alerting.notify(event);
+     *     }
+     *   } catch (error) {
+     *     logger.error('Domained event handler failed', error);
+     *   }
+     * });
+     * ```
+     */
+    onDomainedEvent(listner: (event: ArvoEvent) => PromiseLike<void>): void;
+    /**
+     * Creates a queue and tracks it in the internal queue registry.
+     * Overrides the base class method to maintain queue tracking.
+     *
+     * @param name - Queue name
+     * @param options - Queue configuration options
+     */
+    createQueue(name: string, options?: Omit<Queue, 'name'>): Promise<void>;
+    /**
+     * Registers an event handler with the broker.
+     *
+     * Creates a dedicated queue for the handler and spawns worker instances
+     * to process incoming events. Events emitted by the handler are automatically
+     * routed to their destinations based on the 'to' field.
+     *
+     * @param handler - The ArvoEvent handler to register
+     * @param options - Configuration for queue behavior, worker concurrency, and retry policies
+     * @throws {Error} If a handler with the same source is already registered
+     *
+     * @example
+     * ```typescript
+     * await broker.register(calculatorHandler, {
+     *   recreateQueue: true,
+     *   queue: { deadLetter: 'dlq' },
+     *   worker: {
+     *     concurrency: 5,
+     *     onError: async (job, error) => {
+     *       if (error.message.includes('timeout')) return 'RETRY';
+     *       return 'FAIL';
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    register(handler: IArvoEventHandler, options?: HandlerRegistrationOptions): Promise<void>;
+    /**
+     * Routes an ArvoEvent to its destination queue.
+     *
+     * Internal method that filters out worker configuration options and includes
+     * only job-level options when sending the event. This method performs no
+     * validation and assumes the event and handler have already been verified.
+     *
+     * @param event - The ArvoEvent to route
+     * @returns Job ID if sent successfully, null if handler not found
+     */
+    private _emitArvoEvent;
+    /**
+     * Dispatches an ArvoEvent into the broker system with validation.
+     *
+     * This is the primary entry point for injecting events into the workflow.
+     * The event must originate from the source configured in onWorkflowComplete()
+     * and target a registered handler.
+     *
+     * @param event - The ArvoEvent to dispatch
+     * @returns Job ID assigned by the queue system
+     * @throws {Error} If workflow completion handler is not configured
+     * @throws {Error} If event source doesn't match configured workflow source
+     * @throws {Error} If target handler is not registered
+     *
+     * @example
+     * ```typescript
+     * const event = createArvoEvent({
+     *   source: 'my.workflow',
+     *   to: 'calculator.handler',
+     *   type: 'calculate.request',
+     *   data: { operation: 'add', values: [1, 2] }
+     * });
+     *
+     * await broker.dispatch(event);
+     * ```
+     */
+    dispatch(event: ArvoEvent): Promise<string | null>;
+    /**
+     * Retrieves statistics for all registered queues in the broker.
+     *
+     * @returns Array of queue statistics including active, queued, and total job counts
+     *
+     * @example
+     * ```typescript
+     * const stats = await broker.getStats();
+     * stats.forEach(stat => {
+     *   this.logger.log(`Queue ${stat.name}: ${stat.activeCount} active, ${stat.queuedCount} queued`);
+     * });
+     * ```
+     */
+    getStats(): Promise<import("pg-boss").QueueResult[]>;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/broker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/broker/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,SAAS,EAAe,MAAM,WAAW,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAE,KAAK,KAAK,EAAoB,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,0BAA0B,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGnE,KAAK,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBAAa,mBAAoB,SAAQ,MAAM;IAC7C;;OAEG;IACH,OAAO,CAAC,QAAQ,CAKT;IAEP;;OAEG;IACH,OAAO,CAAC,OAAO,CAAgB;IAE/B;;OAEG;IACH,IAAW,MAAM,IAAI,MAAM,EAAE,CAE5B;IAED;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAoB;IAElC;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,SAAS,CAAC,MAAM,EAAE,OAAO;IAIhC;;OAEG;IACH,OAAO,CAAC,oBAAoB,CAAuB;IAEnD;;OAEG;IACH,OAAO,CAAC,kBAAkB,CAC4C;IAEtE;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAC4C;IAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,kBAAkB,CAAC,KAAK,EAAE;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,WAAW,CAAC,IAAI,CAAC,CAAC;QAClD,OAAO,CAAC,EAAE,0BAA0B,CAAC;KACtC;IA+BD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,iBAAiB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,WAAW,CAAC,IAAI,CAAC;IAIlE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,eAAe,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,WAAW,CAAC,IAAI,CAAC;IAIhE;;;;;;OAMG;IACY,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAKtF;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,QAAQ,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;IA6D/F;;;;;;;;;OASG;YACW,cAAc;IAiB5B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,QAAQ,CAAC,KAAK,EAAE,SAAS;IAgC/B;;;;;;;;;;;;OAYG;IACG,QAAQ;CAGf"}