Workflow

The @talosjs/workflow component is a transition-based workflow engine. A workflow is an ordered list of transitions: small, focused steps that each decide whether they run, do their work, and know how to undo it. When you run a workflow, the active transitions execute in order. If any step throws, the engine rolls back the ones that already succeeded, in reverse, and raises a typed WorkflowException.

The transition model

A workflow breaks a process into small, focused steps rather than one monolithic function. Each transition’s isActive(data, context?) decides whether it runs for the current data, so the active set can vary from one run to the next. When a step fails, the transitions that already executed roll back in reverse order before the error propagates. You can react around every step with the onStart, onFinish, and onFail hooks. Workflows and transitions are registered with a decorator and resolved from @talosjs/container, and generic Data and Output types thread through the workflow and its transitions.

How it works

A workflow extends the abstract Workflow<Data, Output> class and implements getName, getDescription, and getTransitions. Each transition implements the ITransition<Data, Output> interface. Calling run(data, context?) does the following:

Every transition’s isActive(data, context?) is evaluated to build the list of active transitions.
Active transitions run in order. For each one: onStart fires, then handler(data, context?) produces an output, then onFinish fires with that output.
The output of the last executed transition is returned.
If a step throws, that transition’s onFail fires, the transitions executed so far are rolled back in reverse order, and a WorkflowException is thrown.

A transition implements these members:

Member	Purpose
`getName()`	Unique, human-readable name (used in error messages).
`getDescription()`	Short description of what the transition does.
`isActive(data, context?)`	Whether this transition should run; return `false` to skip it.
`handler(data, context?)`	Performs the work and returns the output.
`rollback(data, context?)`	Undoes the work if a later transition fails.
`onStart(data, context?)`	Fires before the handler runs.
`onFinish(data, output, context?)`	Fires after the handler succeeds, with its output.
`onFail(data, error, context?)`	Fires when the handler (or a hook) throws, with the error.

Every member may be synchronous or asynchronous. The optional context passed to run is forwarded to every member, so request-scoped values such as the current user or a request id reach each step. Rollback is precise. Only transitions whose handler completed are rolled back; the transition that threw is not, since its work never finished. The rollbacks are awaited before the WorkflowException is rethrown.

onStart → handler → onFinish        (success)
onStart → handler ✗ → onFail        (failure) → rollback (reverse) → WorkflowException

Decorator and usage

`@decorator.transition()`

Registers a transition class with the container. It accepts an optional scope (defaults to EContainerScope.Singleton).

import { decorator } from "@talosjs/workflow";
import type { ITransition } from "@talosjs/workflow";

interface OrderData extends Record<string, unknown> {
  orderId: string;
  amount: number;
}

@decorator.transition()
export class ChargePaymentTransition implements ITransition<OrderData, string> {
  public getName = () => "charge-payment";
  public getDescription = () => "Charges the customer for the order";
  public isActive = (data: OrderData) => data.amount > 0;

  public handler = async (data: OrderData) => {
    return paymentGateway.charge(data.orderId, data.amount);
  };

  public rollback = async (data: OrderData) => {
    await paymentGateway.refund(data.orderId);
  };

  public onStart = (data: OrderData) => logger.info(`Charging ${data.orderId}`);
  public onFinish = (data: OrderData, chargeId: string) => logger.info(`Charged ${chargeId}`);
  public onFail = (data: OrderData, error: unknown) => logger.error("Charge failed", error);
}

`@decorator.workflow()`

Registers a workflow class with the container. It also accepts an optional scope (defaults to EContainerScope.Singleton). List the transition classes in getTransitions() in the order they should run, returning the class references only, never instances, since they are resolved from the container.

import { decorator, Workflow } from "@talosjs/workflow";
import type { WorkflowTransitionClassType } from "@talosjs/workflow";

@decorator.workflow()
export class CheckoutWorkflow extends Workflow<OrderData, string> {
  public getName = () => "checkout";
  public getDescription = () => "Processes an order from payment to receipt";

  public getTransitions = (): WorkflowTransitionClassType[] => [
    ChargePaymentTransition,
    SendReceiptTransition,
  ];
}

Resolve the workflow from the container and run it. The output is whatever the last executed transition returns:

import { container } from "@talosjs/container";
import { WorkflowException } from "@talosjs/workflow";

const workflow = container.get(CheckoutWorkflow);

try {
  const output = await workflow.run(
    { orderId: "ord_123", amount: 4200 },
    { requestId: "req_1", user: currentUser }, // optional context
  );
  console.log(output);
} catch (error) {
  if (error instanceof WorkflowException) {
    console.error(error.message); // Workflow "checkout" failed at transition "...".
    console.error(error.data); // { workflow, transition, error }
  }
}

Exceptions

A failed run throws a WorkflowException. It carries a machine-readable key, a human-readable message, an HTTP status, and a data object.

Key	When
`WORKFLOW_RUN_FAILED`	A transition’s `handler` or a lifecycle hook threw during `run()`. The executed transitions have already been rolled back in reverse order.

The message reads Workflow "<name>" failed at transition "<name>"., the status is 500 (Internal Server Error), and data is { workflow, transition, error }, where error is the original message (non-Error throwables are stringified).

import { WorkflowException } from "@talosjs/workflow";

try {
  await workflow.run(data);
} catch (error) {
  if (error instanceof WorkflowException) {
    logger.error(`Workflow error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

Composing workflows that recover

Keep each transition on a single, nameable action so it stays easy to test and roll back. Make rollback the true inverse of handler: whatever side effect a handler creates, whether a charge, a reservation, or a record, its rollback should undo it. Guard with isActive to skip steps that don’t apply to the current data instead of branching inside the handler. Order transitions deliberately. They run in the order getTransitions() returns and roll back in reverse, so put the reversible, cheap steps first where you can. List the transition classes in getTransitions(), never instances, since the container resolves them. Pass request-scoped values like the current user or a request id through the second run argument as context rather than threading them into Data. And catch WorkflowException at the boundary, reading its stable key and data to report the failing workflow and transition.

CLI command

Scaffold a workflow with workflow:create and each of its steps with workflow:transition:create. The generators write the class and a matching test under the target module and install @talosjs/workflow if it is missing.

# Interactive: prompts for the name
talos workflow:create
talos workflow:transition:create

# Provide the name
talos workflow:create --name=Checkout
talos workflow:transition:create --name=ChargePayment

# Target a module and overwrite
talos workflow:create --name=Checkout --module=orders --override

Option	Description	Default
`--name`	Class name. `workflow:create` appends the `Workflow` suffix; `workflow:transition:create` appends `Transition`.	Prompted if omitted
`--module`	Target module the class is generated into.	`shared`
`--override`	Overwrite an existing class without prompting.	`false`

workflow:create writes the class under modules/<module>/src/workflows/<Name>Workflow.ts as a Workflow subclass with an empty transition list, ready for you to fill in:

import type { WorkflowTransitionClassType } from "@talosjs/workflow";
import { decorator, Workflow } from "@talosjs/workflow";

/** Data threaded through CheckoutWorkflow and each of its transitions. */
export type CheckoutWorkflowDataType = Record<string, unknown>;

@decorator.workflow()
export class CheckoutWorkflow extends Workflow<CheckoutWorkflowDataType> {
  public getName = (): string => "checkout";

  public getDescription = (): string => "";

  /** Transitions run in order; each one's `isActive` decides if it executes. */
  public getTransitions = (): WorkflowTransitionClassType[] => [];
}

workflow:transition:create writes the class under modules/<module>/src/workflows/transitions/<Name>Transition.ts as an ITransition stub with every member ready to implement:

import type { ITransition } from "@talosjs/workflow";
import { decorator } from "@talosjs/workflow";

/** Data threaded through the workflow run and read by ChargePaymentTransition. */
export type ChargePaymentTransitionDataType = Record<string, unknown>;

@decorator.transition()
export class ChargePaymentTransition
  implements ITransition<ChargePaymentTransitionDataType, unknown>
{
  public getName = (): string => "charge-payment";

  public getDescription = (): string => "";

  /** Whether this transition should run for the given data. */
  public isActive = (_data: ChargePaymentTransitionDataType): boolean => true;

  /** Performs the transition's work and returns its output. */
  public handler = async (data: ChargePaymentTransitionDataType): Promise<unknown> => {
    return data;
  };

  /** Undoes handler() when a later transition in the workflow fails. */
  public rollback = async (_data: ChargePaymentTransitionDataType): Promise<void> => {};

  /** Runs before handler(). */
  public onStart = async (_data: ChargePaymentTransitionDataType): Promise<void> => {};

  /** Runs after handler() resolves successfully. */
  public onFinish = async (
    _data: ChargePaymentTransitionDataType,
    _output: unknown,
  ): Promise<void> => {};

  /** Runs when handler() throws. */
  public onFail = async (
    _data: ChargePaymentTransitionDataType,
    _error: unknown,
  ): Promise<void> => {};
}

See workflow:create and workflow:transition:create for the full command references.

Use with Claude and Codex

The generators ship matching workflow:create and workflow:transition:create skills. They run the scaffold, then guide your AI agent through completing the workflow: defining the Data type, listing the transitions in order, and implementing each transition’s isActive, handler, and rollback. Initialize the skills once for your agent.

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generators, runs them, and fills in the implementation:

Prompt

Create an order workflow with pending, paid, and shipped states.

talos agent:skills:create

Then ask Codex in natural language. It maps the request to the generators, runs them, and fills in the implementation:

Prompt

Create an order workflow with pending, paid, and shipped states.

For example, the prompt above maps to workflow:create --name=Order, then a workflow:transition:create for each step, wiring the transitions into getTransitions() in order.

Getting Started

AI

Framework

Command Line

The transition model

How it works

Decorator and usage

`@decorator.transition()`

`@decorator.workflow()`

Exceptions

Composing workflows that recover

CLI command

Use with Claude and Codex

​The transition model

​How it works

​Decorator and usage

​@decorator.transition()

​@decorator.workflow()

​Exceptions

​Composing workflows that recover

​CLI command

​Use with Claude and Codex

The transition model

How it works

Decorator and usage

`@decorator.transition()`

`@decorator.workflow()`

Exceptions

Composing workflows that recover

CLI command

Use with Claude and Codex