Extracting the Hidden State Machine from n8n Workflows in TypeScript

The pattern has four moves: walk the canvas to discover the implicit state, model the states explicitly in TypeScript, persist the state in Postgres so the workflow survives a process restart, and replicate the retry behavior as explicit code instead of a runtime setting. None of them are individually clever. Skipping any one of them is what produces the migration that limps for a quarter.

Canvas walk to enumerate hidden states

Start with the canvas walk. Open the n8n workflow and go node by node with one question: what failure modes does n8n silently handle for me here? Every answer is a hidden state in the machine you are about to write. A node with Retry on Fail enabled is two states — attempting and waiting-to-retry-after-failure. A node with Continue on Fail enabled is two outcome branches that both need explicit handling in the new code. A Wait node is its own state with a wake-up condition. The Loop Over Items node — which the n8n docs describe as the explicit looping construct on top of n8n's implicit per-item processing — is a state with a pointer into the batch and a transition that fires once the batch is exhausted. An Error Trigger workflow is a separate state machine that runs in response to a transition into a failed state in the primary one.

By the time you have walked every node, you have a state list. It is typically longer than the node count. A ten-node workflow routinely produces a fifteen-to-twenty-state machine, because the states are not the nodes — they are the boundaries between nodes plus all the failure modes that n8n was handling between them.

Explicit state model in TypeScript or XState

Now model it explicitly. For a linear pipeline with three or four states, a hand-rolled TypeScript enum and a switch statement is enough:

type WorkflowState =
  | "pending"
  | "fetching_customer"
  | "creating_invoice"
  | "creating_invoice_retrying"
  | "sending_email"
  | "completed"
  | "failed";

type WorkflowContext = {
  customer_id: string;
  customer?: Customer;
  invoice?: Invoice;
  attempt_count: number;
  last_error?: string;
};

async function step(
  run: WorkflowRun,
  tx: DatabaseTransaction,
): Promise<WorkflowRun> {
  switch (run.state) {
    case "pending":
      return transition(run, tx, { state: "fetching_customer" });

    case "fetching_customer": {
      const customer = await fetchCustomer(run.context.customer_id);
      return transition(run, tx, {
        state: "creating_invoice",
        context: { ...run.context, customer },
      });
    }

    case "creating_invoice":
    case "creating_invoice_retrying": {
      try {
        const invoice = await createInvoice(run.context.customer!);
        return transition(run, tx, {
          state: "sending_email",
          context: { ...run.context, invoice, attempt_count: 0 },
        });
      } catch (err) {
        if (run.context.attempt_count >= 4) {
          return transition(run, tx, {
            state: "failed",
            context: {
              ...run.context,
              last_error: String(err),
            },
          });
        }
        return transition(run, tx, {
          state: "creating_invoice_retrying",
          context: {
            ...run.context,
            attempt_count: run.context.attempt_count + 1,
            last_error: String(err),
          },
        });
      }
    }

    case "sending_email": {
      await sendInvoiceEmail(run.context.customer!, run.context.invoice!);
      return transition(run, tx, { state: "completed" });
    }

    case "completed":
    case "failed":
      return run;
  }
}

For workflows with parallel sub-flows, guarded transitions, or where a visual of the machine would help non-engineers understand the flow, XState earns its weight. XState models the workflow as actors — running processes that, per the XState docs, can receive events, send events, and change behavior based on the events they receive. Each actor has internal encapsulated state that only the actor can update, and processes one message at a time through a mailbox. Transitions are deterministic: each state-event combination leads to the same next state, which is what makes the machine testable. Context — n8n's accumulated data between nodes — becomes XState context, updated immutably via the assign(...) action.

Postgres row per workflow run

The persistence move is what makes the migration survive a deploy or a crash. n8n persisted execution data between nodes for you. In your TypeScript code that becomes a Postgres row per workflow run, with the state column committed inside the same transaction as the side effect. The schema is small on purpose:

CREATE TABLE workflow_runs (
  id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  workflow_name   text NOT NULL,
  state           text NOT NULL,
  context         jsonb NOT NULL DEFAULT '{}'::jsonb,
  attempt_count   integer NOT NULL DEFAULT 0,
  created_at      timestamptz NOT NULL DEFAULT now(),
  updated_at      timestamptz NOT NULL DEFAULT now(),
  completed_at    timestamptz,
  failed_at       timestamptz,
  last_error      text
);

CREATE INDEX workflow_runs_resumable ON workflow_runs (state, updated_at)
  WHERE state NOT IN ('completed', 'failed');

CREATE INDEX workflow_runs_stuck ON workflow_runs (updated_at)
  WHERE state NOT IN ('completed', 'failed')
    AND updated_at < now() - interval '5 minutes';

The transition function commits the new state and the new context in a single transaction with any side effect that the state entry produced. A worker that wakes up after a crash queries the resumable index, picks up rows in non-terminal states, and calls step() on them. The state column is enough to know where to resume — no log replay, no event sourcing required for the migration. (If the workflow grows to need full audit history later, append-only event sourcing on top of this is straightforward. Start with the row and add events when you need them.)

For XState specifically, the persistence story is built in. The XState docs document actor.getPersistedSnapshot() for serializing actor state and createActor(logic, { snapshot: restoredState }) for restoring it, and persistence is deep — invoked and spawned child actors persist and restore recursively. The wrapper around this in production code is a loadActor(runId) that pulls the snapshot from Postgres and rehydrates it, and a saveActor(runId, actor) that writes the current snapshot back, called after every transition.

Per-call-site retry policy

The last move is the retry behavior. n8n's node-level Retry on Fail setting is the most invisible piece of the runtime — a node either has it on or off, and when it is on the runtime quietly tries the node again on failure. In the migrated TypeScript code, this becomes explicit. Pick the retry count, the wait between attempts, and the backoff shape per-step based on what each downstream service needs, not by copying one global default across every call site. Stripe API calls want exponential backoff with idempotency keys. SMTP sends want a short retry with a circuit breaker. Internal database operations should rarely retry at all — they should let the transaction roll back and the worker pick the row up again. The default n8n applies uniformly is a reasonable starting point; the right code applies a different policy per call site.

A small helper makes this consistent without leaking the choice across handlers:

async function withRetry<T>(
  fn: () => Promise<T>,
  opts: { maxAttempts: number; waitMs: number; backoff?: "linear" | "exponential" },
): Promise<T> {
  let attempt = 0;
  while (true) {
    try {
      return await fn();
    } catch (err) {
      attempt += 1;
      if (attempt >= opts.maxAttempts) throw err;
      const wait =
        opts.backoff === "exponential"
          ? opts.waitMs * Math.pow(2, attempt - 1)
          : opts.waitMs;
      await new Promise((r) => setTimeout(r, wait));
    }
  }
}

This is the part teams underweight: the retry policy is now a per-call decision a code reviewer sees, instead of a checkbox a node author clicked once. That is the migration's real value — every implicit choice in the n8n workflow becomes a visible code change with a commit and a reviewer.