arvo-event-handler
Version:
A complete set of orthogonal event handler and orchestration primitives for Arvo based applications, featuring declarative state machines (XState), imperative resumables for agentic workflows, contract-based routing, OpenTelemetry observability, and in-me
277 lines (276 loc) • 13.3 kB
JavaScript
;
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.createSimpleEventBroker = void 0;
var _1 = require(".");
/**
* 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.
*/
var createSimpleEventBroker = function (eventHandlers, options) {
var _a;
var broker = new _1.SimpleEventBroker({
maxQueueSize: 1000,
errorHandler: (_a = options === null || options === void 0 ? void 0 : options.onError) !== null && _a !== void 0 ? _a : (function (error, event) {
console.error('Broker error:', {
message: error.message,
eventType: event.to,
event: event,
});
}),
});
var _loop_1 = function (handler) {
broker.subscribe(handler.source, function (event) { return __awaiter(void 0, void 0, void 0, function () {
var response, _i, _a, evt;
var _b;
return __generator(this, function (_c) {
switch (_c.label) {
case 0: return [4 /*yield*/, handler.execute(event, {
inheritFrom: 'EVENT',
})];
case 1:
response = _c.sent();
_i = 0, _a = response.events;
_c.label = 2;
case 2:
if (!(_i < _a.length)) return [3 /*break*/, 7];
evt = _a[_i];
if (!evt.domain) return [3 /*break*/, 4];
return [4 /*yield*/, ((_b = options === null || options === void 0 ? void 0 : options.onDomainedEvents) === null || _b === void 0 ? void 0 : _b.call(options, {
domain: evt.domain,
event: evt,
broker: broker,
}))];
case 3:
_c.sent();
return [3 /*break*/, 6];
case 4: return [4 /*yield*/, broker.publish(evt)];
case 5:
_c.sent();
_c.label = 6;
case 6:
_i++;
return [3 /*break*/, 2];
case 7: return [2 /*return*/];
}
});
}); }, true);
};
// Wire up each handler to its source topic
for (var _i = 0, eventHandlers_1 = eventHandlers; _i < eventHandlers_1.length; _i++) {
var handler = eventHandlers_1[_i];
_loop_1(handler);
}
return {
broker: broker,
resolve: function (_event) { return __awaiter(void 0, void 0, void 0, function () {
var resolvedEvent;
return __generator(this, function (_a) {
switch (_a.label) {
case 0:
if (broker.topics.includes(_event.source)) {
throw new Error("The event source cannot be one of the handlers in the broker. Please update the event.source, the given is '".concat(_event.source, "'"));
}
resolvedEvent = null;
broker.subscribe(_event.source, function (event) { return __awaiter(void 0, void 0, void 0, function () {
return __generator(this, function (_a) {
resolvedEvent = event;
return [2 /*return*/];
});
}); });
return [4 /*yield*/, broker.publish(_event)];
case 1:
_a.sent();
if (resolvedEvent === null) {
return [2 /*return*/, null];
}
return [2 /*return*/, resolvedEvent];
}
});
}); },
};
};
exports.createSimpleEventBroker = createSimpleEventBroker;