pure-effect 0.3.0 → 0.5.0

package/CLAUDE.md

@@ -0,0 +1,59 @@
+# 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 |
+| `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`) |
+
+### 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
+  → 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.
+
+`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/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Aycan Gulez
+Copyright (c) 2025-2026 Aycan Gulez
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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 `index.d.ts` declaration file with full generic types for TypeScript users.
 
 ## Installation
 
@@ -53,12 +53,12 @@ const registerUserFlow = (input) =>
     )(input);
 
 // The Imperative Shell
-async function registerUser() {
+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, 'registerUser');
+    const result = await runEffect(logic);
 
     if (result.type === 'Success') {
         console.log('User created:', result.value);
@@ -105,38 +105,45 @@ Returns an object `{ type: 'Success', value }`. Represents a successful computat
 
 Returns an object `{ type: 'Failure', error, initialInput }`. Represents a failed computation. Stops the pipeline immediately.
 
-### `Command(cmdFn, nextFn)`
+### `Command(cmdFn, nextFn, meta)`
 
-Returns an object `{ type: 'Command', cmd, next }`.
+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.
 
 ### `effectPipe(...functions)`
 
 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.
 
-### `runEffect(effect, flowName = '')`
+### `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`. It also accepts an optional `flowName` that comes in handy for telemetry.
+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.
 
 ---
 
-### `configureTelemetry(options)`
+### `configureEffect(options)`
 
-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).
+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.
 
-Please see **opentelemetry-example.js** to see a quick example.
+`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.
+    -   `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,127 @@
+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 Effect<T, E = unknown> =
+    | SuccessState<T>
+    | FailureState<E>
+    | CommandState<any, 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 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

@@ -7,6 +7,7 @@
  *   type: 'Command',
  *   cmd: () => Promise<any>|any,
  *   next: (result: any) => Effect,
+ *   meta?: any,
  *   initialInput?: any
  * }} CommandState
  */
@@ -35,9 +36,10 @@ const Failure = (error, initialInput) => ({ type: 'Failure', error, initialInput
  * Represents a side effect to be executed later
  * @param {() => Promise<any>|any} cmd - The side-effect function to execute
  * @param {(result: any) => Effect} next - A function that receives the result of `cmd` and returns the next Effect
+ * @param {any} [meta] - Optional metadata
  * @returns {CommandState}
  */
-const Command = (cmd, next) => ({ type: 'Command', cmd, next });
+const Command = (cmd, next, meta) => ({ type: 'Command', cmd, next, meta });
 
 /**
  * Connects an Effect to the next function in the pipeline.
@@ -55,7 +57,7 @@ const chain = (effect, fn) => {
             return effect;
         case 'Command':
             const next = (/** @type {Effect} */ result) => chain(effect.next(result), fn);
-            return Command(effect.cmd, next);
+            return Command(effect.cmd, next, effect.meta);
     }
 };
 
@@ -74,54 +76,68 @@ const effectPipe = (...fns) => {
     };
 };
 
-/** @type {(name: string, type: string, op: function) => Promise<any>} */
+/** @typedef {(name: string, type: string, op: function) => Promise<any>} StepRunner */
+/** @type StepRunner */
 const defaultStepRunner = async (name, type, op) => await op();
 
-/** @type {(effect: Effect, op: function, flowName?: string) => Promise<any>} */
+/** @typedef {(effect: Effect, op: function, flowName?: string) => Promise<any>} RunWrapper */
+/** @type RunWrapper */
 const defaultRunWrapper = async (effect, op, flowName) => await op();
 
+/** @typedef {(command: CommandState, context?: any) => Promise<any>} CommandInterceptor */
+/** @type CommandInterceptor */
+const defaultCommandInterceptor = async (command, context) => {};
+
 let stepRunner = defaultStepRunner;
 let runWrapper = defaultRunWrapper;
+let commandInterceptor = defaultCommandInterceptor;
 
 /**
- * Enables OpenTelemetry support if it receives an OpenTelemetry onStep option.
- * Otherwise OpenTelemetry support is disabled.
+ * @typedef {Object} EffectConfiguration
+ * @property {StepRunner} [onStep] - Fires once per runEffect call. It wraps the entire workflow execution.
+ * @property {RunWrapper} [onRun] - Fires every time a Command is executed.
+ * @property {CommandInterceptor} [onBeforeCommand] - Intercepts a Command and any context passed to runEffect before execution.
+ */
+
+/**
+ * Configures the global behavior of the Effect runner, including the command interceptor and telemetry.
  *
- * @param {any} options
+ * @param {EffectConfiguration} options - The configuration object for the effect pipeline.
  */
-const configureTelemetry = (/** @type any **/ options) => {
+const configureEffect = (options) => {
     stepRunner = options.onStep ? options.onStep : defaultStepRunner;
     runWrapper = options.onRun ? options.onRun : defaultRunWrapper;
+    commandInterceptor = options.onBeforeCommand ? options.onBeforeCommand : defaultCommandInterceptor;
 };
 
-/**
- * The Interpreter
- * Iterates through the Effect tree, executing Commands and handling async flow.
- *
- * @param {Effect} effect - The Effect tree returned by a pipeline
- * @param {string} flowName - Name of the workflow
- * @returns {Promise<SuccessState | FailureState>}
- */
-async function runEffect(effect, flowName = '') {
-    return runWrapper(
-        effect,
-        async () => {
-            while (effect.type === 'Command') {
-                const currentCmd = effect.cmd;
-                const cmdName = currentCmd.name || 'anonymous';
-
-                try {
-                    const result = await stepRunner(cmdName, 'Command', currentCmd);
-                    effect = effect.next(result);
-                } catch (e) {
-                    return Failure(e, effect.initialInput);
+const runEffect =
+    /**
+     * The Interpreter
+     * Iterates through the Effect tree, executing Commands and handling async flow.
+     *
+     * @param {Effect} effect - The Effect tree returned by a pipeline
+     * @param {any} [context] - Optional context object passed to the Command Interceptor
+     * @returns {Promise<SuccessState | FailureState>}
+     */
+    async function runEffect(effect, context = {}) {
+        return runWrapper(
+            effect,
+            async () => {
+                while (effect.type === 'Command') {
+                    const cmdName = effect.cmd.name || 'anonymous';
+                    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 effect;
-        },
-        flowName || ''
-    );
-}
+                return effect;
+            },
+            context?.flowName || ''
+        );
+    };
 
-export { Success, Failure, Command, effectPipe, runEffect, configureTelemetry };
+export { Success, Failure, Command, effectPipe, runEffect, configureEffect };

package/opentelemetry-example.js

@@ -4,7 +4,9 @@ import { NodeSDK } from '@opentelemetry/sdk-node';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
 import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { trace, SpanStatusCode } from '@opentelemetry/api';
-import { configureTelemetry } from './index.js';
+import { configureEffect } from './index.js';
+
+/** @import { RunWrapper, StepRunner } from "./index.js" */
 
 const traceExporter = new OTLPTraceExporter({
     url: 'http://localhost:4318/v1/traces',
@@ -28,12 +30,13 @@ process.on('SIGTERM', () => {
 
 export function enableTelemetry() {
     const tracer = trace.getTracer('pure-effect-test');
-    configureTelemetry({
-        onRun: (/** @type any */ effect, /** @type any */ pipeline, /** @type string */ flowName) => {
+    configureEffect({
+        /** @type RunWrapper */
+        onRun: (effect, pipeline, flowName) => {
             return tracer.startActiveSpan('Effect Pipeline', async (rootSpan) => {
                 try {
                     rootSpan.setAttribute('effect.initialInput', JSON.stringify(effect.initialInput));
-                    rootSpan.setAttribute('effect.flow', flowName);
+                    rootSpan.setAttribute('effect.flow', flowName || '');
 
                     const result = await pipeline();
 
@@ -56,8 +59,8 @@ export function enableTelemetry() {
                 }
             });
         },
-
-        onStep: (/** @type string */ name, /** @type string */ type, /** @type function */ op) => {
+        /** @type StepRunner */
+        onStep: (name, type, op) => {
             return tracer.startActiveSpan(name, async (span) => {
                 span.setAttribute('effect.type', type);
                 try {

package/package.json

@@ -1,11 +1,15 @@
 {
     "name": "pure-effect",
-    "version": "0.3.0",
-    "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript without mocks.",
+    "version": "0.5.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,9 +1,11 @@
 // @ts-check
 
 import { strict as assert } from 'assert';
-import { Success, Failure, Command, effectPipe, runEffect } from '../index.js';
+import { Success, Failure, Command, effectPipe, runEffect, configureEffect } from '../index.js';
 import { enableTelemetry } from '../opentelemetry-example.js';
 
+/** @import { CommandInterceptor } from "../index.js" */
+
 /** @typedef {{id?: number, email: string, password: string}} User */
 
 const db = {
@@ -57,7 +59,7 @@ const registerUserFlow = (/** @type {User} */ input) =>
     )(input);
 
 async function registerUser(/** @type {User} */ input) {
-    return await runEffect(registerUserFlow(input), 'registerUser');
+    return await runEffect(registerUserFlow(input), { flowName: 'registerUser' });
 }
 
 describe('Pure Effect', function () {
@@ -78,6 +80,16 @@ describe('Pure Effect', function () {
         assert.equal(step2.cmd.name, 'cmdSaveUser');
     });
 
+    it('should access context through onBeforeCommand', async function () {
+        configureEffect({
+            onBeforeCommand: /** @type CommandInterceptor */ async (command, context) =>
+                assert.equal(context.env, 'test'),
+        });
+        const input = { email: 'context@test.com', password: 'password123' };
+        const result = await runEffect(registerUserFlow(input), { env: 'test' });
+        configureEffect({ onBeforeCommand: undefined });
+    });
+
     it('should return Success after runEffect with telemetry disabled', async function () {
         const input = { email: 'test-no-telemetry@test.com', password: 'password123' };
         const result = await registerUser(input);

package/test/types.test-d.ts

@@ -0,0 +1,53 @@
+import { expectType, expectError } from 'tsd';
+import { Success, Failure, Command, effectPipe, runEffect } from '../index.js';
+import type { SuccessState, FailureState, CommandState, 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);