resonate-saga-pattern-typescript

Resonate Saga Pattern (TypeScript)

Overview

The Saga pattern coordinates long-running distributed transactions by breaking them into smaller, isolated steps with compensating actions. If any step fails, the saga executes compensation logic to undo completed steps, maintaining eventual consistency without distributed locks or two-phase commits.

Core principle: Each step has a forward action (transaction) and a compensating action (rollback). On failure, compensations execute in reverse order to restore consistency.

Mental Model

Forward Execution (Happy Path):
  Step 1 → Step 2 → Step 3 → Success

Failure with Compensation:
  Step 1 ✓ → Step 2 ✓ → Step 3 ✗
         ↓
  Compensate 2 → Compensate 1 → Saga Failed (Consistent)

Basic Saga Structure

function* sagaWorkflow(ctx: Context, orderId: string) {
  const completedSteps: string[] = [];

  try {
    // Step 1: Reserve inventory
    yield* ctx.run(reserveInventory, orderId);
    completedSteps.push("inventory");

    // Step 2: Charge payment
    yield* ctx.run(chargePayment, orderId);
    completedSteps.push("payment");

    // Step 3: Create shipment
    yield* ctx.run(createShipment, orderId);
    completedSteps.push("shipment");

    return { status: "success", orderId };

  } catch (error) {
    // Compensate in reverse order
    for (const step of completedSteps.reverse()) {
      yield* ctx.run(compensate, step, orderId);
    }

    return { status: "failed", orderId, compensated: completedSteps };
  }
}

async function compensate(_ctx: Context, step: string, orderId: string) {
  switch (step) {
    case "shipment":
      await cancelShipment(orderId);
      break;
    case "payment":
      await refundPayment(orderId);
      break;
    case "inventory":
      await releaseInventory(orderId);
      break;
  }
}

Pattern Variants

1. Explicit Compensation Functions

interface SagaStep<T> {
  name: string;
  action: (ctx: Context, data: T) => Generator;
  compensate: (ctx: Context, data: T) => Generator;
}

function* genericSaga<T>(ctx: Context, steps: SagaStep<T>[], data: T) {
  const completed: SagaStep<T>[] = [];

  try {
    for (const step of steps) {
      yield* step.action(ctx, data);
      completed.push(step);
    }

    return { status: "success" };
  } catch (error) {
    console.error(`Saga failed at step ${completed.length + 1}:`, error);

    // Compensate in reverse
    for (const step of completed.reverse()) {
      try {
        yield* step.compensate(ctx, data);
      } catch (compensateError) {
        console.error(`Compensation failed for ${step.name}:`, compensateError);
        // Log but continue compensating other steps
      }
    }

    return { status: "failed", error, compensated: completed.map(s => s.name) };
  }
}

// Usage
function* orderSaga(ctx: Context, order: Order) {
  const steps: SagaStep<Order>[] = [
    {
      name: "inventory",
      action: function* (ctx, order) {
        yield* ctx.run(reserveInventory, order.id);
      },
      compensate: function* (ctx, order) {
        yield* ctx.run(releaseInventory, order.id);
      }
    },
    {
      name: "payment",
      action: function* (ctx, order) {
        yield* ctx.run(chargePayment, order.id, order.total);
      },
      compensate: function* (ctx, order) {
        yield* ctx.run(refundPayment, order.id);
      }
    },
    {
      name: "shipment",
      action: function* (ctx, order) {
        yield* ctx.run(createShipment, order.id);
      },
      compensate: function* (ctx, order) {
        yield* ctx.run(cancelShipment, order.id);
      }
    }
  ];

  return yield* genericSaga(ctx, steps, order);
}