arvo-event-handler 2.0.4 → 2.1.0

package/dist/AbstractArvoEventHandler/index.d.ts

@@ -1,5 +1,5 @@
 import { ArvoContractRecord, ArvoEvent } from 'arvo-core';
-import { OpenTelemetryConfig } from '../OpenTelemetry/types';
+import { ArvoEventHandlerOpenTelemetryOptions } from '../types';
 /**
  * Abstract base class for Arvo event handlers.
  *
@@ -11,27 +11,14 @@ import { OpenTelemetryConfig } from '../OpenTelemetry/types';
  * ```
  */
 export default abstract class AbstractArvoEventHandler {
-    /**
-     * The source identifier for the event handler.
-     *
-     * @description
-     * Uniquely identifies the '<ArvoEvent>.type' of events processed by this handler.
-     *
-     * @remarks
-     * - Should be unique across all event handlers in the system
-     * - Typically follows a dotted notation pattern (e.g., 'domain.entity.action')
-     * - Used for routing, logging, and observability purposes
-     */
-    abstract readonly source: string;
     /**
      * Executes the event handling logic for a given Arvo event.
      *
      * @abstract
-     * @param {ArvoEvent} event - The Arvo event to be processed. This event should conform
+     * @param event - The Arvo event to be processed. This event should conform
      *                           to the expected schema for the specific handler implementation.
-     * @param {OpenTelemetryConfig} opentelemetry - Configuration for OpenTelemetry
-     *                                                             integration, including tracing options
-     *                                                             and context inheritance settings.
+     * @param opentelemetry - Configuration for OpenTelemetry integration
+     *
      * @returns {Promise<ArvoEvent[]>} A promise that resolves to an array of resulting Arvo events.
      *                                 These events represent the outcome of processing the input event.
      *
@@ -64,7 +51,7 @@ export default abstract class AbstractArvoEventHandler {
      * - Properly handling span lifecycle (creation and completion)
      * - Propagating context appropriately
      */
-    abstract execute(event: ArvoEvent, opentelemetry?: OpenTelemetryConfig): Promise<ArvoEvent[]>;
+    abstract execute(event: ArvoEvent, opentelemetry: ArvoEventHandlerOpenTelemetryOptions): Promise<ArvoEvent[]>;
     /**
      * Provides the schema for system error events.
      *

package/dist/ArvoEventHandler/helpers.d.ts

@@ -2,32 +2,21 @@ import { ArvoContract } from 'arvo-core';
 import { IArvoEventHandler } from './types';
 import ArvoEventHandler from '.';
 /**
- * Creates an ArvoEventHandler instance for a given ArvoContract.
+ * Creates an ArvoEventHandler for processing events defined by a specific contract.
+ * Each handler manages event validation, processing, and telemetry for its contract.
  *
- * @template TContract - The type of ArvoContract this handler is associated with.
- * @param param - The configuration parameters for the event handler.
- * @returns A new instance of ArvoEventHandler<TContract>.
- *
- * @remarks
- * This function is a factory for creating ArvoEventHandler instances.
- * It encapsulates the creation process and provides a convenient way to instantiate
- * handlers for specific Arvo contracts.
+ * @param param Configuration including contract, execution metrics and version handlers
+ * @returns Configured ArvoEventHandler instance for the specified contract
  *
  * @example
- * ```typescript
- * const myContract = new ArvoContract(...);
- * const myHandler = createArvoEventHandler({
- *   contract: myContract,
- *   executionunits: 100,
+ * const handler = createArvoEventHandler({
+ *   contract: userContract,
+ *   executionunits: 10,
  *   handler: {
- *      '0.0.1': async ({ event }) => {
- *          // Handler implementation
- *      }
+ *     '1.0.0': async ({ event }) => {
+ *       // Process event according to contract v1.0.0
+ *     }
  *   }
  * });
- * ```
- *
- * @see {@link IArvoEventHandler} for the full configuration options
- * @see {@link ArvoEventHandler} for the handler class implementation
  */
 export declare const createArvoEventHandler: <TContract extends ArvoContract>(param: IArvoEventHandler<TContract>) => ArvoEventHandler<TContract>;

package/dist/ArvoEventHandler/helpers.js

@@ -6,33 +6,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createArvoEventHandler = void 0;
 var _1 = __importDefault(require("."));
 /**
- * Creates an ArvoEventHandler instance for a given ArvoContract.
+ * Creates an ArvoEventHandler for processing events defined by a specific contract.
+ * Each handler manages event validation, processing, and telemetry for its contract.
  *
- * @template TContract - The type of ArvoContract this handler is associated with.
- * @param param - The configuration parameters for the event handler.
- * @returns A new instance of ArvoEventHandler<TContract>.
- *
- * @remarks
- * This function is a factory for creating ArvoEventHandler instances.
- * It encapsulates the creation process and provides a convenient way to instantiate
- * handlers for specific Arvo contracts.
+ * @param param Configuration including contract, execution metrics and version handlers
+ * @returns Configured ArvoEventHandler instance for the specified contract
  *
  * @example
- * ```typescript
- * const myContract = new ArvoContract(...);
- * const myHandler = createArvoEventHandler({
- *   contract: myContract,
- *   executionunits: 100,
+ * const handler = createArvoEventHandler({
+ *   contract: userContract,
+ *   executionunits: 10,
  *   handler: {
- *      '0.0.1': async ({ event }) => {
- *          // Handler implementation
- *      }
+ *     '1.0.0': async ({ event }) => {
+ *       // Process event according to contract v1.0.0
+ *     }
  *   }
  * });
- * ```
- *
- * @see {@link IArvoEventHandler} for the full configuration options
- * @see {@link ArvoEventHandler} for the handler class implementation
  */
 var createArvoEventHandler = function (param) { return new _1.default(param); };
 exports.createArvoEventHandler = createArvoEventHandler;

package/dist/ArvoEventHandler/index.d.ts

@@ -1,110 +1,75 @@
-import { ArvoContract, ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
-import { IArvoEventHandler } from './types';
-import { SpanKind } from '@opentelemetry/api';
+import { ArvoContract, ArvoEvent } from 'arvo-core';
+import { IArvoEventHandler, ArvoEventHandlerFunction } from './types';
+import { SpanOptions } from '@opentelemetry/api';
 import AbstractArvoEventHandler from '../AbstractArvoEventHandler';
-import { OpenTelemetryConfig } from '../OpenTelemetry/types';
+import { ArvoEventHandlerOpenTelemetryOptions } from '../types';
 /**
- * Represents an event handler for Arvo contracts.
+ * ArvoEventHandler manages the execution and processing of events in accordance with
+ * Arvo contracts. This class serves as the cornerstone for event handling operations,
+ * integrating contract validation, telemetry management, and event processing.
  *
- * @template TContract - The type of ArvoContract this handler is associated with.
- *
- * @remarks
- * This class is the core component for handling Arvo events. It encapsulates the logic
- * for executing event handlers, managing telemetry, and ensuring proper contract validation.
- * It's designed to be flexible and reusable across different Arvo contract implementations.
+ * The handler implements a robust execution flow that ensures proper validation,
+ * versioning, and error handling while maintaining detailed telemetry through
+ * OpenTelemetry integration. It supports versioned contracts and handles routing
+ * of both successful and error events.
  */
 export default class ArvoEventHandler<TContract extends ArvoContract> extends AbstractArvoEventHandler {
-    /** The contract of the handler to which it is bound */
+    /** Contract instance that defines the event schema and validation rules */
     readonly contract: TContract;
-    /** The default execution cost associated with this handler */
+    /** Computational cost metric associated with event handling operations */
     readonly executionunits: number;
+    /** OpenTelemetry configuration for event handling spans */
+    readonly spanOptions: SpanOptions;
+    /** Version-specific event handler implementation map */
+    readonly handler: ArvoEventHandlerFunction<TContract>;
+    /** The source identifier for events produced by this handler */
+    get source(): TContract['type'];
     /**
-     * The source identifier for events produced by this handler
-     *
-     * @remarks
-     * For all the events which are emitted by the handler, this is
-     * the source field value of them all.
-     */
-    readonly source: string;
-    readonly openInferenceSpanKind: OpenInferenceSpanKind;
-    readonly arvoExecutionSpanKind: ArvoExecutionSpanKind;
-    readonly openTelemetrySpanKind: SpanKind;
-    private readonly _handler;
-    /**
-     * Creates an instance of ArvoEventHandler.
+     * Initializes a new ArvoEventHandler instance with the specified contract and configuration.
+     * Validates handler implementations against contract versions during initialization.
      *
-     * @param param - The configuration parameters for the event handler.
+     * The constructor ensures that handler implementations exist for all supported contract
+     * versions and configures OpenTelemetry span attributes for monitoring event handling.
      *
-     * @throws {Error} Throws an error if the provided source is invalid.
-     *
-     * @remarks
-     * The constructor validates the source parameter against the CloudEventContextSchema.
-     * If no source is provided, it defaults to the contract's accepted event type.
+     * @param param - Handler configuration including contract, execution units, and handler implementations
+     * @throws When handler implementations are missing for any contract version
      */
     constructor(param: IArvoEventHandler<TContract>);
     /**
-     * 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. Default is inherit from event and internal tracer
-     * @returns A promise that resolves to an array of resulting ArvoEvents.
-     *
-     * This method performs the following steps:
-     * 1. Creates an OpenTelemetry span for the execution.
-     * 2. Validates the input event against the contract.
-     * 3. Executes the handler function.
-     * 4. Creates and returns the result event(s).
-     * 5. Handles any errors and creates an error event if necessary.
-     *
-     * All telemetry data is properly set and propagated throughout the execution.
-     *
-     * @example
-     * ```typescript
-     * const contract = createArvoContract({ ... })
-     * const handler = createArvoEventHandler({
-     *    contract: contract,
-     *    ...
-     * });
-     * const inputEvent: ArvoEvent<...> = createArvoEvent({ ... });
-     * const resultEvents = await handler.execute(inputEvent);
-     * ```
-     *
-     * @throws All error throw during the execution are returned as a system error event
-     *
-     * **Routing**
-     *
-     * The routing of the resulting events is determined as follows:
-     * - The `to` field of the output event is set in this priority:
-     *   1. The `to` field provided by the handler result
-     *   2. The `redirectto` field from the input event
-     *   3. The `source` field from the input event (as a form of reply)
-     * - For system error events, the `to` field is always set to the `source` of the input event.
-     *
-     * **Telemetry**
-     *
-     * - Creates a new span for each execution as per the traceparent and tracestate field
-     *   of the event. If those are not present, then a brand new span is created and distributed
-     *   tracing is disabled
-     * - Sets span attributes for input and output events
-     * - Propagates trace context to output events
-     * - Handles error cases and sets appropriate span status
+     * Processes an event according to the contract specifications. The execution flow encompasses
+     * span management, validation, handler execution, and error processing phases.
+     *
+     * Event Routing Logic:
+     * - Success events: Routes based on priority (handler result -> redirectto -> source)
+     * - Error events: Always routes back to the source
+     *
+     * Telemetry Integration:
+     * - Creates and manages OpenTelemetry spans for execution tracking
+     * - Propagates trace context through the event chain
+     * - Records execution metrics and error details
+     *
+     * Version Resolution:
+     * - Extracts version from event dataschema
+     * - Falls back to latest version if unspecified
+     * - Validates event data against versioned contract schema
+     *
+     * Error Handling:
+     * - Converts all errors to system error events
+     * - Maintains telemetry context for error scenarios
+     * - Ensures proper error event routing
+     *
+     * @param event - The event to process
+     * @param opentelemetry - Configuration for OpenTelemetry context inheritance
+     * @returns Promise resolving to array of result events or error event
      */
-    execute(event: ArvoEvent, opentelemetry?: OpenTelemetryConfig): Promise<ArvoEvent[]>;
+    execute(event: ArvoEvent, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): 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 contract's accepted event type and '.error'.
-     * The schema used for these error events is the standard ArvoErrorSchema.
+     * Provides access to the system error event schema configuration.
+     * The schema defines the structure of error events emitted during execution failures.
      *
-     * @example
-     * // If the contract's accepted event type is 'user.created'
-     * // The system error event type would be 'sys.user.created.error'
+     * Error events follow the naming convention: sys.<contract-type>.error
+     * For example, a contract handling 'user.created' events will emit error events
+     * with the type 'sys.user.created.error'.
      */
     get systemErrorSchema(): import("arvo-core").ArvoContractRecord<`sys.${string}.error`, import("zod").ZodObject<{
         errorName: import("zod").ZodString;