arvo-event-handler 1.1.7 → 1.1.9

package/dist/AbstractArvoEventHandler/index.d.ts

@@ -1,4 +1,5 @@
 import { ArvoContractRecord, ArvoEvent } from 'arvo-core';
+import { ExecutionOpenTelemetryConfiguration } from './types';
 /**
  * Abstract base class for Arvo event handlers.
  *
@@ -14,22 +15,44 @@ 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.
+     * @param {ArvoEvent} event - The Arvo event to be processed. This event should conform
+     *                           to the expected schema for the specific handler implementation.
+     * @param {ExecutionOpenTelemetryConfiguration} opentelemetry - Configuration for OpenTelemetry
+     *                                                             integration, including tracing options
+     *                                                             and context inheritance settings.
      * @returns {Promise<ArvoEvent[]>} A promise that resolves to an array of resulting Arvo events.
+     *                                 These events represent the outcome of processing the input event.
      *
      * @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.
+     * This method defines the core event processing logic that each concrete handler must implement.
+     * It should handle the complete lifecycle of an event, including:
+     * - Validation of the input event
+     * - Processing of the event according to business rules
+     * - Generation of any resulting events
+     * - Error handling and reporting
+     * - OpenTelemetry integration for observability
      *
-     * @throws {Error} Implementations may throw errors for invalid inputs or processing failures.
+     * @throws {Error}
+     * - When the input event fails validation
+     * - When processing encounters an unrecoverable error
+     * - When the handler is unable to properly execute the event
      *
      * @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.
+     * Implementation considerations:
+     * - Ensure proper error handling and event validation
+     * - Implement appropriate retry logic for transient failures
+     * - Use the provided OpenTelemetry configuration for tracing
+     * - Consider performance implications for long-running operations
+     * - Maintain idempotency where appropriate
+     * - Document any specific requirements for event schemas
+     *
+     * The method should handle observability concerns by:
+     * - Creating appropriate spans for tracing
+     * - Recording relevant attributes and events
+     * - Properly handling span lifecycle (creation and completion)
+     * - Propagating context appropriately
      */
-    abstract execute(event: ArvoEvent): Promise<ArvoEvent[]>;
+    abstract execute(event: ArvoEvent, opentelemetry: ExecutionOpenTelemetryConfiguration): Promise<ArvoEvent[]>;
     /**
      * Provides the schema for system error events.
      *

package/dist/AbstractArvoEventHandler/types.d.ts

@@ -0,0 +1,33 @@
+import { Tracer } from '@opentelemetry/api';
+/**
+ * Configuration options for OpenTelemetry integration in execution context.
+ *
+ * This type defines how tracing should be configured and inherited within
+ * the execution pipeline.
+ *
+ * @example
+ * ```typescript
+ * const config: ExecutionOpenTelemetryConfiguration = {
+ *   inheritFrom: 'event',
+ *   tracer: new OpenTelemetry.Tracer('service-name')
+ * };
+ * ```
+ */
+export type ExecutionOpenTelemetryConfiguration = {
+    /**
+     * Specifies the context from which to inherit OpenTelemetry context.
+     *
+     * @property {('event' | 'execution')} inheritFrom
+     * - 'event': Inherits context from the event that triggered the execution
+     * - 'execution': Inherits context from the parent execution context
+     */
+    inheritFrom: 'event' | 'execution';
+    /**
+     * Optional OpenTelemetry tracer instance to use for creating spans.
+     * If not provided, a default tracer may be used depending on the implementation.
+     *
+     * @property {Tracer} [tracer]
+     * @see {@link https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_api.Tracer.html OpenTelemetry Tracer}
+     */
+    tracer?: Tracer;
+};

package/dist/AbstractArvoEventHandler/types.js

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

package/dist/ArvoEventHandler/index.d.ts

@@ -2,6 +2,7 @@ import { ArvoContract, ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind,
 import { IArvoEventHandler } from './types';
 import { SpanKind } from '@opentelemetry/api';
 import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
+import { ExecutionOpenTelemetryConfiguration } from '../AbstractArvoEventHandler/types';
 /**
  * Represents an event handler for Arvo contracts.
  *
@@ -45,6 +46,8 @@ export default class ArvoEventHandler<TContract extends ArvoContract> extends Ab
      * Executes the event handler for a given event.
      *
      * @param event - The event to handle.
+     * @param opentelemetry - Configuration for OpenTelemetry integration, including tracing options
+     *                        and context inheritance settings.
      * @returns A promise that resolves to an array of resulting ArvoEvents.
      *
      * @remarks
@@ -88,9 +91,7 @@ export default class ArvoEventHandler<TContract extends ArvoContract> extends Ab
      * - Propagates trace context to output events
      * - Handles error cases and sets appropriate span status
      */
-    execute(event: ArvoEvent<ResolveArvoContractRecord<TContract['accepts']>, Record<string, any>, TContract['accepts']['type']>, opentelemetry?: {
-        inheritFrom: 'event' | 'execution';
-    }): Promise<ArvoEvent[]>;
+    execute(event: ArvoEvent<ResolveArvoContractRecord<TContract['accepts']>, Record<string, any>, TContract['accepts']['type']>, opentelemetry?: ExecutionOpenTelemetryConfiguration): Promise<ArvoEvent[]>;
     /**
      * Provides the schema for system error events.
      *

package/dist/ArvoEventHandler/index.js

@@ -114,6 +114,8 @@ var ArvoEventHandler = /** @class */ (function (_super) {
      * Executes the event handler for a given event.
      *
      * @param event - The event to handle.
+     * @param opentelemetry - Configuration for OpenTelemetry integration, including tracing options
+     *                        and context inheritance settings.
      * @returns A promise that resolves to an array of resulting ArvoEvents.
      *
      * @remarks
@@ -162,11 +164,13 @@ var ArvoEventHandler = /** @class */ (function (_super) {
             var spanName, spanKinds, spanOptions, span, eventFactory;
             var _a;
             var _this = this;
+            var _b;
             if (opentelemetry === void 0) { opentelemetry = {
                 inheritFrom: 'event',
+                tracer: OpenTelemetry_1.ArvoEventHandlerTracer,
             }; }
-            return __generator(this, function (_b) {
-                switch (_b.label) {
+            return __generator(this, function (_c) {
+                switch (_c.label) {
                     case 0:
                         spanName = "ArvoEventHandler<".concat(this.contract.uri, ">.execute<").concat(event.type, ">");
                         spanKinds = {
@@ -182,8 +186,8 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                                 _a),
                         };
                         span = opentelemetry.inheritFrom === 'event'
-                            ? (0, utils_2.createSpanFromEvent)(spanName, event, spanKinds)
-                            : OpenTelemetry_1.ArvoEventHandlerTracer.startSpan(spanName, spanOptions);
+                            ? (0, utils_2.createSpanFromEvent)(spanName, event, spanKinds, opentelemetry.tracer)
+                            : ((_b = opentelemetry.tracer) !== null && _b !== void 0 ? _b : OpenTelemetry_1.ArvoEventHandlerTracer).startSpan(spanName, spanOptions);
                         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;
@@ -257,7 +261,7 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                                     }
                                 });
                             }); })];
-                    case 1: return [2 /*return*/, _b.sent()];
+                    case 1: return [2 /*return*/, _c.sent()];
                 }
             });
         });

package/dist/ArvoEventRouter/index.d.ts

@@ -3,6 +3,7 @@ import ArvoEventHandler from '../ArvoEventHandler';
 import { IArvoEventRouter } from './types';
 import { SpanKind } from '@opentelemetry/api';
 import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
+import { ExecutionOpenTelemetryConfiguration } from '../AbstractArvoEventHandler/types';
 /**
  * ArvoEventRouter class handles routing of ArvoEvents to appropriate event handlers.
  */
@@ -48,6 +49,8 @@ export declare class ArvoEventRouter extends AbstractArvoEventHandler {
      * Executes the routing process for a given ArvoEvent.
      *
      * @param event - The ArvoEvent to be processed and routed.
+     * @param opentelemetry - Configuration for OpenTelemetry integration, including tracing options
+     *                        and context inheritance settings.
      * @returns A Promise that resolves to an array of ArvoEvents.
      *
      * @remarks
@@ -89,7 +92,7 @@ export declare class ArvoEventRouter extends AbstractArvoEventHandler {
      * - 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[]>;
+    execute(event: ArvoEvent, opentelemetry?: ExecutionOpenTelemetryConfiguration): Promise<ArvoEvent[]>;
     /**
      * Provides the schema for system error events.
      *

package/dist/ArvoEventRouter/index.js

@@ -61,6 +61,7 @@ var api_1 = require("@opentelemetry/api");
 var utils_2 = require("./utils");
 var utils_3 = require("../OpenTelemetry/utils");
 var AbstractArvoEventHandler_1 = __importDefault(require("../AbstractArvoEventHandler"));
+var OpenTelemetry_1 = require("../OpenTelemetry");
 /**
  * ArvoEventRouter class handles routing of ArvoEvents to appropriate event handlers.
  */
@@ -122,6 +123,8 @@ var ArvoEventRouter = /** @class */ (function (_super) {
      * Executes the routing process for a given ArvoEvent.
      *
      * @param event - The ArvoEvent to be processed and routed.
+     * @param opentelemetry - Configuration for OpenTelemetry integration, including tracing options
+     *                        and context inheritance settings.
      * @returns A Promise that resolves to an array of ArvoEvents.
      *
      * @remarks
@@ -163,19 +166,35 @@ var ArvoEventRouter = /** @class */ (function (_super) {
      * - 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 span;
-            var _this = this;
+    ArvoEventRouter.prototype.execute = function (event_1) {
+        return __awaiter(this, arguments, void 0, function (event, opentelemetry) {
+            var spanName, spanKinds, spanOptions, span;
             var _a;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
+            var _this = this;
+            var _b, _c;
+            if (opentelemetry === void 0) { opentelemetry = {
+                inheritFrom: 'event',
+                tracer: OpenTelemetry_1.ArvoEventHandlerTracer,
+            }; }
+            return __generator(this, function (_d) {
+                switch (_d.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, {
+                        spanName = "ArvoEventRouter.source<".concat((_b = this._source) !== null && _b !== void 0 ? _b : 'arvo.event.router', ">.execute<").concat(event.type, ">");
+                        spanKinds = {
                             kind: this.openTelemetrySpanKind,
                             openInference: this.openInferenceSpanKind,
                             arvoExecution: this.arvoExecutionSpanKind,
-                        });
+                        };
+                        spanOptions = {
+                            kind: spanKinds.kind,
+                            attributes: (_a = {},
+                                _a[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = spanKinds.openInference,
+                                _a[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = spanKinds.arvoExecution,
+                                _a),
+                        };
+                        span = opentelemetry.inheritFrom === 'event'
+                            ? (0, utils_3.createSpanFromEvent)(spanName, event, spanKinds, opentelemetry.tracer)
+                            : ((_c = opentelemetry.tracer) !== null && _c !== void 0 ? _c : 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;
                                 var _this = this;
@@ -195,7 +214,7 @@ var ArvoEventRouter = /** @class */ (function (_super) {
                                             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)];
+                                            return [4 /*yield*/, this.handlersMap[newEvent.type].execute(newEvent, { inheritFrom: 'execution', tracer: opentelemetry.tracer })];
                                         case 2:
                                             results = _a.sent();
                                             return [2 /*return*/, results.map(function (event) {
@@ -233,7 +252,7 @@ var ArvoEventRouter = /** @class */ (function (_super) {
                                     }
                                 });
                             }); })];
-                    case 1: return [2 /*return*/, _b.sent()];
+                    case 1: return [2 /*return*/, _d.sent()];
                 }
             });
         });

package/dist/MultiArvoEventHandler/index.d.ts

@@ -2,6 +2,7 @@ import { SpanKind } from '@opentelemetry/api';
 import { ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
 import { IMultiArvoEventHandler } from './types';
 import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
+import { ExecutionOpenTelemetryConfiguration } from '../AbstractArvoEventHandler/types';
 /**
  * Represents a Multi ArvoEvent handler that can process multiple event types.
  *
@@ -41,6 +42,8 @@ export default class MultiArvoEventHandler extends AbstractArvoEventHandler {
      * Executes the event handler for a given event.
      *
      * @param event - The event to handle.
+     * @param opentelemetry - Configuration for OpenTelemetry integration, including tracing options
+     *                        and context inheritance settings.
      * @returns A promise that resolves to an array of resulting ArvoEvents.
      *
      * @remarks
@@ -90,9 +93,7 @@ export default class MultiArvoEventHandler extends AbstractArvoEventHandler {
      * - 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, opentelemetry?: {
-        inheritFrom: 'event' | 'execution';
-    }): Promise<ArvoEvent[]>;
+    execute(event: ArvoEvent, opentelemetry?: ExecutionOpenTelemetryConfiguration): Promise<ArvoEvent[]>;
     /**
      * Provides the schema for system error events.
      *

package/dist/MultiArvoEventHandler/index.js

@@ -101,6 +101,8 @@ var MultiArvoEventHandler = /** @class */ (function (_super) {
      * Executes the event handler for a given event.
      *
      * @param event - The event to handle.
+     * @param opentelemetry - Configuration for OpenTelemetry integration, including tracing options
+     *                        and context inheritance settings.
      * @returns A promise that resolves to an array of resulting ArvoEvents.
      *
      * @remarks
@@ -155,11 +157,13 @@ var MultiArvoEventHandler = /** @class */ (function (_super) {
             var spanName, spanKinds, spanOptions, span;
             var _a;
             var _this = this;
+            var _b;
             if (opentelemetry === void 0) { opentelemetry = {
                 inheritFrom: 'event',
+                tracer: OpenTelemetry_1.ArvoEventHandlerTracer,
             }; }
-            return __generator(this, function (_b) {
-                switch (_b.label) {
+            return __generator(this, function (_c) {
+                switch (_c.label) {
                     case 0:
                         spanName = "MutliArvoEventHandler.source<".concat(this.source, ">.execute<").concat(event.type, ">");
                         spanKinds = {
@@ -175,8 +179,8 @@ var MultiArvoEventHandler = /** @class */ (function (_super) {
                                 _a),
                         };
                         span = opentelemetry.inheritFrom === 'event'
-                            ? (0, utils_2.createSpanFromEvent)(spanName, event, spanKinds)
-                            : OpenTelemetry_1.ArvoEventHandlerTracer.startSpan(spanName, spanOptions);
+                            ? (0, utils_2.createSpanFromEvent)(spanName, event, spanKinds, opentelemetry.tracer)
+                            : ((_b = opentelemetry.tracer) !== null && _b !== void 0 ? _b : 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, _handlerOutput, outputs, error_1;
                                 return __generator(this, function (_a) {
@@ -232,7 +236,7 @@ var MultiArvoEventHandler = /** @class */ (function (_super) {
                                     }
                                 });
                             }); })];
-                    case 1: return [2 /*return*/, _b.sent()];
+                    case 1: return [2 /*return*/, _c.sent()];
                 }
             });
         });

package/dist/index.d.ts

@@ -11,4 +11,5 @@ import { ArvoEventRouter } from './ArvoEventRouter';
 import { createArvoEventRouter } from './ArvoEventRouter/helpers';
 import AbstractArvoEventHandler from './AbstractArvoEventHandler';
 import { createSpanFromEvent } from './OpenTelemetry/utils';
-export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, IArvoEventRouter, ArvoEventRouter, createArvoEventRouter, AbstractArvoEventHandler, createSpanFromEvent as createOtelSpanFromEvent, };
+import { ExecutionOpenTelemetryConfiguration } from './AbstractArvoEventHandler/types';
+export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, IArvoEventRouter, ArvoEventRouter, createArvoEventRouter, AbstractArvoEventHandler, createSpanFromEvent as createOtelSpanFromEvent, ExecutionOpenTelemetryConfiguration, };

package/package.json

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