# @mwillbanks/tuil-operations

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

Observable asynchronous operations, progress, retries, rollback, and cancellation for tuil.



## Overview [#overview]

Observable asynchronous operations, progress, retries, rollback, and cancellation for tuil.

`@mwillbanks/tuil-operations` 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-operations
    ```
  </CodeBlockTab>

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

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

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

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

Operation executors track progress, retries, cancellation, timeouts, dependencies, rollback, logs, and immutable observable snapshots.

<Mermaid
  chart="flowchart LR
  S0[&#x22;idle&#x22;]
  S1[&#x22;running&#x22;]
  S2[&#x22;succeeded | failed | cancelled&#x22;]
  S3[&#x22;optional rollback&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3"
/>

## API [#api]

| API                                                                                              | Signature                            | Description                                |
| ------------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------------------------ |
| [`createOperation`](/tuil/docs/reference/packages/operations/api/create-operation)                    | `function createOperation`           | Public function createOperation.           |
| [`defineOperation`](/tuil/docs/reference/packages/operations/api/define-operation)                    | `function defineOperation`           | Public function defineOperation.           |
| [`OperationBlockedError`](/tuil/docs/reference/packages/operations/api/operation-blocked-error)       | `class OperationBlockedError`        | Public class OperationBlockedError.        |
| [`OperationContext`](/tuil/docs/reference/packages/operations/api/operation-context)                  | `interface OperationContext`         | Public interface OperationContext.         |
| [`OperationDefinition`](/tuil/docs/reference/packages/operations/api/operation-definition)            | `interface OperationDefinition`      | Public interface OperationDefinition.      |
| [`OperationError`](/tuil/docs/reference/packages/operations/api/operation-error)                      | `interface OperationError`           | Public interface OperationError.           |
| [`OperationEvent`](/tuil/docs/reference/packages/operations/api/operation-event)                      | `interface OperationEvent`           | Public interface OperationEvent.           |
| [`OperationExecutor`](/tuil/docs/reference/packages/operations/api/operation-executor)                | `class OperationExecutor`            | Public class OperationExecutor.            |
| [`OperationExecutorOptions`](/tuil/docs/reference/packages/operations/api/operation-executor-options) | `interface OperationExecutorOptions` | Public interface OperationExecutorOptions. |
| [`OperationFeedback`](/tuil/docs/reference/packages/operations/api/operation-feedback)                | `type OperationFeedback`             | Public type OperationFeedback.             |
| [`operationFeedbackDelays`](/tuil/docs/reference/packages/operations/api/operation-feedback-delays)   | `constant operationFeedbackDelays`   | Public constant operationFeedbackDelays.   |
| [`OperationProgress`](/tuil/docs/reference/packages/operations/api/operation-progress)                | `interface OperationProgress`        | Public interface OperationProgress.        |
| [`OperationSnapshot`](/tuil/docs/reference/packages/operations/api/operation-snapshot)                | `interface OperationSnapshot`        | Public interface OperationSnapshot.        |
| [`OperationStatus`](/tuil/docs/reference/packages/operations/api/operation-status)                    | `type OperationStatus`               | Public type OperationStatus.               |
| [`OperationTimeoutError`](/tuil/docs/reference/packages/operations/api/operation-timeout-error)       | `class OperationTimeoutError`        | Public class OperationTimeoutError.        |
| [`resolveOperationFeedback`](/tuil/docs/reference/packages/operations/api/resolve-operation-feedback) | `function resolveOperationFeedback`  | Public function resolveOperationFeedback.  |

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

Executors expose snapshot subscriptions and operation progress rather than stringly typed global events.

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

## Example [#example]

```tsx
import { defineOperation } from "@mwillbanks/tuil-operations";

const operation = defineOperation({ id: "build", run: async ({ progress }) => progress(1) });
```

## Related [#related]

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