arvo-event-handler 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## [0.0.1] - 2024-09-07
 
 - Finalised version 0.0.1 of the event handlers for Arvo
+
 ## [0.0.4] - 2024-09-09
 
 - Finalised Event Handler implementation
@@ -14,4 +15,7 @@
 ## [1.0.0] - 2024-09-10
 
 - First version rrelease
+## [1.0.2] - 2024-09-10
+
+- Added ArvoEventRouter as a mechanism to group ArvoEventHandlers
 

package/README.md

@@ -25,18 +25,61 @@ Whether you're building a small microservice or a large-scale distributed system
 
 # Arvo - Event Handler
 
+This package contains the event handler primitive required to enable an Arvo Event Driven System. These are light weight classes and types which take care of event listening, contract bound type inference, distributed open telemetry and much more.
+
+## Documentation & Resources
+
+| Source       | Link                                                              |
+| ------------ | ----------------------------------------------------------------- |
+| Package      | https://www.npmjs.com/package/arvo-event-handler?activeTab=readme |
+| Github       | https://github.com/SaadAhmad123/arvo-event-handler                |
+| Documenation | https://saadahmad123.github.io/arvo-event-handler/index.html      |
+
 ## Installation
 
 You can install the core package via `npm` or `yarn`
 
 ```bash
-npm install arvo-event-handler
+npm install arvo-event-handler arvo-core
 ```
 
 ```bash
-yarn add arvo-event-handler
+yarn add arvo-event-handler arvo-core
+```
+
+## Components
+
+There 2 main types of event handlers in Arvo event driven system
+
+- [ArvoEventHandler](src/ArvoEventHandler/README.md) is designed to facilitate the handling of events as per an `ArvoContract` (see [arvo-core](https://saadahmad123.github.io/arvo-core/documents/ArvoContract.html)). It provides a robust and flexible way to create, manage, and execute event handlers for Arvo-based event driven systems.
+- [ArvoEventRouter](src/ArvoEventRouter/README.md) is designed to route ArvoEvents to appropriate ArvoEventHandlers. It provides a centralized mechanism for managing and executing multiple event handlers based on event types.
+- [MultiArvoEventHandler](src/MultiArvoEventHandler/README.md) is a flexible and powerful event handling class designed to process multiple event types across different ArvoContracts. This handler offers greater versatility compared to the more specialized `ArvoEventHandler`, as it's not bound to a specific contract or event type.
+
+
+## Getting Started
+
+To start using Arvo Event Handlers in your project:
+
+- Install the package as shown in the Installation section.
+- Import the necessary components:
+
+```javascript
+import {
+  createArvoEvent,
+  createArvoContract,
+  createArvoContractLibrary,
+  createArvoEventFactory,
+} from 'arvo-core';
+
+import {
+  createArvoEventHandler,
+  createMultiArvoEventHandler,
+  createArvoEventRouter,
+} from 'arvo-event-handler'
 ```
 
+- Begin defining your events, contracts, and handlers using the provided classes.
+
 ## License
 
 This package is available under the MIT License. For more details, refer to the [LICENSE.md](LICENSE.md) file in the project repository.
@@ -58,4 +101,4 @@ For a detailed list of changes and updates, please refer to the [document](CHANG
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
-[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)

package/dist/ArvoEventHandler/index.d.ts

@@ -22,7 +22,7 @@ export default class ArvoEventHandler<TContract extends ArvoContract> {
      * @remarks
      * For all the events which are emitted by the handler, this is
      * the source field value of them all.
-    */
+     */
     readonly source: string;
     readonly openInferenceSpanKind: OpenInferenceSpanKind;
     readonly arvoExecutionSpanKind: ArvoExecutionSpanKind;

package/dist/ArvoEventHandler/index.js

@@ -102,9 +102,12 @@ var ArvoEventHandler = /** @class */ (function () {
             }
         }
         this.source = param.source || this.contract.accepts.type;
-        this.arvoExecutionSpanKind = ((_a = param.spanKind) === null || _a === void 0 ? void 0 : _a.arvoExecution) || this.arvoExecutionSpanKind;
-        this.openInferenceSpanKind = ((_b = param.spanKind) === null || _b === void 0 ? void 0 : _b.openInference) || this.openInferenceSpanKind;
-        this.openTelemetrySpanKind = ((_c = param.spanKind) === null || _c === void 0 ? void 0 : _c.openTelemetry) || this.openTelemetrySpanKind;
+        this.arvoExecutionSpanKind =
+            ((_a = param.spanKind) === null || _a === void 0 ? void 0 : _a.arvoExecution) || this.arvoExecutionSpanKind;
+        this.openInferenceSpanKind =
+            ((_b = param.spanKind) === null || _b === void 0 ? void 0 : _b.openInference) || this.openInferenceSpanKind;
+        this.openTelemetrySpanKind =
+            ((_c = param.spanKind) === null || _c === void 0 ? void 0 : _c.openTelemetry) || this.openTelemetrySpanKind;
     }
     /**
      * Executes the event handler for a given event.
@@ -167,7 +170,7 @@ var ArvoEventHandler = /** @class */ (function () {
                             attributes: (_a = {},
                                 _a[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = this.openInferenceSpanKind,
                                 _a[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = this.arvoExecutionSpanKind,
-                                _a)
+                                _a),
                         };
                         if (event.traceparent) {
                             inheritedContext = (0, OpenTelemetry_1.extractContext)(event.traceparent, event.tracestate);
@@ -196,7 +199,10 @@ var ArvoEventHandler = /** @class */ (function () {
                                             if (inputEventValidation.error) {
                                                 throw new Error("Invalid event payload: ".concat(inputEventValidation.error));
                                             }
-                                            return [4 /*yield*/, this._handler({ event: event, source: this.source })];
+                                            return [4 /*yield*/, this._handler({
+                                                    event: event,
+                                                    source: this.source,
+                                                })];
                                         case 2:
                                             _handleOutput = _a.sent();
                                             if (!_handleOutput)
@@ -212,9 +218,9 @@ var ArvoEventHandler = /** @class */ (function () {
                                                     var __extensions = output.__extensions, handlerResult = __rest(output, ["__extensions"]);
                                                     var result = eventFactory.emits(__assign(__assign({}, handlerResult), { traceparent: otelSpanHeaders.traceparent || undefined, tracestate: otelSpanHeaders.tracestate || undefined, source: _this.source, subject: event.subject, 
                                                         // The user should be able to override the `to` field
-                                                        // If that is not present then the 'redirectto' field 
+                                                        // If that is not present then the 'redirectto' field
                                                         // is referred to. Then, after all else, 'source' field
-                                                        // is used as a form of reply. 
+                                                        // is used as a form of reply.
                                                         to: (0, utils_1.coalesceOrDefault)([handlerResult.to, event.redirectto], event.source), executionunits: (0, utils_1.coalesce)(handlerResult.executionunits, _this.executionunits) }), __extensions);
                                                     Object.entries(result.otelAttributes).forEach(function (_a) {
                                                         var key = _a[0], value = _a[1];
@@ -232,7 +238,7 @@ var ArvoEventHandler = /** @class */ (function () {
                                             result = eventFactory.systemError({
                                                 source: this.source,
                                                 subject: event.subject,
-                                                // The system error must always got back to 
+                                                // The system error must always got back to
                                                 // the source
                                                 to: event.source,
                                                 error: error_1,
@@ -276,7 +282,7 @@ var ArvoEventHandler = /** @class */ (function () {
         get: function () {
             return {
                 type: "sys.".concat(this.contract.accepts.type, ".error"),
-                schema: arvo_core_1.ArvoErrorSchema
+                schema: arvo_core_1.ArvoErrorSchema,
             };
         },
         enumerable: false,

package/dist/ArvoEventRouter/helpers.d.ts

@@ -0,0 +1,36 @@
+import { ArvoEventRouter } from '.';
+import { IArvoEventRouter } from './types';
+/**
+ * Creates and returns a new instance of ArvoEventRouter.
+ *
+ * @param {IArvoEventRouter} param - Configuration object for the ArvoEventRouter.
+ * @returns {ArvoEventRouter} A new instance of ArvoEventRouter.
+ *
+ * @throws {Error} If there are duplicate handlers for the same event type.
+ * @throws {Error} If the provided source is an invalid string.
+ *
+ * @example
+ * const router = createArvoEventRouter({
+ *   source: 'my-router',
+ *   handlers: [handler1, handler2],
+ *   executionunits: 10
+ * });
+ *
+ * @remarks
+ * This function is a factory method that simplifies the creation of an ArvoEventRouter instance.
+ * It encapsulates the instantiation process, allowing for a more concise and readable way to create routers.
+ *
+ * The `IArvoEventRouter` parameter should include:
+ * - `source`: (optional) A string identifying the source of the router. Used to match the `event.to` field.
+ * - `handlers`: An array of ArvoEventHandler instances that the router will use to process events.
+ * - `executionunits`: A number representing the default execution cost of the function.
+ *
+ * The created ArvoEventRouter will:
+ * - Validate the source string if provided.
+ * - Check for and prevent duplicate handlers for the same event type.
+ * - Set up internal data structures for efficient event routing.
+ *
+ * @see {@link ArvoEventRouter} for more details on the router's functionality.
+ * @see {@link IArvoEventRouter} for the structure of the configuration object.
+ */
+export declare const createArvoEventRouter: (param: IArvoEventRouter) => ArvoEventRouter;

package/dist/ArvoEventRouter/helpers.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createArvoEventRouter = void 0;
+var _1 = require(".");
+/**
+ * Creates and returns a new instance of ArvoEventRouter.
+ *
+ * @param {IArvoEventRouter} param - Configuration object for the ArvoEventRouter.
+ * @returns {ArvoEventRouter} A new instance of ArvoEventRouter.
+ *
+ * @throws {Error} If there are duplicate handlers for the same event type.
+ * @throws {Error} If the provided source is an invalid string.
+ *
+ * @example
+ * const router = createArvoEventRouter({
+ *   source: 'my-router',
+ *   handlers: [handler1, handler2],
+ *   executionunits: 10
+ * });
+ *
+ * @remarks
+ * This function is a factory method that simplifies the creation of an ArvoEventRouter instance.
+ * It encapsulates the instantiation process, allowing for a more concise and readable way to create routers.
+ *
+ * The `IArvoEventRouter` parameter should include:
+ * - `source`: (optional) A string identifying the source of the router. Used to match the `event.to` field.
+ * - `handlers`: An array of ArvoEventHandler instances that the router will use to process events.
+ * - `executionunits`: A number representing the default execution cost of the function.
+ *
+ * The created ArvoEventRouter will:
+ * - Validate the source string if provided.
+ * - Check for and prevent duplicate handlers for the same event type.
+ * - Set up internal data structures for efficient event routing.
+ *
+ * @see {@link ArvoEventRouter} for more details on the router's functionality.
+ * @see {@link IArvoEventRouter} for the structure of the configuration object.
+ */
+var createArvoEventRouter = function (param) {
+    return new _1.ArvoEventRouter(param);
+};
+exports.createArvoEventRouter = createArvoEventRouter;

package/dist/ArvoEventRouter/index.d.ts

@@ -0,0 +1,85 @@
+import { ArvoContract, ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
+import ArvoEventHandler from '../ArvoEventHandler';
+import { IArvoEventRouter } from './types';
+import { SpanKind } from '@opentelemetry/api';
+/**
+ * ArvoEventRouter class handles routing of ArvoEvents to appropriate event handlers.
+ */
+export declare class ArvoEventRouter {
+    /**
+     * The source name of the router. The router attempts
+     * to match the `event.to` field with this value
+     * @property {string} [source]
+     */
+    readonly source: string | null;
+    /**
+     * A list of all available event handlers to be used by the router.
+     * @property {ArvoEventHandler<ArvoContract>[]} handlers
+     */
+    readonly handlers: ArvoEventHandler<ArvoContract>[];
+    /**
+     * The default execution cost of the function.
+     * This can represent a dollar value or some other number with a rate card.
+     */
+    readonly executionunits: number;
+    /**
+     * A map of all the available event handlers
+     */
+    readonly handlersMap: Record<string, ArvoEventHandler<ArvoContract>>;
+    readonly openInferenceSpanKind: OpenInferenceSpanKind;
+    readonly arvoExecutionSpanKind: ArvoExecutionSpanKind;
+    readonly openTelemetrySpanKind: SpanKind;
+    /**
+     * Creates an instance of ArvoEventRouter.
+     * @param {IArvoEventRouter} param - The parameters for initializing the router
+     * @throws {Error} If there are duplicate handlers for the same event type or the
+     *                 source in an invalid string
+     */
+    constructor(param: IArvoEventRouter);
+    /**
+     * Executes the routing process for a given ArvoEvent.
+     *
+     * @param event - The ArvoEvent to be processed and routed.
+     * @returns A Promise that resolves to an array of ArvoEvents.
+     *
+     * @remarks
+     * This function performs the following steps:
+     * 1. Initializes OpenTelemetry span for tracing and monitoring.
+     * 2. Validates the event's destination ('to' field) against the router's source.
+     * 3. Finds the appropriate handler for the event based on its type.
+     * 4. Executes the handler and processes the results.
+     * 5. Handles any errors that occur during the process.
+     *
+     * @throws Error event if the event's 'to' field doesn't match the router's source.
+     * @throws Error event if no valid handler is found for the event type.
+     *
+     * **Telemetry**
+     *
+     * - Creates an OpenTelemetry span for the entire execution process.
+     * - Sets span attributes for OpenInference and ArvoExecution.
+     * - Propagates trace context from the input event if available.
+     * - Records any errors in the span and sets the span status accordingly.
+     * - Adds event attributes to the span for both input and output events.
+     *
+     * **Routing**
+     *
+     * The routing process involves:
+     * 1. Matching the event's 'to' field with the router's source (if specified).
+     * 2. Finding a handler that accepts the event's type.
+     * 3. Executing the matched handler with the event.
+     * 4. Processing the handler's results and creating new events.
+     *
+     * **Error Handling**
+     *
+     * If an error occurs during execution:
+     * 1. The error is recorded in the OpenTelemetry span.
+     * 2. A new error event is created and returned.
+     * 3. The error event is sent back to the original event's source.
+     *
+     * **Performance**
+     *
+     * - Execution units are tracked for both successful executions and errors.
+     * - The router's default execution units are used for error events.
+     */
+    execute(event: ArvoEvent): Promise<ArvoEvent[]>;
+}

package/dist/ArvoEventRouter/index.js

@@ -0,0 +1,242 @@
+"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;
+    return g = { next: verb(0), "throw": verb(1), "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.ArvoEventRouter = void 0;
+var arvo_core_1 = require("arvo-core");
+var utils_1 = require("../utils");
+var api_1 = require("@opentelemetry/api");
+var OpenTelemetry_1 = require("../OpenTelemetry");
+var utils_2 = require("./utils");
+var schema_1 = require("arvo-core/dist/ArvoEvent/schema");
+/**
+ * ArvoEventRouter class handles routing of ArvoEvents to appropriate event handlers.
+ */
+var ArvoEventRouter = /** @class */ (function () {
+    /**
+     * Creates an instance of ArvoEventRouter.
+     * @param {IArvoEventRouter} param - The parameters for initializing the router
+     * @throws {Error} If there are duplicate handlers for the same event type or the
+     *                 source in an invalid string
+     */
+    function ArvoEventRouter(param) {
+        /**
+         * A map of all the available event handlers
+         */
+        this.handlersMap = {};
+        this.openInferenceSpanKind = arvo_core_1.OpenInferenceSpanKind.CHAIN;
+        this.arvoExecutionSpanKind = arvo_core_1.ArvoExecutionSpanKind.EVENT_HANDLER;
+        this.openTelemetrySpanKind = api_1.SpanKind.INTERNAL;
+        this.handlers = param.handlers;
+        if (param.source) {
+            var error = schema_1.CloudEventContextSchema.pick({
+                source: true,
+            }).safeParse({ source: param.source }).error;
+            if (error) {
+                throw new Error("The provided 'source' is not a valid string. Error: ".concat(error.message));
+            }
+        }
+        this.source = (0, utils_1.isNullOrUndefined)(param.source) ? null : param.source;
+        this.executionunits = param.executionunits;
+        for (var _i = 0, _a = this.handlers; _i < _a.length; _i++) {
+            var handler = _a[_i];
+            if (this.handlersMap[handler.contract.accepts.type]) {
+                var existingHandler = this.handlersMap[handler.contract.accepts.type];
+                throw new Error((0, arvo_core_1.cleanString)("\n          Duplicate handlers for event.type=".concat(handler.contract.accepts.type, " found. There are same 'contract.accept.types' in \n          contracts 'uri=").concat(existingHandler.contract.uri, "' and 'uri=").concat(handler.contract.uri, "'. This router does not support handlers\n          with the same 'contract.accept.type'.\n        ")));
+            }
+            this.handlersMap[handler.contract.accepts.type] = handler;
+        }
+        Object.freeze(this.handlers);
+        Object.freeze(this.handlersMap);
+    }
+    /**
+     * Executes the routing process for a given ArvoEvent.
+     *
+     * @param event - The ArvoEvent to be processed and routed.
+     * @returns A Promise that resolves to an array of ArvoEvents.
+     *
+     * @remarks
+     * This function performs the following steps:
+     * 1. Initializes OpenTelemetry span for tracing and monitoring.
+     * 2. Validates the event's destination ('to' field) against the router's source.
+     * 3. Finds the appropriate handler for the event based on its type.
+     * 4. Executes the handler and processes the results.
+     * 5. Handles any errors that occur during the process.
+     *
+     * @throws Error event if the event's 'to' field doesn't match the router's source.
+     * @throws Error event if no valid handler is found for the event type.
+     *
+     * **Telemetry**
+     *
+     * - Creates an OpenTelemetry span for the entire execution process.
+     * - Sets span attributes for OpenInference and ArvoExecution.
+     * - Propagates trace context from the input event if available.
+     * - Records any errors in the span and sets the span status accordingly.
+     * - Adds event attributes to the span for both input and output events.
+     *
+     * **Routing**
+     *
+     * The routing process involves:
+     * 1. Matching the event's 'to' field with the router's source (if specified).
+     * 2. Finding a handler that accepts the event's type.
+     * 3. Executing the matched handler with the event.
+     * 4. Processing the handler's results and creating new events.
+     *
+     * **Error Handling**
+     *
+     * If an error occurs during execution:
+     * 1. The error is recorded in the OpenTelemetry span.
+     * 2. A new error event is created and returned.
+     * 3. The error event is sent back to the original event's source.
+     *
+     * **Performance**
+     *
+     * - Execution units are tracked for both successful executions and errors.
+     * - The router's default execution units are used for error events.
+     */
+    ArvoEventRouter.prototype.execute = function (event) {
+        return __awaiter(this, void 0, void 0, function () {
+            var spanName, spanOptions, span, inheritedContext;
+            var _a;
+            var _this = this;
+            var _b;
+            return __generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        spanName = "ArvoEventRouter.source<".concat((_b = this.source) !== null && _b !== void 0 ? _b : 'arvo.event.router', ">.execute<").concat(event.type, ">");
+                        spanOptions = {
+                            kind: this.openTelemetrySpanKind,
+                            attributes: (_a = {},
+                                _a[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = this.openInferenceSpanKind,
+                                _a[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = this.arvoExecutionSpanKind,
+                                _a),
+                        };
+                        if (event.traceparent) {
+                            inheritedContext = (0, OpenTelemetry_1.extractContext)(event.traceparent, event.tracestate);
+                            span = OpenTelemetry_1.ArvoEventHandlerTracer.startSpan(spanName, spanOptions, inheritedContext);
+                        }
+                        else {
+                            span = OpenTelemetry_1.ArvoEventHandlerTracer.startSpan(spanName, spanOptions);
+                        }
+                        return [4 /*yield*/, api_1.context.with(api_1.trace.setSpan(api_1.context.active(), span), function () { return __awaiter(_this, void 0, void 0, function () {
+                                var otelSpanHeaders, newEvent, results, error_1, result;
+                                var _this = this;
+                                var _a, _b;
+                                return __generator(this, function (_c) {
+                                    switch (_c.label) {
+                                        case 0:
+                                            otelSpanHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
+                                            newEvent = (0, utils_2.deleteOtelHeaders)(event);
+                                            _c.label = 1;
+                                        case 1:
+                                            _c.trys.push([1, 3, 4, 5]);
+                                            span.setStatus({ code: api_1.SpanStatusCode.OK });
+                                            if (!(0, utils_1.isNullOrUndefined)(this.source) && newEvent.to !== this.source) {
+                                                throw new Error((0, arvo_core_1.cleanString)("\n            Invalid event. The 'event.to' is ".concat(newEvent.to, " while this handler \n            listens to only 'event.to' equal to ").concat(this.source, ". If this is a mistake,\n            please update the 'source' field of the handler\n          ")));
+                                            }
+                                            if (!this.handlersMap[newEvent.type]) {
+                                                throw new Error((0, arvo_core_1.cleanString)("\n            Invalid event (type=".concat(newEvent.type, "). No valid handler \n            <handler[*].contract.accepts.type> found in the router.\n          ")));
+                                            }
+                                            return [4 /*yield*/, this.handlersMap[newEvent.type].execute(newEvent)];
+                                        case 2:
+                                            results = _c.sent();
+                                            return [2 /*return*/, results.map(function (event) {
+                                                    var _a;
+                                                    return new arvo_core_1.ArvoEvent({
+                                                        id: event.id,
+                                                        time: event.time,
+                                                        source: (0, utils_1.getValueOrDefault)(_this.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: ((_a = event.executionunits) !== null && _a !== void 0 ? _a : 0) + _this.executionunits,
+                                                        traceparent: otelSpanHeaders.traceparent,
+                                                        tracestate: otelSpanHeaders.tracestate,
+                                                    }, event.data, event.cloudevent.extensions);
+                                                })];
+                                        case 3:
+                                            error_1 = _c.sent();
+                                            (0, arvo_core_1.exceptionToSpan)(error_1);
+                                            span.setStatus({
+                                                code: api_1.SpanStatusCode.ERROR,
+                                                message: error_1.message,
+                                            });
+                                            Object.entries(event.otelAttributes).forEach(function (_a) {
+                                                var key = _a[0], value = _a[1];
+                                                return span.setAttribute("to_process.0.".concat(key), value);
+                                            });
+                                            result = (0, arvo_core_1.createArvoEvent)({
+                                                type: "sys.arvo.event.router.error",
+                                                source: this.source || "arvo.event.router",
+                                                subject: event.subject,
+                                                // The system error must always got back to
+                                                // the source
+                                                to: event.source,
+                                                executionunits: this.executionunits,
+                                                traceparent: (_a = otelSpanHeaders.traceparent) !== null && _a !== void 0 ? _a : undefined,
+                                                tracestate: (_b = otelSpanHeaders.tracestate) !== null && _b !== void 0 ? _b : undefined,
+                                                data: {
+                                                    errorName: error_1.name,
+                                                    errorMessage: error_1.message,
+                                                    errorStack: error_1.stack || null,
+                                                },
+                                            });
+                                            Object.entries(result.otelAttributes).forEach(function (_a) {
+                                                var key = _a[0], value = _a[1];
+                                                return span.setAttribute("to_emit.0.".concat(key), value);
+                                            });
+                                            return [2 /*return*/, [result]];
+                                        case 4:
+                                            span.end();
+                                            return [7 /*endfinally*/];
+                                        case 5: return [2 /*return*/];
+                                    }
+                                });
+                            }); })];
+                    case 1: return [2 /*return*/, _c.sent()];
+                }
+            });
+        });
+    };
+    return ArvoEventRouter;
+}());
+exports.ArvoEventRouter = ArvoEventRouter;

package/dist/ArvoEventRouter/types.d.ts

@@ -0,0 +1,56 @@
+import { ArvoContract, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
+import ArvoEventHandler from '../ArvoEventHandler';
+import { SpanKind } from '@opentelemetry/api';
+/**
+ * Interface for defining an Arvo Event Router.
+ *
+ * @interface IArvoEventRouter
+ */
+export interface IArvoEventRouter {
+    /**
+     * Defines the source name of the router.
+     *
+     * @property {string} [source]
+     *
+     * @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.
+     *
+     * If this field is not defined:
+     * - The router will listen to all events.
+     * - If no appropriate handler is found for an event, a system error event will be emitted.
+     * - The `source` field of emitted events will be set according to the configuration
+     *   in the relevant `ArvoEventHandler`.
+     */
+    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.
+     *
+     * @property {ArvoEventHandler<ArvoContract>[]} handlers
+     *
+     * @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, any>>[];
+    /**
+     * The OpenTelemetry span kind attributes for the handler
+     * executor.
+     * @param [openInference] - The OpenInference span kind. Default is "CHAIN"
+     * @param [arvoExecution] - The ArvoExecution span kind. Default is "EVENT_HANDLER"
+     * @param [openTelemetry] - The OpenTelemetry span kind. Default is "INTERNAL"
+     */
+    spanKind?: {
+        openInference?: OpenInferenceSpanKind;
+        arvoExecution?: ArvoExecutionSpanKind;
+        openTelemetry?: SpanKind;
+    };
+}

package/dist/ArvoEventRouter/types.js

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

package/dist/ArvoEventRouter/utils.d.ts

@@ -0,0 +1,10 @@
+import { ArvoEvent } from 'arvo-core';
+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;
+} & {
+    traceparent: string | null;
+    tracestate: string | null;
+}, string>;

package/dist/ArvoEventRouter/utils.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteOtelHeaders = void 0;
+var arvo_core_1 = require("arvo-core");
+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,
+    }, event.data, event.cloudevent.extensions);
+};
+exports.deleteOtelHeaders = deleteOtelHeaders;

package/dist/MultiArvoEventHandler/index.d.ts

@@ -1,6 +1,6 @@
 import { SpanKind } from '@opentelemetry/api';
-import { ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from "arvo-core";
-import { IMultiArvoEventHandler } from "./types";
+import { ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
+import { IMultiArvoEventHandler } from './types';
 /**
  * Represents a Multi ArvoEvent handler that can process multiple event types.
  *
@@ -17,9 +17,13 @@ export default class MultiArvoEventHandler {
      * The source identifier for events produced by this handler
      *
      * @remarks
+     * The handler listens to the events with field `event.to` equal
+     * to the this `source` value. If the event does not confirm to
+     * this, a system error event is returned
+     *
      * For all the events which are emitted by the handler, this is
      * the source field value of them all.
-    */
+     */
     readonly source: string;
     readonly openInferenceSpanKind: OpenInferenceSpanKind;
     readonly arvoExecutionSpanKind: ArvoExecutionSpanKind;
@@ -41,9 +45,10 @@ export default class MultiArvoEventHandler {
      * @remarks
      * This method performs the following steps:
      * 1. Creates an OpenTelemetry span for the execution.
-     * 2. Executes the handler function.
-     * 3. Creates and returns the result event(s).
-     * 4. Handles any errors and creates an error event if necessary.
+     * 2. Validates that the event's 'to' field matches the handler's 'source'.
+     * 3. Executes the handler function.
+     * 4. Creates and returns the result event(s).
+     * 5. Handles any errors and creates an error event if necessary.
      *
      * All telemetry data is properly set and propagated throughout the execution.
      *
@@ -57,7 +62,8 @@ export default class MultiArvoEventHandler {
      * const resultEvents = await handler.execute(inputEvent);
      * ```
      *
-     * @throws All errors thrown during the execution are returned as a system error event
+     * @throws {Error} Throws an error if the event's 'to' field doesn't match the handler's 'source'.
+     * All other errors thrown during the execution are returned as a system error event.
      *
      * **Routing**
      *
@@ -76,6 +82,12 @@ export default class MultiArvoEventHandler {
      * - Sets span attributes for input and output events
      * - Propagates trace context to output events
      * - Handles error cases and sets appropriate span status
+     *
+     * **Event Validation**
+     *
+     * - Checks if the event's 'to' field matches the handler's 'source'.
+     * - If they don't match, an error is thrown with a descriptive message.
+     * - This ensures that the handler only processes events intended for it.
      */
     execute(event: ArvoEvent): Promise<ArvoEvent[]>;
     /**

package/dist/MultiArvoEventHandler/index.js

@@ -87,15 +87,18 @@ var MultiArvoEventHandler = /** @class */ (function () {
         this.executionunits = param.executionunits;
         this._handler = param.handler;
         var error = schema_1.CloudEventContextSchema.pick({
-            source: true
+            source: true,
         }).safeParse({ source: param.source }).error;
         if (error) {
             throw new Error("The provided 'source' is not a valid string. Error: ".concat(error.message));
         }
         this.source = param.source;
-        this.arvoExecutionSpanKind = ((_a = param.spanKind) === null || _a === void 0 ? void 0 : _a.arvoExecution) || this.arvoExecutionSpanKind;
-        this.openInferenceSpanKind = ((_b = param.spanKind) === null || _b === void 0 ? void 0 : _b.openInference) || this.openInferenceSpanKind;
-        this.openTelemetrySpanKind = ((_c = param.spanKind) === null || _c === void 0 ? void 0 : _c.openTelemetry) || this.openTelemetrySpanKind;
+        this.arvoExecutionSpanKind =
+            ((_a = param.spanKind) === null || _a === void 0 ? void 0 : _a.arvoExecution) || this.arvoExecutionSpanKind;
+        this.openInferenceSpanKind =
+            ((_b = param.spanKind) === null || _b === void 0 ? void 0 : _b.openInference) || this.openInferenceSpanKind;
+        this.openTelemetrySpanKind =
+            ((_c = param.spanKind) === null || _c === void 0 ? void 0 : _c.openTelemetry) || this.openTelemetrySpanKind;
     }
     /**
      * Executes the event handler for a given event.
@@ -106,9 +109,10 @@ var MultiArvoEventHandler = /** @class */ (function () {
      * @remarks
      * This method performs the following steps:
      * 1. Creates an OpenTelemetry span for the execution.
-     * 2. Executes the handler function.
-     * 3. Creates and returns the result event(s).
-     * 4. Handles any errors and creates an error event if necessary.
+     * 2. Validates that the event's 'to' field matches the handler's 'source'.
+     * 3. Executes the handler function.
+     * 4. Creates and returns the result event(s).
+     * 5. Handles any errors and creates an error event if necessary.
      *
      * All telemetry data is properly set and propagated throughout the execution.
      *
@@ -122,7 +126,8 @@ var MultiArvoEventHandler = /** @class */ (function () {
      * const resultEvents = await handler.execute(inputEvent);
      * ```
      *
-     * @throws All errors thrown during the execution are returned as a system error event
+     * @throws {Error} Throws an error if the event's 'to' field doesn't match the handler's 'source'.
+     * All other errors thrown during the execution are returned as a system error event.
      *
      * **Routing**
      *
@@ -141,6 +146,12 @@ var MultiArvoEventHandler = /** @class */ (function () {
      * - Sets span attributes for input and output events
      * - Propagates trace context to output events
      * - Handles error cases and sets appropriate span status
+     *
+     * **Event Validation**
+     *
+     * - Checks if the event's 'to' field matches the handler's 'source'.
+     * - If they don't match, an error is thrown with a descriptive message.
+     * - This ensures that the handler only processes events intended for it.
      */
     MultiArvoEventHandler.prototype.execute = function (event) {
         return __awaiter(this, void 0, void 0, function () {
@@ -156,7 +167,7 @@ var MultiArvoEventHandler = /** @class */ (function () {
                             attributes: (_a = {},
                                 _a[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = this.openInferenceSpanKind,
                                 _a[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = this.arvoExecutionSpanKind,
-                                _a)
+                                _a),
                         };
                         if (event.traceparent) {
                             inheritedContext = (0, OpenTelemetry_1.extractContext)(event.traceparent, event.tracestate);
@@ -180,7 +191,13 @@ var MultiArvoEventHandler = /** @class */ (function () {
                                                 var key = _a[0], value = _a[1];
                                                 return span.setAttribute("to_process.0.".concat(key), value);
                                             });
-                                            return [4 /*yield*/, this._handler({ event: event, source: this.source })];
+                                            if (event.to !== this.source) {
+                                                throw new Error((0, arvo_core_1.cleanString)("\n            Invalid event. The 'event.to' is ".concat(event.to, " while this handler \n            listens to only 'event.to' equal to ").concat(this.source, ". If this is a mistake,\n            please update the 'source' field of the handler\n          ")));
+                                            }
+                                            return [4 /*yield*/, this._handler({
+                                                    event: event,
+                                                    source: this.source,
+                                                })];
                                         case 2:
                                             _handlerOutput = _a.sent();
                                             if (!_handlerOutput)
@@ -196,9 +213,9 @@ var MultiArvoEventHandler = /** @class */ (function () {
                                                     var __extensions = output.__extensions, handlerResult = __rest(output, ["__extensions"]);
                                                     var result = (0, arvo_core_1.createArvoEvent)(__assign(__assign({}, handlerResult), { traceparent: otelSpanHeaders.traceparent || undefined, tracestate: otelSpanHeaders.tracestate || undefined, source: _this.source, subject: event.subject, 
                                                         // The user should be able to override the `to` field
-                                                        // If that is not present then the 'redirectto' field 
+                                                        // If that is not present then the 'redirectto' field
                                                         // is referred to. Then, after all else, 'source' field
-                                                        // is used as a form of reply. 
+                                                        // is used as a form of reply.
                                                         to: (0, utils_1.coalesceOrDefault)([handlerResult.to, event.redirectto], event.source), executionunits: (0, utils_1.coalesce)(handlerResult.executionunits, _this.executionunits) }), __extensions);
                                                     Object.entries(result.otelAttributes).forEach(function (_a) {
                                                         var key = _a[0], value = _a[1];
@@ -217,7 +234,7 @@ var MultiArvoEventHandler = /** @class */ (function () {
                                                 type: "sys.".concat(this.source, ".error"),
                                                 source: this.source,
                                                 subject: event.subject,
-                                                // The system error must always got back to 
+                                                // The system error must always got back to
                                                 // the source
                                                 to: event.source,
                                                 executionunits: this.executionunits,
@@ -226,8 +243,8 @@ var MultiArvoEventHandler = /** @class */ (function () {
                                                 data: {
                                                     errorName: error_1.name,
                                                     errorMessage: error_1.message,
-                                                    errorStack: error_1.stack || null
-                                                }
+                                                    errorStack: error_1.stack || null,
+                                                },
                                             });
                                             Object.entries(result.otelAttributes).forEach(function (_a) {
                                                 var key = _a[0], value = _a[1];
@@ -265,7 +282,7 @@ var MultiArvoEventHandler = /** @class */ (function () {
         get: function () {
             return {
                 type: "sys.".concat(this.source, ".error"),
-                schema: arvo_core_1.ArvoErrorSchema
+                schema: arvo_core_1.ArvoErrorSchema,
             };
         },
         enumerable: false,

package/dist/MultiArvoEventHandler/types.d.ts

@@ -1,5 +1,5 @@
-import { SpanKind } from "@opentelemetry/api";
-import { ArvoEvent, ArvoExecutionSpanKind, CreateArvoEvent, OpenInferenceSpanKind } from "arvo-core";
+import { SpanKind } from '@opentelemetry/api';
+import { ArvoEvent, ArvoExecutionSpanKind, CreateArvoEvent, OpenInferenceSpanKind } from 'arvo-core';
 /**
  * Represents the input for a Multi ArvoEvent handler function.
  */
@@ -35,11 +35,15 @@ export type MultiArvoEventHandlerFunction = (param: MultiArvoEventHandlerFunctio
  */
 export interface IMultiArvoEventHandler {
     /**
-     * The source definition of the MultiArvoEventHanlder.
+     * The source identifier for events produced by this handler
      *
      * @remarks
-     * For all the events which are emitted by the handler, this will be the source
-     * field value of them all.
+     * The handler listens to the events with field `event.to` equal
+     * to the this `source` value. If the event does not confirm to
+     * this, a system error event is returned
+     *
+     * For all the events which are emitted by the handler, this is
+     * the source field value of them all.
      */
     source: string;
     /**

package/dist/index.d.ts

@@ -6,4 +6,7 @@ import MultiArvoEventHandler from './MultiArvoEventHandler';
 import { MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler } from './MultiArvoEventHandler/types';
 import { createMultiArvoEventHandler } from './MultiArvoEventHandler/helpers';
 import { isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault } from './utils';
-export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, };
+import { IArvoEventRouter } from './ArvoEventRouter/types';
+import { ArvoEventRouter } from './ArvoEventRouter';
+import { createArvoEventRouter } from './ArvoEventRouter/helpers';
+export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, IArvoEventRouter, ArvoEventRouter, createArvoEventRouter, };

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
+exports.createArvoEventRouter = exports.ArvoEventRouter = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
 var ArvoEventHandler_1 = __importDefault(require("./ArvoEventHandler"));
 exports.ArvoEventHandler = ArvoEventHandler_1.default;
 var helpers_1 = require("./ArvoEventHandler/helpers");
@@ -17,3 +17,7 @@ Object.defineProperty(exports, "isNullOrUndefined", { enumerable: true, get: fun
 Object.defineProperty(exports, "getValueOrDefault", { enumerable: true, get: function () { return utils_1.getValueOrDefault; } });
 Object.defineProperty(exports, "coalesce", { enumerable: true, get: function () { return utils_1.coalesce; } });
 Object.defineProperty(exports, "coalesceOrDefault", { enumerable: true, get: function () { return utils_1.coalesceOrDefault; } });
+var ArvoEventRouter_1 = require("./ArvoEventRouter");
+Object.defineProperty(exports, "ArvoEventRouter", { enumerable: true, get: function () { return ArvoEventRouter_1.ArvoEventRouter; } });
+var helpers_3 = require("./ArvoEventRouter/helpers");
+Object.defineProperty(exports, "createArvoEventRouter", { enumerable: true, get: function () { return helpers_3.createArvoEventRouter; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-event-handler",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "This package contains class and function for event handlers in an Arvo Event Driven system",
   "main": "dist/index.js",
   "scripts": {