Reproduce a production bug on your laptop, no database required.
Pure Effect records what your business logic did in production and replays it anywhere: time-travel debugging for JavaScript and TypeScript. Your business logic returns plain objects describing the I/O it would perform, instead of performing it. You can read those objects in a test or replay them from a failed production run, and the database is never touched until the interpreter runs them.
It works on your machine. It broke in production. You can't reproduce it.
The cause is usually the same: business logic and I/O are tangled together. When you write await db.findUser(email), the call fires immediately, mid-logic. So a test can only check what happened by making the I/O happen too, against a mock, a fake, or a container. And when production fails, all you have is a stack trace, because the calls the request actually made were never captured to replay.
async / await: the I/O is the logic
// The call fires immediately, mid-logic. async function registerUser(input) { const found = await db.findUser(input.email); if (found) throw new Error('Email in use'); return db.saveUser(input); } // To test it you must run it. When it fails // in prod, nothing was recorded to replay.
You check behavior by executing it. The failed run leaves no trace you can step through.
pure-effect: the logic returns I/O as data
// Read what it would do first. Nothing ran. const flow = registerUserFlow(input); assert.equal(flow.cmd.name, 'cmdFindUser'); // Feed in what production saw and walk the // exact same path, no database is touched. const next = flow.next(recordedUser); assert.equal(next.cmd.name, 'cmdSaveUser');
You check it by reading the tree. The same calls can be recorded in prod and replayed here, with no infrastructure.
Six pieces. Learnable in an afternoon.
Every Effect is one of these shapes. They compose into trees the interpreter walks at the edge of your system.
Success(value)
A successful computation result. Returns { type: 'Success', value }. Any pipeline step can return one to feed the next.
Failure(error)
Stops the pipeline immediately and short-circuits remaining steps. Optional initialInput is preserved for diagnostics.
Command(cmd, next?, meta?)
A side effect described as data. cmd is the function that would run; next turns its result into the next Effect, defaulting to a pass-through. meta.name names the step for traces, replay, and spans.
Ask(next)
Reads the context object passed to runEffect such as tenant, request id, and config without threading it through every signature.
Retry(effect, opts?)
Wraps any Effect with retry-on-failure. Configure attempts, delay, backoff. On exhaustion: a structured Failure, or a fallback Effect via onExhausted.
Parallel(effects, next?)
Runs Effect trees concurrently. Ask context flows into every branch. First Failure short-circuits.
import { Success, Failure, Command, effectPipe, runEffect } from 'pure-effect'; // Pure. No I/O, instantly testable. const validateRegistration = (input) => { if (!input.email.includes('@')) return Failure('Invalid email.'); if (input.password.length < 8) return Failure('Password too short.'); return Success(input); }; // A Command object. It does NOT call the database. const ensureEmailAvailable = (input) => { const cmdFindUser = () => db.findUser(input.email); const next = (found) => (found ? Failure('Email already in use.') : Success(input)); return Command(cmdFindUser, next); }; // With no continuation, the result passes straight through. const saveUser = (input) => { const cmdSaveUser = () => db.saveUser(input); return Command(cmdSaveUser); }; // Pipeline: every step receives the value the previous step produced. const registerUserFlow = (input) => effectPipe(validateRegistration, ensureEmailAvailable, saveUser)(input); // Test: assert on structure, no mocks, no I/O. const flow = registerUserFlow({ email: '[email protected]', password: 'password123' }); assert.equal(flow.cmd.name, 'cmdFindUser'); assert.equal(flow.next(null).cmd.name, 'cmdSaveUser'); // Run: hand the tree to the interpreter at the boundary. const result = await runEffect(registerUserFlow(input), { flowName: 'register' });
What you get out of the box.
Assert what your code would do.
Pipelines return inert objects. Walk the tree and check each step: no mock, no in-memory fake, no container.
Step through the failed request locally.
Record what each Command returned in production, then replay the trace through the same flow to retrace the exact path it took: narrated, timed, and with zero I/O. Errors replay faithfully, cause chains included, and a divergent flow raises a TimeParadox.
await timeTravel(checkoutFlow, trace); // no database, no network
Test resilience without waiting.
Wrap any Effect with retry semantics, and recover in-flow when every attempt fails: onExhausted runs a fallback Effect whose success feeds the rest of the pipeline. Because it is all plain data, tests assert on it directly: no timers, no sleeps, no flaky timing.
Concurrent branches, ordered results.
Supports cooperative event cancellation. Sibling branches are cancelled on the first failure.
Context without polluting signatures.
Resolve tenant, trace id, or config from the framework layer. Domain functions stay clean and just Ask.
Lifecycle hooks for tracing.
onRun, onStep, and onBeforeCommand let you wrap workflows in spans without touching domain code. Configurations merge, so tracing and production recording share the hooks.
Where it fits, and where it doesn't.
Pure Effect uses the same record-and-replay idea as durable execution engines, minus the server. A flow is one finite operation you can read before it runs. Use it for work that starts and finishes within a request, not for workflows that sleep for days.
Hand the AI last night's incident. It can't touch production.
A recorded trace is the only thing that enters the replay sandbox. Inside it, an agent re-runs the failing request as many times as it needs: read what happened step by step, edit the flow, replay again. The functions that talk to your database and your payment provider are never invoked during replay, not mocked and not disabled, simply never called. When the recording plays through to success, the incident leaves the sandbox as a regression test that runs in milliseconds forever.
The same property covers generation, not just maintenance: because a flow is plain data, AI-written code can be audited by reading the tree before anything executes.
async / await: run to verify
// Did the AI handle the error path? // Did it thread context correctly? // You won't know until you run it. async function registerUser(input) { const found = await db.findUser(input.email); if (found) throw new Error('Email in use'); return db.saveUser(input); // awaited? who knows. }
You audit by executing. Every verification touches infrastructure.
pure-effect: read to verify
// AI generated this flow. Inspect it before it runs. const flow = registerUserFlow(input); assert.equal(flow.type, 'Command'); assert.equal(flow.cmd.name, 'cmdFindUser'); const step2 = flow.next(null); assert.equal(step2.cmd.name, 'cmdSaveUser'); // Control flow confirmed. Nothing executed.
You audit by reading the tree. No database, no network.
Safety is unconditional; confirmation is not. A fix that restructures the flow fails loudly at the exact point it diverges from the recording, and still runs no I/O. The worst an agent can do in the sandbox is be wrong.