pure-effect 0.5.0 → 0.7.0

package/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx mocha *)",
+      "Bash(npm test *)",
+      "Bash(git *)",
+      "Bash(node *)",
+      "Bash(npx tsc *)",
+      "Bash(npx tsd *)"
+    ]
+  }
+}

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+    "tabWidth": 4,
+    "useTabs": false,
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "none",
+    "jsxSingleQuote": true,
+    "printWidth": 120,
+    "arrowParens": "always",
+    "endOfLine": "lf"
+}

package/CLAUDE.md

@@ -17,43 +17,56 @@ 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 |
-| `effectPipe(...fns)` | — | Composes functions into a sequential pipeline via `chain` |
-| `runEffect(effect, context)` | async | Interpreter: traverses the effect tree, executes Commands |
-| `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 values
-
-runEffect(tree, context)
-  → executes Commands async, passes results into next(), repeats
+  → 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, 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. `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` options (all overridable per-call via `runEffect`'s third argument):
 
-`configureEffect` hooks:
 - `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.
 
 ### Tests
 
-`test/all.js` contains all runtime tests and uses a user-registration domain as the running example. Tests assert on the *returned data structures* (Commands, Failures) rather than on side effects, which is the core usage pattern to preserve.
+`test/all.js` contains all runtime tests and uses a user-registration domain as the running example. Tests assert on the _returned data structures_ (Commands, Failures) rather than on side effects, which is the core usage pattern to preserve.
 
 `test/types.test-d.ts` contains type-level tests using `tsd`, verifying that generic type parameters flow correctly through `effectPipe` and `runEffect`.

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 `index.d.ts` 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,80 +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 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 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) => {
+        const cmdFindProduct = () => db[ctx.tenant].findProduct(productId);
+        return Command(cmdFindProduct, (product) => (product ? Success(product) : Failure('Product not found.')));
+    });
+
+const reserveStock = (product) =>
+    Ask((ctx) => {
+        const cmdReserveStock = () => db[ctx.tenant].reserveStock(product.id);
+        return Command(cmdReserveStock, (reserved) => Success({ product, reserved }));
+    });
+
+const checkoutFlow = (productId) => effectPipe(findProduct, ({ product }) => reserveStock(product))(productId);
+
+app.post('/checkout', async (req, res) => {
+    const result = await runEffect(checkoutFlow(req.body.productId), {
+        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.
+- `cmdFn`: A function (sync or async) that performs the side effect.
+- `nextFn`: Receives the result of `cmdFn` and returns the next Effect.
+- `meta`: Optional metadata (available to `onBeforeCommand`).
 
-### `effectPipe(...functions)`
+### `Ask(nextFn)`
+
+Returns `{ type: 'Ask', next }`. Passes the `context` from `runEffect` into `nextFn`, which returns the next Effect. Works at any point in a pipeline.
 
-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.
+```js
+const findProduct = (productId) =>
+    Ask((ctx) => {
+        const cmdFindProduct = () => db[ctx.tenant].findProduct(productId);
+        return Command(cmdFindProduct, (product) => (product ? Success(product) : Failure('Product not found.')));
+    });
+```
 
-### `runEffect(effect, context = {})`
+### `Retry(effect, options?)`
 
-The interpreter. It takes an `effect` object, executes any nested Commands recursively using `async/await`, and returns the final `Success` or `Failure`. The optional `context` object is _only_ passed to the command interceptor configured via the `onBeforeCommand` option in `configureEffect` (see below). Additionally, `context.flowName` may be used for naming workflows in telemetry.
+Returns `{ type: 'Retry', effect, options, next }`. Wraps any Effect with retry-on-failure semantics.
 
----
+- `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).
 
-### `configureEffect(options)`
+On exhaustion, returns `Failure({ retryExhausted: true, lastError, attempts })`.
+
+### `effectPipe(...functions)`
+
+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.
 
-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.
+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` also accepts `onBeforeCommand`, which can be used to intercept each `Command` and the context passed to `runEffect` before execution.
+### `runEffect(effect, context?, callConfig?)`
 
--   `onRun (effect, pipeline, flowName)`  
-    Fires once per `runEffect` call. It wraps the entire workflow execution.
+The interpreter. Traverses the effect tree, executes Commands with `async/await`, resolves `Ask` with the supplied `context`, and returns the final `Success` or `Failure`.
 
-    -   `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`.
+- `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.
 
--   `onStep (name, type, op)`  
-    Fires every time a `Command` is executed.
+### `configureEffect(options)`
 
-    -   `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.