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
99 lines (98 loc) • 5.5 kB
TypeScript
import { type Span } from '@opentelemetry/api';
import { type ArvoEvent, type ArvoOrchestratorContract, type VersionedArvoContract } from 'arvo-core';
import { type EventValidationResult } from '../ArvoOrchestrationUtils/inputValidation';
import type IArvoEventHandler from '../IArvoEventHandler';
import type { IMachineMemory } from '../MachineMemory/interface';
import { SyncEventResource } from '../SyncEventResource/index';
import type { ArvoEventHandlerOpenTelemetryOptions, ArvoEventHandlerOtelSpanOptions } from '../types';
import type { ArvoResumableHandler, ArvoResumableParam, ArvoResumableState } from './types';
/**
* ArvoResumable complements {@link ArvoOrchestrator} by providing imperative
* handler functions for orchestration logic instead of declarative state machines.
* While ArvoOrchestrator excels at complex static workflows with deterministic
* branching, ArvoResumable handles dynamic orchestrations where branching logic
* depends on runtime context and event data.
*
* Use this for dynamic orchestrations with context-dependent branching
* or when preferring imperative programming patterns over state machines.
*/
export declare class ArvoResumable<TMemory extends Record<string, any> = Record<string, any>, TSelfContract extends ArvoOrchestratorContract = ArvoOrchestratorContract, TServiceContract extends Record<string, VersionedArvoContract<any, any>> = Record<string, VersionedArvoContract<any, any>>> implements IArvoEventHandler {
/** Computational cost metric for workflow operations */
readonly executionunits: number;
/** Resource manager for state synchronization and memory access */
readonly syncEventResource: SyncEventResource<ArvoResumableState<TMemory>>;
/** Versioned handler map for processing workflow events. */
readonly handler: ArvoResumableHandler<ArvoResumableState<TMemory>, TSelfContract, TServiceContract>;
/** Optional domains for routing events */
readonly defaultEventEmissionDomains: Required<NonNullable<ArvoResumableParam<TMemory, TSelfContract, TServiceContract>['defaultEventEmissionDomains']>>;
/** OpenTelemetry span configuration for observability */
readonly spanOptions: ArvoEventHandlerOtelSpanOptions;
/** Source identifier from the first registered machine */
readonly source: string;
/**
* Contract definitions for the resumable's event interface.
* Defines accepted events, emitted events, and service integrations.
*/
readonly contracts: {
/**
* Self contract defining initialization input and completion output structures.
*/
self: TSelfContract;
/**
* Service contracts defining external service interfaces.
*/
services: TServiceContract;
};
/** Whether this resumable requires resource locking for concurrent safety */
get requiresResourceLocking(): boolean;
/** Memory interface for state persistence and retrieval */
get memory(): IMachineMemory<ArvoResumableState<TMemory>>;
/** The contract-defined domain for the handler */
get domain(): string | null;
constructor(param: ArvoResumableParam<TMemory, TSelfContract, TServiceContract>);
/**
* Validates incoming event against self or service contracts.
*
* Resolves the appropriate contract (self for initialization, service for responses),
* validates schema compatibility, and ensures event data matches contract requirements.
*
* See {@link validateInputEvent} for more infromation
*/
protected validateInput(event: ArvoEvent, span?: Span): EventValidationResult;
/**
* Executes the workflow handler for an incoming event.
*
* Processes initialization events or service responses through the versioned handler,
* manages state persistence, tracks expected events, and generates output events.
* Workflows in 'done' status ignore subsequent events without processing.
*
* For violation errors (transaction, config, contract), the error is thrown to enable
* retry mechanisms. For non-violation errors, system error events are emitted to the
* workflow initiator, and the workflow enters a terminal failure state.
*
* @param event - The incoming event triggering handler execution
* @param opentelemetry - Optional OpenTelemetry configuration for tracing
* @returns Object containing emitted events from the handler or system errors
*
* @throws {TransactionViolation} When distributed lock acquisition fails
* @throws {ConfigViolation} When handler resolution or contract validation fails
* @throws {ContractViolation} When event schema validation fails
* @throws {ExecutionViolation} When workflow execution encounters critical errors defined by the handler developer
*/
execute(event: ArvoEvent, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): Promise<{
events: ArvoEvent[];
}>;
get systemErrorSchema(): import("arvo-core").ArvoContractRecord<`sys.arvo.orc.${string}.error`, import("zod").ZodObject<{
errorName: import("zod").ZodString;
errorMessage: import("zod").ZodString;
errorStack: import("zod").ZodNullable<import("zod").ZodString>;
}, "strip", import("zod").ZodTypeAny, {
errorName: string;
errorMessage: string;
errorStack: string | null;
}, {
errorName: string;
errorMessage: string;
errorStack: string | null;
}>>;
}