arvo-event-handler 1.1.8 → 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

@@ -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

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

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

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.9",
   "description": "This package contains class and function for event handlers in an Arvo Event Driven system",
   "main": "dist/index.js",
   "scripts": {