@arvo-tools/postgres 1.1.0 → 1.2.1

package/dist/broker/index.js

@@ -0,0 +1,629 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresEventBroker = void 0;
+var api_1 = require("@opentelemetry/api");
+var arvo_core_1 = require("arvo-core");
+var pg_boss_1 = require("pg-boss");
+var utils_1 = require("./utils");
+/**
+ * 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();
+ * ```
+ */
+var PostgresEventBroker = /** @class */ (function (_super) {
+    __extends(PostgresEventBroker, _super);
+    function PostgresEventBroker() {
+        var _this = _super.apply(this, __spreadArray([], __read(arguments), false)) || this;
+        /**
+         * Internal registry of handler configurations keyed by handler source.
+         */
+        _this.handlers = {};
+        /**
+         * Internal list of all registered queue names.
+         */
+        _this._queues = [];
+        /**
+         * Logger instance used for all broker operational logging.
+         * Defaults to console but can be replaced via setLogger().
+         */
+        _this.logger = console;
+        /**
+         * The configured event source for workflow completion.
+         */
+        _this.injectionEventSource = null;
+        /**
+         * Default callback invoked when an event has no registered destination handler.
+         */
+        _this._onHandlerNotFound = function (event) {
+            return _this.logger.error('Handler not found for event', event.toString(2));
+        };
+        /**
+         * Callback invoked when a domained event is encountered during routing.
+         */
+        _this._onDomainedEvent = function (event) {
+            return _this.logger.info('Domained event encountered', event.toString(2));
+        };
+        return _this;
+    }
+    Object.defineProperty(PostgresEventBroker.prototype, "queues", {
+        /**
+         * List of all registered queue names in the broker.
+         */
+        get: function () {
+            return this._queues;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * 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);
+     * ```
+     */
+    PostgresEventBroker.prototype.setLogger = function (logger) {
+        this.logger = logger;
+    };
+    /**
+     * 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);
+     *     }
+     *   },
+     * });
+     * ```
+     */
+    PostgresEventBroker.prototype.onWorkflowComplete = function (param) {
+        return __awaiter(this, void 0, void 0, function () {
+            var i;
+            var _this = this;
+            var _a, _b, _c, _d, _e, _f, _g, _h;
+            return __generator(this, function (_j) {
+                switch (_j.label) {
+                    case 0:
+                        this.injectionEventSource = param.source;
+                        this.handlers[param.source] = { options: param.options };
+                        if (!((_a = param.options) === null || _a === void 0 ? void 0 : _a.recreateQueue)) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.deleteQueue(param.source)];
+                    case 1:
+                        _j.sent();
+                        _j.label = 2;
+                    case 2: return [4 /*yield*/, this.createQueue(param.source, (_b = param.options) === null || _b === void 0 ? void 0 : _b.queue)];
+                    case 3:
+                        _j.sent();
+                        i = 0;
+                        _j.label = 4;
+                    case 4:
+                        if (!(i < Math.max((_e = (_d = (_c = param.options) === null || _c === void 0 ? void 0 : _c.worker) === null || _d === void 0 ? void 0 : _d.concurrency) !== null && _e !== void 0 ? _e : 0, 1))) return [3 /*break*/, 7];
+                        return [4 /*yield*/, this.work(param.source, {
+                                pollingIntervalSeconds: (_h = (_g = (_f = param.options) === null || _f === void 0 ? void 0 : _f.worker) === null || _g === void 0 ? void 0 : _g.pollingIntervalSeconds) !== null && _h !== void 0 ? _h : 2,
+                                batchSize: 1,
+                            }, function (_a) { return __awaiter(_this, [_a], void 0, function (_b) {
+                                var eventFromJob_1, error_1;
+                                var _this = this;
+                                var _c = __read(_b, 1), job = _c[0];
+                                return __generator(this, function (_d) {
+                                    switch (_d.label) {
+                                        case 0:
+                                            _d.trys.push([0, 2, , 3]);
+                                            eventFromJob_1 = (0, utils_1.createArvoEventFromJob)(job);
+                                            return [4 /*yield*/, api_1.context.with((0, utils_1.otelParentContext)(eventFromJob_1), function () { return __awaiter(_this, void 0, void 0, function () {
+                                                    return __generator(this, function (_a) {
+                                                        switch (_a.label) {
+                                                            case 0: return [4 /*yield*/, param.listener(eventFromJob_1)];
+                                                            case 1: return [2 /*return*/, _a.sent()];
+                                                        }
+                                                    });
+                                                }); })];
+                                        case 1:
+                                            _d.sent();
+                                            return [3 /*break*/, 3];
+                                        case 2:
+                                            error_1 = _d.sent();
+                                            this.logger.error("[onWorkflowComplete] Error in worker handler for ".concat(param.source), error_1);
+                                            return [3 /*break*/, 3];
+                                        case 3: return [2 /*return*/];
+                                    }
+                                });
+                            }); })];
+                    case 5:
+                        _j.sent();
+                        _j.label = 6;
+                    case 6:
+                        i++;
+                        return [3 /*break*/, 4];
+                    case 7: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * 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);
+     *   }
+     * });
+     * ```
+     */
+    PostgresEventBroker.prototype.onHandlerNotFound = function (listner) {
+        this._onHandlerNotFound = listner;
+    };
+    /**
+     * 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);
+     *   }
+     * });
+     * ```
+     */
+    PostgresEventBroker.prototype.onDomainedEvent = function (listner) {
+        this._onDomainedEvent = listner;
+    };
+    /**
+     * 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
+     */
+    PostgresEventBroker.prototype.createQueue = function (name, options) {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                this._queues.push(name);
+                return [2 /*return*/, _super.prototype.createQueue.call(this, name, options)];
+            });
+        });
+    };
+    /**
+     * 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';
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    PostgresEventBroker.prototype.register = function (handler, options) {
+        return __awaiter(this, void 0, void 0, function () {
+            var handlerSource, workHandler, i;
+            var _this = this;
+            var _a, _b, _c, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        if (this.handlers[handler.source]) {
+                            throw new Error((0, arvo_core_1.cleanString)("\n        Handler registration failed: A handler with source '".concat(handler.source, "' is already registered.\n        Each handler must have a unique source identifier. Attempted duplicate registration will be\n        ignored to prevent queue conflicts.\n      ")));
+                        }
+                        this.handlers[handler.source] = { options: __assign({}, options) };
+                        if (!(options === null || options === void 0 ? void 0 : options.recreateQueue)) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.deleteQueue(handler.source)];
+                    case 1:
+                        _e.sent();
+                        _e.label = 2;
+                    case 2: return [4 /*yield*/, this.createQueue(handler.source, options === null || options === void 0 ? void 0 : options.queue)];
+                    case 3:
+                        _e.sent();
+                        handlerSource = handler.source;
+                        workHandler = function (_a) { return __awaiter(_this, [_a], void 0, function (_b) {
+                            var eventFromJob_2, events, error_2;
+                            var _this = this;
+                            var _c = __read(_b, 1), job = _c[0];
+                            return __generator(this, function (_d) {
+                                switch (_d.label) {
+                                    case 0:
+                                        _d.trys.push([0, 3, , 4]);
+                                        eventFromJob_2 = (0, utils_1.createArvoEventFromJob)(job);
+                                        return [4 /*yield*/, api_1.context.with((0, utils_1.otelParentContext)(eventFromJob_2), function () { return __awaiter(_this, void 0, void 0, function () {
+                                                return __generator(this, function (_a) {
+                                                    switch (_a.label) {
+                                                        case 0: return [4 /*yield*/, handler.execute(eventFromJob_2, {
+                                                                inheritFrom: 'EVENT',
+                                                            })];
+                                                        case 1: return [2 /*return*/, _a.sent()];
+                                                    }
+                                                });
+                                            }); })];
+                                    case 1:
+                                        events = (_d.sent()).events;
+                                        return [4 /*yield*/, Promise.all(events.map(function (evt) { return __awaiter(_this, void 0, void 0, function () {
+                                                var error_3;
+                                                var _a;
+                                                return __generator(this, function (_b) {
+                                                    switch (_b.label) {
+                                                        case 0:
+                                                            if (!evt.domain) return [3 /*break*/, 5];
+                                                            _b.label = 1;
+                                                        case 1:
+                                                            _b.trys.push([1, 3, , 4]);
+                                                            return [4 /*yield*/, ((_a = this._onDomainedEvent) === null || _a === void 0 ? void 0 : _a.call(this, evt))];
+                                                        case 2:
+                                                            _b.sent();
+                                                            return [3 /*break*/, 4];
+                                                        case 3:
+                                                            error_3 = _b.sent();
+                                                            this.logger.error('Error in onDomainedEvent', error_3);
+                                                            return [3 /*break*/, 4];
+                                                        case 4: return [2 /*return*/, undefined];
+                                                        case 5: return [4 /*yield*/, this._emitArvoEvent(evt)];
+                                                        case 6: return [2 /*return*/, _b.sent()];
+                                                    }
+                                                });
+                                            }); }))];
+                                    case 2:
+                                        _d.sent();
+                                        return [3 /*break*/, 4];
+                                    case 3:
+                                        error_2 = _d.sent();
+                                        this.logger.error("Error in worker handler for ".concat(handlerSource), error_2);
+                                        throw error_2;
+                                    case 4: return [2 /*return*/];
+                                }
+                            });
+                        }); };
+                        i = 0;
+                        _e.label = 4;
+                    case 4:
+                        if (!(i < Math.max((_b = (_a = options === null || options === void 0 ? void 0 : options.worker) === null || _a === void 0 ? void 0 : _a.concurrency) !== null && _b !== void 0 ? _b : 0, 1))) return [3 /*break*/, 7];
+                        return [4 /*yield*/, this.work(handler.source, {
+                                pollingIntervalSeconds: (_d = (_c = options === null || options === void 0 ? void 0 : options.worker) === null || _c === void 0 ? void 0 : _c.pollingIntervalSeconds) !== null && _d !== void 0 ? _d : 2,
+                                batchSize: 1,
+                            }, workHandler)];
+                    case 5:
+                        _e.sent();
+                        _e.label = 6;
+                    case 6:
+                        i++;
+                        return [3 /*break*/, 4];
+                    case 7: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * 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
+     */
+    PostgresEventBroker.prototype._emitArvoEvent = function (event) {
+        return __awaiter(this, void 0, void 0, function () {
+            var e_1, _a, concurrency, pollingIntervalSeconds, rest;
+            var _b, _c, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        if (!(!event.to || !this._queues.includes(event.to))) return [3 /*break*/, 5];
+                        _e.label = 1;
+                    case 1:
+                        _e.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, ((_b = this._onHandlerNotFound) === null || _b === void 0 ? void 0 : _b.call(this, event))];
+                    case 2:
+                        _e.sent();
+                        return [3 /*break*/, 4];
+                    case 3:
+                        e_1 = _e.sent();
+                        this.logger.error('Error in onHandlerNotFound ', e_1);
+                        return [3 /*break*/, 4];
+                    case 4: return [2 /*return*/, null];
+                    case 5:
+                        _a = (_d = (_c = this.handlers[event.to].options) === null || _c === void 0 ? void 0 : _c.worker) !== null && _d !== void 0 ? _d : {}, concurrency = _a.concurrency, pollingIntervalSeconds = _a.pollingIntervalSeconds, rest = __rest(_a, ["concurrency", "pollingIntervalSeconds"]);
+                        return [4 /*yield*/, this.send(event.to, event.toJSON(), __assign({}, (rest !== null && rest !== void 0 ? rest : {})))];
+                    case 6: return [2 /*return*/, _e.sent()];
+                }
+            });
+        });
+    };
+    /**
+     * 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);
+     * ```
+     */
+    PostgresEventBroker.prototype.dispatch = function (event) {
+        return __awaiter(this, void 0, void 0, function () {
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        if (!this.injectionEventSource) {
+                            throw new Error((0, arvo_core_1.cleanString)("\n        Workflow completion handler not configured: Cannot dispatch ArvoEvent without setting up\n        the workflow completion handler. Call onWorkflowComplete({ source: string, handler: Function })\n        to register the completion point before dispatching events into the system.\n      "));
+                        }
+                        if (this.injectionEventSource !== event.source) {
+                            throw new Error((0, arvo_core_1.cleanString)("\n        Event source mismatch: The dispatched event source '".concat(event.source, "' does not match the\n        configured workflow completion source '").concat(this.injectionEventSource, "'. Events dispatched\n        through dispatch() must originate from the source specified in onWorkflowComplete().\n        Verify the event's source property matches '").concat(this.injectionEventSource, "'.\n      ")));
+                        }
+                        if (!this._queues.includes((_a = event.to) !== null && _a !== void 0 ? _a : '')) {
+                            throw new Error((0, arvo_core_1.cleanString)("\n        Handler not registered: No handler found for destination '".concat(event.to, "'. The target handler\n        must be registered using register() before events can be routed to it. Register the required\n        handler or verify the event's 'to' property is correct.\n      ")));
+                        }
+                        return [4 /*yield*/, this._emitArvoEvent(event)];
+                    case 1: return [2 /*return*/, _b.sent()];
+                }
+            });
+        });
+    };
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    PostgresEventBroker.prototype.getStats = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, Promise.all(this._queues.map(function (q) { return __awaiter(_this, void 0, void 0, function () { return __generator(this, function (_a) {
+                            return [2 /*return*/, this.getQueueStats(q)];
+                        }); }); }))];
+                    case 1: return [2 /*return*/, _a.sent()];
+                }
+            });
+        });
+    };
+    return PostgresEventBroker;
+}(pg_boss_1.PgBoss));
+exports.PostgresEventBroker = PostgresEventBroker;
+//# sourceMappingURL=index.js.map

package/dist/broker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/broker/index.ts"],"names":[],"mappings":"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"}