@canonical/task

A monadic effect framework for composable, testable, dry-runnable CLI operations.

Tasks are pure descriptions of computations — they don't execute until interpreted. This lets you test filesystem operations, shell commands, and user prompts without touching real I/O.

Installation

bun add @canonical/task

Entry points

The package ships two entries, split by what they reach:

• @canonical/task — the node-free base: core types, the task monad, effect constructors, primitives, combinators, the dry-run/testing interpreters (dryRun, dryRunWith, collectEffects, …), undo collection (collectUndos), and TaskExecutionError. No Node builtin is reachable from this entry's import graph (pinned by a closure-walking test), so it bundles cleanly for browser and edge targets. Everything about describing, composing, and previewing work lives here.
• @canonical/task/node — the node-touching interpreters: runTask / run / executeEffect (which execute filesystem, exec, and prompt effects, importing node:fs/promises, node:path, and node:child_process) and runUndo. Only actually running a task against the host needs this entry.

The split matters because module resolution happens before tree-shaking: if the interpreters lived in the base entry, importing even a single pure function would pull node: imports into the module graph and fail any browser-platform build — regardless of what the bundle actually uses.

Quick Start

import { gen, $, writeFile, readFile, info } from "@canonical/task";
import { runTask } from "@canonical/task/node";

const setup = gen(function* () {
  const name = yield* $(readFile("name.txt"));
  yield* $(writeFile("greeting.txt", `Hello, ${name}!`));
  yield* $(info("Done"));
});

await runTask(setup);

Core Concepts

Task Monad

A Task<A> is one of three things:

• Pure — a completed computation holding a value
• Effect — a side-effect description with a continuation
• Fail — a failed computation with a structured error

Tasks compose with flatMap or, more ergonomically, with generator syntax:

import { flatMap, readFile, writeFile } from "@canonical/task";

// flatMap style
const greet = flatMap(
  readFile("name.txt"),
  (name) => writeFile("greeting.txt", `Hello, ${name}!`),
);

Generator Syntax

The gen / $ pair lets you write sequential effectful code without nested flatMap chains. Use yield* with $(task) to unwrap a task and get its value:

import { gen, $, readFile, writeFile, info, exists } from "@canonical/task";

const migrate = gen(function* () {
  const raw = yield* $(readFile("config.json"));
  const config = JSON.parse(raw);

  config.version = 2;

  yield* $(writeFile("config.json", JSON.stringify(config, null, 2)));
  yield* $(info(`Migrated to v${config.version}`));

  return config;
});

Under the hood, gen composes flatMap calls — the task is still a pure data structure until interpreted. Use whichever style you prefer; gen is recommended for anything beyond two or three steps.

Effects

Effects are pure data — tagged unions describing what should happen:

Primitives

Task-returning wrappers for every effect. These are the building blocks you'll use most:

import {
  readFile, writeFile, appendFile, copyFile, copyDirectory,
  deleteFile, deleteDirectory, mkdir, exists, symlink, glob,
  exec, execSimple,
  prompt, promptText, promptConfirm, promptSelect, promptMultiselect,
  log, debug, info, warn, error,
  getContext, setContext, withContext,
  noop, succeed,
} from "@canonical/task";

File system

const content = yield* $(readFile("src/index.ts"));
yield* $(writeFile("dist/index.js", compiled));
yield* $(appendFile("log.txt", `Built at ${Date.now()}\n`));
yield* $(copyFile("template.json", "output/package.json"));
yield* $(copyDirectory("templates/", "output/"));
yield* $(mkdir("output/lib"));
yield* $(symlink("../shared/utils", "src/utils"));

const found = yield* $(exists("tsconfig.json"));
const files = yield* $(glob("src/**/*.ts", "."));

Process execution

const result = yield* $(exec("git", ["status", "--short"]));
// result: { stdout: string, stderr: string, exitCode: number }

const simple = yield* $(execSimple("ls -la"));

User prompts

const name = yield* $(promptText("name", "Project name?", "my-app"));
const ok = yield* $(promptConfirm("confirm", "Continue?", true));
const lang = yield* $(promptSelect("lang", "Language?", [
  { label: "TypeScript", value: "ts" },
  { label: "JavaScript", value: "js" },
]));
const features = yield* $(promptMultiselect("features", "Features?", [
  { label: "Linting", value: "lint" },
  { label: "Testing", value: "test" },
]));

Logging

yield* $(debug("Verbose detail"));   // shown with --verbose
yield* $(info("Progress update"));
yield* $(warn("Non-fatal issue"));
yield* $(error("Something broke"));

Context

Context is a key-value store that lives for the duration of a task execution. Use it to pass data between steps without threading values manually:

import { gen, $, setContext, getContext, withContext } from "@canonical/task";

const setup = gen(function* () {
  yield* $(setContext("projectName", "my-app"));

  // later, in a different part of the task tree
  const name = yield* $(getContext<string>("projectName"));
  // name: "my-app"
});

// withContext sets a key for the duration of a child task
const scoped = withContext("env", "production", deployTask);

Context is backed by a Map<string, unknown> in the production interpreter. The dry-run interpreter does not persist context by default — use dryRunWith to provide mock context values.

Error Model

Tasks fail with structured TaskError values:

interface TaskError {
  code: string;              // programmatic error code
  message: string;           // human-readable description
  cause?: unknown;           // original error that caused this failure
  context?: Record<string, unknown>;  // additional structured data
  stack?: string;            // stack trace if available
  suppressed?: TaskError[];  // for parallel: all errors, not just the first
}

Creating errors

import { fail, failWith } from "@canonical/task";

const notFound = failWith("FILE_NOT_FOUND", "Config file missing");

const detailed = fail({
  code: "VALIDATION_FAILED",
  message: "Schema mismatch",
  context: { path: "config.json", expected: "v2" },
});

The framework defines base error codes (FILE_NOT_FOUND, EXEC_FAILED, PROMPT_CANCELLED, TASK_INTERRUPTED, INTERNAL); consumers can use any string code.

Handling errors

import { recover, mapError, orElse, optional, attempt, fold } from "@canonical/task";

// recover: catch a failure and produce a new task
const safe = recover(riskyTask, (err) =>
  err.code === "FILE_NOT_FOUND" ? writeFile("config.json", "{}") : fail(err),
);

// mapError: transform the error without changing recovery
const retagged = mapError(innerTask, (err) => ({
  ...err,
  code: "DEPLOY_FAILED",
  context: { ...err.context, phase: "build" },
}));

// orElse: try A, fall back to B
const config = orElse(readFile("config.local.json"), readFile("config.json"));

// optional: swallow failure, return undefined
const maybePkg = optional(readFile("package.json"));

// attempt: capture success or failure as a value
const result = yield* $(attempt(riskyTask));
if (result.ok) { /* result.value */ } else { /* result.error */ }

// fold: handle both branches and unify the type
const status = fold(deployTask, () => "deployed", (err) => `failed: ${err.code}`);

Parallel errors

When parallel tasks fail, the first error becomes the primary TaskError and any remaining errors are attached as suppressed:

// If tasks[0] and tasks[2] both fail:
// error.code      → first failure's code
// error.suppressed → [task[2]'s error]

Combinators

Compose tasks into larger workflows:

Sequencing

import { sequence, sequence_, traverse, traverse_ } from "@canonical/task";

// Run in order, collect results
const contents = sequence([readFile("a.txt"), readFile("b.txt")]);

// Run in order, discard results
sequence_([writeFile("a.txt", "A"), writeFile("b.txt", "B")]);

// Map + sequence over an array
const compiled = traverse(sourceFiles, (f) => readFile(f));

// Map + sequence, discard results
traverse_(files, (f) => deleteFile(f));

Parallel execution

import { parallel, parallelN, race } from "@canonical/task";

// Run concurrently, collect all results
const all = parallel([fetchA, fetchB, fetchC]);

// Run with concurrency limit (batches of 3)
const throttled = parallelN(3, manyTasks);

// Return first to complete
const fastest = race([mirrorA, mirrorB]);

Conditionals

import { when, unless, ifElse, whenM, ifElseM } from "@canonical/task";

// Run only if condition is true
when(isDirty, cleanUp);

// Run only if condition is false
unless(isCI, promptForConfirmation);

// Choose between two tasks
ifElse(hasConfig, loadConfig, useDefaults);

// Condition is itself a task
whenM(exists("package.json"), installDeps);

// Both condition and branches are tasks
ifElseM(exists(".env"), loadEnv, createEnv);

Dispatch

import { switchMap } from "@canonical/task";

// Detect-then-dispatch: run a detection task, branch on its result
const result = switchMap(
  detectHarness,                // Task<"jest" | "vitest" | null>
  {
    jest: configureJest,        // Task<Config>
    vitest: configureVitest,    // Task<Config>
  },
  useDefaultConfig,             // fallback Task<Config>
);

Error handling

import { retry, orElse, optional, attempt, bracket, ensure } from "@canonical/task";

// Retry up to 3 times
const resilient = retry(flakyTask, 3);

// Try primary, fall back to secondary
const config = orElse(readFile("local.json"), readFile("default.json"));

// Swallow errors, return undefined
const maybe = optional(readFile("optional.json"));

// Capture result or error as a value
const result = attempt(riskyTask);

// Resource management (acquire → use → release, even on failure)
const safe = bracket(acquireConn, useConn, releaseConn);

// Ensure cleanup runs regardless of outcome
const withCleanup = ensure(mainTask, cleanup);

Utilities

import { tap, tapError, fold, zip, zip3 } from "@canonical/task";

// Side-effect without changing the value
const logged = tap(readFile("a.txt"), (content) => info(`Read ${content.length} bytes`));

// Side-effect on failure
const observed = tapError(riskyTask, (err) => error(`Failed: ${err.code}`));

// Handle both success and failure → unified type
const status = fold(deploy, () => "ok", (err) => `fail: ${err.code}`);

// Combine tasks into tuples
const [a, b] = yield* $(zip(readFile("a.txt"), readFile("b.txt")));
const [x, y, z] = yield* $(zip3(taskX, taskY, taskZ));

Fluent Builder

The task() / of() API provides a chainable alternative:

import { task, of, mkdir, writeFile, info } from "@canonical/task";

const result = task(mkdir("output"))
  .andThen(writeFile("output/a.txt", "A"))
  .andThen(writeFile("output/b.txt", "B"))
  .andThen(info("Done!"))
  .unwrap();

const doubled = of(21)
  .map((n) => n * 2)
  .flatMap((n) => writeFile("answer.txt", String(n)))
  .unwrap();

Call .unwrap() to extract the underlying Task<A> when you need to pass it to combinators or interpreters.

Interpreters

Tasks are inert data until an interpreter walks the structure and decides what to do with each effect. The package ships three interpreters:

Production interpreter (runTask)

Executes effects against real I/O — filesystem, processes, prompts:

import { runTask } from "@canonical/task/node";

const value = await runTask(myTask);

runTask accepts a RunTaskOptions object:

await runTask(myTask, {
  // Shared key-value context for ReadContext/WriteContext effects
  context: new Map([["env", "production"]]),

  // Custom prompt handler (required if the task uses Prompt effects)
  promptHandler: async (effect) => {
    // effect.question: PromptQuestion
    return "user input";
  },

  // Log routing (default: console.log with level prefix)
  onLog: (level, message) => logger[level](message),

  // Effect lifecycle hooks
  onEffectStart: (effect) => { /* before each effect */ },
  onEffectComplete: (effect, durationMs) => { /* after each effect */ },

  // AbortSignal for interruption
  signal: controller.signal,
});

When a task fails, runTask throws a TaskExecutionError that wraps the TaskError:

import { TaskExecutionError } from "@canonical/task";
import { runTask } from "@canonical/task/node";

try {
  await runTask(myTask);
} catch (err) {
  if (err instanceof TaskExecutionError) {
    console.log(err.code);          // error code string
    console.log(err.taskError);     // full TaskError object
  }
}

Dry-run interpreter (dryRun)

Collects effects without executing them. Each effect gets a mock return value so the task can continue:

import { dryRun } from "@canonical/task";

const { value, effects } = dryRun(myTask);
// value: the task's return value (using mocked effect results)
// effects: Effect[] — every effect the task would have performed

Default mocks: ReadFile → "[mock content of <path>]", Exists → true, Exec → { stdout: "", stderr: "", exitCode: 0 }, Prompt → default or first choice, write effects → undefined.

The dry-run interpreter tracks a virtual filesystem — files created by WriteFile or MakeDir effects are visible to subsequent Exists checks within the same run.

Custom mocks with dryRunWith

Override mock behaviour per effect type:

import { dryRunWith } from "@canonical/task";

const mocks = new Map([
  ["ReadFile", (effect) => {
    if (effect.path === "package.json") return '{"name": "my-app"}';
    return "default content";
  }],
  ["Exists", () => false],
]);

const { value, effects } = dryRunWith(myTask, mocks);

Effect analysis utilities

import {
  collectEffects, countEffects, filterEffects,
  getFileWrites, getAffectedFiles,
} from "@canonical/task";

const effects = collectEffects(myTask);

countEffects(effects);
// { WriteFile: 3, ReadFile: 1, Log: 2 }

filterEffects(effects, "WriteFile");
// [{ _tag: "WriteFile", path: "...", content: "..." }, ...]

getFileWrites(effects);
// [{ path: "a.txt", content: "A" }, ...]

getAffectedFiles(effects);
// ["a.txt", "b.txt", "output/"] — sorted, deduplicated

Undo interpreter (runUndo)

Walks the task tree with mocked forward effects (like dryRun), collects the undo task attached to each effect, then executes them in reverse (LIFO) order. This enables --undo on any CLI command without storing state — the same task definition plus the same answers yields deterministic undo.

import { collectUndos } from "@canonical/task";
import { runUndo } from "@canonical/task/node";

// Forward run:
await runTask(generator.generate(answers));

// Undo (later, same answers):
await runUndo(generator.generate(answers));

How undo metadata works

Write-capable effects carry an optional undo?: Task<void> field. Primitives supply sensible defaults:

Custom undo

Override the default undo or provide one where no default exists:

// Custom undo for append
appendFile(indexPath, exportLine, true, {
  undo: removeLineFromFile(indexPath, exportLine),
});

// Disable default undo
writeFile(tempPath, content, { undo: null });

Collecting undos without executing

const undos = collectUndos(myTask);
// undos: Task<void>[] — undo tasks in forward execution order
// (runUndo reverses them automatically)

Composability

Undo composes automatically with all existing combinators:

• when(false, writeFile(...)) — skipped effects produce no undos
• sequence_([...]) — undos collected in sequence, executed in reverse
• parallel([...]) — undos collected from all children
• gen(function* () { ... }) — works identically

Test assertions

import { assertEffects, assertFileWrites, expectTask } from "@canonical/task";

// Assert exact effect sequence
assertEffects(myTask, [
  { _tag: "MakeDir", path: "output" },
  { _tag: "WriteFile", path: "output/index.ts" },
]);

// Assert which files would be written
assertFileWrites(myTask, ["output/index.ts", "output/package.json"]);

// Fluent matcher
const result = expectTask(myTask);
result.toHaveValue("done");
result.toHaveEffectCount(3);
result.toWriteFile("output/index.ts");
result.toNotWriteFile("output/secret.key");

API Summary

License

LGPL-3.0