Skip to main content

API Reference

Complete API documentation for the @hex-di/saga library.

Steps​

defineStep​

Creates a type-safe step definition.

function defineStep<TName, TInput, TOutput, TError, TPort>(
  config: StepConfig<TName, TInput, TOutput, TError, TPort>
): StepDefinition<TName, TInput, TOutput, TError, TPort>;
ParameterTypeDescription
config.nameTNameLiteral string name for the step
config.portTPortPort dependency for service resolution
config.execute(input: TInput, port: TPort) => ResultAsync<TOutput, TError>Step execution function
config.compensate(context: CompensationContext) => ResultAsync<void, unknown>Optional compensation function
config.retryRetryConfigOptional retry configuration
config.timeoutnumberOptional timeout in milliseconds
config.condition(input, results) => booleanOptional condition for execution

StepDefinition​

The type returned by defineStep.

interface StepDefinition<TName, TInput, TOutput, TError, TPort> {
  name: TName;
  port: TPort;
  execute: (input: TInput, port: TPort) => ResultAsync<TOutput, TError>;
  compensate?: (context: CompensationContext) => ResultAsync<void, unknown>;
  retry?: RetryConfig;
  timeout?: number;
  condition?: (input: TInput, results: any) => boolean;
}

StepContext​

Context available during step execution.

interface StepContext {
  executionId: string;
  stepName: string;
  stepIndex: number;
  attemptNumber: number;
  startedAt: Date;
}

CompensationContext​

Context passed to compensation functions.

interface CompensationContext<TInput, TResults, TPort> {
  input: TInput;
  results: TResults;
  originalError: unknown;
  port: TPort;
  executionId: string;
  stepName: string;
}

RetryConfig​

Configuration for step retry behavior.

interface RetryConfig {
  maxAttempts: number;
  delay: number;
  backoff?: "fixed" | "linear" | "exponential";
}

Sagas​

defineSaga​

Creates a saga builder with progressive type safety.

function defineSaga<TName extends string>(name: TName): SagaBuilder<TName>;

SagaDefinition​

The type returned by the saga builder.

interface SagaDefinition<TName, TInput, TOutput, TSteps> {
  name: TName;
  input: TInput;
  output: TOutput;
  steps: TSteps[];
  options?: SagaOptions;
  validate?: (input: TInput) => Result<TInput, unknown>;
  version?: string;
}

SagaOptions​

Configuration options for saga behavior.

interface SagaOptions {
  compensationStrategy?: "sequential" | "parallel" | "best-effort";
  persistent?: boolean;
  maxConcurrency?: number;
  timeout?: number;
  hooks?: SagaHooks;
  metadata?: Record<string, unknown>;
  checkpointPolicy?: "swallow" | "abort" | "warn";
}

SagaHooks​

Lifecycle hooks for saga execution.

interface SagaHooks {
  beforeStep?: (context: StepHookContext) => Promise<void>;
  afterStep?: (context: StepHookResultContext) => Promise<void>;
  beforeCompensation?: (context: CompensationHookContext) => Promise<void>;
  afterCompensation?: (context: CompensationResultHookContext) => Promise<void>;
}

AccumulatedResults​

Type representing accumulated step outputs.

type AccumulatedResults<TSteps> = {
  [K in StepName<TSteps>]: StepOutput<TSteps, K>;
};

Compensation​

executeCompensation​

Executes compensation for completed steps.

function executeCompensation(
  plan: CompensationPlan,
  context: CompensationExecutionContext
): Promise<CompensationResult>;

CompensationStrategy​

Available compensation strategies.

type CompensationStrategy = "sequential" | "parallel" | "best-effort";

CompensationResult​

Result of compensation execution.

interface CompensationResult {
  compensatedSteps: string[];
  failedSteps: string[];
  errors: Record<string, unknown>;
  allSucceeded: boolean;
  deadLetterEntries: string[];
}

CompensationPlan​

Execution plan for compensation.

interface CompensationPlan {
  steps: CompensationPlanStep[];
  strategy: CompensationStrategy;
}

DeadLetterQueue​

Queue for failed compensations.

class DeadLetterQueue {
  add(entry: Omit<DeadLetterEntry, "id">): Promise<string>;
  retry(id: string, fn: () => Promise<any>): Promise<Result<any, unknown>>;
  list(filters?: DeadLetterFilters): Promise<DeadLetterEntry[]>;
  acknowledge(id: string): Promise<void>;
  size(): number;
}

Runtime​

createSagaRunner​

Creates a saga runner instance.

function createSagaRunner(portResolver: PortResolver, config?: SagaRunnerConfig): SagaRunner;

executeSaga​

Type-safe wrapper for saga execution.

function executeSaga<T extends AnySagaDefinition>(
  runner: SagaRunner,
  saga: T,
  input: InferSagaInput<T>,
  options?: ExecuteOptions
): ResultAsync<InferSagaOutput<T>, SagaError>;

SagaRunner​

Interface for saga execution and management.

interface SagaRunner {
  execute<T>(saga: T, input: Input<T>, options?: ExecuteOptions): ResultAsync<Output<T>, SagaError>;
  resume(executionId: string): ResultAsync<unknown, SagaError>;
  cancel(executionId: string): ResultAsync<void, SagaError>;
  getStatus(executionId: string): ResultAsync<SagaStatus, ManagementError>;
  subscribe(executionId: string, listener: SagaEventListener): Unsubscribe;
  getTrace(executionId: string): ExecutionTrace | null;
}

ExecuteOptions​

Options for saga execution.

interface ExecuteOptions {
  executionId?: string;
  timeout?: number;
  signal?: AbortSignal;
  metadata?: Record<string, unknown>;
  listeners?: SagaEventListener[];
}

SagaRunnerConfig​

Configuration for saga runner.

interface SagaRunnerConfig {
  persister?: SagaPersister;
  tracingHook?: SagaTracingHook;
  tracer?: TracerLike;
  suppressGxpWarnings?: boolean;
}

PortResolver​

Function to resolve port dependencies.

type PortResolver = (port: Port<any>) => Promise<any>;

Ports​

sagaPort​

Creates a saga execution port.

function sagaPort<TName, TInput, TOutput, TError>(): (
  name: TName
) => SagaPort<TName, TInput, TOutput, TError>;

sagaManagementPort​

Creates a saga management port.

function sagaManagementPort<TName, TOutput, TError>(): (
  name: TName
) => SagaManagementPort<TName, TOutput, TError>;

SagaExecutor​

Interface for saga execution through ports.

interface SagaExecutor<TInput, TOutput, TError> {
  execute(input: TInput): ResultAsync<TOutput, TError>;
}

SagaManagementExecutor​

Interface for saga management operations.

interface SagaManagementExecutor<TOutput, TError> {
  resume(executionId: string): ResultAsync<TOutput, TError>;
  cancel(executionId: string): ResultAsync<void, TError>;
  getStatus(executionId: string): ResultAsync<SagaStatus, TError>;
  listExecutions(filters?: ExecutionFilters): ResultAsync<SagaExecutionSummary[], TError>;
}

SagaPersister​

Interface for saga state persistence.

interface SagaPersister {
  save(state: SagaExecutionState): Promise<void>;
  load(executionId: string): Promise<SagaExecutionState | null>;
  delete(executionId: string): Promise<void>;
  list(filters?: PersisterFilters): Promise<SagaExecutionSummary[]>;
  update(executionId: string, updates: Partial<SagaExecutionState>): Promise<void>;
}

Integration​

createSagaAdapter​

Creates a unified saga adapter for DI.

function createSagaAdapter(config: SagaAdapterConfig): Adapter;

createSagaExecutor​

Creates a saga executor from a definition.

function createSagaExecutor<T extends AnySagaDefinition>(
  saga: T,
  runner: SagaRunner
): SagaExecutor<InferSagaInput<T>, InferSagaOutput<T>, InferSagaErrors<T>>;

createSagaManagementExecutor​

Creates a management executor.

function createSagaManagementExecutor(
  runner: SagaRunner
): SagaManagementExecutor<unknown, ManagementError>;

Introspection​

createSagaInspector​

Creates an inspector for saga introspection.

function createSagaInspector(config: SagaInspectorConfig): SagaInspector;

createSagaRegistry​

Creates a registry for saga definitions.

function createSagaRegistry(): SagaRegistry;

SagaInspector​

Interface for saga introspection.

interface SagaInspector {
  getDefinitions(): SagaDefinitionInfo[];
  getActiveExecutions(): InspectorSagaExecutionSummary[];
  getHistory(filters?: HistoryFilters): InspectorSagaExecutionSummary[];
  getTrace(executionId: string): ExecutionTrace | null;
  getCompensationStats(): CompensationStats;
  getSuggestions(sagaName?: string): SagaSuggestion[];
  subscribe(listener: InspectorEventListener): Unsubscribe;
}

SagaSuggestion​

Improvement suggestions for sagas.

interface SagaSuggestion {
  type: SagaSuggestionType;
  sagaName: string;
  stepName?: string;
  message: string;
  severity: "info" | "warning" | "error";
}

Events​

SagaEvent​

Union type of all saga events.

type SagaEvent =
  | SagaStartedEvent
  | StepStartedEvent
  | StepCompletedEvent
  | StepFailedEvent
  | StepSkippedEvent
  | StepResumedEvent
  | CompensationStartedEvent
  | CompensationStepEvent
  | CompensationCompletedEvent
  | CompensationFailedEvent
  | SagaCompletedEvent
  | SagaFailedEvent
  | SagaCancelledEvent
  | CheckpointWarningEvent;

Event structure example:

interface StepCompletedEvent extends SagaEventBase {
  type: "step:completed";
  stepName: string;
  stepIndex: number;
  output: unknown;
  duration: number;
  attemptCount: number;
}

Tracing​

ExecutionTrace​

Complete execution trace.

interface ExecutionTrace {
  executionId: string;
  sagaName: string;
  input: unknown;
  output?: unknown;
  status: SagaStatusType;
  startedAt: Date;
  completedAt?: Date;
  duration?: number;
  steps: StepTrace[];
  compensation?: CompensationTrace;
  metadata?: Record<string, unknown>;
}

StepTrace​

Trace for individual step execution.

interface StepTrace {
  stepName: string;
  stepIndex: number;
  status: "success" | "failed" | "skipped";
  startedAt: Date;
  completedAt?: Date;
  durationMs?: number;
  attemptCount: number;
  error?: unknown;
  output?: unknown;
}

CompensationTrace​

Trace for compensation execution.

interface CompensationTrace {
  triggeredBy: string;
  startedAt: Date;
  completedAt?: Date;
  status: "success" | "partial" | "failed";
  steps: CompensationStepTrace[];
  errors: Record<string, unknown>;
  totalDurationMs?: number;
}

Persistence​

createInMemoryPersister​

Creates an in-memory persister for development.

function createInMemoryPersister(config?: {
  maxEntries?: number;
  ttl?: number;
  cleanupInterval?: number;
}): SagaPersister;

SagaExecutionState​

Persisted execution state.

interface SagaExecutionState {
  executionId: string;
  sagaName: string;
  sagaVersion?: string;
  input: unknown;
  currentStep: number;
  completedSteps: CompletedStepState[];
  accumulatedResults: Record<string, unknown>;
  accumulatedErrors: Record<string, unknown>;
  status: SagaStatusType;
  startedAt: Date;
  updatedAt: Date;
  completedAt?: Date;
  error?: SerializedSagaError;
  compensation?: CompensationState;
  metadata?: Record<string, unknown>;
}

Errors​

SagaError​

Union type of all saga errors.

type SagaError =
  | StepFailedError
  | CompensationFailedError
  | TimeoutError
  | CancelledError
  | ValidationFailedError
  | PortNotFoundError
  | PersistenceFailedError;

SagaSuccess​

Success result type.

interface SagaSuccess<TOutput> {
  type: "success";
  output: TOutput;
  executionId: string;
  duration: number;
  completedAt: Date;
}

SagaStatus​

Execution status information.

interface SagaStatus {
  executionId: string;
  sagaName: string;
  status: SagaStatusType;
  currentStep?: string;
  completedSteps: string[];
  startedAt: Date;
  updatedAt: Date;
  completedAt?: Date;
  error?: unknown;
}

ID Generation​

generateExecutionId​

Generates unique execution IDs.

function generateExecutionId(prefix?: string): string;

Example: "saga-1234567890-abc123"