# @mwillbanks/tuil-workflow

Source: /tuil/docs/reference/packages/workflow
Locale: en

Persistent, resumable, observable multi-step workflows for tuil applications.



## Overview [#overview]

Persistent, resumable, observable multi-step workflows for tuil applications.

`@mwillbanks/tuil-workflow` is independently installable and also participates in the
umbrella `@mwillbanks/tuil` runtime where applicable.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @mwillbanks/tuil-workflow
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @mwillbanks/tuil-workflow
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @mwillbanks/tuil-workflow
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @mwillbanks/tuil-workflow
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## How it operates [#how-it-operates]

Workflow runners coordinate typed state, guarded transitions, validation, nested and parallel work, operations, persistence, migration, retry, cancellation, and compensation.

<Mermaid
  chart="flowchart LR
  S0[&#x22;idle&#x22;]
  S1[&#x22;running&#x22;]
  S2[&#x22;blocked | completed | failed | cancelled | rolling-back&#x22;]
  S0 --> S1
  S1 --> S2"
/>

## API [#api]

| API                                                                                            | Signature                            | Description                                |
| ---------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------ |
| [`createWorkflow`](/tuil/docs/reference/packages/workflow/api/create-workflow)                      | `function createWorkflow`            | Public function createWorkflow.            |
| [`defineOperationStep`](/tuil/docs/reference/packages/workflow/api/define-operation-step)           | `function defineOperationStep`       | Public function defineOperationStep.       |
| [`defineStep`](/tuil/docs/reference/packages/workflow/api/define-step)                              | `function defineStep`                | Public function defineStep.                |
| [`defineWorkflow`](/tuil/docs/reference/packages/workflow/api/define-workflow)                      | `function defineWorkflow`            | Public function defineWorkflow.            |
| [`PersistedWorkflow`](/tuil/docs/reference/packages/workflow/api/persisted-workflow)                | `interface PersistedWorkflow`        | Public interface PersistedWorkflow.        |
| [`transition`](/tuil/docs/reference/packages/workflow/api/transition)                               | `function transition`                | Public function transition.                |
| [`WorkflowContext`](/tuil/docs/reference/packages/workflow/api/workflow-context)                    | `interface WorkflowContext`          | Public interface WorkflowContext.          |
| [`WorkflowDefinition`](/tuil/docs/reference/packages/workflow/api/workflow-definition)              | `interface WorkflowDefinition`       | Public interface WorkflowDefinition.       |
| [`WorkflowEvent`](/tuil/docs/reference/packages/workflow/api/workflow-event)                        | `interface WorkflowEvent`            | Public interface WorkflowEvent.            |
| [`WorkflowEventType`](/tuil/docs/reference/packages/workflow/api/workflow-event-type)               | `type WorkflowEventType`             | Public type WorkflowEventType.             |
| [`WorkflowParallelBranch`](/tuil/docs/reference/packages/workflow/api/workflow-parallel-branch)     | `interface WorkflowParallelBranch`   | Public interface WorkflowParallelBranch.   |
| [`WorkflowParallelSnapshot`](/tuil/docs/reference/packages/workflow/api/workflow-parallel-snapshot) | `interface WorkflowParallelSnapshot` | Public interface WorkflowParallelSnapshot. |
| [`WorkflowPersistence`](/tuil/docs/reference/packages/workflow/api/workflow-persistence)            | `interface WorkflowPersistence`      | Public interface WorkflowPersistence.      |
| [`WorkflowRunner`](/tuil/docs/reference/packages/workflow/api/workflow-runner)                      | `class WorkflowRunner`               | Public class WorkflowRunner.               |
| [`WorkflowSnapshot`](/tuil/docs/reference/packages/workflow/api/workflow-snapshot)                  | `interface WorkflowSnapshot`         | Public interface WorkflowSnapshot.         |
| [`WorkflowStatus`](/tuil/docs/reference/packages/workflow/api/workflow-status)                      | `type WorkflowStatus`                | Public type WorkflowStatus.                |
| [`WorkflowStep`](/tuil/docs/reference/packages/workflow/api/workflow-step)                          | `interface WorkflowStep`             | Public interface WorkflowStep.             |
| [`WorkflowTransition`](/tuil/docs/reference/packages/workflow/api/workflow-transition)              | `interface WorkflowTransition`       | Public interface WorkflowTransition.       |

## Events and lifecycle [#events-and-lifecycle]

`workflow:start`, `workflow:step-enter`, `workflow:step-leave`, `workflow:validate`, `workflow:skip`, `workflow:back`, `workflow:resume`, `workflow:retry`, `workflow:rollback`, `workflow:cancel`, `workflow:complete`, and `workflow:error`.

All subscriptions and registrations return a disposer or belong to an owning
runtime that disposes them in reverse order.

## Example [#example]

```tsx
import { createWorkflow, defineWorkflow } from "@mwillbanks/tuil-workflow";

const runner = createWorkflow(defineWorkflow({ id: "setup", version: 1, initialState: {}, steps, transitions }));
```

## Related [#related]

* [Package architecture](/tuil/docs/concepts/packages)
* [Events](/tuil/docs/concepts/events)
* [Testing](/tuil/docs/guides/testing)