arvo-event-handler 1.1.8 → 1.1.10

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

@@ -1,7 +1,8 @@
 import { ArvoContract, ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind, ResolveArvoContractRecord } from 'arvo-core';
 import { IArvoEventHandler } from './types';
-import { SpanKind, Tracer } from '@opentelemetry/api';
+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,10 +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';
-        tracer?: Tracer;
-    }): 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
@@ -189,14 +191,14 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                         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;
-                                var _a, _b, _c;
-                                return __generator(this, function (_d) {
-                                    switch (_d.label) {
+                                var _a, _b, _c, _d;
+                                return __generator(this, function (_e) {
+                                    switch (_e.label) {
                                         case 0:
                                             otelSpanHeaders = (0, arvo_core_1.currentOpenTelemetryHeaders)();
-                                            _d.label = 1;
+                                            _e.label = 1;
                                         case 1:
-                                            _d.trys.push([1, 3, 4, 5]);
+                                            _e.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];
@@ -211,7 +213,7 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                                                     source: this.source,
                                                 })];
                                         case 2:
-                                            _handleOutput = _d.sent();
+                                            _handleOutput = _e.sent();
                                             if (!_handleOutput)
                                                 return [2 /*return*/, []];
                                             outputs = [];
@@ -221,15 +223,14 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                                             else {
                                                 outputs = [_handleOutput];
                                             }
-                                            return [2 /*return*/, (0, utils_1.eventHandlerOutputEventCreator)(outputs, otelSpanHeaders, this.source, event, this.executionunits, function () {
-                                                    var args = [];
-                                                    for (var _i = 0; _i < arguments.length; _i++) {
-                                                        args[_i] = arguments[_i];
-                                                    }
-                                                    return eventFactory.emits.apply(eventFactory, args);
+                                            return [2 /*return*/, (0, utils_1.eventHandlerOutputEventCreator)(outputs, otelSpanHeaders, this.source, event, this.executionunits, function (param, extension) {
+                                                    var _a;
+                                                    return eventFactory.emits(param, extension, {
+                                                        tracer: (_a = opentelemetry.tracer) !== null && _a !== void 0 ? _a : OpenTelemetry_1.ArvoEventHandlerTracer,
+                                                    });
                                                 })];
                                         case 3:
-                                            error_1 = _d.sent();
+                                            error_1 = _e.sent();
                                             (0, arvo_core_1.exceptionToSpan)(error_1);
                                             span.setStatus({
                                                 code: api_1.SpanStatusCode.ERROR,
@@ -246,7 +247,7 @@ var ArvoEventHandler = /** @class */ (function (_super) {
                                                 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,
-                                            }, {});
+                                            }, {}, { tracer: (_d = opentelemetry.tracer) !== null && _d !== void 0 ? _d : OpenTelemetry_1.ArvoEventHandlerTracer });
                                             Object.entries(result.otelAttributes).forEach(function (_a) {
                                                 var key = _a[0], value = _a[1];
                                                 return span.setAttribute("to_emit.0.".concat(key), value);

package/dist/ArvoEventRouter/index.d.ts

@@ -1,8 +1,9 @@
 import { ArvoContract, ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
 import ArvoEventHandler from '../ArvoEventHandler';
 import { IArvoEventRouter } from './types';
-import { SpanKind, Tracer } from '@opentelemetry/api';
+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,10 +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, opentelemetry?: {
-        inheritFrom: 'event' | 'execution';
-        tracer?: Tracer;
-    }): Promise<ArvoEvent[]>;
+    execute(event: ArvoEvent, opentelemetry?: ExecutionOpenTelemetryConfiguration): Promise<ArvoEvent[]>;
     /**
      * Provides the schema for system error events.
      *

package/dist/ArvoEventRouter/index.js

@@ -123,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
@@ -236,12 +238,11 @@ var ArvoEventRouter = /** @class */ (function (_super) {
                                                 })];
                                         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 () {
-                                                    var args = [];
-                                                    for (var _i = 0; _i < arguments.length; _i++) {
-                                                        args[_i] = arguments[_i];
-                                                    }
-                                                    return arvo_core_1.createArvoEvent.apply(void 0, args);
+                                            return [2 /*return*/, (0, utils_1.createHandlerErrorOutputEvent)(error_1, otelSpanHeaders, "sys.".concat(this.source, ".error"), this.source, event, this.executionunits, function (param, extension) {
+                                                    var _a;
+                                                    return (0, arvo_core_1.createArvoEvent)(param, extension, {
+                                                        tracer: (_a = opentelemetry.tracer) !== null && _a !== void 0 ? _a : OpenTelemetry_1.ArvoEventHandlerTracer,
+                                                    });
                                                 })];
                                         case 4:
                                             span.end();

package/dist/MultiArvoEventHandler/index.d.ts

@@ -1,7 +1,8 @@
-import { SpanKind, Tracer } from '@opentelemetry/api';
+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,10 +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';
-        tracer?: Tracer;
-    }): 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
@@ -211,21 +213,19 @@ var MultiArvoEventHandler = /** @class */ (function (_super) {
                                             else {
                                                 outputs = [_handlerOutput];
                                             }
-                                            return [2 /*return*/, (0, utils_1.eventHandlerOutputEventCreator)(outputs, otelSpanHeaders, this.source, event, this.executionunits, function () {
-                                                    var args = [];
-                                                    for (var _i = 0; _i < arguments.length; _i++) {
-                                                        args[_i] = arguments[_i];
-                                                    }
-                                                    return arvo_core_1.createArvoEvent.apply(void 0, args);
+                                            return [2 /*return*/, (0, utils_1.eventHandlerOutputEventCreator)(outputs, otelSpanHeaders, this.source, event, this.executionunits, function (param, extension) {
+                                                    var _a;
+                                                    return (0, arvo_core_1.createArvoEvent)(param, extension, {
+                                                        tracer: (_a = opentelemetry.tracer) !== null && _a !== void 0 ? _a : OpenTelemetry_1.ArvoEventHandlerTracer,
+                                                    });
                                                 })];
                                         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 () {
-                                                    var args = [];
-                                                    for (var _i = 0; _i < arguments.length; _i++) {
-                                                        args[_i] = arguments[_i];
-                                                    }
-                                                    return arvo_core_1.createArvoEvent.apply(void 0, args);
+                                            return [2 /*return*/, (0, utils_1.createHandlerErrorOutputEvent)(error_1, otelSpanHeaders, "sys.".concat(this.source, ".error"), this.source, event, this.executionunits, function (param, extension) {
+                                                    var _a;
+                                                    return (0, arvo_core_1.createArvoEvent)(param, extension, {
+                                                        tracer: (_a = opentelemetry.tracer) !== null && _a !== void 0 ? _a : OpenTelemetry_1.ArvoEventHandlerTracer,
+                                                    });
                                                 })];
                                         case 4:
                                             span.end();

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.8",
+  "version": "1.1.10",
   "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.16",
+    "arvo-core": "^1.1.17",
     "uuid": "^10.0.0",
     "zod": "^3.23.8"
   }