Tx

Tx is an execution layer that bundles optimistic UI updates and server requests into a single transaction and automatically rolls back on failure.

• Run multiple steps in one go
• If something fails in the middle, execute compensating steps in reverse order to restore the UI
• Handle retries (linear/exponential backoff), global timeouts, ViewTransition, and DevTools events in a consistent way.

1. Installation & the simplest usage: startTransaction

First, install Tx. The examples in this document use the Local-First model, so we show them installed together.

@firsttx/tx itself has no runtime dependency on any particular state management layer.
It only requires react as a peerDependency for the useTx hook.
In this document we choose to use the Local-First model in the examples. (GitHub)

Here is an example of adding an item to the cart as a single transaction.

import { startTransaction } from "@firsttx/tx";
import { CartModel } from "./models/cart";

async function addToCart(item: { id: string; name: string; qty: number }) {
  // Start a transaction with ViewTransition enabled (timeout defaults to 30s)
  const tx = startTransaction({
    transition: true,
    // timeout: 30_000, // You can adjust the global timeout (ms) if needed.
  });

  // Step 1: optimistic update to the local model + compensation
  await tx.run(
    () =>
      CartModel.patch((draft) => {
        draft.items.push(item);
      }),
    {
      compensate: () =>
        CartModel.patch((draft) => {
          draft.items.pop();
        }),
    },
  );

  // Step 2: server request (can receive an AbortSignal)
  await tx.run((signal) =>
    fetch("/api/cart", {
      method: "POST",
      body: JSON.stringify(item),
      signal, // Will be aborted when the transaction times out.
    }),
  );

  // If all steps succeeded, commit the transaction
  await tx.commit();
}

Key points here,

• startTransaction(options?)

  • Configures the transaction ID, whether to use ViewTransition, and the global timeout.

• tx.run(fn, options?)

  • Executes a step function fn.
  • If a step fails, later steps are not run and Tx will roll back only the steps that have already succeeded, in reverse order.

• tx.commit()

  • Signals that all steps have finished successfully.
  • If an error occurs before commit, Tx automatically goes into the rollback path.
  • If the transaction is already committed, calling commit() again is a no-op (idempotent).

2. Transaction lifecycle & states

Internally, the transaction engine roughly has the following states,

• pending - No steps have been executed yet
• running - One or more steps are currently being executed
• committed - All steps finished and commit has been called
• rolled-back - A failure occurred and all compensations have completed successfully
• failed - An error occurred even while running compensation (see CompensationFailedError below)

Which steps get rolled back

• When a failure occurs, only the steps that have already succeeded are candidates for rollback.
• The failing step’s own compensate is never called.
• Compensations are always executed in “reverse order of successful steps”.

Valid call states

• You may call run() and commit() only while the transaction is in pending or running.
• If you call them after the transaction has already been committed or has reached rolled-back / failed, a TransactionStateError is thrown.

Global timeout & Abort

• By default, a 30-second global timeout (timeout: 30000) is applied to the entire transaction.

• For each step, Tx creates an internal AbortController, and the step function passed to tx.run can optionally accept an AbortSignal argument.

• When the remaining time is exhausted, that step’s AbortSignal is aborted,

  • APIs like fetch(url, { signal }),
  • abortableSleep(ms, signal) can react immediately to the signal and stop execution.

• If your step function ignores the AbortSignal, it may keep running even after the timeout, but Tx will already treat the step as failed due to timeout.

3. tx.run and retry

Each step can have its own retry strategy. Internally, retry.ts implements linear and exponential backoff. If the step never succeeds after all attempts, a RetryExhaustedError is thrown.

const tx = startTransaction();

await tx.run(
  async (signal) => {
    const res = await fetch("/api/order", {
      method: "POST",
      signal,
    });

    if (!res.ok) {
      throw new Error("Order failed");
    }
  },
  {
    // Only this step is retried. Compensation is executed only after the final failure.
    retry: {
      maxAttempts: 3,
      delayMs: 300,
      backoff: "exponential", // or "linear"
    },
    compensate: async () => {
      // Optional rollback API call, etc.
      await fetch("/api/order/cancel", { method: "POST" });
    },
  },
);

The library also exports DEFAULT_RETRY_CONFIG and RETRY_PRESETS,

import { DEFAULT_RETRY_CONFIG, RETRY_PRESETS } from "@firsttx/tx";

tx.run(doSomething, {
  retry: RETRY_PRESETS.aggressive,
});

4. React hook: useTx

In real apps, you usually don’t call startTransaction + tx.run by hand for every case. Instead, you can use the useTx hook, which bundles optimistic update + rollback + request into a single API.

import { useTx } from "@firsttx/tx";
import { CartModel } from "./models/cart";

export function AddToCartButton({
  item,
}: {
  item: { id: string; name: string; qty: number };
}) {
  const { mutate, isPending, isError, error } = useTx({
    // 1) Optimistic UI update
    optimistic: (input) => {
      CartModel.patch((draft) => {
        draft.items.push(input);
      });

      // Whatever you return here becomes a snapshot passed to rollback / onSuccess, etc.
      // In this example we don't need it, so we just return void (snapshot type: void).
    },

    // 2) Rollback (can receive both variables and snapshot)
    rollback: (input, _snapshot) => {
      CartModel.patch((draft) => {
        // Simplest case: remove the last added item
        draft.items.pop();
      });
    },

    // 3) Actual server request (snapshot is available if needed)
    request: (input, _snapshot) =>
      fetch("/api/cart", {
        method: "POST",
        body: JSON.stringify(input),
      }),

    // Optional: whether to use ViewTransition (default is false)
    transition: true,

    // Optional: retry policy
    retry: {
      maxAttempts: 2,
      delayMs: 200,
      backoff: "exponential",
    },

    // Optional: logical cancellation on unmount
    cancelOnUnmount: true,

    onSuccess: () => {
      // e.g. show a toast
      console.log("Added to cart");
    },

    onError: (err) => {
      console.error("Failed to add item", err);
    },
  });

  return (
    <div className="flex items-center gap-2">
      <button
        type="button"
        disabled={isPending}
        onClick={() => mutate(item)}
        className="rounded-full bg-foreground px-4 py-2 text-xs font-medium text-background transition hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-60"
      >
        {isPending ? "Adding..." : "Add to cart"}
      </button>
      {isError && (
        <p className="text-xs text-destructive">
          {error?.message ?? "Failed to add item"}
        </p>
      )}
    </div>
  );
}

useTx is generic over variables (V), result (R), and snapshot (S),

• optimistic(variables) => snapshot
• rollback(variables, snapshot)
• request(variables, snapshot) => result
• onSuccess(result, snapshot)
• onError(error, snapshot)

5. Error model & DevTools

Tx uses a shared error hierarchy TxError and several concrete subclasses.

5.1 Error hierarchy

• TxError (abstract base class)

  • getUserMessage(): string - Message safe to show to end users
  • getDebugInfo(): string - Detailed string for logging/diagnostics
  • isRecoverable(): boolean - Whether retry/“try again” UX makes sense

• TransactionTimeoutError

  • Thrown when the transaction is interrupted due to the global timeout (or when there’s effectively no time left).
  • Typically caused by transient network/system issues and treated as recoverable (true).

• RetryExhaustedError

  • Thrown when a step still fails after the configured maxAttempts.
  • Also treated as recoverable (true), as it often indicates temporary network/server instability.

• CompensationFailedError

  • Thrown when one or more compensate calls fail during rollback.
  • Contains the original error plus all compensation errors in an internal array.
  • Indicates data inconsistency or a case needing manual intervention, and is treated as non-recoverable (false).

• TransactionStateError

  • Thrown when run/commit is called on a transaction that is already committed or is in rolled-back / failed.
  • Signals a programming error and is treated as non-recoverable (false).

In the UI layer you can handle them like this,

import { TxError } from "@firsttx/tx";

try {
  await mutateAsync(input);
} catch (error) {
  if (error instanceof TxError) {
    toast(error.getUserMessage());

    logger.error(error.getDebugInfo(), {
      recoverable: error.isRecoverable(),
    });

    if (error.isRecoverable()) {
      // Show a “Try again” button or similar UX.
    }
  } else {
    // Plain Error
    toast("An unknown error occurred.");
  }
}

5.2 DevTools events

If window.__FIRSTTX_DEVTOOLS__ exists, Tx emits events describing transaction activity,

window.__FIRSTTX_DEVTOOLS__?.emit({
  id: crypto.randomUUID(),
  category: "tx",
  type: "step.success", // e.g. 'start' | 'step.start' | 'step.success' | ...
  timestamp: Date.now(),
  priority: 1,
  data: { /* transaction/step metadata */ },
});

Typical type values include,

• start - Transaction started
• step.start / step.success / step.retry / step.fail - Per-step start/success/retry/failure
• commit - Commit completed
• rollback.start / rollback.success / rollback.fail - Rollback began/completed/failed
• timeout - Global timeout occurred

The priority field controls importance in DevTools,

• 0 : Normal flow (step.success, etc.)
• 1 : Key events (start, commit, step.retry, etc.)
• 2 : Failures/rollbacks/timeouts and other critical events

6. Using Tx with Local-First / Prepaint

Finally, Tx can be used on its own, but it really shines when combined with Local-First + Prepaint,

• Prepaint - Restores the last screen immediately on revisit to avoid blank screens. (GitHub)
• Local-First - Uses IndexedDB as the single source of truth so state survives reloads and offline usage. (GitHub)
• Tx - Sits on top to group optimistic updates into atomic transactions and roll them back cleanly on failure. (GitHub)

These layers are separate packages,

• Prepaint: render/initialization layer
• Local-First: data/synchronization layer
• Tx: execution/transaction layer

You can mix and match as needed. See /docs/prepaint and /docs/local-first for details on the other layers.