pure-effect 0.7.0 → 0.8.0

package/.claude/settings.local.json

@@ -6,7 +6,8 @@
       "Bash(git *)",
       "Bash(node *)",
       "Bash(npx tsc *)",
-      "Bash(npx tsd *)"
+      "Bash(npx tsd *)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); hooks=d.get\\('hooks',{}\\); print\\(json.dumps\\(hooks, indent=2\\)\\)\")"
     ]
   }
 }

package/CLAUDE.md

@@ -17,16 +17,17 @@ 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`                                                                          |
-| `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` |
+| 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                                                               |
+| `Parallel(effects, next)`                 | `{ type: 'Parallel', effects, next }`      | Runs multiple Effect trees concurrently via `Promise.all`; returns the first Failure by array order if any effect fails; context flows into all branches |
+| `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
 
@@ -43,6 +44,10 @@ runEffect(tree, context, callConfig?)
   → 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 Parallel by running all effects via Promise.all with the same
+    context; if any effect returns Failure, returns the first Failure by
+    array index and skips next; otherwise calls next with the array of
+    unwrapped success values
   → resolves to final Success or Failure
 ```
 

package/README.md

@@ -8,11 +8,11 @@
 
 - No mocks needed to test async pipelines
 - Inject context without touching function signatures
-- Built-in retry with configurable delay and backoff
+- Built-in retry and parallel execution with configurable delay, backoff, and `Promise.all` semantics
 - 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
+- Six primitives: learn the whole API in an afternoon
 
 ## Table of Contents
 
@@ -21,6 +21,7 @@
 - [Testing Without Mocks](#testing-without-mocks)
 - [Passing Runtime Context](#passing-runtime-context)
 - [Retrying Transient Failures](#retrying-transient-failures)
+- [Running Effects in Parallel](#running-effects-in-parallel)
 - [TypeScript: Typed Errors and Context](#typescript-typed-errors-and-context)
 - [Why Pure Effect](#why-pure-effect)
 - [API Reference](#api-reference)
@@ -44,7 +45,7 @@ const validateRegistration = (input) => {
     return Success(input);
 };
 
-// Theese function return a Command object. They do NOT call the database.
+// These functions return a Command object. They do NOT call the database.
 const findUser = (email) => {
     const cmdFindUser = () => db.findUser(email);
     return Command(cmdFindUser, (user) => Success(user));
@@ -181,6 +182,51 @@ configureEffect({
 Retry(effect, { delay: 500 }); // uses global attempts, custom delay
 ```
 
+## Running Effects in Parallel
+
+`Parallel` runs multiple Effect trees concurrently and passes their results to `next` as an ordered array. If any effect fails, `next` is not called and the `Failure` propagates immediately.
+
+```js
+import { Success, Failure, Command, Parallel, effectPipe, runEffect } from 'pure-effect';
+
+const getUser = (id) => {
+    const cmdGetUser = () => db.users.findById(id);
+    return Command(cmdGetUser, (user) => (user ? Success(user) : Failure('user_not_found')));
+};
+
+const getPermissions = (id) => {
+    const cmdGetPermissions = () => db.permissions.findByUserId(id);
+    return Command(cmdGetPermissions, (perms) => Success(perms));
+};
+
+const loadProfile = (userId) =>
+    Parallel([getUser(userId), getPermissions(userId)], ([user, permissions]) => Success({ user, permissions }));
+```
+
+Because `Parallel` is a plain object, you can assert on its structure without running anything:
+
+```js
+const flow = loadProfile('user-123');
+assert.equal(flow.type, 'Parallel');
+assert.equal(flow.effects.length, 2);
+assert.equal(flow.effects[0].type, 'Command');
+assert.equal(flow.effects[0].cmd.name, 'cmdGetUser');
+```
+
+`Parallel` composes naturally inside `effectPipe`:
+
+```js
+const checkoutFlow = (input) =>
+    effectPipe(
+        validate,
+        ({ productId, userId }) =>
+            Parallel([getProduct(productId), getUser(userId)], ([product, user]) => Success({ product, user })),
+        ({ product, user }) => reserveStock(product, user)
+    )(input);
+```
+
+`Ask` context flows into all parallel branches without any extra wiring.
+
 ## TypeScript: Typed Errors and Context
 
 ### Error union across pipeline steps
@@ -236,11 +282,11 @@ const result = await runEffect(findProduct('abc'), { tenant: 'acme', requestId:
 
 ## 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. Effect-TS:** Effect-TS is a full functional programming ecosystem with fibers, streaming, schema validation, structured concurrency, and more, though it comes with a steep learning curve. Pure Effect covers a narrower scope: testable pipelines, context injection, retry, and parallel execution. If your problem is testability and async pipeline boilerplate, Pure Effect solves it with just six primitives you can learn in an afternoon. If you need fibers, in-flight cancellation, or streaming, Effect-TS is the right tool.
 
-**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. fp-ts:** fp-ts brings category theory abstractions (functors, monads, applicatives) to TypeScript. Pure Effect borrows only the concept of effects as data, 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.
+**vs. plain async/await with mocks:** A mock that passes all your tests but diverges from what the real database driver or HTTP client actually does is worse than no test at all; it gives false confidence. Pure Effect eliminates the problem at the source: business logic never executes I/O, so there is nothing to mock. You assert on what the code _intends_ to do, not on a substitute that approximates it.
 
 **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.
 
@@ -285,6 +331,13 @@ Returns `{ type: 'Retry', effect, options, next }`. Wraps any Effect with retry-
 
 On exhaustion, returns `Failure({ retryExhausted: true, lastError, attempts })`.
 
+### `Parallel(effects, next)`
+
+Returns `{ type: 'Parallel', effects, next }`. Runs all effects concurrently via `Promise.all`. If any effect fails, the first `Failure` is returned immediately and `next` is not called. `Ask` context flows into all branches.
+
+- `effects`: Array of any Effects such as `Command`s, `effectPipe` results, nested `Retry`s, etc.
+- `next`: Receives the array of unwrapped success values in the same order as `effects`, returns the next Effect.
+
 ### `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.
@@ -313,7 +366,7 @@ The interpreter. Traverses the effect tree, executes Commands with `async/await`
 
 - `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.
+- `onBeforeCommand(command, context)` fires before each Command; throw to abort the pipeline.
 - `retry: { attempts?, delay?, backoff? }` global retry defaults.
 
 See **opentelemetry-example.js** in the repository for a complete OpenTelemetry wiring example.

package/index.d.ts

@@ -44,12 +44,20 @@ export type RetryExhaustedError<E = unknown> = {
     attempts: number;
 };
 
+export type ParallelState<T extends readonly unknown[], R, E = unknown, Ctx = unknown> = {
+    type: 'Parallel';
+    effects: { [K in keyof T]: Effect<T[K], E, Ctx> };
+    next: (values: [...T]) => Effect<R, E, Ctx>;
+    initialInput?: unknown;
+};
+
 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>;
+    | RetryState<T, E, Ctx>
+    | ParallelState<any, T, E, Ctx>;
 
 export declare function Success<T>(value: T): SuccessState<T>;
 
@@ -70,6 +78,11 @@ export declare function Retry<T, E = unknown, Ctx = unknown>(
     options?: RetryOptions
 ): RetryState<T, E, Ctx>;
 
+export declare function Parallel<T extends readonly unknown[], R, E = unknown, Ctx = unknown>(
+    effects: { [K in keyof T]: Effect<T[K], E, Ctx> },
+    next: (values: [...T]) => Effect<R, E, Ctx>
+): ParallelState<[...T], R, 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>;

package/index.js

@@ -29,9 +29,18 @@
  * }} RetryState
  */
 
+/**
+ * @typedef {{
+ *   type: 'Parallel',
+ *   effects: Effect[],
+ *   next: (values: any[]) => Effect,
+ *   initialInput?: any
+ * }} ParallelState
+ */
+
 /**
  * The Union type for all possible states
- * @typedef {SuccessState | FailureState | CommandState | AskState | RetryState} Effect
+ * @typedef {SuccessState | FailureState | CommandState | AskState | RetryState | ParallelState} Effect
  */
 
 /**
@@ -85,6 +94,14 @@ const Retry = (effect, options = {}) => ({
     next: (value) => Success(value)
 });
 
+/**
+ * Runs multiple Effect trees concurrently. If any effect fails, returns the first Failure by array order and skips next.
+ * @param {Effect[]} effects - Array of Effect trees to run concurrently
+ * @param {(values: any[]) => Effect} next - Receives array of success values in order, returns next Effect
+ * @returns {ParallelState}
+ */
+const Parallel = (effects, next) => ({ type: 'Parallel', effects, next });
+
 /**
  * Connects an Effect to the next function in the pipeline.
  * Handles the branching logic for Success, Failure, Command, Ask, and Retry.
@@ -120,6 +137,10 @@ const chain = (effect, fn, initialInput) => {
             const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput);
             return withII({ ...effect, next });
         }
+        case 'Parallel': {
+            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput);
+            return withII({ ...effect, next });
+        }
     }
 };
 
@@ -202,7 +223,7 @@ const runEffect =
          * @returns {Promise<SuccessState | FailureState>}
          */
         async function execute(eff) {
-            while (eff.type === 'Command' || eff.type === 'Ask' || eff.type === 'Retry') {
+            while (eff.type === 'Command' || eff.type === 'Ask' || eff.type === 'Retry' || eff.type === 'Parallel') {
                 if (eff.type === 'Ask') {
                     eff = eff.next(context);
                     continue;
@@ -231,6 +252,13 @@ const runEffect =
                     }
                     continue;
                 }
+                if (eff.type === 'Parallel') {
+                    const results = await Promise.all(eff.effects.map((e) => execute(e)));
+                    const failure = results.find((r) => r.type === 'Failure');
+                    if (failure) return failure;
+                    eff = eff.next(results.map((r) => /** @type {SuccessState} */ (r).value));
+                    continue;
+                }
                 const cmdName = eff.cmd.name || 'anonymous';
                 const initialInput = eff.initialInput;
                 try {
@@ -247,4 +275,4 @@ const runEffect =
         return localRunWrapper(effect, () => execute(effect), context?.flowName || '');
     };
 
-export { Success, Failure, Command, Ask, Retry, effectPipe, runEffect, configureEffect };
+export { Success, Failure, Command, Ask, Retry, Parallel, effectPipe, runEffect, configureEffect };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "pure-effect",
-    "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.",
+    "version": "0.8.0",
+    "description": "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.",
     "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, Retry, effectPipe, runEffect, configureEffect } from '../index.js';
+import { Success, Failure, Command, Ask, Retry, Parallel, effectPipe, runEffect, configureEffect } from '../index.js';
 import { enableTelemetry } from '../opentelemetry-example.js';
 
 /** @import { CommandInterceptor } from "../index.js" */
@@ -227,6 +227,71 @@ describe('Pure Effect', function () {
         assert.equal(result.value, 'HELLO!');
     });
 
+    it('should return a Parallel data structure', () => {
+        const e1 = Success(1);
+        const e2 = Success(2);
+        const next = (/** @type {any[]} */ values) => Success(values);
+        const result = Parallel([e1, e2], next);
+        assert.equal(result.type, 'Parallel');
+        assert.deepEqual(result.effects, [e1, e2]);
+        assert.equal(result.next, next);
+    });
+
+    it('should run effects concurrently and pass results to next', async () => {
+        const e1 = Command(
+            async () => 'a',
+            (v) => Success(v)
+        );
+        const e2 = Command(
+            async () => 'b',
+            (v) => Success(v)
+        );
+        const flow = Parallel([e1, e2], ([a, b]) => Success({ a, b }));
+        const result = await runEffect(flow);
+        assert.equal(result.type, 'Success');
+        assert.deepEqual(result.value, { a: 'a', b: 'b' });
+    });
+
+    it('should return Failure if any parallel effect fails', async () => {
+        const e1 = Success('ok');
+        const e2 = Failure('oops');
+        const flow = Parallel([e1, e2], ([a, b]) => Success({ a, b }));
+        const result = await runEffect(flow);
+        assert.equal(result.type, 'Failure');
+        assert.equal(result.error, 'oops');
+    });
+
+    it('should work inside effectPipe', async () => {
+        const flow = effectPipe((input) =>
+            Parallel(
+                [
+                    Command(
+                        async () => input.a,
+                        (v) => Success(v)
+                    ),
+                    Command(
+                        async () => input.b,
+                        (v) => Success(v)
+                    )
+                ],
+                ([a, b]) => Success({ a, b })
+            )
+        );
+        const result = await runEffect(flow({ a: 1, b: 2 }));
+        assert.equal(result.type, 'Success');
+        assert.deepEqual(result.value, { a: 1, b: 2 });
+    });
+
+    it('should pass context to parallel branches via Ask', async () => {
+        const flow = Parallel(
+            [Ask((/** @type {any} */ ctx) => Success(ctx.x)), Ask((/** @type {any} */ ctx) => Success(ctx.y))],
+            ([x, y]) => Success({ x, y })
+        );
+        const result = await runEffect(flow, { x: 10, y: 20 });
+        assert.equal(result.type, 'Success');
+        assert.deepEqual(result.value, { x: 10, y: 20 });
+    });
+
     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);

package/test/types.test-d.ts

@@ -1,13 +1,18 @@
 import { expectType, expectError } from 'tsd';
-import { Success, Failure, Command, Ask, Retry, effectPipe, runEffect } from '../index.js';
+import { Success, Failure, Command, Ask, Retry, Parallel, effectPipe, runEffect, configureEffect } from '../index.js';
 import type {
     SuccessState,
     FailureState,
     CommandState,
     AskState,
     RetryState,
+    ParallelState,
     RetryExhaustedError,
-    Effect
+    Effect,
+    EffectConfiguration,
+    StepRunner,
+    RunWrapper,
+    CommandInterceptor
 } from '../index.js';
 
 interface User {
@@ -131,3 +136,85 @@ expectType<Effect<SavedUser, ValidationError | DbError>>(typedFlow({ email: 'a@b
 
 const typedResult = await runEffect(typedFlow({ email: 'a@b.com', password: 'secret123' }));
 expectType<SuccessState<SavedUser> | FailureState<ValidationError | DbError>>(typedResult);
+
+// --- Parallel ---
+
+// Values tuple is correctly typed
+const par = Parallel([Success(42), Success('hello')], ([n, s]) => {
+    expectType<number>(n);
+    expectType<string>(s);
+    return Success({ n, s });
+});
+expectType<ParallelState<[number, string], { n: number; s: string }>>(par);
+
+// Parallel in effectPipe preserves type flow
+const parallelFlow = effectPipe((input: User) =>
+    Parallel([Success(input.email), Success(input.password)], ([email, password]) => Success({ email, password }))
+);
+expectType<Effect<{ email: string; password: string }>>(parallelFlow({ email: 'a@b.com', password: 'secret123' }));
+
+// runEffect return type flows through Parallel
+const parallelResult = await runEffect(Parallel([Success(1), Success('x')], ([n, s]) => Success({ n, s })));
+expectType<SuccessState<{ n: number; s: string }> | FailureState<unknown>>(parallelResult);
+
+// --- Ctx (context type) ---
+
+interface AppCtx {
+    db: string;
+}
+
+// Ask infers Ctx from callback parameter type
+const askWithCtx = Ask((ctx: AppCtx) => Success(ctx.db));
+expectType<AskState<string, unknown, AppCtx>>(askWithCtx);
+
+// effectPipe propagates Ctx through steps
+const ctxFlow = effectPipe((input: User) => Ask((ctx: AppCtx) => Success({ ...input, conn: ctx.db })));
+expectType<Effect<{ email: string; password: string; conn: string }, unknown, AppCtx>>(
+    ctxFlow({ email: 'a@b.com', password: 'secret123' })
+);
+
+// runEffect enforces context argument matches Ctx
+const ctxResult = await runEffect(ctxFlow({ email: 'a@b.com', password: 'secret123' }), { db: 'conn' });
+expectType<SuccessState<{ email: string; password: string; conn: string }> | FailureState<unknown>>(ctxResult);
+
+// wrong context shape should error
+expectError(runEffect(ctxFlow({ email: 'a@b.com', password: 'secret123' }), { wrong: 'thing' }));
+
+// --- configureEffect / EffectConfiguration ---
+
+// accepts full configuration
+configureEffect({
+    onStep: async (_name, _type, op) => op(),
+    onRun: async (_effect, op, _flowName) => op(),
+    onBeforeCommand: async (_cmd, _ctx) => {},
+    retry: { attempts: 3, delay: 100, backoff: 2 }
+});
+
+// accepts partial configuration
+configureEffect({ retry: { attempts: 5 } });
+configureEffect({});
+
+// rejects invalid shapes
+expectError(configureEffect({ onStep: 'not-a-function' }));
+expectError(configureEffect({ retry: { attempts: 'three' } }));
+
+// hook types are correctly shaped
+const myStep: StepRunner = async (name, type, op) => {
+    expectType<string>(name);
+    expectType<string>(type);
+    return op();
+};
+
+const myRun: RunWrapper = async (effect, op, flowName) => {
+    expectType<Effect<unknown>>(effect);
+    expectType<string | undefined>(flowName);
+    return op();
+};
+
+const myInterceptor: CommandInterceptor = async (cmd, _ctx) => {
+    expectType<CommandState<unknown, unknown>>(cmd);
+};
+
+// EffectConfiguration is a usable type
+const config: EffectConfiguration = { onStep: myStep, onRun: myRun, onBeforeCommand: myInterceptor };
+expectType<EffectConfiguration>(config);