Class ArvoResumable<TMemory, TSelfContract, TServiceContract>

ArvoResumable - A stateful orchestration handler for managing distributed workflows

ArvoResumable provides a handler-based approach to workflow orchestration that prioritizes explicit control and simplicity over declarative abstractions. It excels at straightforward request-response patterns and linear workflows while maintaining full type safety and contract validation throughout the execution lifecycle.

This class addresses fundamental issues in event-driven architecture including:

  • Contract management with runtime validation and type safety
  • Graduated complexity allowing simple workflows to remain simple
  • Unified event handling across initialization and service responses
  • Explicit state management without hidden abstractions

Key capabilities:

  • Handler-based workflow orchestration with explicit state control
  • Contract-driven event validation with runtime schema enforcement
  • Distributed resource locking for transaction safety
  • Comprehensive OpenTelemetry integration for observability
  • Automatic error handling with system error event generation
  • Support for orchestrator chaining and nested workflow patterns
  • Domain-based event routing and organization

Unlike state machine approaches, ArvoResumable uses imperative handler functions that provide direct control over workflow logic. This makes debugging easier and reduces the learning curve for teams familiar with traditional programming patterns.

See

Type Parameters

  • TMemory extends Record<string, any> = Record<string, any>
  • TSelfContract extends ArvoOrchestratorContract = ArvoOrchestratorContract
  • TServiceContract extends Record<string, VersionedArvoContract<any, any>> = Record<string, VersionedArvoContract<any, any>>

Hierarchy (view full)

Constructors

constructor

Properties

contracts executionunits handler source syncEventResource systemErrorDomain?

Accessors

domain memory requiresResourceLocking systemErrorSchema

Methods

createEmittableEvent execute validateInput

Constructors

constructor

Properties

Readonlycontracts

contracts: {
    self: TSelfContract;
    services: TServiceContract;
}

Readonlyexecutionunits

executionunits: number

Readonlyhandler

handler: ArvoResumableHandler<ArvoResumableState<TMemory>, TSelfContract, TServiceContract>

Readonlysource

source: string

Unique identifier for the event handler source system

ReadonlysyncEventResource

syncEventResource: SyncEventResource<ArvoResumableState<TMemory>>

Optional ReadonlysystemErrorDomain

systemErrorDomain?: (null | string)[] = []

Accessors

domain

memory

requiresResourceLocking

AbstractsystemErrorSchema

  • get systemErrorSchema(): ArvoContractRecord<`sys.arvo.orc.${string}.error`, ZodObject<{
        errorMessage: ZodString;
        errorName: ZodString;
        errorStack: ZodNullable<ZodString>;
    }, "strip", ZodTypeAny, {
        errorMessage: string;
        errorName: string;
        errorStack: null | string;
    }, {
        errorMessage: string;
        errorName: string;
        errorStack: null | string;
    }>>

  • Provides the schema for system error events.

    Returns ArvoContractRecord<`sys.arvo.orc.${string}.error`, ZodObject<{
        errorMessage: ZodString;
        errorName: ZodString;
        errorStack: ZodNullable<ZodString>;
    }, "strip", ZodTypeAny, {
        errorMessage: string;
        errorName: string;
        errorStack: null | string;
    }, {
        errorMessage: string;
        errorName: string;
        errorStack: null | string;
    }>>

    An object containing the error event type and schema.

    Description

    This getter should define the structure for system error events that may be emitted when an unexpected error occurs during event handling.

    Remarks

    • The returned ArvoContractRecord typically includes:
      • type: A string representing the error event type.
      • schema: The schema definition for the error event.
    • Implementations should ensure that the error schema is consistent with the overall system's error handling strategy.
    • The error event type often follows a pattern like 'sys.[eventType].error'.

    Example

    public get systemErrorSchema(): ArvoContractRecord {
      return {
        type: 'sys.myEvent.error',
        schema: MyCustomErrorSchema
      };
    }

Methods

ProtectedcreateEmittableEvent

  • createEmittableEvent(event, otelHeaders, orchestrationParentSubject, sourceEvent, selfVersionedContract, initEventId, _domain): ArvoEvent<Record<string, any>, Record<string,
        | null
        | string
        | number
        | boolean>, string>

  • Creates emittable event from execution result

    Parameters

    • event: EnqueueArvoEventActionParam

      Source event to emit

    • otelHeaders: OpenTelemetryHeaders

      OpenTelemetry headers

    • orchestrationParentSubject: null | string

      Parent orchestration subject

    • sourceEvent: ArvoEvent<Record<string, any>, Record<string,
          | null
          | string
          | number
          | boolean>, string>

      Original triggering event

    • selfVersionedContract: VersionedArvoContract<TSelfContract, `${number}.${number}.${number}`>

      The self versioned contract

    • initEventId: string

      The id of the event which initiated the orchestration in the first place

    • _domain: null | string

      The domain of the event.

    Returns ArvoEvent<Record<string, any>, Record<string,
        | null
        | string
        | number
        | boolean>, string>

    Throws

    On schema/contract mismatch

    Throws

    On invalid parentSubject$$ format

execute

  • execute(event, opentelemetry): Promise<{
        events: ArvoEvent<Record<string, any>, Record<string,
            | null
            | string
            | number
            | boolean>, string>[];
    }>

  • Executes the orchestration workflow for an incoming event

    Parameters

    • event: ArvoEvent<Record<string, any>, Record<string,
          | null
          | string
          | number
          | boolean>, string>

      The triggering event to process

    • opentelemetry: ArvoEventHandlerOpenTelemetryOptions

      OpenTelemetry configuration for trace inheritance

    Returns Promise<{
        events: ArvoEvent<Record<string, any>, Record<string,
            | null
            | string
            | number
            | boolean>, string>[];
    }>

    Object containing domained events

    Throws

    When distributed lock acquisition fails

    Throws

    When handler resolution or contract validation fails

    Throws

    When event schema validation fails

    Throws

    When workflow execution encounters critical errors

ProtectedvalidateInput

  • validateInput(event): {
        contractType: "self" | "service";
    }

  • Parameters

    • event: ArvoEvent<Record<string, any>, Record<string,
          | null
          | string
          | number
          | boolean>, string>

    Returns {
        contractType: "self" | "service";
    }

    • contractType: "self" | "service"

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods