pure-effect 0.5.0 → 0.6.0

package/.claude/settings.local.json

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

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,29 +17,33 @@ 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`                       |
+| `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`)                         |
 
 ### Data flow
 
 ```
 effectPipe(f1, f2, f3)(input)
-  → returns tree of Success / Failure / Command values
+  → returns tree of Success / Failure / Command / Ask values
+  → f1 runs eagerly here
 
 runEffect(tree, context)
-  → executes Commands async, passes results into next(), repeats
+  → executes Commands async, passes results into next(result), repeats
+  → resolves Ask by calling next(context), continues
   → 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. `runEffect` loops through the tree with a `while` loop rather than recursion.
 
 `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
 - `onBeforeCommand` — intercepts each Command before execution; receives the Command and the `context` passed to `runEffect`
@@ -54,6 +58,6 @@ Full generic type declarations are in `index.d.ts` and referenced via the `types
 
 ### 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

@@ -4,7 +4,7 @@
 
 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.
+**Pure Effect** ships with JSDoc type annotations for JavaScript users and a bundled declaration file with full generic types for TypeScript users.
 
 ## Installation
 
@@ -95,6 +95,49 @@ assert.equal(step2.cmd.name, 'cmdSaveUser');
 // ✅ We verified the *intent* of the code without touching a real DB.
 ```
 
+## 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.
+
+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:
+
+```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.'))
+        )
+    );
+
+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);
+```
+
+The router identifies the tenant and passes it as context. `checkoutFlow` never needs a tenant parameter:
+
+```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
+    });
+    res.json(result);
+});
+```
+
 ## API Reference
 
 ### `Success(value)`
@@ -109,9 +152,25 @@ Returns an object `{ type: 'Failure', error, initialInput }`. Represents a faile
 
 Returns an object `{ 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`: A function that receives the result of `cmdFn` and returns the next Effect (Success, Failure, or another Command).
+- `meta`: Optional metadata.
+
+### `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.
+
+```js
+const findProduct = (productId) =>
+    Ask((ctx) =>
+        Command(
+            () => db[ctx.tenant].findProduct(productId),
+            (product) => (product ? Success(product) : Failure('Product not found.'))
+        )
+    );
+```
+
+See [Passing Runtime Context](#passing-runtime-context) for a full example.
 
 ### `effectPipe(...functions)`
 
@@ -119,7 +178,12 @@ A combinator that runs functions in sequence. It automatically handles unpacking
 
 ### `runEffect(effect, context = {})`
 
-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.
+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:
+
+- `Ask` continuations — use `Ask` to read context inside pipeline steps
+- The `onBeforeCommand` interceptor (see `configureEffect` below)
+
+`context.flowName` may be used for naming workflows in telemetry.
 
 ---
 
@@ -129,21 +193,19 @@ A configuration function that injects observability, tracing, or logging interce
 
 `configureEffect` also accepts `onBeforeCommand`, which can be used to intercept each `Command` and the context passed to `runEffect` before execution.
 
--   `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`.
-
--   `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.
-
--   `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.
+- `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`.
+
+- `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.
+
+- `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.

package/index.d.ts

@@ -18,17 +18,17 @@ export type CommandState<R, T, E = unknown> = {
     initialInput?: unknown;
 };
 
-export type Effect<T, E = unknown> =
-    | SuccessState<T>
-    | FailureState<E>
-    | CommandState<any, T, E>;
+export type AskState<T, E = unknown> = {
+    type: 'Ask';
+    next: (context: unknown) => Effect<T, E>;
+    initialInput?: unknown;
+};
+
+export type Effect<T, E = unknown> = SuccessState<T> | FailureState<E> | CommandState<any, T, E> | AskState<T, E>;
 
 export declare function Success<T>(value: T): SuccessState<T>;
 
-export declare function Failure<E = unknown>(
-    error: E,
-    initialInput?: unknown
-): FailureState<E>;
+export declare function Failure<E = unknown>(error: E, initialInput?: unknown): FailureState<E>;
 
 export declare function Command<R, T, E = unknown>(
     cmd: () => Promise<R> | R,
@@ -36,9 +36,9 @@ export declare function Command<R, T, E = unknown>(
     meta?: unknown
 ): CommandState<R, T, E>;
 
-export declare function effectPipe<A, B, E = unknown>(
-    f1: (a: A) => Effect<B, E>
-): (start: A) => Effect<B, 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>,
@@ -101,11 +101,7 @@ export declare function runEffect<T, E = unknown>(
     context?: unknown
 ): Promise<SuccessState<T> | FailureState<E>>;
 
-export type StepRunner = (
-    name: string,
-    type: string,
-    op: () => Promise<unknown>
-) => Promise<unknown>;
+export type StepRunner = (name: string, type: string, op: () => Promise<unknown>) => Promise<unknown>;
 
 export type RunWrapper = (
     effect: Effect<unknown>,
@@ -113,10 +109,7 @@ export type RunWrapper = (
     flowName?: string
 ) => Promise<SuccessState<unknown> | FailureState<unknown>>;
 
-export type CommandInterceptor = (
-    command: CommandState<unknown, unknown>,
-    context?: any
-) => Promise<void>;
+export type CommandInterceptor = (command: CommandState<unknown, unknown>, context?: any) => Promise<void>;
 
 export interface EffectConfiguration {
     onStep?: StepRunner;

package/index.js

@@ -11,10 +11,17 @@
  *   initialInput?: any
  * }} CommandState
  */
+/**
+ * @typedef {{
+ *   type: 'Ask',
+ *   next: (context: any) => Effect,
+ *   initialInput?: any
+ * }} AskState
+ */
 
 /**
  * The Union type for all possible states
- * @typedef {SuccessState | FailureState | CommandState} Effect
+ * @typedef {SuccessState | FailureState | CommandState | AskState} Effect
  */
 
 /**
@@ -30,7 +37,11 @@ const Success = (value) => ({ type: 'Success', value });
  * @param {any} [initialInput] - initial input passed to the flow (optional)
  * @returns {FailureState}
  */
-const Failure = (error, initialInput) => ({ type: 'Failure', error, initialInput });
+const Failure = (error, initialInput) => ({
+    type: 'Failure',
+    error,
+    initialInput
+});
 
 /**
  * Represents a side effect to be executed later
@@ -41,9 +52,16 @@ const Failure = (error, initialInput) => ({ type: 'Failure', error, initialInput
  */
 const Command = (cmd, next, meta) => ({ type: 'Command', cmd, next, meta });
 
+/**
+ * Reads the context object from the current `runEffect` call.
+ * @param {(context: any) => Effect} next - Receives the context and returns the next Effect
+ * @returns {AskState}
+ */
+const Ask = (next) => ({ type: 'Ask', next });
+
 /**
  * Connects an Effect to the next function in the pipeline.
- * Handles the branching logic for Success, Failure, and Command.
+ * Handles the branching logic for Success, Failure, Command, and Ask.
  *
  * @param {Effect} effect - The current Effect object
  * @param {(value: any) => Effect} fn - The next function to run if the current effect is a Success
@@ -55,9 +73,14 @@ const chain = (effect, fn) => {
             return fn(effect.value);
         case 'Failure':
             return effect;
-        case 'Command':
-            const next = (/** @type {Effect} */ result) => chain(effect.next(result), fn);
+        case 'Command': {
+            const next = (/** @type {any} */ result) => chain(effect.next(result), fn);
             return Command(effect.cmd, next, effect.meta);
+        }
+        case 'Ask': {
+            const next = (/** @type {any} */ ctx) => chain(effect.next(ctx), fn);
+            return Ask(next);
+        }
     }
 };
 
@@ -65,12 +88,12 @@ const chain = (effect, fn) => {
  * Composes a list of functions into a single Effect pipeline.
  * Each function receives the output of the previous one.
  *
- * @param {...(input: any) => Effect} fns - Functions that return Success, Failure, or Command.
+ * @param {...(input: any) => Effect} fns - Functions that return Success, Failure, Command, or Ask.
  * @returns {(start: any) => Effect} A function that accepts an initial input and returns the final Effect tree.
  */
 const effectPipe = (...fns) => {
     return (start) => {
-        const effect = fns.reduce(chain, Success(start));
+        const effect = fns.reduce(chain, /** @type {Effect} */ (Success(start)));
         effect.initialInput = start;
         return effect;
     };
@@ -114,23 +137,29 @@ const runEffect =
     /**
      * The Interpreter
      * Iterates through the Effect tree, executing Commands and handling async flow.
+     * Ask effects are resolved synchronously with the context object.
      *
      * @param {Effect} effect - The Effect tree returned by a pipeline
-     * @param {any} [context] - Optional context object passed to the Command Interceptor
+     * @param {any} [context] - Optional context object. Passed to Ask continuations and the Command Interceptor.
      * @returns {Promise<SuccessState | FailureState>}
      */
     async function runEffect(effect, context = {}) {
         return runWrapper(
             effect,
             async () => {
-                while (effect.type === 'Command') {
+                while (effect.type === 'Command' || effect.type === 'Ask') {
+                    if (effect.type === 'Ask') {
+                        effect = effect.next(context);
+                        continue;
+                    }
                     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, effect.initialInput);
+                        return Failure(e, initialInput);
                     }
                 }
 
@@ -140,4 +169,4 @@ const runEffect =
         );
     };
 
-export { Success, Failure, Command, effectPipe, runEffect, configureEffect };
+export { Success, Failure, Command, Ask, effectPipe, runEffect, configureEffect };

package/opentelemetry-example.js

@@ -9,14 +9,14 @@ import { configureEffect } from './index.js';
 /** @import { RunWrapper, StepRunner } from "./index.js" */
 
 const traceExporter = new OTLPTraceExporter({
-    url: 'http://localhost:4318/v1/traces',
+    url: 'http://localhost:4318/v1/traces'
 });
 
 const sdk = new NodeSDK({
     serviceName: 'pure-effect-test',
     traceExporter,
     spanProcessor: new SimpleSpanProcessor(traceExporter),
-    instrumentations: [],
+    instrumentations: []
 });
 
 sdk.start();
@@ -43,7 +43,7 @@ export function enableTelemetry() {
                     if (result.type === 'Failure') {
                         rootSpan.setStatus({
                             code: SpanStatusCode.ERROR,
-                            message: String(result.error),
+                            message: String(result.error)
                         });
                     } else {
                         rootSpan.setStatus({ code: SpanStatusCode.OK });
@@ -79,13 +79,13 @@ export function enableTelemetry() {
                     span.recordException(err);
                     span.setStatus({
                         code: SpanStatusCode.ERROR,
-                        message: err.message,
+                        message: err.message
                     });
                     throw err;
                 } finally {
                     span.end();
                 }
             });
-        },
+        }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pure-effect",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript/TypeScript without mocks.",
     "type": "module",
     "exports": "./index.js",

package/test/all.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 import { strict as assert } from 'assert';
-import { Success, Failure, Command, effectPipe, runEffect, configureEffect } from '../index.js';
+import { Success, Failure, Command, Ask, effectPipe, runEffect, configureEffect } from '../index.js';
 import { enableTelemetry } from '../opentelemetry-example.js';
 
 /** @import { CommandInterceptor } from "../index.js" */
@@ -17,7 +17,7 @@ const db = {
         const u = { ...user, id: Date.now() };
         this.users.set(user.email, u);
         return u;
-    },
+    }
 };
 
 function validateRegistration(/** @type {User} */ input) {
@@ -83,7 +83,7 @@ describe('Pure Effect', function () {
     it('should access context through onBeforeCommand', async function () {
         configureEffect({
             onBeforeCommand: /** @type CommandInterceptor */ async (command, context) =>
-                assert.equal(context.env, 'test'),
+                assert.equal(context.env, 'test')
         });
         const input = { email: 'context@test.com', password: 'password123' };
         const result = await runEffect(registerUserFlow(input), { env: 'test' });
@@ -102,4 +102,30 @@ describe('Pure Effect', function () {
         const result = await registerUser(input);
         assert.equal(result.type, 'Success');
     });
+
+    it('should access context through Ask', async function () {
+        /** @type {any} */
+        let capturedCtx;
+        const step = () =>
+            Ask((ctx) => {
+                capturedCtx = ctx;
+                return Success(null);
+            });
+        await runEffect(step(), { env: 'test' });
+        assert.equal(capturedCtx.env, 'test');
+    });
+
+    it('should work with Ask at any point in the pipeline', async function () {
+        const flow = effectPipe(
+            () =>
+                Command(
+                    () => 'value',
+                    (r) => Success(r)
+                ),
+            (value) => Ask((/** @type {any} */ ctx) => Success({ value, env: ctx.env }))
+        );
+        const result = await runEffect(flow(null), { env: 'test' });
+        assert.equal(result.type, 'Success');
+        assert.deepEqual(result.value, { value: 'value', env: 'test' });
+    });
 });

package/test/types.test-d.ts

@@ -1,9 +1,15 @@
 import { expectType, expectError } from 'tsd';
-import { Success, Failure, Command, effectPipe, runEffect } from '../index.js';
-import type { SuccessState, FailureState, CommandState, Effect } from '../index.js';
+import { Success, Failure, Command, Ask, effectPipe, runEffect } from '../index.js';
+import type { SuccessState, FailureState, CommandState, AskState, Effect } from '../index.js';
 
-interface User { email: string; password: string; }
-interface SavedUser { id: number; email: string; }
+interface User {
+    email: string;
+    password: string;
+}
+interface SavedUser {
+    id: number;
+    email: string;
+}
 
 // --- Success ---
 
@@ -19,15 +25,22 @@ expectType<FailureState<string>>(f);
 // --- Command ---
 
 const cmd = Command(
-    async () => ({ id: 1, email: 'a@b.com' } as SavedUser),
-    (saved) => { expectType<SavedUser>(saved); return Success(saved); }
+    async () => ({ id: 1, email: 'a@b.com' }) as SavedUser,
+    (saved) => {
+        expectType<SavedUser>(saved);
+        return Success(saved);
+    }
 );
 expectType<CommandState<SavedUser, SavedUser, unknown>>(cmd);
 
 // --- effectPipe type propagation ---
 
 const step1 = (input: User) => Success(input);
-const step2 = (user: User) => Command(async () => ({ id: 1, ...user } as SavedUser), (s) => Success(s));
+const step2 = (user: User) =>
+    Command(
+        async () => ({ id: 1, ...user }) as SavedUser,
+        (s) => Success(s)
+    );
 
 const flow = effectPipe(step1, step2);
 expectType<Effect<SavedUser>>(flow({ email: 'a@b.com', password: 'secret123' }));
@@ -51,3 +64,11 @@ if (result.type === 'Success') {
 const failFlow = effectPipe((input: User): Effect<User, string> => Failure<string>('bad'));
 const failResult = await runEffect(failFlow({ email: 'a@b.com', password: 'x' }));
 expectType<SuccessState<User> | FailureState<string>>(failResult);
+
+// --- Ask ---
+
+const ask = Ask((ctx) => Success(ctx as User));
+expectType<AskState<User, unknown>>(ask);
+
+const askFlow = effectPipe((input: User) => Ask((_ctx) => Success(input)));
+expectType<Effect<User>>(askFlow({ email: 'a@b.com', password: 'secret123' }));