arvo-event-handler/dist/ArvoOrchestrationUtils/handlerErrors.d.ts

Type-safe event handler system with versioning, telemetry, and contract validation for distributed Arvo event-driven architectures, featuring routing and multi-handler support.

import { type Span } from '@opentelemetry/api';
import { type ArvoContract, type ArvoEvent, type ArvoSemanticVersion, type OpenTelemetryHeaders, type VersionedArvoContract, type ViolationError } from 'arvo-core';
import type { SyncEventResource } from '../SyncEventResource';
import type { OrchestrationExecutionMemoryRecord } from './orchestrationExecutionState';
import { type ArvoOrchestrationHandlerType } from './types';
/**
 * Parameters for creating system error events during orchestration failures.
 */
export type CreateSystemErrorEventsParams = {
    /** The error that occurred */
    error: unknown;
    /** Event that triggered the error */
    event: ArvoEvent;
    /** OpenTelemetry headers for tracing */
    otelHeaders: OpenTelemetryHeaders;
    /** Parent orchestration subject if nested */
    orchestrationParentSubject: string | null;
    /** ID of the initiating event */
    initEventId: string | null;
    /** Self contract defining error schema */
    selfContract: VersionedArvoContract<ArvoContract, ArvoSemanticVersion>;
    /** Optional domains for error event routing */
    systemErrorDomain?: (string | null)[];
    /** Execution units for error events */
    executionunits: number;
    /** Source identifier */
    source: string;
    /** Domain for error events */
    domain: string | null;
    /** Type of handler reporting the error */
    handlerType: ArvoOrchestrationHandlerType;
};
/**
 * Creates standardized system error events for orchestration failures.
 *
 * Generates error events that route back to the workflow initiator, preserving
 * tracing context and orchestration hierarchy. Supports multiple domains for
 * error distribution.
 *
 * @param params - Error event creation parameters
 * @returns Array of system error events for each configured domain
 */
export declare const createSystemErrorEvents: ({ error, event, otelHeaders, orchestrationParentSubject: _orchestrationParentSubject, initEventId, selfContract, systemErrorDomain, executionunits, source, domain, handlerType, }: CreateSystemErrorEventsParams & {
    error: Error;
}) => ArvoEvent[];
/**
 * Handles errors during orchestration execution with proper state management.
 *
 * Processes errors by determining if they are violations (retriable) or execution
 * errors (terminal). For execution errors, persists failure state and generates
 * system error events. For violations, returns the error to be thrown without
 * state persistence.
 *
 * @returns Either the violation error to throw or system error events to emit
 */
export declare const handleOrchestrationErrors: (_handlerType: ArvoOrchestrationHandlerType, param: CreateSystemErrorEventsParams & {
    syncEventResource: SyncEventResource<OrchestrationExecutionMemoryRecord<Record<string, any>>>;
}, span: Span) => Promise<{
    errorToThrow: ViolationError;
    events: null;
} | {
    errorToThrow: null;
    events: ArvoEvent[];
}>;