arvo-event-handler 2.2.1 → 2.2.6

package/CHANGELOG.md

@@ -35,7 +35,11 @@
 ## [2.1.4] - 2024-12-19
 
 - Updated the opentelemetry core version and arvo core versions
+
 ## [2.2.0] - 2024-12-25
 
 - Stable release for arvo event handler version 2
 
+## [2.2.5] - 2024-12-25
+
+- Added better error boundaries for the handlers

package/README.md

@@ -1,5 +1,6 @@
 [![SonarCloud](https://sonarcloud.io/images/project_badges/sonarcloud-white.svg)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-event-handler&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-event-handler)
+
 # Arvo
 
 ## What is Arvo

package/dist/ArvoEventHandler/index.js

@@ -69,6 +69,7 @@ var arvo_core_1 = require("arvo-core");
 var api_1 = require("@opentelemetry/api");
 var utils_1 = require("../utils");
 var AbstractArvoEventHandler_1 = __importDefault(require("../AbstractArvoEventHandler"));
+var errors_1 = require("../errors");
 /**
  * ArvoEventHandler manages the execution and processing of events in accordance with
  * Arvo contracts. This class serves as the cornerstone for event handling operations,
@@ -169,7 +170,7 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                                                     return span.setAttribute("to_process.0.".concat(key), value);
                                                 });
                                                 if (this.contract.type !== event.type) {
-                                                    throw new Error("Event type mismatch: Received '".concat(event.type, "', expected '").concat(this.contract.type, "'"));
+                                                    throw new errors_1.ContractViolation("Event type mismatch: Received '".concat(event.type, "', expected '").concat(this.contract.type, "'"));
                                                 }
                                                 (0, arvo_core_1.logToSpan)({
                                                     level: 'INFO',
@@ -178,7 +179,7 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                                                 parsedDataSchema = arvo_core_1.EventDataschemaUtil.parse(event);
                                                 if ((parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.uri) &&
                                                     (parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.uri) !== this.contract.uri) {
-                                                    throw new Error("Contract URI mismatch: Handler expects '".concat(this.contract.uri, "' but event dataschema specifies '").concat(event.dataschema, "'. Events must reference the same contract URI as their handler."));
+                                                    throw new errors_1.ContractViolation("Contract URI mismatch: Handler expects '".concat(this.contract.uri, "' but event dataschema specifies '").concat(event.dataschema, "'. Events must reference the same contract URI as their handler."));
                                                 }
                                                 if (!(parsedDataSchema === null || parsedDataSchema === void 0 ? void 0 : parsedDataSchema.version)) {
                                                     (0, arvo_core_1.logToSpan)({
@@ -193,7 +194,7 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                                                 });
                                                 inputEventValidation = handlerContract.accepts.schema.safeParse(event.data);
                                                 if (inputEventValidation.error) {
-                                                    throw new Error("Event payload validation failed: ".concat(inputEventValidation.error));
+                                                    throw new errors_1.ContractViolation("Input event payload validation failed: ".concat(inputEventValidation.error));
                                                 }
                                                 (0, arvo_core_1.logToSpan)({
                                                     level: 'INFO',
@@ -220,7 +221,14 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                                                     outputs = [_handleOutput];
                                                 }
                                                 eventFactory_1 = (0, arvo_core_1.createArvoEventFactory)(handlerContract);
-                                                result = (0, utils_1.eventHandlerOutputEventCreator)(outputs, otelSpanHeaders, this.source, event, this.executionunits, function (param, extensions) { return eventFactory_1.emits(param, extensions); });
+                                                result = (0, utils_1.eventHandlerOutputEventCreator)(outputs, otelSpanHeaders, this.source, event, this.executionunits, function (param, extensions) {
+                                                    try {
+                                                        return eventFactory_1.emits(param, extensions);
+                                                    }
+                                                    catch (e) {
+                                                        throw new errors_1.ContractViolation(e.message);
+                                                    }
+                                                });
                                                 (0, arvo_core_1.logToSpan)({
                                                     level: 'INFO',
                                                     message: "Event processing completed successfully. Generated ".concat(result.length, " event(s)"),
@@ -232,12 +240,15 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                                                 return [2 /*return*/, result];
                                             case 3:
                                                 error_1 = _e.sent();
-                                                eventFactory = (0, arvo_core_1.createArvoEventFactory)(this.contract.version('latest'));
                                                 (0, arvo_core_1.exceptionToSpan)(error_1);
                                                 span.setStatus({
                                                     code: api_1.SpanStatusCode.ERROR,
                                                     message: "Event processing failed: ".concat(error_1.message),
                                                 });
+                                                if (error_1.name.includes('ViolationError')) {
+                                                    throw error_1;
+                                                }
+                                                eventFactory = (0, arvo_core_1.createArvoEventFactory)(this.contract.version('latest'));
                                                 result = eventFactory.systemError({
                                                     source: this.source,
                                                     subject: event.subject,

package/dist/ArvoEventRouter/index.js

@@ -71,6 +71,7 @@ var utils_1 = require("../utils");
 var api_1 = require("@opentelemetry/api");
 var utils_2 = require("./utils");
 var AbstractArvoEventHandler_1 = __importDefault(require("../AbstractArvoEventHandler"));
+var errors_1 = require("../errors");
 /**
  * ArvoEventRouter manages event routing and execution within the Arvo event system. It directs
  * incoming events to appropriate handlers based on event type while maintaining telemetry
@@ -181,11 +182,11 @@ var ArvoEventRouter = /** @class */ (function (_super) {
                                                 message: "Initiating event resolution - Type: ".concat(newEvent.type, ", Source: ").concat(newEvent.source, ", Destination: ").concat(newEvent.to),
                                             });
                                             if (newEvent.to !== this.source) {
-                                                throw new Error("Event destination mismatch: Received destination '".concat(newEvent.to, "', ") +
+                                                throw new errors_1.ConfigViolation("Event destination mismatch: Received destination '".concat(newEvent.to, "', ") +
                                                     "but router accepts only '".concat(this.source, "'"));
                                             }
                                             if (!this.handlersMap[newEvent.type]) {
-                                                throw new Error("No registered handler found for event type '".concat(newEvent.type, "'"));
+                                                throw new errors_1.ConfigViolation("No registered handler found for event type '".concat(newEvent.type, "'"));
                                             }
                                             (0, arvo_core_1.logToSpan)({
                                                 level: 'INFO',
@@ -228,7 +229,7 @@ var ArvoEventRouter = /** @class */ (function (_super) {
                                             return [2 /*return*/, resultingEvents];
                                         case 3:
                                             error_1 = _a.sent();
-                                            return [2 /*return*/, (0, utils_1.createHandlerErrorOutputEvent)(error_1, otelSpanHeaders, this.systemErrorSchema.type, this.source, event, this.executionunits, function (param, extensions) { return (0, arvo_core_1.createArvoEvent)(param, extensions); })];
+                                            return [2 /*return*/, (0, utils_1.handleArvoEventHandlerCommonError)(error_1, otelSpanHeaders, this.systemErrorSchema.type, this.source, event, this.executionunits, function (param, extensions) { return (0, arvo_core_1.createArvoEvent)(param, extensions); })];
                                         case 4:
                                             span.end();
                                             return [7 /*endfinally*/];

package/dist/MultiArvoEventHandler/index.js

@@ -69,6 +69,7 @@ var api_1 = require("@opentelemetry/api");
 var arvo_core_1 = require("arvo-core");
 var utils_1 = require("../utils");
 var AbstractArvoEventHandler_1 = __importDefault(require("../AbstractArvoEventHandler"));
+var errors_1 = require("../errors");
 /**
  * MultiArvoEventHandler processes multiple event types without being bound to specific contracts.
  * Manages event execution, telemetry tracking, and error handling for diverse event streams.
@@ -140,7 +141,7 @@ var MultiArvoEventHandler = /** @class */ (function (_super) {
                                                     message: "Initiating event resolution - Type: ".concat(event.type, ", Source: ").concat(event.source, ", Destination: ").concat(event.to),
                                                 });
                                                 if (event.to !== this.source) {
-                                                    throw new Error("Event destination mismatch: Expected '".concat(this.source, "', received '").concat(event.to, "'"));
+                                                    throw new errors_1.ConfigViolation("Event destination mismatch: Expected '".concat(this.source, "', received '").concat(event.to, "'"));
                                                 }
                                                 return [4 /*yield*/, this.handler({
                                                         event: event,
@@ -166,7 +167,7 @@ var MultiArvoEventHandler = /** @class */ (function (_super) {
                                                 return [2 /*return*/, resultingEvents];
                                             case 3:
                                                 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 (param, extensions) { return (0, arvo_core_1.createArvoEvent)(param, extensions); })];
+                                                return [2 /*return*/, (0, utils_1.handleArvoEventHandlerCommonError)(error_1, otelSpanHeaders, "sys.".concat(this.source, ".error"), this.source, event, this.executionunits, function (param, extensions) { return (0, arvo_core_1.createArvoEvent)(param, extensions); })];
                                             case 4:
                                                 span.end();
                                                 return [7 /*endfinally*/];

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+import { ViolationError } from 'arvo-core';
+/**
+ * Represents violations of service contracts, typically involving invalid inputs,
+ * outputs, or state transitions that break expected invariants.
+ */
+export declare class ContractViolation extends ViolationError<'Contract'> {
+    constructor(message: string, metadata?: Record<string, any>);
+}
+/**
+ * Represents violations related to system configuration, typically involving
+ * missing, invalid, or conflicting configuration requirement by the event
+ * being processed.
+ */
+export declare class ConfigViolation extends ViolationError<'Config'> {
+    constructor(message: string, metadata?: Record<string, any>);
+}
+/**
+ * Represents violations that occur during system execution, typically involving
+ * runtime failures that require explicit handling or intervention. This allow
+ * the developer to throw an error which must be handled explicity at `.execute`
+ * of an Arvo event handler. Otherwise, the the error throw during exection are
+ * converted to system error event and require to be handled by the workflow
+ * orchestration.
+ *
+ * @example
+ * ```typescript
+ * throw new ExecutionViolation(
+ *   'API rate limit exceeded',
+ *   {
+ *     rateLimitRemaining: 0,
+ *     resetAfterSeconds: 60
+ *   }
+ * );
+ * ```
+ */
+export declare class ExecutionViolation extends ViolationError<'Execution'> {
+    constructor(message: string, metadata?: Record<string, any>);
+}

package/dist/errors.js

@@ -0,0 +1,83 @@
+"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 __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionViolation = exports.ConfigViolation = exports.ContractViolation = void 0;
+var arvo_core_1 = require("arvo-core");
+/**
+ * Represents violations of service contracts, typically involving invalid inputs,
+ * outputs, or state transitions that break expected invariants.
+ */
+var ContractViolation = /** @class */ (function (_super) {
+    __extends(ContractViolation, _super);
+    function ContractViolation(message, metadata) {
+        return _super.call(this, {
+            type: 'Contract',
+            message: message,
+            metadata: metadata,
+        }) || this;
+    }
+    return ContractViolation;
+}(arvo_core_1.ViolationError));
+exports.ContractViolation = ContractViolation;
+/**
+ * Represents violations related to system configuration, typically involving
+ * missing, invalid, or conflicting configuration requirement by the event
+ * being processed.
+ */
+var ConfigViolation = /** @class */ (function (_super) {
+    __extends(ConfigViolation, _super);
+    function ConfigViolation(message, metadata) {
+        return _super.call(this, {
+            type: 'Config',
+            message: message,
+            metadata: metadata,
+        }) || this;
+    }
+    return ConfigViolation;
+}(arvo_core_1.ViolationError));
+exports.ConfigViolation = ConfigViolation;
+/**
+ * Represents violations that occur during system execution, typically involving
+ * runtime failures that require explicit handling or intervention. This allow
+ * the developer to throw an error which must be handled explicity at `.execute`
+ * of an Arvo event handler. Otherwise, the the error throw during exection are
+ * converted to system error event and require to be handled by the workflow
+ * orchestration.
+ *
+ * @example
+ * ```typescript
+ * throw new ExecutionViolation(
+ *   'API rate limit exceeded',
+ *   {
+ *     rateLimitRemaining: 0,
+ *     resetAfterSeconds: 60
+ *   }
+ * );
+ * ```
+ */
+var ExecutionViolation = /** @class */ (function (_super) {
+    __extends(ExecutionViolation, _super);
+    function ExecutionViolation(message, metadata) {
+        return _super.call(this, {
+            type: 'Execution',
+            message: message,
+            metadata: metadata,
+        }) || this;
+    }
+    return ExecutionViolation;
+}(arvo_core_1.ViolationError));
+exports.ExecutionViolation = ExecutionViolation;

package/dist/index.d.ts

@@ -11,4 +11,5 @@ import { ArvoEventRouter } from './ArvoEventRouter';
 import { createArvoEventRouter } from './ArvoEventRouter/helpers';
 import AbstractArvoEventHandler from './AbstractArvoEventHandler';
 import { deleteOtelHeaders } from './ArvoEventRouter/utils';
-export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, IArvoEventRouter, ArvoEventRouter, createArvoEventRouter, AbstractArvoEventHandler, deleteOtelHeaders, ArvoEventHandlerOpenTelemetryOptions, EventHandlerFactory, };
+import { ContractViolation, ConfigViolation, ExecutionViolation } from './errors';
+export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, IArvoEventRouter, ArvoEventRouter, createArvoEventRouter, AbstractArvoEventHandler, deleteOtelHeaders, ArvoEventHandlerOpenTelemetryOptions, EventHandlerFactory, ContractViolation, ConfigViolation, ExecutionViolation, };

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.deleteOtelHeaders = exports.AbstractArvoEventHandler = exports.createArvoEventRouter = exports.ArvoEventRouter = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
+exports.ExecutionViolation = exports.ConfigViolation = exports.ContractViolation = exports.deleteOtelHeaders = exports.AbstractArvoEventHandler = exports.createArvoEventRouter = exports.ArvoEventRouter = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
 var ArvoEventHandler_1 = __importDefault(require("./ArvoEventHandler"));
 exports.ArvoEventHandler = ArvoEventHandler_1.default;
 var helpers_1 = require("./ArvoEventHandler/helpers");
@@ -25,3 +25,7 @@ var AbstractArvoEventHandler_1 = __importDefault(require("./AbstractArvoEventHan
 exports.AbstractArvoEventHandler = AbstractArvoEventHandler_1.default;
 var utils_2 = require("./ArvoEventRouter/utils");
 Object.defineProperty(exports, "deleteOtelHeaders", { enumerable: true, get: function () { return utils_2.deleteOtelHeaders; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ContractViolation", { enumerable: true, get: function () { return errors_1.ContractViolation; } });
+Object.defineProperty(exports, "ConfigViolation", { enumerable: true, get: function () { return errors_1.ConfigViolation; } });
+Object.defineProperty(exports, "ExecutionViolation", { enumerable: true, get: function () { return errors_1.ExecutionViolation; } });

package/dist/utils.d.ts

@@ -61,7 +61,7 @@ export declare function coalesceOrDefault<T>(values: (T | null | undefined)[], _
 export declare const eventHandlerOutputEventCreator: (events: Array<ArvoEventHandlerFunctionOutput<any> | MultiArvoEventHandlerFunctionOutput>, otelSpanHeaders: OpenTelemetryHeaders, 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>[];
-export declare const createHandlerErrorOutputEvent: (error: Error, otelSpanHeaders: OpenTelemetryHeaders, type: string, source: string, originalEvent: ArvoEvent, handlerExectionUnits: number, factory: (param: CreateArvoEvent<any, any> & {
+export declare const handleArvoEventHandlerCommonError: (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>[];
 /**

package/dist/utils.js

@@ -22,7 +22,7 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createEventHandlerTelemetryConfig = exports.createHandlerErrorOutputEvent = exports.eventHandlerOutputEventCreator = void 0;
+exports.createEventHandlerTelemetryConfig = exports.handleArvoEventHandlerCommonError = exports.eventHandlerOutputEventCreator = void 0;
 exports.isNullOrUndefined = isNullOrUndefined;
 exports.getValueOrDefault = getValueOrDefault;
 exports.coalesce = coalesce;
@@ -120,13 +120,16 @@ var eventHandlerOutputEventCreator = function (events, otelSpanHeaders, source,
     });
 };
 exports.eventHandlerOutputEventCreator = eventHandlerOutputEventCreator;
-var createHandlerErrorOutputEvent = function (error, otelSpanHeaders, type, source, originalEvent, handlerExectionUnits, factory) {
+var handleArvoEventHandlerCommonError = function (error, otelSpanHeaders, type, source, originalEvent, handlerExectionUnits, factory) {
     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,
         message: error.message,
     });
+    if (error.name.includes('ViolationError')) {
+        throw error;
+    }
     var result = factory({
         type: type,
         source: source,
@@ -149,7 +152,7 @@ var createHandlerErrorOutputEvent = function (error, otelSpanHeaders, type, sour
     });
     return [result];
 };
-exports.createHandlerErrorOutputEvent = createHandlerErrorOutputEvent;
+exports.handleArvoEventHandlerCommonError = handleArvoEventHandlerCommonError;
 /**
  * Validates if a string contains only uppercase or lowercase alphanumeric characters.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-event-handler",
-  "version": "2.2.1",
+  "version": "2.2.6",
   "description": "Type-safe event handler system with versioning, telemetry, and contract validation for distributed Arvo event-driven architectures, featuring routing and multi-handler support.",
   "main": "dist/index.js",
   "scripts": {
@@ -51,7 +51,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/core": "^1.28.0",
-    "arvo-core": "^2.2.2",
+    "arvo-core": "^2.2.6",
     "uuid": "^10.0.0",
     "zod": "^3.23.8"
   }