arvo-event-handler
Version:
A complete set of orthogonal event handler and orchestration primitives for Arvo based applications, featuring declarative state machines (XState), imperative resumables for agentic workflows, contract-based routing, OpenTelemetry observability, and in-me
80 lines (79 loc) • 4.12 kB
TypeScript
import { type Span } from '@opentelemetry/api';
import { type ArvoEvent, type ArvoOrchestrationSubjectContent, type ArvoOrchestratorContract, type ArvoSemanticVersion, type OpenTelemetryHeaders, type VersionedArvoContract } from 'arvo-core';
import type IArvoEventHandler from '../../IArvoEventHandler';
import type { SyncEventResource } from '../../SyncEventResource';
import { type ArvoEventHandlerOpenTelemetryOptions, type ArvoEventHandlerOtelSpanOptions, type NonEmptyArray } from '../../types';
import { type OrchestrationExecutionMemoryRecord } from '../orchestrationExecutionState';
import type { ArvoOrchestrationHandlerType } from '../types';
/**
* Configuration context for orchestration execution.
* Contains all resources and settings needed for the execution lifecycle.
*/
export type OrchestrationExecutionContext<TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>> = {
/** Event triggering the orchestration */
event: ArvoEvent;
/** OpenTelemetry configuration for tracing */
opentelemetry: ArvoEventHandlerOpenTelemetryOptions;
/** Source identifier for the orchestrator */
source: string;
/** Resource manager for state and lock operations */
syncEventResource: SyncEventResource<TState>;
/** Maximum execution units per cycle */
executionunits: number;
/** Optional domains for system error routing */
systemErrorDomain: NonEmptyArray<string | null>;
/** Self contract defining orchestrator interface */
selfContract: VersionedArvoContract<ArvoOrchestratorContract, ArvoSemanticVersion>;
/** Type of orchestration handler */
_handlerType: ArvoOrchestrationHandlerType;
/** OpenTelemetry span configuration */
spanOptions: ArvoEventHandlerOtelSpanOptions & {
spanName: NonNullable<ArvoEventHandlerOtelSpanOptions['spanName']>;
};
};
/**
* Core execution function signature for orchestration logic.
* Receives prepared context and returns emitted events with new state.
*/
export type CoreExecutionFn<TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>> = (params: {
/** OpenTelemetry span for tracing */
span: any;
/** Current OpenTelemetry headers */
otelHeaders: OpenTelemetryHeaders;
/** Parent orchestration subject if nested */
orchestrationParentSubject: string | null;
/** ID of the initialization event */
initEventId: string;
/** Parsed event subject content */
parsedEventSubject: ArvoOrchestrationSubjectContent;
/** Current persisted state or null for new orchestrations */
state: TState | null;
/** Type of handler executing */
_handlerType: ArvoOrchestrationHandlerType;
}) => Promise<{
/** Events to emit from this execution */
emittables: ArvoEvent[];
/** New state to persist */
newState: TState;
}>;
/**
* Helper to log and return execution results.
* @returns The same result after logging
*/
export declare const returnEventsWithLogging: (param: Awaited<ReturnType<IArvoEventHandler["execute"]>>, span: Span) => Awaited<ReturnType<IArvoEventHandler["execute"]>>;
/**
* Wraps orchestration execution with infrastructure concerns.
*
* Provides a complete execution wrapper that handles:
* - OpenTelemetry span creation and management
* - Event subject validation and parsing
* - Lock acquisition for concurrent safety
* - State retrieval and persistence
* - Error handling with system error event generation
* - Lock release in all scenarios
*
* This wrapper ensures consistent behavior across all orchestration handlers
* while allowing custom core logic via the execution function parameter.
* @returns Emitted events from successful execution or error handling
*/
export declare const executeWithOrchestrationWrapper: <TState extends OrchestrationExecutionMemoryRecord<Record<string, any>>>({ event, opentelemetry, spanOptions, source, syncEventResource, executionunits, systemErrorDomain, selfContract, _handlerType, }: OrchestrationExecutionContext<TState>, coreExecutionFn: CoreExecutionFn<TState>) => Promise<Awaited<ReturnType<IArvoEventHandler["execute"]>>>;