Getting Started

Flow is a small TypeScript workflow layer for composing async application behavior with typed success, typed failure, and cooperative cancellation.

Why Flow

Async application code often mixes expected failures, thrown exceptions, timeout handling, and cancellation in one control path. Flow separates those concerns: domain failures are explicit Result values, runtime failures are preserved as runtime errors, and cancellation travels through AbortSignal.

Use Flow when you want workflows that remain easy to compose, test, and reason about after they grow beyond one async function.

For more context on the design tradeoffs, read the Flow Motivation.

Mental Model

A Flow unit is a Behavior<I, O, E, C>. It receives input I, returns output O, can fail with domain error E, and can read context C. Every Behavior receives a RuntimeContext containing an AbortSignal, so parent workflows, timeouts, races, and manual aborts can stop work cooperatively.

Composition helpers connect Behavior values without erasing their types. Sequential helpers pass successful output forward. Parallel helpers preserve object keys. Recovery helpers operate only on expected domain failures.

Install

The shadcn CLI reads a project-root components.json to decide where files go. Flow items are registry:lib sources; targets resolve through the lib alias (@lib/… → aliases.lib).

If the project already uses shadcn/ui, you already have this file. Otherwise create a minimal components.json with only the schema-required fields (style, tailwind, rsc, aliases):

1
{
2
  "$schema": "https://ui.shadcn.com/schema.json",
3
  "style": "default",
4
  "rsc": false,
5
  "tailwind": {
6
    "config": "",
7
    "css": "src/styles.css",
8
    "baseColor": "neutral",
9
    "cssVariables": true
10
  },
11
  "aliases": {
12
    "components": "@/components",
13
    "utils": "@/lib/utils",
14
    "lib": "@/lib"
15
  }
16
}

aliases requires components and utils. Add lib so Flow installs under @/lib/flow/*. Point TypeScript path aliases the same way, for example "@/*": ["./src/*"] in tsconfig.json.

Install the complete Flow bundle when you want every helper at once.

pnpm dlx shadcn@latest add https://archyn.net/r/flow.json

Install a single item when you only need one helper.

pnpm dlx shadcn@latest add https://archyn.net/r/task.json

Files land under @/lib/flow/* (for example @/lib/flow/task).

Quick Start

1
import { map, pipe, retry, task, timeout } from "@/lib/flow";
2

3
type ProfileError = { kind: "not-found" } | { kind: "rate-limited" };
4

5
const loadProfile = task<string, { id: string; name: string }, ProfileError>(
6
  async (id, context) => {
7
    const response = await fetch(`/api/profiles/${id}`);
8

9
    if (response.status === 404) return context.fail({ kind: "not-found" });
10
    if (response.status === 429) return context.fail({ kind: "rate-limited" });
11

12
    return response.json();
13
  },
14
);
15

16
const toName = task((profile: { id: string; name: string }) => profile.name);
17

18
const workflow = pipe(
19
  retry(loadProfile, {
20
    attempts: 3,
21
    delay: 200,
22
    when: (error) => error.kind === "rate-limited",
23
  }),
24
  toName,
25
);
26

27
const boundedWorkflow = timeout(workflow, 1000);

Core Concepts

Flow is built around a small set of types. Behavior describes executable workflow units, Result describes explicit outcomes, and RuntimeContext carries cancellation plus optional application context.

Expected failures should be returned as typed domain errors with context.fail, err, or another Result helper. They stay visible in TypeScript and compose through helpers such as sequence, pipe, all, recover, and mapError.

Thrown exceptions are runtime failures. Flow captures them as Thrown so programming errors and unexpected platform failures do not get confused with domain errors.

Every Behavior runs with an AbortSignal. Helpers check the signal before starting work and pass linked child signals to nested work where needed. timeout, race, and all abort child controllers when continuing work is no longer useful.

Cancellation is cooperative: code that performs long-running work should observe context.signal or use helpers such as wait, timeout, and delay.

Use task to bring application code into Flow. Use sequence or pipe for dependent steps. Use map and tap for success-only transforms and effects. Use recover, catchKind, and mapError for expected domain failures. Use all, allSettled, and race for keyed parallel work.

Learning Path

FAQ

For installation choices, cancellation details, and helper comparisons, read the Flow FAQ.