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
81 lines (80 loc) • 4.36 kB
TypeScript
import { type ArvoEvent } from 'arvo-core';
import type IArvoEventHandler from '../IArvoEventHandler';
import type { IMachineExectionEngine } from '../MachineExecutionEngine/interface';
import type { IMachineMemory } from '../MachineMemory/interface';
import type { IMachineRegistry } from '../MachineRegistry/interface';
import { SyncEventResource } from '../SyncEventResource';
import type { ArvoEventHandlerOpenTelemetryOptions, ArvoEventHandlerOtelSpanOptions } from '../types';
import type { ArvoOrchestratorParam, MachineMemoryRecord } from './types';
/**
* Orchestrates state machine execution and lifecycle management.
*
* Coordinates machine resolution, state persistence, event processing, and error handling
* for Arvo's event-driven orchestration workflows. Manages the complete lifecycle from
* event receipt through machine execution to emitting result events.
*/
export declare class ArvoOrchestrator implements IArvoEventHandler {
/** Computational cost metric associated with event handling operations */
readonly executionunits: number;
/** Registry containing available state machines */
readonly registry: IMachineRegistry;
/** Engine responsible for executing state machine logic */
readonly executionEngine: IMachineExectionEngine;
/** Resource manager for state synchronization and memory access */
readonly syncEventResource: SyncEventResource<MachineMemoryRecord>;
/** Domains for routing events */
readonly defaultEventEmissionDomains: Required<NonNullable<ArvoOrchestratorParam['defaultEventEmissionDomains']>>;
/** OpenTelemetry span configuration for observability */
readonly spanOptions: ArvoEventHandlerOtelSpanOptions;
/** Source identifier from the first registered machine */
get source(): any;
/** Whether this orchestrator requires resource locking for concurrent safety */
get requiresResourceLocking(): boolean;
/** Memory interface for state persistence and retrieval */
get memory(): IMachineMemory<MachineMemoryRecord>;
/** The contract-defined domain for the handler */
get domain(): string | null;
constructor({ executionunits, memory, registry, executionEngine, requiresResourceLocking, defaultEventEmissionDomains, spanOptions, }: ArvoOrchestratorParam);
/**
* Executes state machine orchestration for an incoming event.
*
* Performs the complete orchestration workflow: resolves the appropriate machine,
* validates input, executes the machine logic, processes emitted events, and persists
* the new state. Handles both new orchestrations and continuation of existing ones.
*
* For violation errors (transaction, execution, contract, config), the error is thrown
* to enable retry mechanisms. For non-violation errors, system error events are emitted
* to the workflow initiator, and the orchestration enters a terminal failure state.
*
* @param event - The incoming event triggering orchestration
* @param opentelemetry - Optional OpenTelemetry configuration for tracing
* @returns Object containing emitted events from the orchestration or system errors
*
* @throws {TransactionViolation} When lock acquisition or state operations fail (retriable)
* @throws {ContractViolation} When event data doesn't match contract schema (retriable)
* @throws {ConfigViolation} When machine resolution fails or version is missing (retriable)
* @throws {ExecutionViolation} When workflow execution encounters critical errors defined by the handler developer
*/
execute(event: ArvoEvent, opentelemetry?: ArvoEventHandlerOpenTelemetryOptions): Promise<{
events: ArvoEvent[];
}>;
/**
* Provides access to the system error event schema configuration.
*/
get systemErrorSchema(): {
type: any;
schema: 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;
}>;
};
}