pure-effect 0.4.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

@@ -0,0 +1,63 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm test                                          # run all tests
+npx mocha test/all.js --grep "pattern"            # run a single test by name
+```
+
+No build or lint step — the library ships as plain ES modules with no transpilation.
+
+## Architecture
+
+**pure-effect** is a zero-dependency effect system for JavaScript implementing the "Functional Core, Imperative Shell" pattern. Business logic returns plain data structures instead of executing side effects, enabling testing without mocks.
+
+### 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`)                         |
+
+### Data flow
+
+```
+effectPipe(f1, f2, f3)(input)
+  → returns tree of Success / Failure / Command / Ask values
+  → f1 runs eagerly here
+
+runEffect(tree, context)
+  → 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, `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`
+
+### 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`.
+
+### 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/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** comes with JSDoc type annotations, so it can be used with TypeScript as well.
+**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

@@ -0,0 +1,120 @@
+export type SuccessState<T> = {
+    type: 'Success';
+    value: T;
+    initialInput?: unknown;
+};
+
+export type FailureState<E = unknown> = {
+    type: 'Failure';
+    error: E;
+    initialInput?: unknown;
+};
+
+export type CommandState<R, T, E = unknown> = {
+    type: 'Command';
+    cmd: () => Promise<R> | R;
+    next: (result: R) => Effect<T, E>;
+    meta?: unknown;
+    initialInput?: unknown;
+};
+
+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 Command<R, T, E = unknown>(
+    cmd: () => Promise<R> | R,
+    next: (result: R) => Effect<T, E>,
+    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>>;
+
+export type StepRunner = (name: string, type: string, op: () => Promise<unknown>) => Promise<unknown>;
+
+export type RunWrapper = (
+    effect: Effect<unknown>,
+    op: () => Promise<SuccessState<unknown> | FailureState<unknown>>,
+    flowName?: string
+) => Promise<SuccessState<unknown> | FailureState<unknown>>;
+
+export type CommandInterceptor = (command: CommandState<unknown, unknown>, context?: any) => Promise<void>;
+
+export interface EffectConfiguration {
+    onStep?: StepRunner;
+    onRun?: RunWrapper;
+    onBeforeCommand?: CommandInterceptor;
+}
+
+export declare function configureEffect(options: EffectConfiguration): void;

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,11 +1,15 @@
 {
     "name": "pure-effect",
-    "version": "0.4.0",
-    "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript without mocks.",
+    "version": "0.6.0",
+    "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript/TypeScript without mocks.",
     "type": "module",
     "exports": "./index.js",
+    "types": "./index.d.ts",
     "scripts": {
-        "test": "mocha"
+        "test": "mocha && tsd"
+    },
+    "tsd": {
+        "directory": "test"
     },
     "author": "Aycan Gulez",
     "homepage": "https://github.com/aycangulez/pure-effect",
@@ -14,6 +18,7 @@
         "@opentelemetry/sdk-node": "^0.211.0",
         "@types/mocha": "^10.0.10",
         "@types/node": "^24.10.1",
-        "mocha": "^11.7.5"
+        "mocha": "^11.7.5",
+        "tsd": "^0.33.0"
     }
 }

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

@@ -0,0 +1,74 @@
+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';
+
+interface User {
+    email: string;
+    password: string;
+}
+interface SavedUser {
+    id: number;
+    email: string;
+}
+
+// --- Success ---
+
+const s = Success(42);
+expectType<SuccessState<number>>(s);
+expectError(Success()); // missing argument
+
+// --- Failure ---
+
+const f = Failure('oops');
+expectType<FailureState<string>>(f);
+
+// --- Command ---
+
+const cmd = Command(
+    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 flow = effectPipe(step1, step2);
+expectType<Effect<SavedUser>>(flow({ email: 'a@b.com', password: 'secret123' }));
+expectError(flow({ email: 'a@b.com' })); // missing password
+
+// --- runEffect return type ---
+
+const result = await runEffect(flow({ email: 'a@b.com', password: 'secret123' }));
+expectType<SuccessState<SavedUser> | FailureState<unknown>>(result);
+
+// --- discriminated union narrowing ---
+
+if (result.type === 'Success') {
+    expectType<SavedUser>(result.value);
+} else {
+    expectType<unknown>(result.error);
+}
+
+// --- Failure error type flows through runEffect ---
+
+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' }));