arvo-event-handler 2.3.3 → 3.0.2

package/dist/SyncEventResource/index.js

@@ -0,0 +1,280 @@
+"use strict";
+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 };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SyncEventResource = void 0;
+var arvo_core_1 = require("arvo-core");
+var error_1 = require("../ArvoOrchestrator/error");
+var errors_1 = require("../errors");
+/**
+ * A synchronous event resource that manages machine memory state based on event subjects.
+ *
+ * This class provides a distributed-system-safe mechanism for persisting and retrieving machine memory
+ * objects that are correlated with ArvoEvent subjects. It acts as a key-value store where
+ * the event subject serves as the key and the memory object serves as the value.
+ *
+ * Key features:
+ * - JSON serializable memory persistence
+ * - Optional resource locking for distributed concurrent access control
+ * - Subject-based memory correlation across multiple service instances
+ * - Transaction-safe operations with proper error handling
+ * - Optional OpenTelemetry span integration for observability
+ *
+ * @template T - The type of the memory object, must extend Record<string, any> and be JSON serializable
+ *
+ * @example
+ * ```typescript
+ * type MyMemory = {
+ *   counter: number;
+ *   status: string;
+ * }
+ *
+ * class MemoryImplementation implements IMachineMemory<MyMemory> { ... }
+ *
+ * const resource = new SyncEventResource<MyMemory>(
+ *   new MemoryImplementation(),
+ *   true // enable resource locking for distributed systems
+ * );
+ * ```
+ */
+var SyncEventResource = /** @class */ (function () {
+    function SyncEventResource(memory, requiresResourceLocking) {
+        this.memory = memory;
+        this.requiresResourceLocking = requiresResourceLocking;
+    }
+    /**
+     * Acquires a lock on the event subject to prevent concurrent access across distributed services.
+     *
+     * This method ensures distributed-system-safe access to the memory resource by preventing
+     * multiple service instances from modifying the same event subject simultaneously. If resource
+     * locking is disabled, it will skip the lock acquisition process. The lock is subject-specific,
+     * meaning different event subjects can be processed concurrently across services.
+     *
+     * @returns A promise that resolves to the lock acquisition status:
+     *          - 'ACQUIRED': Lock was successfully acquired
+     *          - 'NOT_ACQUIRED': Lock acquisition failed (resource busy by another service)
+     *          - 'NOOP': Lock acquisition was skipped (locking disabled)
+     *
+     * @throws {TransactionViolation} When lock acquisition fails due to system errors
+     */
+    SyncEventResource.prototype.acquireLock = function (event, span) {
+        return __awaiter(this, void 0, void 0, function () {
+            var acquired, e_1;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!this.requiresResourceLocking) {
+                            (0, arvo_core_1.logToSpan)({
+                                level: 'INFO',
+                                message: "Skipping acquiring lock for event (subject=".concat(event.subject, ") as the resource does not required locking."),
+                            }, span);
+                            return [2 /*return*/, 'NOOP'];
+                        }
+                        _a.label = 1;
+                    case 1:
+                        _a.trys.push([1, 3, , 4]);
+                        (0, arvo_core_1.logToSpan)({
+                            level: 'INFO',
+                            message: 'Acquiring lock for the event',
+                        });
+                        return [4 /*yield*/, this.memory.lock(event.subject)];
+                    case 2:
+                        acquired = _a.sent();
+                        return [2 /*return*/, acquired ? 'ACQUIRED' : 'NOT_ACQUIRED'];
+                    case 3:
+                        e_1 = _a.sent();
+                        throw new error_1.TransactionViolation({
+                            cause: error_1.TransactionViolationCause.LOCK_FAILURE,
+                            message: "Error acquiring lock for event (subject=".concat(event.subject, "): ").concat(e_1 === null || e_1 === void 0 ? void 0 : e_1.message),
+                            initiatingEvent: event,
+                        });
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Retrieves the current state from memory for the given event subject.
+     *
+     * This method reads the persisted memory object associated with the event's subject
+     * from the distributed storage system. If no memory exists for the subject, it returns null.
+     * The operation is wrapped in proper error handling to ensure transaction safety across
+     * distributed service instances.
+     *
+     * @returns A promise that resolves to the memory object if found, or null if no memory exists
+     *
+     * @throws {TransactionViolation} When the read operation fails due to storage errors
+     */
+    SyncEventResource.prototype.acquireState = function (event, span) {
+        return __awaiter(this, void 0, void 0, function () {
+            var e_2;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 2, , 3]);
+                        (0, arvo_core_1.logToSpan)({
+                            level: 'INFO',
+                            message: 'Reading machine state for the event',
+                        }, span);
+                        return [4 /*yield*/, this.memory.read(event.subject)];
+                    case 1: return [2 /*return*/, _a.sent()];
+                    case 2:
+                        e_2 = _a.sent();
+                        throw new error_1.TransactionViolation({
+                            cause: error_1.TransactionViolationCause.READ_FAILURE,
+                            message: "Error reading state for event (subject=".concat(event.subject, "): ").concat(e_2 === null || e_2 === void 0 ? void 0 : e_2.message),
+                            initiatingEvent: event,
+                        });
+                    case 3: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Persists the updated memory state to distributed storage.
+     *
+     * This method writes the new memory record to the distributed storage system, associating
+     * it with the event's subject. It provides both the new record and the previous record for
+     * implementations that need to perform atomic updates, maintain audit trails, or handle
+     * optimistic concurrency control in distributed environments.
+     *
+     * @throws {TransactionViolation} When the write operation fails due to storage errors
+     */
+    SyncEventResource.prototype.persistState = function (event, record, prevRecord, span) {
+        return __awaiter(this, void 0, void 0, function () {
+            var e_3;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 2, , 3]);
+                        (0, arvo_core_1.logToSpan)({
+                            level: 'INFO',
+                            message: 'Persisting machine state to the storage',
+                        }, span);
+                        return [4 /*yield*/, this.memory.write(event.subject, record, prevRecord)];
+                    case 1:
+                        _a.sent();
+                        return [3 /*break*/, 3];
+                    case 2:
+                        e_3 = _a.sent();
+                        throw new error_1.TransactionViolation({
+                            cause: error_1.TransactionViolationCause.WRITE_FAILURE,
+                            message: "Error writing state for event (subject=".concat(event.subject, "): ").concat(e_3 === null || e_3 === void 0 ? void 0 : e_3.message),
+                            initiatingEvent: event,
+                        });
+                    case 3: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Validates that the event subject conforms to the ArvoOrchestrationSubject format.
+     *
+     * This method ensures that the event subject follows the expected schema format
+     * required by the Arvo orchestration system. Invalid subjects will result in
+     * execution violations to prevent processing of malformed events across the
+     * distributed service architecture.
+     *
+     * @throws {ExecutionViolation} When the event subject format is invalid
+     *
+     * @protected
+     */
+    SyncEventResource.prototype.validateEventSubject = function (event, span) {
+        (0, arvo_core_1.logToSpan)({
+            level: 'INFO',
+            message: 'Validating event subject',
+        }, span);
+        var isValid = arvo_core_1.ArvoOrchestrationSubject.isValid(event.subject);
+        if (!isValid) {
+            throw new errors_1.ExecutionViolation("Invalid event (id=".concat(event.id, ") subject format. Expected an ArvoOrchestrationSubject but received '").concat(event.subject, "'. The subject must follow the format specified by ArvoOrchestrationSubject schema"));
+        }
+    };
+    /**
+     * Releases a previously acquired lock on the event subject.
+     *
+     * This method safely releases locks that were acquired during event processing to prevent
+     * resource leaks in distributed systems. It handles cases where no lock was acquired
+     * (NOOP operations) and provides proper error handling for unlock failures. Failed unlock
+     * operations are logged as potential resource leaks but do not throw exceptions to avoid
+     * disrupting the main processing flow as it assumes that the lock will have the lifedspan.
+     *
+     * @returns A promise that resolves to the lock release status:
+     *          - 'NOOP': No lock was acquired, so no operation was performed
+     *          - 'RELEASED': Lock was successfully released
+     *          - 'ERROR': Lock release failed, potential resource leak
+     *
+     * @protected
+     */
+    SyncEventResource.prototype.releaseLock = function (event, acquiredLock, span) {
+        return __awaiter(this, void 0, void 0, function () {
+            var err_1;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (acquiredLock !== 'ACQUIRED') {
+                            (0, arvo_core_1.logToSpan)({
+                                level: 'INFO',
+                                message: 'Lock was not acquired by the process so perfroming no operation',
+                            }, span);
+                            return [2 /*return*/, 'NOOP'];
+                        }
+                        _a.label = 1;
+                    case 1:
+                        _a.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, this.memory.unlock(event.subject)];
+                    case 2:
+                        _a.sent();
+                        (0, arvo_core_1.logToSpan)({
+                            level: 'INFO',
+                            message: 'Lock successfully released',
+                        }, span);
+                        return [2 /*return*/, 'RELEASED'];
+                    case 3:
+                        err_1 = _a.sent();
+                        (0, arvo_core_1.logToSpan)({
+                            level: 'ERROR',
+                            message: "Memory unlock operation failed - Possible resource leak: ".concat(err_1.message),
+                        }, span);
+                        return [2 /*return*/, 'ERROR'];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    return SyncEventResource;
+}());
+exports.SyncEventResource = SyncEventResource;

package/dist/SyncEventResource/types.d.ts

@@ -0,0 +1,2 @@
+export type AcquiredLockStatusType = 'NOOP' | 'ACQUIRED' | 'NOT_ACQUIRED';
+export type ReleasedLockStatusType = 'NOOP' | 'RELEASED' | 'ERROR';

package/dist/SyncEventResource/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -2,14 +2,32 @@ import AbstractArvoEventHandler from './AbstractArvoEventHandler';
 import ArvoEventHandler from './ArvoEventHandler';
 import { createArvoEventHandler } from './ArvoEventHandler/helpers';
 import { ArvoEventHandlerFunction, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunctionOutput, IArvoEventHandler } from './ArvoEventHandler/types';
-import { ArvoEventRouter } from './ArvoEventRouter';
-import { createArvoEventRouter } from './ArvoEventRouter/helpers';
-import { IArvoEventRouter } from './ArvoEventRouter/types';
-import { deleteOtelHeaders } from './ArvoEventRouter/utils';
-import MultiArvoEventHandler from './MultiArvoEventHandler';
-import { createMultiArvoEventHandler } from './MultiArvoEventHandler/helpers';
-import { IMultiArvoEventHandler, MultiArvoEventHandlerFunction, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput } from './MultiArvoEventHandler/types';
 import { ConfigViolation, ContractViolation, ExecutionViolation } from './errors';
 import { ArvoEventHandlerOpenTelemetryOptions, EventHandlerFactory, PartialExcept } from './types';
 import { coalesce, coalesceOrDefault, getValueOrDefault, isNullOrUndefined } from './utils';
-export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, IArvoEventRouter, ArvoEventRouter, createArvoEventRouter, AbstractArvoEventHandler, deleteOtelHeaders, ArvoEventHandlerOpenTelemetryOptions, EventHandlerFactory, ContractViolation, ConfigViolation, ExecutionViolation, };
+import { assign, emit } from 'xstate';
+import ArvoMachine from './ArvoMachine';
+import { setupArvoMachine } from './ArvoMachine/createMachine';
+import { ArvoMachineContext, EnqueueArvoEventActionParam } from './ArvoMachine/types';
+import { ArvoOrchestrator } from './ArvoOrchestrator';
+import { TransactionViolation, TransactionViolationCause } from './ArvoOrchestrator/error';
+import { createArvoOrchestrator } from './ArvoOrchestrator/factory';
+import { IArvoOrchestrator, MachineMemoryRecord } from './ArvoOrchestrator/types';
+import { MachineExecutionEngine } from './MachineExecutionEngine';
+import { IMachineExectionEngine } from './MachineExecutionEngine/interface';
+import { ExecuteMachineInput, ExecuteMachineOutput } from './MachineExecutionEngine/types';
+import { SimpleMachineMemory } from './MachineMemory/Simple';
+import { TelemetredSimpleMachineMemory } from './MachineMemory/TelemetredSimple';
+import { IMachineMemory } from './MachineMemory/interface';
+import { MachineRegistry } from './MachineRegistry';
+import { IMachineRegistry } from './MachineRegistry/interface';
+import { SimpleEventBroker } from './utils/SimpleEventBroker';
+import { createSimpleEventBroker } from './utils/SimpleEventBroker/helper';
+import { ArvoResumable } from './ArvoResumable';
+import { createArvoResumable } from './ArvoResumable/factory';
+import { ArvoResumableHandler, ArvoResumableState } from './ArvoResumable/types';
+declare const xstate: {
+    emit: typeof emit;
+    assign: typeof assign;
+};
+export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, AbstractArvoEventHandler, ArvoEventHandlerOpenTelemetryOptions, EventHandlerFactory, ContractViolation, ConfigViolation, ExecutionViolation, ArvoMachine, setupArvoMachine, ArvoMachineContext, EnqueueArvoEventActionParam, IMachineRegistry, MachineRegistry, MachineExecutionEngine, IMachineExectionEngine, ExecuteMachineInput, ExecuteMachineOutput, IMachineMemory, SimpleMachineMemory, MachineMemoryRecord, IArvoOrchestrator, TransactionViolation, TransactionViolationCause, ArvoOrchestrator, createArvoOrchestrator, SimpleEventBroker, createSimpleEventBroker, TelemetredSimpleMachineMemory, xstate, ArvoResumable, createArvoResumable, ArvoResumableHandler, ArvoResumableState, };

package/dist/index.js

@@ -3,29 +3,52 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExecutionViolation = exports.ConfigViolation = exports.ContractViolation = exports.deleteOtelHeaders = exports.AbstractArvoEventHandler = exports.createArvoEventRouter = exports.ArvoEventRouter = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
+exports.createArvoResumable = exports.ArvoResumable = exports.xstate = exports.TelemetredSimpleMachineMemory = exports.createSimpleEventBroker = exports.SimpleEventBroker = exports.createArvoOrchestrator = exports.ArvoOrchestrator = exports.TransactionViolationCause = exports.TransactionViolation = exports.SimpleMachineMemory = exports.MachineExecutionEngine = exports.MachineRegistry = exports.setupArvoMachine = exports.ArvoMachine = exports.ExecutionViolation = exports.ConfigViolation = exports.ContractViolation = exports.AbstractArvoEventHandler = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
 var AbstractArvoEventHandler_1 = __importDefault(require("./AbstractArvoEventHandler"));
 exports.AbstractArvoEventHandler = AbstractArvoEventHandler_1.default;
 var ArvoEventHandler_1 = __importDefault(require("./ArvoEventHandler"));
 exports.ArvoEventHandler = ArvoEventHandler_1.default;
 var helpers_1 = require("./ArvoEventHandler/helpers");
 Object.defineProperty(exports, "createArvoEventHandler", { enumerable: true, get: function () { return helpers_1.createArvoEventHandler; } });
-var ArvoEventRouter_1 = require("./ArvoEventRouter");
-Object.defineProperty(exports, "ArvoEventRouter", { enumerable: true, get: function () { return ArvoEventRouter_1.ArvoEventRouter; } });
-var helpers_2 = require("./ArvoEventRouter/helpers");
-Object.defineProperty(exports, "createArvoEventRouter", { enumerable: true, get: function () { return helpers_2.createArvoEventRouter; } });
-var utils_1 = require("./ArvoEventRouter/utils");
-Object.defineProperty(exports, "deleteOtelHeaders", { enumerable: true, get: function () { return utils_1.deleteOtelHeaders; } });
-var MultiArvoEventHandler_1 = __importDefault(require("./MultiArvoEventHandler"));
-exports.MultiArvoEventHandler = MultiArvoEventHandler_1.default;
-var helpers_3 = require("./MultiArvoEventHandler/helpers");
-Object.defineProperty(exports, "createMultiArvoEventHandler", { enumerable: true, get: function () { return helpers_3.createMultiArvoEventHandler; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "ConfigViolation", { enumerable: true, get: function () { return errors_1.ConfigViolation; } });
 Object.defineProperty(exports, "ContractViolation", { enumerable: true, get: function () { return errors_1.ContractViolation; } });
 Object.defineProperty(exports, "ExecutionViolation", { enumerable: true, get: function () { return errors_1.ExecutionViolation; } });
-var utils_2 = require("./utils");
-Object.defineProperty(exports, "coalesce", { enumerable: true, get: function () { return utils_2.coalesce; } });
-Object.defineProperty(exports, "coalesceOrDefault", { enumerable: true, get: function () { return utils_2.coalesceOrDefault; } });
-Object.defineProperty(exports, "getValueOrDefault", { enumerable: true, get: function () { return utils_2.getValueOrDefault; } });
-Object.defineProperty(exports, "isNullOrUndefined", { enumerable: true, get: function () { return utils_2.isNullOrUndefined; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "coalesce", { enumerable: true, get: function () { return utils_1.coalesce; } });
+Object.defineProperty(exports, "coalesceOrDefault", { enumerable: true, get: function () { return utils_1.coalesceOrDefault; } });
+Object.defineProperty(exports, "getValueOrDefault", { enumerable: true, get: function () { return utils_1.getValueOrDefault; } });
+Object.defineProperty(exports, "isNullOrUndefined", { enumerable: true, get: function () { return utils_1.isNullOrUndefined; } });
+var xstate_1 = require("xstate");
+var ArvoMachine_1 = __importDefault(require("./ArvoMachine"));
+exports.ArvoMachine = ArvoMachine_1.default;
+var createMachine_1 = require("./ArvoMachine/createMachine");
+Object.defineProperty(exports, "setupArvoMachine", { enumerable: true, get: function () { return createMachine_1.setupArvoMachine; } });
+var ArvoOrchestrator_1 = require("./ArvoOrchestrator");
+Object.defineProperty(exports, "ArvoOrchestrator", { enumerable: true, get: function () { return ArvoOrchestrator_1.ArvoOrchestrator; } });
+var error_1 = require("./ArvoOrchestrator/error");
+Object.defineProperty(exports, "TransactionViolation", { enumerable: true, get: function () { return error_1.TransactionViolation; } });
+Object.defineProperty(exports, "TransactionViolationCause", { enumerable: true, get: function () { return error_1.TransactionViolationCause; } });
+var factory_1 = require("./ArvoOrchestrator/factory");
+Object.defineProperty(exports, "createArvoOrchestrator", { enumerable: true, get: function () { return factory_1.createArvoOrchestrator; } });
+var MachineExecutionEngine_1 = require("./MachineExecutionEngine");
+Object.defineProperty(exports, "MachineExecutionEngine", { enumerable: true, get: function () { return MachineExecutionEngine_1.MachineExecutionEngine; } });
+var Simple_1 = require("./MachineMemory/Simple");
+Object.defineProperty(exports, "SimpleMachineMemory", { enumerable: true, get: function () { return Simple_1.SimpleMachineMemory; } });
+var TelemetredSimple_1 = require("./MachineMemory/TelemetredSimple");
+Object.defineProperty(exports, "TelemetredSimpleMachineMemory", { enumerable: true, get: function () { return TelemetredSimple_1.TelemetredSimpleMachineMemory; } });
+var MachineRegistry_1 = require("./MachineRegistry");
+Object.defineProperty(exports, "MachineRegistry", { enumerable: true, get: function () { return MachineRegistry_1.MachineRegistry; } });
+var SimpleEventBroker_1 = require("./utils/SimpleEventBroker");
+Object.defineProperty(exports, "SimpleEventBroker", { enumerable: true, get: function () { return SimpleEventBroker_1.SimpleEventBroker; } });
+var helper_1 = require("./utils/SimpleEventBroker/helper");
+Object.defineProperty(exports, "createSimpleEventBroker", { enumerable: true, get: function () { return helper_1.createSimpleEventBroker; } });
+var ArvoResumable_1 = require("./ArvoResumable");
+Object.defineProperty(exports, "ArvoResumable", { enumerable: true, get: function () { return ArvoResumable_1.ArvoResumable; } });
+var factory_2 = require("./ArvoResumable/factory");
+Object.defineProperty(exports, "createArvoResumable", { enumerable: true, get: function () { return factory_2.createArvoResumable; } });
+var xstate = {
+    emit: xstate_1.emit,
+    assign: xstate_1.assign,
+};
+exports.xstate = xstate;

package/dist/utils/SimpleEventBroker/helper.d.ts

@@ -0,0 +1,166 @@
+import type { ArvoEvent } from 'arvo-core';
+import { SimpleEventBroker } from '.';
+import type AbstractArvoEventHandler from '../../AbstractArvoEventHandler';
+/**
+ * Creates a local event broker configured with domain event handlers and provides event resolution capabilities
+ *
+ * This factory function establishes a comprehensive event-driven architecture within a single process,
+ * automatically wiring event handlers to their source topics and providing sophisticated event propagation
+ * with domain-specific routing capabilities. The broker implements sequential queue-based processing
+ * with built-in error handling and observability features.
+ *
+ * **Core Architecture:**
+ * The broker acts as an in-memory event bus that connects ArvoResumable orchestrators, ArvoOrchestrator
+ * state machines, and ArvoEventHandler services in a unified event-driven system. This enables
+ * local testing of distributed workflows and provides a foundation for event-driven microservices.
+ *
+ * **Event Processing Flow:**
+ * 1. Events are published to handler source topics
+ * 2. Handlers execute and produce response events
+ * 3. Domain-specific events are routed through onDomainedEvents callback
+ * 4. Default domain events are automatically propagated through the broker
+ * 5. Event chains continue until all handlers complete processing
+ *
+ * @param eventHandlers - Array of event handlers to register with the broker. Each handler is automatically
+ *                        subscribed to its source topic and executed when matching events are received.
+ *                        Supports ArvoResumable, ArvoOrchestrator, and ArvoEventHandler instances.
+ *
+ * @param options - Optional configuration for customizing broker behavior and event processing
+ * @param options.onError - Custom error handler invoked when processing failures occur. Receives the error
+ *                          and triggering event for logging, monitoring, or recovery actions. Defaults to
+ *                          console.error with structured event information for debugging.
+ * @param options.onDomainedEvents - Callback for processing domain-specific events produced by handlers.
+ *                                   Enables custom routing logic, external system integration, or
+ *                                   domain-specific event processing patterns. Receives events grouped
+ *                                   by domain (excluding 'all') and the broker instance for republishing.
+ *
+ * @returns Configuration object containing the broker instance and event resolution function
+ * @returns result.broker - Configured SimpleEventBroker with all handlers subscribed and ready for processing
+ * @returns result.resolve - Async function that executes complete event processing chains and returns
+ *                           the final resolved event. Returns null if resolution fails or handler is not found
+ *                           for an intermetiate event.
+ *
+ * @throws {Error} When event source conflicts with registered handler sources during resolution
+ *
+ * @example
+ * **Basic Event-Driven Architecture Setup:**
+ * ```typescript
+ * const userHandler = createArvoEventHandler({
+ *   contract: userContract,
+ *   handler: { '1.0.0': async ({ event }) => ({ type: 'user.processed', data: event.data }) }
+ * });
+ *
+ * const orderOrchestrator = createArvoResumable({
+ *   contracts: { self: orderContract, services: { user: userContract } },
+ *   handler: {
+ *     '1.0.0': async ({ init, service }) => {
+ *       if (init) return { services: [{ type: 'user.process', data: init.data }] };
+ *       if (service) return { complete: { data: { orderId: 'order-123' } } };
+ *     }
+ *   }
+ * });
+ *
+ * const { broker, resolve } = createSimpleEventBroker([userHandler, orderOrchestrator]);
+ * ```
+ *
+ * @example
+ * **Advanced Configuration with Domain Routing:**
+ * ```typescript
+ * const { broker, resolve } = createSimpleEventBroker(
+ *   [orchestrator, paymentHandler, notificationHandler],
+ *   {
+ *     onError: (error, event) => {
+ *       logger.error('Event processing failed', {
+ *         error: error.message,
+ *         eventType: event.type,
+ *         eventId: event.id,
+ *         source: event.source,
+ *         timestamp: new Date().toISOString()
+ *       });
+ *       // Could implement retry logic, dead letter queues, etc.
+ *     },
+ *     onDomainedEvents: ({ events, broker }) => {
+ *       // Route payment events to external payment processor
+ *       if (events.payment) {
+ *         events.payment.forEach(event => paymentGateway.send(event));
+ *       }
+ *
+ *       // Route notification events to messaging service
+ *       if (events.notifications) {
+ *         events.notifications.forEach(event => messagingService.send(event));
+ *       }
+ *
+ *       // Republish other domain events through the broker
+ *       Object.entries(events).forEach(([domain, domainEvents]) => {
+ *         if (!['payment', 'notifications'].includes(domain)) {
+ *           domainEvents.forEach(event => broker.publish(event));
+ *         }
+ *       });
+ *     }
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * **Event Resolution for Integration Testing:**
+ * ```typescript
+ * // Test complete workflow execution
+ * const testEvent = createArvoEvent({
+ *   type: 'order.create',
+ *   source: 'test.client',
+ *   to: 'order.orchestrator',
+ *   data: { userId: '123', items: ['item1', 'item2'] }
+ * });
+ *
+ * const finalEvent = await resolve(testEvent);
+ *
+ * if (finalEvent) {
+ *   // Verify the complete workflow executed successfully
+ *   expect(finalEvent.type).toBe('order.completed');
+ *   expect(finalEvent.data.orderId).toBeDefined();
+ *   expect(finalEvent.source).toBe('test.client'); // Original source preserved
+ * } else {
+ *   throw new Error('Order processing workflow failed');
+ * }
+ * ```
+ *
+ * @example
+ * **Direct Event Publishing:**
+ * ```typescript
+ * // Publish events directly to the broker for real-time processing
+ * await broker.publish(createArvoEvent({
+ *   type: 'user.signup',
+ *   source: 'web.app',
+ *   to: 'user.service',
+ *   data: { email: 'user@example.com', name: 'John Doe' }
+ * }));
+ *
+ * // The event will be routed to the user service handler automatically
+ * // Any resulting events will propagate through the broker
+ * ```
+ *
+ * @remarks
+ * **Event Source Conflict Prevention:**
+ * The resolve function validates that the input event's source doesn't conflict
+ * with registered handler sources to prevent infinite loops and routing ambiguity.
+ *
+ * **Sequential Processing Guarantee:**
+ * Events are processed sequentially within each topic to maintain ordering
+ * guarantees and prevent race conditions in workflow state management.
+ *
+ * **Integration Testing Benefits:**
+ * This pattern enables comprehensive integration testing of event-driven workflows
+ * without requiring external message brokers, making test suites faster and
+ * more reliable while maintaining production-like behavior patterns.
+ */
+export declare const createSimpleEventBroker: (eventHandlers: AbstractArvoEventHandler[], options?: {
+    onError?: (error: Error, event: ArvoEvent) => void;
+    onDomainedEvents?: (param: {
+        domain: string;
+        event: ArvoEvent;
+        broker: SimpleEventBroker;
+    }) => Promise<void>;
+}) => {
+    broker: SimpleEventBroker;
+    resolve: (_event: ArvoEvent) => Promise<ArvoEvent | null>;
+};