pure-effect 0.6.0 → 0.7.0

package/.claude/settings.local.json

@@ -5,7 +5,8 @@
       "Bash(npm test *)",
       "Bash(git *)",
       "Bash(node *)",
-      "Bash(npx tsc *)"
+      "Bash(npx tsc *)",
+      "Bash(npx tsd *)"
     ]
   }
 }

package/CLAUDE.md

@@ -17,41 +17,50 @@ No build or lint step — the library ships as plain ES modules with no transpil
 
 ### Core abstractions (all in `index.js`)
 
-| Export                         | Shape                                      | Purpose                                                                                |
-| ------------------------------ | ------------------------------------------ | -------------------------------------------------------------------------------------- |
-| `Success(value)`               | `{ type: 'Success', value }`               | Wraps a successful result                                                              |
-| `Failure(error, initialInput)` | `{ type: 'Failure', error, initialInput }` | Short-circuits the pipeline                                                            |
-| `Command(cmdFn, nextFn, meta)` | `{ type: 'Command', cmd, next, meta }`     | Defers a side effect for the interpreter                                               |
-| `Ask(nextFn)`                  | `{ type: 'Ask', next }`                    | Reads the `context` passed to `runEffect`; passes it to `nextFn`                       |
-| `effectPipe(...fns)`           | —                                          | Composes functions into a sequential pipeline via `chain`                              |
-| `runEffect(effect, context)`   | async                                      | Interpreter: traverses the effect tree, executes Commands; resolves `Ask` with context |
-| `configureEffect(options)`     | —                                          | Injects telemetry hooks (`onStep`, `onRun`, `onBeforeCommand`)                         |
+| Export                                    | Shape                                      | Purpose                                                                                                                                   |
+| ----------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `Success(value)`                          | `{ type: 'Success', value }`               | Wraps a successful result                                                                                                                 |
+| `Failure(error, initialInput)`            | `{ type: 'Failure', error, initialInput }` | Short-circuits the pipeline                                                                                                               |
+| `Command(cmdFn, nextFn, meta)`            | `{ type: 'Command', cmd, next, meta }`     | Defers a side effect for the interpreter                                                                                                  |
+| `Ask(nextFn)`                             | `{ type: 'Ask', next }`                    | Reads the `context` passed to `runEffect`; passes it to `nextFn`                                                                          |
+| `Retry(effect, options)`                  | `{ type: 'Retry', effect, options, next }` | Wraps any Effect tree with retry-on-failure semantics; handled natively by the interpreter                                                |
+| `effectPipe(...fns)`                      | —                                          | Composes functions into a sequential pipeline via `chain`                                                                                 |
+| `runEffect(effect, context, callConfig?)` | async                                      | Interpreter: traverses the effect tree, executes Commands; resolves `Ask` and `Retry`; per-call `callConfig` overrides global defaults    |
+| `configureEffect(options)`                | —                                          | Sets process-wide telemetry hooks (`onStep`, `onRun`, `onBeforeCommand`) and global `retry` defaults; overridden by per-call `callConfig` |
 
 ### Data flow
 
 ```
 effectPipe(f1, f2, f3)(input)
-  → returns tree of Success / Failure / Command / Ask values
-  → f1 runs eagerly here
+  → returns tree of Success / Failure / Command / Ask / Retry values
+  → f1 runs eagerly here; initialInput is threaded through chain so every
+    node in the tree carries it without post-construction mutation
 
-runEffect(tree, context)
+runEffect(tree, context, callConfig?)
+  → per-call callConfig merges over global configureEffect defaults
   → executes Commands async, passes results into next(result), repeats
   → resolves Ask by calling next(context), continues
+  → resolves Retry via an inner execute() loop (not recursive runEffect),
+    so onRun fires exactly once per runEffect call regardless of attempts;
+    on exhaustion returns Failure({ retryExhausted: true, lastError, attempts })
   → resolves to final Success or Failure
 ```
 
-The `chain` combinator (internal) drives composition: `Success` passes its value to the next function, `Failure` short-circuits, `Command` defers execution, `Ask` wraps its continuation so the chain propagates through it. `runEffect` loops through the tree with a `while` loop rather than recursion.
+The `chain` combinator (internal) drives composition: `Success` passes its value to the next function, `Failure` short-circuits, `Command` defers execution, `Ask` wraps its continuation so the chain propagates through it, `Retry` wraps its continuation via object spread (same pattern as `Ask`). `chain` accepts an optional `initialInput` parameter; `effectPipe` passes the pipeline's starting value through every `chain` call so that `initialInput` is stamped on all nodes — including mid-pipeline `Failure`s — without mutation. `runEffect` loops through the tree with a `while` loop rather than recursion.
 
-`configureEffect` hooks:
+`configureEffect` options (all overridable per-call via `runEffect`'s third argument):
 
 - `onStep` — fires on every Command execution; wraps the `cmd` call (use for per-command tracing)
-- `onRun` — fires once per `runEffect` call; wraps the whole workflow (use for top-level spans); receives `context.flowName` as the third argument
+- `onRun` — fires once per `runEffect` call; wraps the whole workflow (use for top-level spans); receives `context.flowName` as the third argument; does **not** fire again for Retry attempts
 - `onBeforeCommand` — intercepts each Command before execution; receives the Command and the `context` passed to `runEffect`
+- `retry` — global Retry defaults `{ attempts, delay, backoff }`; per-use options passed to `Retry(effect, options)` merge on top (defaults: `attempts: 3`, `delay: 100ms`, `backoff: 1` flat)
 
 ### TypeScript
 
 Full generic type declarations are in `index.d.ts` and referenced via the `types` field in `package.json`. Type-level tests live in `test/types.test-d.ts` and run via `tsd` as part of `npm test`.
 
+`Effect<T, E, Ctx>` carries three type parameters: value type, error union, and context type. `Ctx` flows through `AskState`, `CommandState`, `RetryState`, and all `effectPipe` overloads. `Ask<T, E, Ctx>` types the context callback parameter, and `runEffect<T, E, Ctx>` enforces that the supplied context matches. `Ctx` defaults to `unknown` so existing code without context typing is unaffected.
+
 ### Observability
 
 `opentelemetry-example.js` shows how to wire OpenTelemetry spans into `configureEffect`'s hooks — it is reference code, not part of the library.

package/README.md

@@ -1,10 +1,29 @@
 # Pure Effect
 
-**Pure Effect** is a tiny, zero-dependency effect system for writing pure, testable JavaScript without mocks.
-
-It implements the "Functional Core, Imperative Shell" pattern, allowing you to decouple your business logic from external side effects like database calls or API requests. Instead of executing side effects immediately, your functions return Commands which are executed later by an interpreter.
-
-**Pure Effect** ships with JSDoc type annotations for JavaScript users and a bundled declaration file with full generic types for TypeScript users.
+[![npm version](https://img.shields.io/npm/v/pure-effect)](https://www.npmjs.com/package/pure-effect)
+[![bundle size](https://img.shields.io/badge/minified%2Bgzipped-%3C1KB-brightgreen)](https://bundlephobia.com/package/pure-effect)
+[![license](https://img.shields.io/npm/l/pure-effect)](./LICENSE)
+
+**Pure Effect** is a zero-dependency effect library for JavaScript and TypeScript with built-in support for dependency injection, retry, and OpenTelemetry where business logic is plain data you can test without mocks.
+
+- No mocks needed to test async pipelines
+- Inject context without touching function signatures
+- Built-in retry with configurable delay and backoff
+- OpenTelemetry-ready via lifecycle hooks
+- Zero dependencies, under 1 KB minified and gzipped
+- Works in JavaScript and TypeScript (full generics, bundled `.d.ts`)
+- Five primitives: learn the whole API in an afternoon
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Testing Without Mocks](#testing-without-mocks)
+- [Passing Runtime Context](#passing-runtime-context)
+- [Retrying Transient Failures](#retrying-transient-failures)
+- [TypeScript: Typed Errors and Context](#typescript-typed-errors-and-context)
+- [Why Pure Effect](#why-pure-effect)
+- [API Reference](#api-reference)
 
 ## Installation
 
@@ -12,9 +31,9 @@ It implements the "Functional Core, Imperative Shell" pattern, allowing you to d
 npm install pure-effect
 ```
 
-## Usage
+## Quick Start
 
-Here is a complete example of a User Registration flow.
+Here is a complete example of a user registration flow:
 
 ```js
 import { Success, Failure, Command, effectPipe, runEffect } from 'pure-effect';
@@ -25,40 +44,33 @@ const validateRegistration = (input) => {
     return Success(input);
 };
 
-// These functions do NOT run the DB call. They return a Command object.
-// The 'next' function defines what happens with the result of the async call.
+// Theese function return a Command object. They do NOT call the database.
 const findUser = (email) => {
-    const cmdFindUser = () => db.findUser(email); // The work to do later
-    const next = (user) => Success(user); // Wrap result in Success
-    return Command(cmdFindUser, next);
+    const cmdFindUser = () => db.findUser(email);
+    return Command(cmdFindUser, (user) => Success(user));
 };
 
 const saveUser = (input) => {
     const cmdSaveUser = () => db.saveUser(input);
-    const next = (saved) => Success(saved);
-    return Command(cmdSaveUser, next);
+    return Command(cmdSaveUser, (saved) => Success(saved));
 };
 
-const ensureEmailAvailable = (user) => {
-    return user ? Failure('Email already in use.') : Success(true);
-};
+const ensureEmailAvailable = (user) => (user ? Failure('Email already in use.') : Success(true));
 
-// The Pipeline uses arrow functions to capture 'input' from the scope where needed.
+// effectPipe threads the output of each step into the next.
+// When you need to use a captured variable instead of the piped value,
+// wrap the call in an arrow function.
 const registerUserFlow = (input) =>
     effectPipe(
-        validateRegistration,
-        () => findUser(input.email),
-        ensureEmailAvailable,
-        () => saveUser(input)
+        validateRegistration, // input -> Success(input)
+        () => findUser(input.email), // ignores piped value, uses captured input
+        ensureEmailAvailable, // found user (or null) -> Success(true)
+        () => saveUser(input) // ignores piped value, uses captured input
     )(input);
 
-// The Imperative Shell
+// Imperative shell: this is the only place side effects run
 async function registerUser(input) {
-    // logic is just a data structure until we pass it to runEffect
-    const logic = registerUserFlow(input);
-
-    // runEffect performs the actual async work
-    const result = await runEffect(logic);
+    const result = await runEffect(registerUserFlow(input));
 
     if (result.type === 'Success') {
         console.log('User created:', result.value);
@@ -70,142 +82,238 @@ async function registerUser(input) {
 
 ## Testing Without Mocks
 
-The biggest benefit of **Pure Effect** is testability. Because `registerUserFlow` returns a data structure (a tree of objects) instead of running a Promise, you can test your logic without mocking the database.
+Because pipelines return plain objects, you can assert on _what the code intends to do_ without executing any of it. Using the registration flow defined in the previous section:
 
 ```js
-// 1. Test Validation Failure
+// 1. Test validation failure synchronously
 const badInput = { email: 'bad-email', password: '123' };
 const result = registerUserFlow(badInput);
 
-assert.deepEqual(result, Failure('Invalid email format.', badInput));
-// ✅ Logic tested instantly, no async needed.
+assert.deepEqual(result, Failure('Invalid email.', badInput));
 
-// 2. Test Flow Intent (Introspection)
+// 2. Walk the pipeline to verify intent
 const goodInput = { email: 'test@test.com', password: 'password123' };
 const step1 = registerUserFlow(goodInput);
 
-// Check if the first thing the code does is try to find a user
+// First thing the code does: look up the user
 assert.equal(step1.type, 'Command');
 assert.equal(step1.cmd.name, 'cmdFindUser');
 
-// Check if the next thing the code will do is to save a user
+// Next thing: save the user (simulate "user not found" result)
 const step2 = step1.next(null);
 assert.equal(step2.type, 'Command');
 assert.equal(step2.cmd.name, 'cmdSaveUser');
-// ✅ We verified the *intent* of the code without touching a real DB.
+// The full flow is verified. The database was never touched.
 ```
 
 ## Passing Runtime Context
 
-Some values come from the framework layer such as the authenticated tenant, a request trace ID, environment config rather than from the data being processed. `Ask` lets a pipeline step read the `context` object passed to `runEffect` without touching the function signatures around it.
+Some values come from the framework layer such as an authenticated tenant, a request trace ID, an environment config rather than from the data being processed. `Ask` lets a pipeline step read the `context` object passed to `runEffect` without threading it through every function signature.
 
-In the example below, `ctx.tenant` is identified from the subdomain or JWT by the router. The domain layer never needs it as a parameter; it just asks for it when needed:
+In the example below, `ctx.tenant` is resolved from the JWT by the router. The domain layer never receives it as a parameter; it just asks for it when needed:
 
 ```js
 import { Success, Failure, Command, Ask, effectPipe, runEffect } from 'pure-effect';
 
 const findProduct = (productId) =>
-    Ask((ctx) =>
-        Command(
-            () => db[ctx.tenant].findProduct(productId),
-            (product) => (product ? Success(product) : Failure('Product not found.'))
-        )
-    );
+    Ask((ctx) => {
+        const cmdFindProduct = () => db[ctx.tenant].findProduct(productId);
+        return Command(cmdFindProduct, (product) => (product ? Success(product) : Failure('Product not found.')));
+    });
 
 const reserveStock = (product) =>
-    Ask((ctx) =>
-        Command(
-            () => db[ctx.tenant].reserveStock(product.id),
-            (reserved) => Success({ product, reserved })
-        )
-    );
-
-const checkoutFlow = (productId) =>
-    effectPipe(
-        () => findProduct(productId),
-        ({ product }) => reserveStock(product)
-    )(productId);
-```
+    Ask((ctx) => {
+        const cmdReserveStock = () => db[ctx.tenant].reserveStock(product.id);
+        return Command(cmdReserveStock, (reserved) => Success({ product, reserved }));
+    });
 
-The router identifies the tenant and passes it as context. `checkoutFlow` never needs a tenant parameter:
+const checkoutFlow = (productId) => effectPipe(findProduct, ({ product }) => reserveStock(product))(productId);
 
-```js
 app.post('/checkout', async (req, res) => {
     const result = await runEffect(checkoutFlow(req.body.productId), {
-        tenant: req.subdomains[0] // e.g. 'acme' from acme.myapp.com
+        tenant: req.tenant
     });
     res.json(result);
 });
 ```
 
+## Retrying Transient Failures
+
+`Retry` wraps any Effect tree with retry-on-failure semantics. Like everything else in Pure Effect, the retry configuration is a plain object you can inspect and assert on without running anything.
+
+```js
+import { Success, Failure, Command, Retry, effectPipe, runEffect } from 'pure-effect';
+
+const fetchWeather = (city) => {
+    const cmdFetchWeather = () =>
+        fetch(`https://example-weather-api.com/v1/current?city=${city}`).then((r) => r.json());
+    return Retry(
+        Command(cmdFetchWeather, (data) => (data.error ? Failure(data.error) : Success(data))),
+        { attempts: 3, delay: 200, backoff: 2 } // 200ms, 400ms, 800ms
+    );
+};
+
+// Assert on the retry config without making any network calls
+const weatherFn = fetchWeather('Tokyo');
+assert.equal(weatherFn.type, 'Retry');
+assert.equal(weatherFn.options.attempts, 3);
+assert.equal(weatherFn.effect.type, 'Command');
+```
+
+When all attempts are exhausted, `runEffect` returns a structured `Failure`:
+
+```js
+{
+    retryExhausted: true,
+    lastError: <the last error>,
+    attempts: 3
+}
+```
+
+Global defaults can be set via `configureEffect` and overridden per-use:
+
+```js
+configureEffect({
+    retry: { attempts: 3, delay: 100, backoff: 1 } // flat delay by default
+});
+
+// Per-use options are merged on top of global defaults
+Retry(effect, { delay: 500 }); // uses global attempts, custom delay
+```
+
+## TypeScript: Typed Errors and Context
+
+### Error union across pipeline steps
+
+Each step in `effectPipe` carries its own error type. The compiler collects them into a union automatically, so the return type of `runEffect` tells you exactly which errors are possible with full exhaustive narrowing, no extra boilerplate.
+
+```ts
+import { effectPipe, runEffect, Failure, Success, Command } from 'pure-effect';
+import type { Effect } from 'pure-effect';
+
+type ValidationError = 'invalid_email' | 'weak_password';
+type ApiError = 'network_timeout' | 'rate_limited';
+
+const validate = (input: { email: string }): Effect<{ email: string }, ValidationError> => {
+    if (!input.email.includes('@')) return Failure('invalid_email');
+    return Success(input);
+};
+
+const submit = (input: { email: string }): Effect<{ id: number }, ApiError> => {
+    const cmdSubmitUser = () =>
+        fetch('/api/users', { method: 'POST', body: JSON.stringify(input) }).then((r) => r.json());
+    return Command(cmdSubmitUser, (data) => Success(data));
+};
+
+const flow = effectPipe(validate, submit);
+const result = await runEffect(flow({ email: 'user@example.com' }));
+// result: SuccessState<{ id: number }> | FailureState<ValidationError | ApiError>
+
+if (result.type === 'Failure') {
+    result.error; // 'invalid_email' | 'weak_password' | 'network_timeout' | 'rate_limited'
+}
+```
+
+### Typed context with `Ask`
+
+`Effect<T, E, Ctx>` carries a third type parameter for the context object. TypeScript enforces that `runEffect` receives a matching value when you annotate `Ask` with a context type:
+
+```ts
+import { Ask, Command, Success, Failure, effectPipe, runEffect } from 'pure-effect';
+import type { Effect } from 'pure-effect';
+
+type AppContext = { tenant: string; requestId: string };
+
+const findProduct = (productId: string): Effect<Product, 'not_found', AppContext> =>
+    Ask<Product, 'not_found', AppContext>((ctx) => {
+        const cmdFindProduct = () => db[ctx.tenant].findProduct(productId);
+        return Command(cmdFindProduct, (product) => (product ? Success(product) : Failure('not_found')));
+    });
+
+// ctx is typed as AppContext, no cast needed
+const result = await runEffect(findProduct('abc'), { tenant: 'acme', requestId: '123' });
+```
+
+## Why Pure Effect
+
+**vs. Effect-TS:** Effect-TS is a full functional programming ecosystem with fibers, streaming, schema validation, dependency injection, and is probably the right choice if you need that breadth. It arguably comes with a steep learning curve though. Pure Effect targets a narrower scope (testable pipelines, context injection, retry) and can be learned in an afternoon.
+
+**vs. fp-ts:** fp-ts applies category theory abstractions (functors, monads) to TypeScript. Pure Effect borrows only the concept of effects as data and expresses it without that vocabulary.
+
+**vs. plain async/await with mocks:** Mocks can drift from real implementations silently. Pure Effect sidesteps the problem: business logic never executes I/O, so there is nothing to mock.
+
+**When to use something else:** If your codebase has little async I/O or test isolation isn't a pain point, plain async/await is the simpler choice.
+
 ## API Reference
 
 ### `Success(value)`
 
-Returns an object `{ type: 'Success', value }`. Represents a successful computation.
+Returns `{ type: 'Success', value }`. Represents a successful computation result.
 
-### `Failure(error)`
+### `Failure(error, initialInput?)`
 
-Returns an object `{ type: 'Failure', error, initialInput }`. Represents a failed computation. Stops the pipeline immediately.
+Returns `{ type: 'Failure', error, initialInput }`. Stops the pipeline immediately and short-circuits any remaining steps.
 
-### `Command(cmdFn, nextFn, meta)`
+### `Command(cmdFn, nextFn, meta?)`
 
-Returns an object `{ type: 'Command', cmd, next, meta }`.
+Returns `{ type: 'Command', cmd, next, meta }`.
 
 - `cmdFn`: A function (sync or async) that performs the side effect.
-- `nextFn`: A function that receives the result of `cmdFn` and returns the next Effect (Success, Failure, or another Command).
-- `meta`: Optional metadata.
+- `nextFn`: Receives the result of `cmdFn` and returns the next Effect.
+- `meta`: Optional metadata (available to `onBeforeCommand`).
 
 ### `Ask(nextFn)`
 
-Returns an object `{ type: 'Ask', next }`. Reads the `context` passed to `runEffect` and passes it to `nextFn`, which returns the next Effect. Works at any point in the pipeline, before or after `Command`s.
+Returns `{ type: 'Ask', next }`. Passes the `context` from `runEffect` into `nextFn`, which returns the next Effect. Works at any point in a pipeline.
 
 ```js
 const findProduct = (productId) =>
-    Ask((ctx) =>
-        Command(
-            () => db[ctx.tenant].findProduct(productId),
-            (product) => (product ? Success(product) : Failure('Product not found.'))
-        )
-    );
+    Ask((ctx) => {
+        const cmdFindProduct = () => db[ctx.tenant].findProduct(productId);
+        return Command(cmdFindProduct, (product) => (product ? Success(product) : Failure('Product not found.')));
+    });
 ```
 
-See [Passing Runtime Context](#passing-runtime-context) for a full example.
+### `Retry(effect, options?)`
 
-### `effectPipe(...functions)`
+Returns `{ type: 'Retry', effect, options, next }`. Wraps any Effect with retry-on-failure semantics.
 
-A combinator that runs functions in sequence. It automatically handles unpacking `Success` values and passing them to the next function. If a `Failure` occurs, the pipe stops.
+- `effect`: Any Effect: a `Command`, an `effectPipe` result, or another `Retry`.
+- `options.attempts`: Max retries, not counting the first try (default: `3`).
+- `options.delay`: Ms before the first retry (default: `100`).
+- `options.backoff`: Multiplier applied to delay on each attempt (default: `1`, flat).
 
-### `runEffect(effect, context = {})`
+On exhaustion, returns `Failure({ retryExhausted: true, lastError, attempts })`.
 
-The interpreter. It takes an `effect` object, executes any nested Commands using `async/await`, and returns the final `Success` or `Failure`. The optional `context` object is available to:
+### `effectPipe(...functions)`
 
-- `Ask` continuations — use `Ask` to read context inside pipeline steps
-- The `onBeforeCommand` interceptor (see `configureEffect` below)
+Composes functions into a sequential pipeline. Each function receives the unwrapped `Success` value from the previous step. A `Failure` from any step stops the pipeline immediately.
 
-`context.flowName` may be used for naming workflows in telemetry.
+When a step needs to use a captured variable instead of the piped value, wrap it in an arrow function:
 
----
+```js
+const flow = (input) =>
+    effectPipe(
+        validate, // receives input
+        () => findUser(input.email), // ignores piped value, uses captured input
+        ensureAvailable,
+        () => saveUser(input) // ignores piped value, uses captured input
+    )(input);
+```
 
-### `configureEffect(options)`
+### `runEffect(effect, context?, callConfig?)`
 
-A configuration function that injects observability, tracing, or logging interceptors into the `runEffect` interpreter. By default, **Pure Effect** executes with zero overhead. By providing `onRun` and `onStep` callbacks, you can wrap pipeline executions and individual commands (e.g., inside OpenTelemetry spans). Please see **opentelemetry-example.js** for a quick example.
+The interpreter. Traverses the effect tree, executes Commands with `async/await`, resolves `Ask` with the supplied `context`, and returns the final `Success` or `Failure`.
 
-`configureEffect` also accepts `onBeforeCommand`, which can be used to intercept each `Command` and the context passed to `runEffect` before execution.
+- `context`: Optional object passed to `Ask` continuations and `onBeforeCommand`. `context.flowName` names the workflow in telemetry.
+- `callConfig`: Per-call overrides for `onStep`, `onRun`, `onBeforeCommand`, and `retry`. Takes precedence over `configureEffect` globals.
+- `onRun` fires exactly once per `runEffect` call. Retry attempts run inside that single span. The interpreter does not re-enter `runEffect` per attempt.
 
-- `onRun (effect, pipeline, flowName)`  
-  Fires once per `runEffect` call. It wraps the entire workflow execution.
-    - `effect`: The initial state of the effect tree (useful for extracting `initialInput`).
-    - `pipeline`: The actual interpreter. You must `await pipeline()` inside this callback to run the logic.
-    - `flowName`: The optional name of the workflow passed to `runEffect`.
+### `configureEffect(options)`
 
-- `onStep (name, type, op)`  
-  Fires every time a `Command` is executed.
-    - `name`: The name of the command function (e.g., `cmdFindUser`).
-    - `type`: Effect type.
-    - `op`: The actual side-effect function. You must `await op()` inside this callback and return its result.
+- `onRun(effect, pipeline, flowName)` wraps the entire workflow; must `await pipeline()`.
+- `onStep(name, type, op)` wraps each Command; must `await op()` and return its result.
+- `onBeforeCommand(command, context)` ires before each Command; throw to abort the pipeline.
+- `retry: { attempts?, delay?, backoff? }` global retry defaults.
 
-- `onBeforeCommand (command, context)`
-  Fires before a `Command` is executed. Ideal for inspecting metadata and context. If you throw, the pipeline stops immediately.
-    - `command`: The `Command` object.
-    - `context`: The context object passed to `runEffect`, if any.
+See **opentelemetry-example.js** in the repository for a complete OpenTelemetry wiring example.

package/index.d.ts

@@ -10,96 +10,200 @@ export type FailureState<E = unknown> = {
     initialInput?: unknown;
 };
 
-export type CommandState<R, T, E = unknown> = {
+export type CommandState<R, T, E = unknown, Ctx = unknown> = {
     type: 'Command';
     cmd: () => Promise<R> | R;
-    next: (result: R) => Effect<T, E>;
+    next: (result: R) => Effect<T, E, Ctx>;
     meta?: unknown;
     initialInput?: unknown;
 };
 
-export type AskState<T, E = unknown> = {
+export type AskState<T, E = unknown, Ctx = unknown> = {
     type: 'Ask';
-    next: (context: unknown) => Effect<T, E>;
+    next: (context: Ctx) => Effect<T, E, Ctx>;
     initialInput?: unknown;
 };
 
-export type Effect<T, E = unknown> = SuccessState<T> | FailureState<E> | CommandState<any, T, E> | AskState<T, E>;
+export type RetryOptions = {
+    attempts?: number;
+    delay?: number;
+    backoff?: number;
+};
+
+export type RetryState<T, E = unknown, Ctx = unknown> = {
+    type: 'Retry';
+    effect: Effect<T, E, Ctx>;
+    options: RetryOptions;
+    next: (value: T) => Effect<T, E, Ctx>;
+    initialInput?: unknown;
+};
+
+export type RetryExhaustedError<E = unknown> = {
+    retryExhausted: true;
+    lastError: E;
+    attempts: number;
+};
+
+export type Effect<T, E = unknown, Ctx = unknown> =
+    | SuccessState<T>
+    | FailureState<E>
+    | CommandState<any, T, E, Ctx>
+    | AskState<T, E, Ctx>
+    | RetryState<T, E, Ctx>;
 
 export declare function Success<T>(value: T): SuccessState<T>;
 
 export declare function Failure<E = unknown>(error: E, initialInput?: unknown): FailureState<E>;
 
-export declare function Command<R, T, E = unknown>(
+export declare function Command<R, T, E = unknown, Ctx = unknown>(
     cmd: () => Promise<R> | R,
-    next: (result: R) => Effect<T, E>,
+    next: (result: R) => Effect<T, E, Ctx>,
     meta?: unknown
-): CommandState<R, T, E>;
-
-export declare function Ask<T, E = unknown>(next: (context: unknown) => Effect<T, E>): AskState<T, E>;
-
-export declare function effectPipe<A, B, E = unknown>(f1: (a: A) => Effect<B, E>): (start: A) => Effect<B, E>;
-
-export declare function effectPipe<A, B, C, E = unknown>(
-    f1: (a: A) => Effect<B, E>,
-    f2: (b: B) => Effect<C, E>
-): (start: A) => Effect<C, E>;
-
-export declare function effectPipe<A, B, C, D, E = unknown>(
-    f1: (a: A) => Effect<B, E>,
-    f2: (b: B) => Effect<C, E>,
-    f3: (c: C) => Effect<D, E>
-): (start: A) => Effect<D, E>;
-
-export declare function effectPipe<A, B, C, D, F, E = unknown>(
-    f1: (a: A) => Effect<B, E>,
-    f2: (b: B) => Effect<C, E>,
-    f3: (c: C) => Effect<D, E>,
-    f4: (d: D) => Effect<F, E>
-): (start: A) => Effect<F, E>;
-
-export declare function effectPipe<A, B, C, D, F, G, E = unknown>(
-    f1: (a: A) => Effect<B, E>,
-    f2: (b: B) => Effect<C, E>,
-    f3: (c: C) => Effect<D, E>,
-    f4: (d: D) => Effect<F, E>,
-    f5: (f: F) => Effect<G, E>
-): (start: A) => Effect<G, E>;
-
-export declare function effectPipe<A, B, C, D, F, G, H, E = unknown>(
-    f1: (a: A) => Effect<B, E>,
-    f2: (b: B) => Effect<C, E>,
-    f3: (c: C) => Effect<D, E>,
-    f4: (d: D) => Effect<F, E>,
-    f5: (f: F) => Effect<G, E>,
-    f6: (g: G) => Effect<H, E>
-): (start: A) => Effect<H, E>;
-
-export declare function effectPipe<A, B, C, D, F, G, H, I, E = unknown>(
-    f1: (a: A) => Effect<B, E>,
-    f2: (b: B) => Effect<C, E>,
-    f3: (c: C) => Effect<D, E>,
-    f4: (d: D) => Effect<F, E>,
-    f5: (f: F) => Effect<G, E>,
-    f6: (g: G) => Effect<H, E>,
-    f7: (h: H) => Effect<I, E>
-): (start: A) => Effect<I, E>;
-
-export declare function effectPipe<A, B, C, D, F, G, H, I, J, E = unknown>(
-    f1: (a: A) => Effect<B, E>,
-    f2: (b: B) => Effect<C, E>,
-    f3: (c: C) => Effect<D, E>,
-    f4: (d: D) => Effect<F, E>,
-    f5: (f: F) => Effect<G, E>,
-    f6: (g: G) => Effect<H, E>,
-    f7: (h: H) => Effect<I, E>,
-    f8: (i: I) => Effect<J, E>
-): (start: A) => Effect<J, E>;
-
-export declare function runEffect<T, E = unknown>(
-    effect: Effect<T, E>,
-    context?: unknown
-): Promise<SuccessState<T> | FailureState<E>>;
+): CommandState<R, T, E, Ctx>;
+
+export declare function Ask<T, E = unknown, Ctx = unknown>(
+    next: (context: Ctx) => Effect<T, E, Ctx>
+): AskState<T, E, Ctx>;
+
+export declare function Retry<T, E = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
+    options?: RetryOptions
+): RetryState<T, E, Ctx>;
+
+export declare function effectPipe<A, B, E1 = unknown, Ctx = unknown>(
+    f1: (a: A) => Effect<B, E1, Ctx>
+): (start: A) => Effect<B, E1, Ctx>;
+
+export declare function effectPipe<A, B, C, E1 = unknown, E2 = unknown, Ctx = unknown>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>
+): (start: A) => Effect<C, E1 | E2, Ctx>;
+
+export declare function effectPipe<A, B, C, D, E1 = unknown, E2 = unknown, E3 = unknown, Ctx = unknown>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>
+): (start: A) => Effect<D, E1 | E2 | E3, Ctx>;
+
+export declare function effectPipe<
+    A,
+    B,
+    C,
+    D,
+    F,
+    E1 = unknown,
+    E2 = unknown,
+    E3 = unknown,
+    E4 = unknown,
+    Ctx = unknown
+>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>,
+    f4: (d: D) => Effect<F, E4, Ctx>
+): (start: A) => Effect<F, E1 | E2 | E3 | E4, Ctx>;
+
+export declare function effectPipe<
+    A,
+    B,
+    C,
+    D,
+    F,
+    G,
+    E1 = unknown,
+    E2 = unknown,
+    E3 = unknown,
+    E4 = unknown,
+    E5 = unknown,
+    Ctx = unknown
+>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>,
+    f4: (d: D) => Effect<F, E4, Ctx>,
+    f5: (f: F) => Effect<G, E5, Ctx>
+): (start: A) => Effect<G, E1 | E2 | E3 | E4 | E5, Ctx>;
+
+export declare function effectPipe<
+    A,
+    B,
+    C,
+    D,
+    F,
+    G,
+    H,
+    E1 = unknown,
+    E2 = unknown,
+    E3 = unknown,
+    E4 = unknown,
+    E5 = unknown,
+    E6 = unknown,
+    Ctx = unknown
+>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>,
+    f4: (d: D) => Effect<F, E4, Ctx>,
+    f5: (f: F) => Effect<G, E5, Ctx>,
+    f6: (g: G) => Effect<H, E6, Ctx>
+): (start: A) => Effect<H, E1 | E2 | E3 | E4 | E5 | E6, Ctx>;
+
+export declare function effectPipe<
+    A,
+    B,
+    C,
+    D,
+    F,
+    G,
+    H,
+    I,
+    E1 = unknown,
+    E2 = unknown,
+    E3 = unknown,
+    E4 = unknown,
+    E5 = unknown,
+    E6 = unknown,
+    E7 = unknown,
+    Ctx = unknown
+>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>,
+    f4: (d: D) => Effect<F, E4, Ctx>,
+    f5: (f: F) => Effect<G, E5, Ctx>,
+    f6: (g: G) => Effect<H, E6, Ctx>,
+    f7: (h: H) => Effect<I, E7, Ctx>
+): (start: A) => Effect<I, E1 | E2 | E3 | E4 | E5 | E6 | E7, Ctx>;
+
+export declare function effectPipe<
+    A,
+    B,
+    C,
+    D,
+    F,
+    G,
+    H,
+    I,
+    J,
+    E1 = unknown,
+    E2 = unknown,
+    E3 = unknown,
+    E4 = unknown,
+    E5 = unknown,
+    E6 = unknown,
+    E7 = unknown,
+    E8 = unknown,
+    Ctx = unknown
+>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>,
+    f4: (d: D) => Effect<F, E4, Ctx>,
+    f5: (f: F) => Effect<G, E5, Ctx>,
+    f6: (g: G) => Effect<H, E6, Ctx>,
+    f7: (h: H) => Effect<I, E7, Ctx>,
+    f8: (i: I) => Effect<J, E8, Ctx>
+): (start: A) => Effect<J, E1 | E2 | E3 | E4 | E5 | E6 | E7 | E8, Ctx>;
 
 export type StepRunner = (name: string, type: string, op: () => Promise<unknown>) => Promise<unknown>;
 
@@ -115,6 +219,13 @@ export interface EffectConfiguration {
     onStep?: StepRunner;
     onRun?: RunWrapper;
     onBeforeCommand?: CommandInterceptor;
+    retry?: RetryOptions;
 }
 
 export declare function configureEffect(options: EffectConfiguration): void;
+
+export declare function runEffect<T, E = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
+    context?: Ctx,
+    callConfig?: EffectConfiguration
+): Promise<SuccessState<T> | FailureState<E>>;

package/index.js

@@ -19,9 +19,19 @@
  * }} AskState
  */
 
+/**
+ * @typedef {{
+ *   type: 'Retry',
+ *   effect: Effect,
+ *   options: { attempts?: number, delay?: number, backoff?: number },
+ *   next: (value: any) => Effect,
+ *   initialInput?: any
+ * }} RetryState
+ */
+
 /**
  * The Union type for all possible states
- * @typedef {SuccessState | FailureState | CommandState | AskState} Effect
+ * @typedef {SuccessState | FailureState | CommandState | AskState | RetryState} Effect
  */
 
 /**
@@ -59,27 +69,56 @@ const Command = (cmd, next, meta) => ({ type: 'Command', cmd, next, meta });
  */
 const Ask = (next) => ({ type: 'Ask', next });
 
+/**
+ * Wraps an Effect tree with retry-on-failure semantics.
+ * @param {Effect} effect - The inner Effect tree to retry
+ * @param {Object} [options] - Per-use retry options; merged over global defaults at runtime
+ * @param {number} [options.attempts] - Max retries (not counting first try)
+ * @param {number} [options.delay] - Ms before first retry
+ * @param {number} [options.backoff] - Multiplier applied to delay on each subsequent retry
+ * @returns {RetryState}
+ */
+const Retry = (effect, options = {}) => ({
+    type: 'Retry',
+    effect,
+    options,
+    next: (value) => Success(value)
+});
+
 /**
  * Connects an Effect to the next function in the pipeline.
- * Handles the branching logic for Success, Failure, Command, and Ask.
+ * Handles the branching logic for Success, Failure, Command, Ask, and Retry.
  *
  * @param {Effect} effect - The current Effect object
  * @param {(value: any) => Effect} fn - The next function to run if the current effect is a Success
  * @returns {Effect} The composed Effect
  */
-const chain = (effect, fn) => {
+/**
+ * @param {Effect} effect
+ * @param {(value: any) => Effect} fn
+ * @param {any} [initialInput]
+ * @returns {Effect}
+ */
+const chain = (effect, fn, initialInput) => {
+    const withII = (/** @type {Effect} */ e) =>
+        initialInput !== undefined && e.initialInput === undefined ? { ...e, initialInput } : e;
+
     switch (effect.type) {
         case 'Success':
-            return fn(effect.value);
+            return withII(fn(effect.value));
         case 'Failure':
-            return effect;
+            return withII(effect);
         case 'Command': {
-            const next = (/** @type {any} */ result) => chain(effect.next(result), fn);
-            return Command(effect.cmd, next, effect.meta);
+            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput);
+            return withII(Command(effect.cmd, next, effect.meta));
         }
         case 'Ask': {
-            const next = (/** @type {any} */ ctx) => chain(effect.next(ctx), fn);
-            return Ask(next);
+            const next = (/** @type {any} */ ctx) => chain(effect.next(ctx), fn, initialInput);
+            return withII(Ask(next));
+        }
+        case 'Retry': {
+            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput);
+            return withII({ ...effect, next });
         }
     }
 };
@@ -93,9 +132,8 @@ const chain = (effect, fn) => {
  */
 const effectPipe = (...fns) => {
     return (start) => {
-        const effect = fns.reduce(chain, /** @type {Effect} */ (Success(start)));
-        effect.initialInput = start;
-        return effect;
+        const chainWithII = (/** @type {Effect} */ eff, /** @type {(v: any) => Effect} */ fn) => chain(eff, fn, start);
+        return fns.reduce(chainWithII, /** @type {Effect} */ (Success(start)));
     };
 };
 
@@ -115,11 +153,15 @@ let stepRunner = defaultStepRunner;
 let runWrapper = defaultRunWrapper;
 let commandInterceptor = defaultCommandInterceptor;
 
+const defaultRetryOptions = { attempts: 3, delay: 100, backoff: 1 };
+let retryDefaults = { ...defaultRetryOptions };
+
 /**
  * @typedef {Object} EffectConfiguration
  * @property {StepRunner} [onStep] - Fires once per runEffect call. It wraps the entire workflow execution.
  * @property {RunWrapper} [onRun] - Fires every time a Command is executed.
  * @property {CommandInterceptor} [onBeforeCommand] - Intercepts a Command and any context passed to runEffect before execution.
+ * @property {{ attempts?: number, delay?: number, backoff?: number }} [retry] - Global Retry defaults; merged under per-use options.
  */
 
 /**
@@ -131,6 +173,7 @@ const configureEffect = (options) => {
     stepRunner = options.onStep ? options.onStep : defaultStepRunner;
     runWrapper = options.onRun ? options.onRun : defaultRunWrapper;
     commandInterceptor = options.onBeforeCommand ? options.onBeforeCommand : defaultCommandInterceptor;
+    retryDefaults = options.retry ? { ...defaultRetryOptions, ...options.retry } : defaultRetryOptions;
 };
 
 const runEffect =
@@ -139,34 +182,69 @@ const runEffect =
      * Iterates through the Effect tree, executing Commands and handling async flow.
      * Ask effects are resolved synchronously with the context object.
      *
+     * Per-call config takes precedence over global configureEffect defaults.
+     * onRun fires exactly once per runEffect call — Retry attempts run inside that
+     * single span rather than spawning their own, keeping telemetry non-duplicated.
+     *
      * @param {Effect} effect - The Effect tree returned by a pipeline
      * @param {any} [context] - Optional context object. Passed to Ask continuations and the Command Interceptor.
+     * @param {EffectConfiguration} [callConfig] - Per-call overrides; merged over global configureEffect defaults.
      * @returns {Promise<SuccessState | FailureState>}
      */
-    async function runEffect(effect, context = {}) {
-        return runWrapper(
-            effect,
-            async () => {
-                while (effect.type === 'Command' || effect.type === 'Ask') {
-                    if (effect.type === 'Ask') {
-                        effect = effect.next(context);
-                        continue;
+    async function runEffect(effect, context = {}, callConfig = {}) {
+        const localStepRunner = callConfig.onStep ? callConfig.onStep : stepRunner;
+        const localRunWrapper = callConfig.onRun ? callConfig.onRun : runWrapper;
+        const localCommandInterceptor = callConfig.onBeforeCommand ? callConfig.onBeforeCommand : commandInterceptor;
+        const localRetryDefaults = callConfig.retry ? { ...retryDefaults, ...callConfig.retry } : retryDefaults;
+
+        /**
+         * @param {Effect} eff
+         * @returns {Promise<SuccessState | FailureState>}
+         */
+        async function execute(eff) {
+            while (eff.type === 'Command' || eff.type === 'Ask' || eff.type === 'Retry') {
+                if (eff.type === 'Ask') {
+                    eff = eff.next(context);
+                    continue;
+                }
+                if (eff.type === 'Retry') {
+                    const opts = { ...localRetryDefaults, ...eff.options };
+                    const { attempts } = opts;
+                    let lastError;
+                    let succeeded = false;
+
+                    for (let attempt = 0; attempt <= attempts; attempt++) {
+                        if (attempt > 0) {
+                            await new Promise((r) => setTimeout(r, opts.delay * Math.pow(opts.backoff, attempt - 1)));
+                        }
+                        const result = await execute(eff.effect);
+                        if (result.type === 'Success') {
+                            eff = eff.next(result.value);
+                            succeeded = true;
+                            break;
+                        }
+                        lastError = result.error;
                     }
-                    const cmdName = effect.cmd.name || 'anonymous';
-                    const initialInput = effect.initialInput;
-                    try {
-                        await commandInterceptor(effect, context);
-                        const result = await stepRunner(cmdName, 'Command', effect.cmd);
-                        effect = effect.next(result);
-                    } catch (e) {
-                        return Failure(e, initialInput);
+
+                    if (!succeeded) {
+                        return Failure({ retryExhausted: true, lastError, attempts }, eff.initialInput);
                     }
+                    continue;
                 }
+                const cmdName = eff.cmd.name || 'anonymous';
+                const initialInput = eff.initialInput;
+                try {
+                    await localCommandInterceptor(eff, context);
+                    const result = await localStepRunner(cmdName, 'Command', eff.cmd);
+                    eff = eff.next(result);
+                } catch (e) {
+                    return Failure(e, initialInput);
+                }
+            }
+            return eff;
+        }
 
-                return effect;
-            },
-            context?.flowName || ''
-        );
+        return localRunWrapper(effect, () => execute(effect), context?.flowName || '');
     };
 
-export { Success, Failure, Command, Ask, effectPipe, runEffect, configureEffect };
+export { Success, Failure, Command, Ask, Retry, effectPipe, runEffect, configureEffect };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "pure-effect",
-    "version": "0.6.0",
-    "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript/TypeScript without mocks.",
+    "version": "0.7.0",
+    "description": "A TypeScript effect library where effects are plain objects you can inspect, test, and reason about. Learn the whole API in an afternoon. Tiny footprint, zero dependencies, works with plain JavaScript too.",
     "type": "module",
     "exports": "./index.js",
     "types": "./index.d.ts",

package/test/all.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 import { strict as assert } from 'assert';
-import { Success, Failure, Command, Ask, effectPipe, runEffect, configureEffect } from '../index.js';
+import { Success, Failure, Command, Ask, Retry, effectPipe, runEffect, configureEffect } from '../index.js';
 import { enableTelemetry } from '../opentelemetry-example.js';
 
 /** @import { CommandInterceptor } from "../index.js" */
@@ -81,26 +81,15 @@ describe('Pure Effect', function () {
     });
 
     it('should access context through onBeforeCommand', async function () {
-        configureEffect({
-            onBeforeCommand: /** @type CommandInterceptor */ async (command, context) =>
-                assert.equal(context.env, 'test')
-        });
         const input = { email: 'context@test.com', password: 'password123' };
-        const result = await runEffect(registerUserFlow(input), { env: 'test' });
-        configureEffect({ onBeforeCommand: undefined });
-    });
-
-    it('should return Success after runEffect with telemetry disabled', async function () {
-        const input = { email: 'test-no-telemetry@test.com', password: 'password123' };
-        const result = await registerUser(input);
-        assert.equal(result.type, 'Success');
-    });
-
-    it('should return Success after runEffect with telemetry enabled', async function () {
-        enableTelemetry();
-        const input = { email: 'test-telemetry@test.com', password: 'password123' };
-        const result = await registerUser(input);
-        assert.equal(result.type, 'Success');
+        await runEffect(
+            registerUserFlow(input),
+            { env: 'test' },
+            {
+                onBeforeCommand: /** @type CommandInterceptor */ async (command, context) =>
+                    assert.equal(context.env, 'test')
+            }
+        );
     });
 
     it('should access context through Ask', async function () {
@@ -128,4 +117,126 @@ describe('Pure Effect', function () {
         assert.equal(result.type, 'Success');
         assert.deepEqual(result.value, { value: 'value', env: 'test' });
     });
+
+    it('should return a Retry data structure', function () {
+        const inner = Command(
+            () => 'x',
+            (r) => Success(r)
+        );
+        const effect = Retry(inner, { attempts: 5 });
+        assert.equal(effect.type, 'Retry');
+        assert.deepEqual(effect.options, { attempts: 5 });
+        assert.strictEqual(effect.effect, inner);
+        assert.equal(typeof effect.next, 'function');
+    });
+
+    it('should succeed after transient failures', async function () {
+        let calls = 0;
+        const effect = Retry(
+            Command(
+                function flakyCmd() {
+                    if (++calls < 3) throw new Error('transient');
+                    return 'ok';
+                },
+                (r) => Success(r)
+            ),
+            { attempts: 3, delay: 0 }
+        );
+        const result = await runEffect(effect);
+        assert.equal(result.type, 'Success');
+        assert.equal(result.value, 'ok');
+        assert.equal(calls, 3);
+    });
+
+    it('should return rich Failure when retries are exhausted', async function () {
+        const effect = Retry(
+            Command(
+                function alwaysFails() {
+                    throw new Error('boom');
+                    return /** @type {any} */ (null);
+                },
+                (/** @type {any} */ r) => Success(r)
+            ),
+            { attempts: 2, delay: 0 }
+        );
+        const result = await runEffect(effect);
+        assert.equal(result.type, 'Failure');
+        if (result.type !== 'Failure') throw new Error('expected Failure');
+        const error = /** @type {import('../index.js').RetryExhaustedError<Error>} */ (result.error);
+        assert.equal(error.retryExhausted, true);
+        assert.equal(error.attempts, 2);
+        assert.equal(error.lastError.message, 'boom');
+    });
+
+    it('should apply delay and backoff between retries', async function () {
+        this.timeout(2000);
+        let calls = 0;
+        const start = Date.now();
+        const effect = Retry(
+            Command(
+                function flakyCmd() {
+                    if (++calls < 3) throw new Error('transient');
+                    return 'ok';
+                },
+                (r) => Success(r)
+            ),
+            { attempts: 3, delay: 30, backoff: 1 }
+        );
+        const result = await runEffect(effect);
+        const elapsed = Date.now() - start;
+        assert.equal(result.type, 'Success');
+        // 2 retries × 30 ms = at least 55 ms (5 ms margin for timing variance)
+        assert.ok(elapsed >= 55, `Expected ≥ 55 ms elapsed, got ${elapsed} ms`);
+    });
+
+    it('should merge per-use Retry options with call-level defaults', async function () {
+        // Call-level: attempts 1 (would exhaust on 2nd try)
+        // Per-use: attempts 3 (overrides call-level — should succeed on 3rd try)
+        let calls = 0;
+        const effect = Retry(
+            Command(
+                function flakyCmd() {
+                    if (++calls < 3) throw new Error('x');
+                    return 'ok';
+                },
+                (r) => Success(r)
+            ),
+            { attempts: 3 }
+        );
+        const result = await runEffect(effect, {}, { retry: { attempts: 1, delay: 0, backoff: 1 } });
+        assert.equal(result.type, 'Success');
+        assert.equal(calls, 3);
+    });
+
+    it('should work at any step inside effectPipe', async function () {
+        const flow = effectPipe(
+            (input) =>
+                Retry(
+                    Command(
+                        function fetchCmd() {
+                            return input.toUpperCase();
+                        },
+                        (r) => Success(r)
+                    ),
+                    { attempts: 2, delay: 0 }
+                ),
+            (upper) => Success(`${upper}!`)
+        );
+        const result = await runEffect(flow('hello'));
+        assert.equal(result.type, 'Success');
+        assert.equal(result.value, 'HELLO!');
+    });
+
+    it('should return Success after runEffect with telemetry disabled', async function () {
+        const input = { email: 'test-no-telemetry@test.com', password: 'password123' };
+        const result = await registerUser(input);
+        assert.equal(result.type, 'Success');
+    });
+
+    it('should return Success after runEffect with telemetry enabled', async function () {
+        enableTelemetry();
+        const input = { email: 'test-telemetry@test.com', password: 'password123' };
+        const result = await registerUser(input);
+        assert.equal(result.type, 'Success');
+    });
 });

package/test/types.test-d.ts

@@ -1,6 +1,14 @@
 import { expectType, expectError } from 'tsd';
-import { Success, Failure, Command, Ask, effectPipe, runEffect } from '../index.js';
-import type { SuccessState, FailureState, CommandState, AskState, Effect } from '../index.js';
+import { Success, Failure, Command, Ask, Retry, effectPipe, runEffect } from '../index.js';
+import type {
+    SuccessState,
+    FailureState,
+    CommandState,
+    AskState,
+    RetryState,
+    RetryExhaustedError,
+    Effect
+} from '../index.js';
 
 interface User {
     email: string;
@@ -72,3 +80,54 @@ expectType<AskState<User, unknown>>(ask);
 
 const askFlow = effectPipe((input: User) => Ask((_ctx) => Success(input)));
 expectType<Effect<User>>(askFlow({ email: 'a@b.com', password: 'secret123' }));
+
+// --- Retry ---
+
+const innerCmd = Command(
+    async () => 42,
+    (n) => Success(n)
+);
+
+// Retry with options preserves T
+const retried = Retry(innerCmd, { attempts: 3 });
+expectType<RetryState<number, unknown>>(retried);
+
+// Retry without options is valid
+const retriedNoOpts = Retry(innerCmd);
+expectType<RetryState<number, unknown>>(retriedNoOpts);
+
+// Retry in effectPipe preserves type flow
+const retryFlow = effectPipe((input: User) =>
+    Retry(
+        Command(
+            async () => ({ id: 1, ...input }) as SavedUser,
+            (s) => Success(s)
+        ),
+        { attempts: 2 }
+    )
+);
+expectType<Effect<SavedUser>>(retryFlow({ email: 'a@b.com', password: 'secret123' }));
+
+// RetryExhaustedError shape is usable for narrowing exhaustion failures
+const exhaustedErr: RetryExhaustedError<Error> = {
+    retryExhausted: true,
+    lastError: new Error('boom'),
+    attempts: 3
+};
+expectType<true>(exhaustedErr.retryExhausted);
+expectType<Error>(exhaustedErr.lastError);
+expectType<number>(exhaustedErr.attempts);
+
+// --- error channel union across effectPipe steps ---
+
+type ValidationError = 'invalid_email' | 'weak_password';
+type DbError = 'db_connection' | 'duplicate_key';
+
+const validateStep = (_input: User): Effect<User, ValidationError> => Failure<ValidationError>('invalid_email');
+const saveStep = (_user: User): Effect<SavedUser, DbError> => Failure<DbError>('db_connection');
+
+const typedFlow = effectPipe(validateStep, saveStep);
+expectType<Effect<SavedUser, ValidationError | DbError>>(typedFlow({ email: 'a@b.com', password: 'secret123' }));
+
+const typedResult = await runEffect(typedFlow({ email: 'a@b.com', password: 'secret123' }));
+expectType<SuccessState<SavedUser> | FailureState<ValidationError | DbError>>(typedResult);