arvo-event-handler 1.0.9 → 1.1.0

package/CHANGELOG.md

@@ -19,3 +19,7 @@
 ## [1.0.2] - 2024-09-10
 
 - Added ArvoEventRouter as a mechanism to group ArvoEventHandlers
+## [1.1.0] - 2024-09-30
+
+- Added Abstract handler class and bound all handlers to it
+

package/dist/AbstractArvoEventHandler/index.d.ts

@@ -0,0 +1,62 @@
+import { ArvoContractRecord, ArvoEvent } from "arvo-core";
+/**
+ * Abstract base class for Arvo event handlers.
+ *
+ * @abstract
+ * @description
+ * This class defines the basic structure for all Arvo event handlers.
+ * It provides an abstract method for executing events, which must be
+ * implemented by any concrete subclass.
+ * ```
+ */
+export default abstract class AbstractArvoEventHandler {
+    /**
+     * Executes the event handling logic for a given Arvo event.
+     *
+     * @abstract
+     * @param {ArvoEvent} event - The Arvo event to be processed.
+     * @returns {Promise<ArvoEvent[]>} A promise that resolves to an array of resulting Arvo events.
+     *
+     * @description
+     * This method should contain the core logic for processing an Arvo event.
+     * Implementations should handle the event according to their specific requirements
+     * and return any resulting events.
+     *
+     * @throws {Error} Implementations may throw errors for invalid inputs or processing failures.
+     *
+     * @remarks
+     * - The method is asynchronous to allow for potentially time-consuming operations.
+     * - The returned array may be empty if no new events are generated as a result of processing.
+     * - Implementations should ensure proper error handling and event validation.
+     */
+    abstract execute(event: ArvoEvent): Promise<ArvoEvent[]>;
+    /**
+     * Provides the schema for system error events.
+     *
+     * @abstract
+     * @returns {ArvoContractRecord} An object containing the error event type and schema.
+     *
+     * @description
+     * This getter should define the structure for system error events that may be emitted
+     * when an unexpected error occurs during event handling.
+     *
+     * @remarks
+     * - The returned ArvoContractRecord typically includes:
+     *   - `type`: A string representing the error event type.
+     *   - `schema`: The schema definition for the error event.
+     * - Implementations should ensure that the error schema is consistent with the
+     *   overall system's error handling strategy.
+     * - The error event type often follows a pattern like 'sys.[eventType].error'.
+     *
+     * @example
+     * ```typescript
+     * public get systemErrorSchema(): ArvoContractRecord {
+     *   return {
+     *     type: 'sys.myEvent.error',
+     *     schema: MyCustomErrorSchema
+     *   };
+     * }
+     * ```
+     */
+    abstract get systemErrorSchema(): ArvoContractRecord;
+}

package/dist/AbstractArvoEventHandler/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Abstract base class for Arvo event handlers.
+ *
+ * @abstract
+ * @description
+ * This class defines the basic structure for all Arvo event handlers.
+ * It provides an abstract method for executing events, which must be
+ * implemented by any concrete subclass.
+ * ```
+ */
+var AbstractArvoEventHandler = /** @class */ (function () {
+    function AbstractArvoEventHandler() {
+    }
+    return AbstractArvoEventHandler;
+}());
+exports.default = AbstractArvoEventHandler;

package/dist/ArvoEventHandler/index.d.ts

@@ -1,6 +1,7 @@
 import { ArvoContract, ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind, ResolveArvoContractRecord } from 'arvo-core';
 import { IArvoEventHandler } from './types';
 import { SpanKind } from '@opentelemetry/api';
+import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
 /**
  * Represents an event handler for Arvo contracts.
  *
@@ -11,7 +12,7 @@ import { SpanKind } from '@opentelemetry/api';
  * for executing event handlers, managing telemetry, and ensuring proper contract validation.
  * It's designed to be flexible and reusable across different Arvo contract implementations.
  */
-export default class ArvoEventHandler<TContract extends ArvoContract> {
+export default class ArvoEventHandler<TContract extends ArvoContract> extends AbstractArvoEventHandler {
     /** The contract of the handler to which it is bound */
     readonly contract: TContract;
     /** The default execution cost associated with this handler */
@@ -103,20 +104,17 @@ export default class ArvoEventHandler<TContract extends ArvoContract> {
      * // If the contract's accepted event type is 'user.created'
      * // The system error event type would be 'sys.user.created.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, {
-            errorMessage: string;
-            errorName: string;
-            errorStack: string | null;
-        }, {
-            errorMessage: string;
-            errorName: string;
-            errorStack: string | null;
-        }>;
-    };
+    get systemErrorSchema(): import("arvo-core").ArvoContractRecord<`sys.${string}.error`, import("zod").ZodObject<{
+        errorName: import("zod").ZodString;
+        errorMessage: import("zod").ZodString;
+        errorStack: import("zod").ZodNullable<import("zod").ZodString>;
+    }, "strip", import("zod").ZodTypeAny, {
+        errorMessage: string;
+        errorName: string;
+        errorStack: string | null;
+    }, {
+        errorMessage: string;
+        errorName: string;
+        errorStack: string | null;
+    }>>;
 }

package/dist/ArvoEventHandler/index.js

@@ -1,4 +1,19 @@
 "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 __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) {
@@ -35,12 +50,16 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         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 });
 var arvo_core_1 = require("arvo-core");
 var schema_1 = require("arvo-core/dist/ArvoEvent/schema");
 var api_1 = require("@opentelemetry/api");
 var utils_1 = require("../utils");
 var utils_2 = require("../OpenTelemetry/utils");
+var AbstractArvoEventHandler_1 = __importDefault(require("../AbstractArvoEventHandler"));
 /**
  * Represents an event handler for Arvo contracts.
  *
@@ -51,7 +70,8 @@ var utils_2 = require("../OpenTelemetry/utils");
  * for executing event handlers, managing telemetry, and ensuring proper contract validation.
  * It's designed to be flexible and reusable across different Arvo contract implementations.
  */
-var ArvoEventHandler = /** @class */ (function () {
+var ArvoEventHandler = /** @class */ (function (_super) {
+    __extends(ArvoEventHandler, _super);
     /**
      * Creates an instance of ArvoEventHandler.
      *
@@ -65,12 +85,13 @@ var ArvoEventHandler = /** @class */ (function () {
      */
     function ArvoEventHandler(param) {
         var _a, _b, _c, _d, _e, _f, _g;
-        this.openInferenceSpanKind = arvo_core_1.OpenInferenceSpanKind.CHAIN;
-        this.arvoExecutionSpanKind = arvo_core_1.ArvoExecutionSpanKind.EVENT_HANDLER;
-        this.openTelemetrySpanKind = api_1.SpanKind.INTERNAL;
-        this.contract = param.contract;
-        this.executionunits = param.executionunits;
-        this._handler = param.handler;
+        var _this = _super.call(this) || this;
+        _this.openInferenceSpanKind = arvo_core_1.OpenInferenceSpanKind.CHAIN;
+        _this.arvoExecutionSpanKind = arvo_core_1.ArvoExecutionSpanKind.EVENT_HANDLER;
+        _this.openTelemetrySpanKind = api_1.SpanKind.INTERNAL;
+        _this.contract = param.contract;
+        _this.executionunits = param.executionunits;
+        _this._handler = param.handler;
         if (param.source) {
             var error = schema_1.CloudEventContextSchema.pick({
                 source: true,
@@ -79,13 +100,14 @@ var ArvoEventHandler = /** @class */ (function () {
                 throw new Error("The provided 'source' is not a valid string. Error: ".concat(error.message));
             }
         }
-        this.source = (_a = param.source) !== null && _a !== void 0 ? _a : this.contract.accepts.type;
-        this.arvoExecutionSpanKind =
-            (_c = (_b = param.spanKind) === null || _b === void 0 ? void 0 : _b.arvoExecution) !== null && _c !== void 0 ? _c : this.arvoExecutionSpanKind;
-        this.openInferenceSpanKind =
-            (_e = (_d = param.spanKind) === null || _d === void 0 ? void 0 : _d.openInference) !== null && _e !== void 0 ? _e : this.openInferenceSpanKind;
-        this.openTelemetrySpanKind =
-            (_g = (_f = param.spanKind) === null || _f === void 0 ? void 0 : _f.openTelemetry) !== null && _g !== void 0 ? _g : this.openTelemetrySpanKind;
+        _this.source = (_a = param.source) !== null && _a !== void 0 ? _a : _this.contract.accepts.type;
+        _this.arvoExecutionSpanKind =
+            (_c = (_b = param.spanKind) === null || _b === void 0 ? void 0 : _b.arvoExecution) !== null && _c !== void 0 ? _c : _this.arvoExecutionSpanKind;
+        _this.openInferenceSpanKind =
+            (_e = (_d = param.spanKind) === null || _d === void 0 ? void 0 : _d.openInference) !== null && _e !== void 0 ? _e : _this.openInferenceSpanKind;
+        _this.openTelemetrySpanKind =
+            (_g = (_f = param.spanKind) === null || _f === void 0 ? void 0 : _f.openTelemetry) !== null && _g !== void 0 ? _g : _this.openTelemetrySpanKind;
+        return _this;
     }
     /**
      * Executes the event handler for a given event.
@@ -149,13 +171,14 @@ var ArvoEventHandler = /** @class */ (function () {
                         eventFactory = (0, arvo_core_1.createArvoEventFactory)(this.contract);
                         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, inputEventValidation, _handleOutput, outputs, error_1, result;
-                                return __generator(this, function (_a) {
-                                    switch (_a.label) {
+                                var _a, _b, _c;
+                                return __generator(this, function (_d) {
+                                    switch (_d.label) {
                                         case 0:
                                             otelSpanHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
-                                            _a.label = 1;
+                                            _d.label = 1;
                                         case 1:
-                                            _a.trys.push([1, 3, 4, 5]);
+                                            _d.trys.push([1, 3, 4, 5]);
                                             span.setStatus({ code: api_1.SpanStatusCode.OK });
                                             Object.entries(event.otelAttributes).forEach(function (_a) {
                                                 var key = _a[0], value = _a[1];
@@ -170,7 +193,7 @@ var ArvoEventHandler = /** @class */ (function () {
                                                     source: this.source,
                                                 })];
                                         case 2:
-                                            _handleOutput = _a.sent();
+                                            _handleOutput = _d.sent();
                                             if (!_handleOutput)
                                                 return [2 /*return*/, []];
                                             outputs = [];
@@ -188,7 +211,7 @@ var ArvoEventHandler = /** @class */ (function () {
                                                     return eventFactory.emits.apply(eventFactory, args);
                                                 })];
                                         case 3:
-                                            error_1 = _a.sent();
+                                            error_1 = _d.sent();
                                             (0, arvo_core_1.exceptionToSpan)(error_1);
                                             span.setStatus({
                                                 code: api_1.SpanStatusCode.ERROR,
@@ -202,8 +225,9 @@ var ArvoEventHandler = /** @class */ (function () {
                                                 to: event.source,
                                                 error: error_1,
                                                 executionunits: this.executionunits,
-                                                traceparent: otelSpanHeaders.traceparent || undefined,
-                                                tracestate: otelSpanHeaders.tracestate || undefined,
+                                                traceparent: (_a = otelSpanHeaders.traceparent) !== null && _a !== void 0 ? _a : undefined,
+                                                tracestate: (_b = otelSpanHeaders.tracestate) !== null && _b !== void 0 ? _b : undefined,
+                                                accesscontrol: (_c = event.accesscontrol) !== null && _c !== void 0 ? _c : undefined,
                                             }, {});
                                             Object.entries(result.otelAttributes).forEach(function (_a) {
                                                 var key = _a[0], value = _a[1];
@@ -239,14 +263,11 @@ var ArvoEventHandler = /** @class */ (function () {
          * // The system error event type would be 'sys.user.created.error'
          */
         get: function () {
-            return {
-                type: "sys.".concat(this.contract.accepts.type, ".error"),
-                schema: arvo_core_1.ArvoErrorSchema,
-            };
+            return this.contract.systemError;
         },
         enumerable: false,
         configurable: true
     });
     return ArvoEventHandler;
-}());
+}(AbstractArvoEventHandler_1.default));
 exports.default = ArvoEventHandler;

package/dist/ArvoEventRouter/index.d.ts

@@ -2,16 +2,24 @@ import { ArvoContract, ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind }
 import ArvoEventHandler from '../ArvoEventHandler';
 import { IArvoEventRouter } from './types';
 import { SpanKind } from '@opentelemetry/api';
+import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
 /**
  * ArvoEventRouter class handles routing of ArvoEvents to appropriate event handlers.
  */
-export declare class ArvoEventRouter {
+export declare class ArvoEventRouter extends AbstractArvoEventHandler {
+    private _handlerDefaultSource;
+    private readonly _source;
     /**
-     * The source name of the router. The router attempts
-     * to match the `event.to` field with this value
-     * @property {string} [source]
+     * The source name of the router.
+     * @returns {string} The router's source name.
+     *
+     * @remarks
+     * The router attempts to match the `event.to` field with this value.
+     * If the source is 'arvo.event.router', the `event.to` is not matched and any event is allowed.
+     * 'arvo.event.router' is the default source which is set automatically in case a source
+     * is not explicitly provided
      */
-    readonly source: string | null;
+    get source(): string;
     /**
      * A list of all available event handlers to be used by the router.
      * @property {ArvoEventHandler<ArvoContract>[]} handlers
@@ -82,4 +90,35 @@ export declare class ArvoEventRouter {
      * - The router's default execution units are used for error events.
      */
     execute(event: ArvoEvent): Promise<ArvoEvent[]>;
+    /**
+     * Provides the schema for system error events.
+     *
+     * @returns An object containing the error event type and schema.
+     *
+     * @remarks
+     * This getter defines the structure for system error events that may be emitted
+     * when an unexpected error occurs during event handling. The error event type
+     * is prefixed with 'sys.' followed by the handler's source and '.error'.
+     * The schema used for these error events is the standard ArvoErrorSchema.
+     *
+     * @example
+     * // If the handler's source is 'user.service'
+     * // The system error event type would be 'sys.user.service.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, {
+            errorMessage: string;
+            errorName: string;
+            errorStack: string | null;
+        }, {
+            errorMessage: string;
+            errorName: string;
+            errorStack: string | null;
+        }>;
+    };
 }

package/dist/ArvoEventRouter/index.js

@@ -1,4 +1,19 @@
 "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 __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) {
@@ -35,18 +50,22 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         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 arvo_core_1 = require("arvo-core");
 var utils_1 = require("../utils");
 var api_1 = require("@opentelemetry/api");
 var utils_2 = require("./utils");
-var schema_1 = require("arvo-core/dist/ArvoEvent/schema");
 var utils_3 = require("../OpenTelemetry/utils");
+var AbstractArvoEventHandler_1 = __importDefault(require("../AbstractArvoEventHandler"));
 /**
  * ArvoEventRouter class handles routing of ArvoEvents to appropriate event handlers.
  */
-var ArvoEventRouter = /** @class */ (function () {
+var ArvoEventRouter = /** @class */ (function (_super) {
+    __extends(ArvoEventRouter, _super);
     /**
      * Creates an instance of ArvoEventRouter.
      * @param {IArvoEventRouter} param - The parameters for initializing the router
@@ -54,35 +73,51 @@ var ArvoEventRouter = /** @class */ (function () {
      *                 source in an invalid string
      */
     function ArvoEventRouter(param) {
+        var _this = _super.call(this) || this;
+        _this._handlerDefaultSource = "arvo.event.router";
         /**
          * 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.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 && !(0, utils_1.isLowerAlphanumeric)(param.source)) {
+            throw new Error("Invalid 'source' = '".concat(param.source, "'. The 'source' must only contain alphanumeric characters e.g. test.router"));
         }
-        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++) {
+        _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];
+            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;
+            _this.handlersMap[handler.contract.accepts.type] = handler;
         }
-        Object.freeze(this.handlers);
-        Object.freeze(this.handlersMap);
+        Object.freeze(_this.handlers);
+        Object.freeze(_this.handlersMap);
+        return _this;
     }
+    Object.defineProperty(ArvoEventRouter.prototype, "source", {
+        /**
+         * The source name of the router.
+         * @returns {string} The router's source name.
+         *
+         * @remarks
+         * The router attempts to match the `event.to` field with this value.
+         * If the source is 'arvo.event.router', the `event.to` is not matched and any event is allowed.
+         * 'arvo.event.router' is the default source which is set automatically in case a source
+         * is not explicitly provided
+         */
+        get: function () {
+            var _a;
+            return (_a = this._source) !== null && _a !== void 0 ? _a : this._handlerDefaultSource;
+        },
+        enumerable: false,
+        configurable: true
+    });
     /**
      * Executes the routing process for a given ArvoEvent.
      *
@@ -136,7 +171,7 @@ var ArvoEventRouter = /** @class */ (function () {
             return __generator(this, function (_b) {
                 switch (_b.label) {
                     case 0:
-                        span = (0, utils_3.createSpanFromEvent)("ArvoEventRouter.source<".concat((_a = this.source) !== null && _a !== void 0 ? _a : 'arvo.event.router', ">.execute<").concat(event.type, ">"), event, {
+                        span = (0, utils_3.createSpanFromEvent)("ArvoEventRouter.source<".concat((_a = this._source) !== null && _a !== void 0 ? _a : 'arvo.event.router', ">.execute<").concat(event.type, ">"), event, {
                             kind: this.openTelemetrySpanKind,
                             openInference: this.openInferenceSpanKind,
                             arvoExecution: this.arvoExecutionSpanKind,
@@ -144,31 +179,30 @@ var ArvoEventRouter = /** @class */ (function () {
                         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;
                                 var _this = this;
-                                var _a;
-                                return __generator(this, function (_b) {
-                                    switch (_b.label) {
+                                return __generator(this, function (_a) {
+                                    switch (_a.label) {
                                         case 0:
                                             otelSpanHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
                                             newEvent = (0, utils_2.deleteOtelHeaders)(event);
-                                            _b.label = 1;
+                                            _a.label = 1;
                                         case 1:
-                                            _b.trys.push([1, 3, 4, 5]);
+                                            _a.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 (!(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 = _b.sent();
+                                            results = _a.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),
+                                                        source: event.source,
                                                         specversion: '1.0',
                                                         type: event.type,
                                                         subject: event.subject,
@@ -183,8 +217,8 @@ var ArvoEventRouter = /** @class */ (function () {
                                                     }, event.data, event.cloudevent.extensions);
                                                 })];
                                         case 3:
-                                            error_1 = _b.sent();
-                                            return [2 /*return*/, (0, utils_1.createHandlerErrorOutputEvent)(error_1, otelSpanHeaders, "sys.arvo.event.router.error", (_a = this.source) !== null && _a !== void 0 ? _a : "arvo.event.router", event, this.executionunits, function () {
+                                            error_1 = _a.sent();
+                                            return [2 /*return*/, (0, utils_1.createHandlerErrorOutputEvent)(error_1, otelSpanHeaders, "sys.".concat(this.source, ".error"), this.source, event, this.executionunits, function () {
                                                     var args = [];
                                                     for (var _i = 0; _i < arguments.length; _i++) {
                                                         args[_i] = arguments[_i];
@@ -203,6 +237,31 @@ var ArvoEventRouter = /** @class */ (function () {
             });
         });
     };
+    Object.defineProperty(ArvoEventRouter.prototype, "systemErrorSchema", {
+        /**
+         * Provides the schema for system error events.
+         *
+         * @returns An object containing the error event type and schema.
+         *
+         * @remarks
+         * This getter defines the structure for system error events that may be emitted
+         * when an unexpected error occurs during event handling. The error event type
+         * is prefixed with 'sys.' followed by the handler's source and '.error'.
+         * The schema used for these error events is the standard ArvoErrorSchema.
+         *
+         * @example
+         * // If the handler's source is 'user.service'
+         * // The system error event type would be 'sys.user.service.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/MultiArvoEventHandler/index.d.ts

@@ -1,6 +1,7 @@
 import { SpanKind } from '@opentelemetry/api';
 import { ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
 import { IMultiArvoEventHandler } from './types';
+import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
 /**
  * Represents a Multi ArvoEvent handler that can process multiple event types.
  *
@@ -10,7 +11,7 @@ import { IMultiArvoEventHandler } from './types';
  * without being tied to a specific contract. This makes it more flexible for
  * scenarios where you need to process various event types with a single handler.
  */
-export default class MultiArvoEventHandler {
+export default class MultiArvoEventHandler extends AbstractArvoEventHandler {
     /** The default execution cost associated with this handler */
     readonly executionunits: number;
     /**

package/dist/MultiArvoEventHandler/index.js

@@ -1,4 +1,19 @@
 "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 __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) {
@@ -35,12 +50,15 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         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 });
 var api_1 = require("@opentelemetry/api");
 var arvo_core_1 = require("arvo-core");
-var schema_1 = require("arvo-core/dist/ArvoEvent/schema");
 var utils_1 = require("../utils");
 var utils_2 = require("../OpenTelemetry/utils");
+var AbstractArvoEventHandler_1 = __importDefault(require("../AbstractArvoEventHandler"));
 /**
  * Represents a Multi ArvoEvent handler that can process multiple event types.
  *
@@ -50,7 +68,8 @@ var utils_2 = require("../OpenTelemetry/utils");
  * without being tied to a specific contract. This makes it more flexible for
  * scenarios where you need to process various event types with a single handler.
  */
-var MultiArvoEventHandler = /** @class */ (function () {
+var MultiArvoEventHandler = /** @class */ (function (_super) {
+    __extends(MultiArvoEventHandler, _super);
     /**
      * Creates an instance of MultiArvoEventHandler.
      *
@@ -59,24 +78,23 @@ var MultiArvoEventHandler = /** @class */ (function () {
      */
     function MultiArvoEventHandler(param) {
         var _a, _b, _c;
-        this.openInferenceSpanKind = arvo_core_1.OpenInferenceSpanKind.CHAIN;
-        this.arvoExecutionSpanKind = arvo_core_1.ArvoExecutionSpanKind.EVENT_HANDLER;
-        this.openTelemetrySpanKind = api_1.SpanKind.INTERNAL;
-        this.executionunits = param.executionunits;
-        this._handler = param.handler;
-        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));
+        var _this = _super.call(this) || this;
+        _this.openInferenceSpanKind = arvo_core_1.OpenInferenceSpanKind.CHAIN;
+        _this.arvoExecutionSpanKind = arvo_core_1.ArvoExecutionSpanKind.EVENT_HANDLER;
+        _this.openTelemetrySpanKind = api_1.SpanKind.INTERNAL;
+        _this.executionunits = param.executionunits;
+        _this._handler = param.handler;
+        if (!(0, utils_1.isLowerAlphanumeric)(param.source)) {
+            throw new Error("Invalid 'source' = '".concat(param.source, "'. The 'source' must only contain alphanumeric characters e.g. test.handler"));
         }
-        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.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;
+        return _this;
     }
     /**
      * Executes the event handler for a given event.
@@ -229,5 +247,5 @@ var MultiArvoEventHandler = /** @class */ (function () {
         configurable: true
     });
     return MultiArvoEventHandler;
-}());
+}(AbstractArvoEventHandler_1.default));
 exports.default = MultiArvoEventHandler;

package/dist/index.d.ts

@@ -9,4 +9,5 @@ import { isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault } fro
 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, };
+import AbstractArvoEventHandler from './AbstractArvoEventHandler';
+export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, IArvoEventRouter, ArvoEventRouter, createArvoEventRouter, AbstractArvoEventHandler, };

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.createArvoEventRouter = exports.ArvoEventRouter = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
+exports.AbstractArvoEventHandler = 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");
@@ -21,3 +21,5 @@ 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; } });
+var AbstractArvoEventHandler_1 = __importDefault(require("./AbstractArvoEventHandler"));
+exports.AbstractArvoEventHandler = AbstractArvoEventHandler_1.default;

package/dist/utils.d.ts

@@ -50,6 +50,7 @@ export declare function coalesceOrDefault<T>(values: (T | null | undefined)[], _
  * @param events - An array of event handler function outputs.
  * @param otelSpanHeaders - OpenTelemetry headers for tracing.
  * @param source - The source of the event.
+ * @param defaultAccessControl - The default access control string for the events
  * @param originalEvent - The original ArvoEvent that triggered the handler.
  * @param handlerExectionUnits - The number of execution units for the handler.
  * @param factory - A function to create ArvoEvents.
@@ -61,3 +62,17 @@ export declare const eventHandlerOutputEventCreator: (events: Array<ArvoEventHan
 export declare const createHandlerErrorOutputEvent: (error: Error, otelSpanHeaders: OpenTelemetryHeaders, type: string, source: string, originalEvent: ArvoEvent, handlerExectionUnits: number, factory: (param: CreateArvoEvent<any, any> & {
     to: string;
 }, extensions?: Record<string, string | number | boolean>) => ArvoEvent<any, any, any>) => ArvoEvent<any, any, any>[];
+/**
+ * Validates if a string contains only uppercase or lowercase alphanumeric characters.
+ *
+ * This function checks if the input string consists solely of:
+ * - Lowercase letters (a-z)
+ * - Numbers (0-9)
+ * - Dot (.)
+ *
+ * It does not allow any special characters, spaces, or other non-alphanumeric characters.
+ *
+ * @param input - The string to be validated.
+ * @returns True if the string contains only alphanumeric characters, false otherwise.
+ */
+export declare function isLowerAlphanumeric(input: string): boolean;

package/dist/utils.js

@@ -27,6 +27,7 @@ exports.isNullOrUndefined = isNullOrUndefined;
 exports.getValueOrDefault = getValueOrDefault;
 exports.coalesce = coalesce;
 exports.coalesceOrDefault = coalesceOrDefault;
+exports.isLowerAlphanumeric = isLowerAlphanumeric;
 var arvo_core_1 = require("arvo-core");
 var api_1 = require("@opentelemetry/api");
 /**
@@ -96,6 +97,7 @@ function coalesceOrDefault(values, _default) {
  * @param events - An array of event handler function outputs.
  * @param otelSpanHeaders - OpenTelemetry headers for tracing.
  * @param source - The source of the event.
+ * @param defaultAccessControl - The default access control string for the events
  * @param originalEvent - The original ArvoEvent that triggered the handler.
  * @param handlerExectionUnits - The number of execution units for the handler.
  * @param factory - A function to create ArvoEvents.
@@ -103,11 +105,12 @@ function coalesceOrDefault(values, _default) {
  */
 var eventHandlerOutputEventCreator = function (events, otelSpanHeaders, source, originalEvent, handlerExectionUnits, factory) {
     return events.map(function (item, index) {
+        var _a, _b;
         var __extensions = item.__extensions, handlerResult = __rest(item, ["__extensions"]);
         var result = factory(__assign(__assign({}, handlerResult), { traceparent: otelSpanHeaders.traceparent || undefined, tracestate: otelSpanHeaders.tracestate || undefined, source: source, subject: originalEvent.subject, 
             // prioritise returned 'to', 'redirectto' and then
             // 'source'
-            to: coalesceOrDefault([handlerResult.to, originalEvent.redirectto], originalEvent.source), executionunits: coalesce(handlerResult.executionunits, handlerExectionUnits) }), __extensions);
+            to: coalesceOrDefault([handlerResult.to, originalEvent.redirectto], originalEvent.source), executionunits: coalesce(handlerResult.executionunits, handlerExectionUnits), accesscontrol: (_b = (_a = handlerResult.accesscontrol) !== null && _a !== void 0 ? _a : originalEvent.accesscontrol) !== null && _b !== void 0 ? _b : undefined }), __extensions);
         Object.entries(result.otelAttributes).forEach(function (_a) {
             var _b;
             var key = _a[0], value = _a[1];
@@ -118,7 +121,7 @@ var eventHandlerOutputEventCreator = function (events, otelSpanHeaders, source,
 };
 exports.eventHandlerOutputEventCreator = eventHandlerOutputEventCreator;
 var createHandlerErrorOutputEvent = function (error, otelSpanHeaders, type, source, originalEvent, handlerExectionUnits, factory) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e;
     (0, arvo_core_1.exceptionToSpan)(error);
     (_a = api_1.trace.getActiveSpan()) === null || _a === void 0 ? void 0 : _a.setStatus({
         code: api_1.SpanStatusCode.ERROR,
@@ -137,6 +140,7 @@ var createHandlerErrorOutputEvent = function (error, otelSpanHeaders, type, sour
             errorMessage: error.message,
             errorStack: (_d = error.stack) !== null && _d !== void 0 ? _d : null,
         },
+        accesscontrol: (_e = originalEvent.accesscontrol) !== null && _e !== void 0 ? _e : undefined
     });
     Object.entries(result.otelAttributes).forEach(function (_a) {
         var _b;
@@ -146,3 +150,20 @@ var createHandlerErrorOutputEvent = function (error, otelSpanHeaders, type, sour
     return [result];
 };
 exports.createHandlerErrorOutputEvent = createHandlerErrorOutputEvent;
+/**
+ * Validates if a string contains only uppercase or lowercase alphanumeric characters.
+ *
+ * This function checks if the input string consists solely of:
+ * - Lowercase letters (a-z)
+ * - Numbers (0-9)
+ * - Dot (.)
+ *
+ * It does not allow any special characters, spaces, or other non-alphanumeric characters.
+ *
+ * @param input - The string to be validated.
+ * @returns True if the string contains only alphanumeric characters, false otherwise.
+ */
+function isLowerAlphanumeric(input) {
+    var alphanumericRegex = /^[a-z0-9.]+$/;
+    return alphanumericRegex.test(input);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-event-handler",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "This package contains class and function for event handlers in an Arvo Event Driven system",
   "main": "dist/index.js",
   "scripts": {
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "arvo-core": "^1.1.0",
+    "arvo-core": "^1.1.10",
     "uuid": "^10.0.0",
     "zod": "^3.23.8"
   }