arvo-event-handler 2.3.3 → 3.0.2

package/dist/ArvoEventRouter/index.js

@@ -1,268 +0,0 @@
-"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 __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArvoEventRouter = void 0;
-var api_1 = require("@opentelemetry/api");
-var arvo_core_1 = require("arvo-core");
-var AbstractArvoEventHandler_1 = __importDefault(require("../AbstractArvoEventHandler"));
-var errors_1 = require("../errors");
-var utils_1 = require("../utils");
-var utils_2 = require("./utils");
-/**
- * ArvoEventRouter manages event routing and execution within the Arvo event system. It directs
- * incoming events to appropriate handlers based on event type while maintaining telemetry
- * and error handling.
- *
- * The router enforces contract validation, manages execution costs, and provides comprehensive
- * telemetry via OpenTelemetry integration. It handles event lifecycle management from initial
- * receipt through processing and response generation.
- *
- * @example
- * ```typescript
- * const router = createArvoEventRouter({
- *   source: "payment.service",
- *   executionunits: 1,
- *   handlers: [paymentProcessedHandler, paymentFailedHandler]
- * });
- *
- * // Route an incoming event
- * const results = await router.execute(incomingEvent);
- * ```
- */
-var ArvoEventRouter = /** @class */ (function (_super) {
-    __extends(ArvoEventRouter, _super);
-    /**
-     * Creates an ArvoEventRouter instance with specified configuration.
-     *
-     * @param param - Router configuration containing source, handlers, and execution parameters
-     *
-     * @throws {Error} When source contains invalid characters (non-alphanumeric)
-     * @throws {Error} When multiple handlers are registered for the same event type
-     */
-    function ArvoEventRouter(param) {
-        var _a;
-        var _b, _c;
-        var _this = _super.call(this) || this;
-        /** Registry mapping event types to their handlers */
-        _this.handlersMap = {};
-        if (param.source && !(0, utils_1.isLowerAlphanumeric)(param.source)) {
-            throw new Error("Invalid source identifier '".concat(param.source, "': Must contain only alphanumeric characters (example: payment.service)"));
-        }
-        _this.source = param.source;
-        _this.executionunits = param.executionunits;
-        for (var _i = 0, _d = param.handlers; _i < _d.length; _i++) {
-            var handler = _d[_i];
-            if (_this.handlersMap[handler.contract.type]) {
-                var existingHandler = _this.handlersMap[handler.contract.type];
-                throw new Error("Duplicate handler registration detected for event type '".concat(handler.contract.type, "'. ") +
-                    "Conflicts between contracts: ".concat(existingHandler.contract.uri, " and ").concat(handler.contract.uri));
-            }
-            _this.handlersMap[handler.contract.type] = handler;
-        }
-        _this.spanOptions = __assign(__assign({ kind: api_1.SpanKind.CONSUMER }, param.spanOptions), { attributes: __assign(__assign((_a = {}, _a[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = arvo_core_1.ArvoExecutionSpanKind.EVENT_HANDLER, _a[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = arvo_core_1.OpenInferenceSpanKind.CHAIN, _a), ((_c = (_b = param.spanOptions) === null || _b === void 0 ? void 0 : _b.attributes) !== null && _c !== void 0 ? _c : {})), { 'arvo.handler.source': _this.source }) });
-        return _this;
-    }
-    /**
-     * Routes and executes an event through its appropriate handler. Creates a telemetry span,
-     * validates the event destination, finds a matching handler, and processes the event.
-     * Handles routing errors, missing handlers, and execution failures by returning error
-     * events with telemetry context. Tracks performance through execution units and span
-     * propagation.
-     *
-     * @param event The event to be routed and processed
-     * @param opentelemetry Configuration for telemetry context inheritance
-     * @returns Promise resolving to resulting events or error events
-     *
-     * @throws {ConfigViolation} When event destination does not match router's source
-     * @throws {ConfigViolation} When no registered handler exists for the event type
-     * @throws Other Violation error which are thrown by the registered event handlers
-     */
-    ArvoEventRouter.prototype.execute = function (event_1) {
-        return __awaiter(this, arguments, void 0, function (event, opentelemetry) {
-            var _this = this;
-            if (opentelemetry === void 0) { opentelemetry = {
-                inheritFrom: 'EVENT',
-            }; }
-            return __generator(this, function (_a) {
-                switch (_a.label) {
-                    case 0: return [4 /*yield*/, arvo_core_1.ArvoOpenTelemetry.getInstance().startActiveSpan({
-                            name: 'ArvoEventRouter',
-                            spanOptions: this.spanOptions,
-                            disableSpanManagement: true,
-                            context: opentelemetry.inheritFrom === 'EVENT'
-                                ? {
-                                    inheritFrom: 'TRACE_HEADERS',
-                                    traceHeaders: {
-                                        traceparent: event.traceparent,
-                                        tracestate: event.tracestate,
-                                    },
-                                }
-                                : {
-                                    inheritFrom: 'CONTEXT',
-                                    context: api_1.context.active(),
-                                },
-                            fn: function (span) { return __awaiter(_this, void 0, void 0, function () {
-                                var otelSpanHeaders, newEvent, _i, _a, _b, key, value, results, resultingEvents, index, _c, _d, _e, key, value, error_1, events;
-                                var _this = this;
-                                return __generator(this, function (_f) {
-                                    switch (_f.label) {
-                                        case 0:
-                                            otelSpanHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
-                                            newEvent = (0, utils_2.deleteOtelHeaders)(event);
-                                            _f.label = 1;
-                                        case 1:
-                                            _f.trys.push([1, 3, 4, 5]);
-                                            span.setStatus({ code: api_1.SpanStatusCode.OK });
-                                            for (_i = 0, _a = Object.entries(event.otelAttributes); _i < _a.length; _i++) {
-                                                _b = _a[_i], key = _b[0], value = _b[1];
-                                                span.setAttribute("to_process.0.".concat(key), value);
-                                            }
-                                            (0, arvo_core_1.logToSpan)({
-                                                level: 'INFO',
-                                                message: "Initiating event resolution - Type: ".concat(newEvent.type, ", Source: ").concat(newEvent.source, ", Destination: ").concat(newEvent.to),
-                                            });
-                                            if (newEvent.to !== this.source) {
-                                                throw new errors_1.ConfigViolation("Event destination mismatch: Received destination '".concat(newEvent.to, "', ") +
-                                                    "but router accepts only '".concat(this.source, "'"));
-                                            }
-                                            if (!this.handlersMap[newEvent.type]) {
-                                                throw new errors_1.ConfigViolation("No registered handler found for event type '".concat(newEvent.type, "'"));
-                                            }
-                                            (0, arvo_core_1.logToSpan)({
-                                                level: 'INFO',
-                                                message: "Handler found for event type '".concat(newEvent.type, "' - Beginning event processing"),
-                                            });
-                                            return [4 /*yield*/, this.handlersMap[newEvent.type].execute(newEvent, {
-                                                    inheritFrom: 'CONTEXT',
-                                                })];
-                                        case 2:
-                                            results = _f.sent();
-                                            resultingEvents = results.events.map(function (event) {
-                                                var _a;
-                                                return new arvo_core_1.ArvoEvent({
-                                                    id: event.id,
-                                                    time: event.time,
-                                                    source: _this.source,
-                                                    specversion: '1.0',
-                                                    type: event.type,
-                                                    subject: event.subject,
-                                                    datacontenttype: event.datacontenttype,
-                                                    dataschema: event.dataschema,
-                                                    to: event.to,
-                                                    accesscontrol: event.accesscontrol,
-                                                    redirectto: event.redirectto,
-                                                    executionunits: ((_a = event.executionunits) !== null && _a !== void 0 ? _a : 0) + _this.executionunits,
-                                                    traceparent: otelSpanHeaders.traceparent,
-                                                    tracestate: otelSpanHeaders.tracestate,
-                                                    parentid: event.parentid,
-                                                }, event.data, event.cloudevent.extensions);
-                                            });
-                                            (0, arvo_core_1.logToSpan)({
-                                                level: 'INFO',
-                                                message: "Event processing completed successfully - Generated ".concat(resultingEvents.length, " new event(s)"),
-                                            });
-                                            for (index = 0; index < resultingEvents.length; index++) {
-                                                for (_c = 0, _d = Object.entries(resultingEvents[index].otelAttributes); _c < _d.length; _c++) {
-                                                    _e = _d[_c], key = _e[0], value = _e[1];
-                                                    span.setAttribute("to_emit.".concat(index, ".").concat(key), value);
-                                                }
-                                            }
-                                            return [2 /*return*/, { events: resultingEvents }];
-                                        case 3:
-                                            error_1 = _f.sent();
-                                            events = (0, utils_1.handleArvoEventHandlerCommonError)(error_1, otelSpanHeaders, this.systemErrorSchema.type, this.source, event, this.executionunits, function (param, extensions) { return (0, arvo_core_1.createArvoEvent)(param, extensions); });
-                                            return [2 /*return*/, { events: events }];
-                                        case 4:
-                                            span.end();
-                                            return [7 /*endfinally*/];
-                                        case 5: return [2 /*return*/];
-                                    }
-                                });
-                            }); },
-                        })];
-                    case 1: return [2 /*return*/, _a.sent()];
-                }
-            });
-        });
-    };
-    Object.defineProperty(ArvoEventRouter.prototype, "systemErrorSchema", {
-        /**
-         * System error schema configuration.
-         * Error events follow format: sys.<handler-source>.error
-         */
-        get: function () {
-            return {
-                type: "sys.".concat(this.source, ".error"),
-                schema: arvo_core_1.ArvoErrorSchema,
-            };
-        },
-        enumerable: false,
-        configurable: true
-    });
-    return ArvoEventRouter;
-}(AbstractArvoEventHandler_1.default));
-exports.ArvoEventRouter = ArvoEventRouter;

package/dist/ArvoEventRouter/types.d.ts

@@ -1,36 +0,0 @@
-import type { SpanOptions } from '@opentelemetry/api';
-import type { ArvoContract } from 'arvo-core';
-import type ArvoEventHandler from '../ArvoEventHandler';
-/**
- * Interface for defining an Arvo Event Router.
- */
-export interface IArvoEventRouter {
-    /**
-     * Defines the source name of the router.
-     *
-     * @remarks
-     * If this field is defined:
-     * - The router will only listen to events with a `to` field matching this `source`.
-     * - If an event's `to` field doesn't match, a system error event will be emitted.
-     * - For all emitted events, the `source` field will be overridden by this value.
-     */
-    source: string;
-    /**
-     * The default execution cost of the function.
-     * This can represent a dollar value or some other number with a rate card.
-     */
-    executionunits: number;
-    /**
-     * A list of all available event handlers to be used by the router.
-     *
-     * @remarks
-     * This array contains instances of `ArvoEventHandler<ArvoContract>` which define
-     * how different types of events should be processed. The router will use these
-     * handlers to manage incoming events and generate appropriate responses or actions.
-     */
-    handlers: ArvoEventHandler<ArvoContract<any, any, any>>[];
-    /**
-     * The OpenTelemetry span options
-     */
-    spanOptions?: SpanOptions;
-}

package/dist/ArvoEventRouter/utils.d.ts

@@ -1,30 +0,0 @@
-import { ArvoEvent } from 'arvo-core';
-/**
- * Creates a new ArvoEvent with telemetry headers (traceparent and tracestate) removed.
- *
- * @param event - The original ArvoEvent to process
- * @returns A new ArvoEvent instance with all original properties except telemetry headers
- *
- * @remarks
- * This function creates a clean copy of an ArvoEvent by:
- * 1. Preserving all standard event properties
- * 2. Setting telemetry headers (traceparent and tracestate) to null
- * 3. Maintaining the original data and extensions
- *
- * It's useful when you need to:
- * - Clear existing telemetry context
- * - Start a new telemetry trace
- * - Remove distributed tracing information
- *
- * @see {@link ArvoEvent} for complete event structure
- */
-export declare const deleteOtelHeaders: (event: ArvoEvent) => ArvoEvent<Record<string, any>, Record<string, string | number | boolean | null> & {
-    to: string | null;
-    accesscontrol: string | null;
-    redirectto: string | null;
-    executionunits: number | null;
-    parentid: string | null;
-} & {
-    traceparent: string | null;
-    tracestate: string | null;
-}, string>;

package/dist/ArvoEventRouter/utils.js

@@ -1,43 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.deleteOtelHeaders = void 0;
-var arvo_core_1 = require("arvo-core");
-/**
- * Creates a new ArvoEvent with telemetry headers (traceparent and tracestate) removed.
- *
- * @param event - The original ArvoEvent to process
- * @returns A new ArvoEvent instance with all original properties except telemetry headers
- *
- * @remarks
- * This function creates a clean copy of an ArvoEvent by:
- * 1. Preserving all standard event properties
- * 2. Setting telemetry headers (traceparent and tracestate) to null
- * 3. Maintaining the original data and extensions
- *
- * It's useful when you need to:
- * - Clear existing telemetry context
- * - Start a new telemetry trace
- * - Remove distributed tracing information
- *
- * @see {@link ArvoEvent} for complete event structure
- */
-var deleteOtelHeaders = function (event) {
-    return new arvo_core_1.ArvoEvent({
-        id: event.id,
-        time: event.time,
-        source: event.source,
-        specversion: '1.0',
-        type: event.type,
-        subject: event.subject,
-        datacontenttype: event.datacontenttype,
-        dataschema: event.dataschema,
-        to: event.to,
-        accesscontrol: event.accesscontrol,
-        redirectto: event.redirectto,
-        executionunits: event.executionunits,
-        traceparent: null,
-        tracestate: null,
-        parentid: event.parentid,
-    }, event.data, event.cloudevent.extensions);
-};
-exports.deleteOtelHeaders = deleteOtelHeaders;

package/dist/MultiArvoEventHandler/helpers.d.ts

@@ -1,48 +0,0 @@
-import MultiArvoEventHandler from '.';
-import type { IMultiArvoEventHandler } from './types';
-/**
- * Creates a MultiArvoEventHandler instance capable of handling multiple event types across different ArvoContracts.
- *
- * @param param - The configuration parameters for the event handler.
- * @returns A new instance of MultiArvoEventHandler.
- *
- * @remarks
- * This factory function instantiates a MultiArvoEventHandler, which is designed to process
- * multiple event types from various ArvoContracts. Unlike the more specialized ArvoEventHandler,
- * MultiArvoEventHandler offers greater flexibility by not being bound to a specific contract
- * or event type.
- *
- * Key features of MultiArvoEventHandler:
- * - Handles multiple event types
- * - Works across different ArvoContracts
- * - Provides a unified interface for diverse event processing
- *
- * The handler's behavior and resource allocation are determined by the provided configuration
- * parameters, including execution units and the event processing logic.
- *
- * @example
- * ```typescript
- * const multiEventHandler = createMultiArvoEventHandler({
- *   source: 'com.multi.handler',
- *   executionunits: 100,
- *   handler: async ({ event }) => {
- *     switch(event.type) {
- *       case 'com.user.registered':
- *         // Handle user registration event
- *         break;
- *       case 'com.transaction.complete':
- *         // Handle transaction completion event
- *         break;
- *       // ... handle other event types
- *     }
- *   }
- * });
- *
- * // Use the handler
- * await multiEventHandler.handleEvent(someEvent);
- * ```
- *
- * @see {@link IMultiArvoEventHandler} for the full configuration options
- * @see {@link MultiArvoEventHandler} for the handler class implementation
- */
-export declare const createMultiArvoEventHandler: (param: IMultiArvoEventHandler) => MultiArvoEventHandler;

package/dist/MultiArvoEventHandler/helpers.js

@@ -1,56 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createMultiArvoEventHandler = void 0;
-var _1 = __importDefault(require("."));
-/**
- * Creates a MultiArvoEventHandler instance capable of handling multiple event types across different ArvoContracts.
- *
- * @param param - The configuration parameters for the event handler.
- * @returns A new instance of MultiArvoEventHandler.
- *
- * @remarks
- * This factory function instantiates a MultiArvoEventHandler, which is designed to process
- * multiple event types from various ArvoContracts. Unlike the more specialized ArvoEventHandler,
- * MultiArvoEventHandler offers greater flexibility by not being bound to a specific contract
- * or event type.
- *
- * Key features of MultiArvoEventHandler:
- * - Handles multiple event types
- * - Works across different ArvoContracts
- * - Provides a unified interface for diverse event processing
- *
- * The handler's behavior and resource allocation are determined by the provided configuration
- * parameters, including execution units and the event processing logic.
- *
- * @example
- * ```typescript
- * const multiEventHandler = createMultiArvoEventHandler({
- *   source: 'com.multi.handler',
- *   executionunits: 100,
- *   handler: async ({ event }) => {
- *     switch(event.type) {
- *       case 'com.user.registered':
- *         // Handle user registration event
- *         break;
- *       case 'com.transaction.complete':
- *         // Handle transaction completion event
- *         break;
- *       // ... handle other event types
- *     }
- *   }
- * });
- *
- * // Use the handler
- * await multiEventHandler.handleEvent(someEvent);
- * ```
- *
- * @see {@link IMultiArvoEventHandler} for the full configuration options
- * @see {@link MultiArvoEventHandler} for the handler class implementation
- */
-var createMultiArvoEventHandler = function (param) {
-    return new _1.default(param);
-};
-exports.createMultiArvoEventHandler = createMultiArvoEventHandler;

package/dist/MultiArvoEventHandler/index.d.ts

@@ -1,68 +0,0 @@
-import { type SpanOptions } from '@opentelemetry/api';
-import { type ArvoEvent } from 'arvo-core';
-import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
-import type { ArvoEventHandlerOpenTelemetryOptions } from '../types';
-import type { IMultiArvoEventHandler, MultiArvoEventHandlerFunction } from './types';
-/**
- * MultiArvoEventHandler processes multiple event types without being bound to specific contracts.
- * Manages event execution, telemetry tracking, and error handling for diverse event streams.
- *
- * @example
- * const handler = createMultiArvoEventHandler({
- *   source: "order.handler",
- *   executionunits: 1,
- *   handler: async ({ event }) => {
- *     // Handle multiple event types
- *   }
- * });
- */
-export default class MultiArvoEventHandler extends AbstractArvoEventHandler {
-    /** Computational cost metric for handler operations */
-    readonly executionunits: number;
-    /** Source identifier for event routing */
-    readonly source: string;
-    /** OpenTelemetry configuration */
-    readonly spanOptions: SpanOptions;
-    /** Event processing function */
-    readonly handler: MultiArvoEventHandlerFunction;
-    /**
-     * Creates handler instance with specified configuration.
-     * @param param Handler configuration including source and execution parameters
-     * @throws When source contains invalid characters
-     */
-    constructor(param: IMultiArvoEventHandler);
-    /**
-     * Processes an event through configured handler function. Creates telemetry span,
-     * validates event destination, executes handler, and manages errors.
-     *
-     * @param event Event to process
-     * @param opentelemetry Telemetry context configuration
-     * @returns Resulting events or error events
-     *
-     * @throws {ConfigViolation} When event destination does not match handler source
-     * @throws Other Violation error which are thrown by the event handler function
-     */
-    execute(event: ArvoEvent, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): Promise<{
-        events: ArvoEvent[];
-    }>;
-    /**
-     * System error schema configuration.
-     * Error events follow format: sys.<handler-source>.error
-     */
-    get systemErrorSchema(): {
-        type: string;
-        schema: import("zod").ZodObject<{
-            errorName: import("zod").ZodString;
-            errorMessage: import("zod").ZodString;
-            errorStack: import("zod").ZodNullable<import("zod").ZodString>;
-        }, "strip", import("zod").ZodTypeAny, {
-            errorName: string;
-            errorMessage: string;
-            errorStack: string | null;
-        }, {
-            errorName: string;
-            errorMessage: string;
-            errorStack: string | null;
-        }>;
-    };
-}