pure-effect 0.2.0 → 0.4.0

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

@@ -53,7 +53,7 @@ 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);
 
@@ -77,7 +77,7 @@ The biggest benefit of **Pure Effect** is testability. Because `registerUserFlow
 const badInput = { email: 'bad-email', password: '123' };
 const result = registerUserFlow(badInput);
 
-assert.deepEqual(result, Failure('Invalid email.'));
+assert.deepEqual(result, Failure('Invalid email format.', badInput));
 // ✅ Logic tested instantly, no async needed.
 
 // 2. Test Flow Intent (Introspection)
@@ -103,19 +103,47 @@ Returns an object `{ type: 'Success', value }`. Represents a successful computat
 
 ### `Failure(error)`
 
-Returns an object `{ type: 'Failure', error }`. Represents a failed computation. Stops the pipeline immediately.
+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)`
+### `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 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.
+
+---
+
+### `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). Please see **opentelemetry-example.js** for 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`.
+
+-   `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.js

@@ -1,12 +1,14 @@
 // @ts-check
 
-/** @typedef {{ type: 'Success', value: any }} SuccessState */
-/** @typedef {{ type: 'Failure', error: any }} FailureState */
+/** @typedef {{ type: 'Success', value: any, initialInput?: any }} SuccessState */
+/** @typedef {{ type: 'Failure', error: any, initialInput?: any }} FailureState */
 /**
  * @typedef {{
  *   type: 'Command',
  *   cmd: () => Promise<any>|any,
- *   next: (result: any) => Effect
+ *   next: (result: any) => Effect,
+ *   meta?: any,
+ *   initialInput?: any
  * }} CommandState
  */
 
@@ -25,17 +27,19 @@ const Success = (value) => ({ type: 'Success', value });
 /**
  * Represents a failed computation. Stops the pipeline execution
  * @param {any} error - The error reason (string, Error object, etc).
+ * @param {any} [initialInput] - initial input passed to the flow (optional)
  * @returns {FailureState}
  */
-const Failure = (error) => ({ type: 'Failure', error });
+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.
@@ -53,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);
     }
 };
 
@@ -65,25 +69,75 @@ const chain = (effect, fn) => {
  * @returns {(start: any) => Effect} A function that accepts an initial input and returns the final Effect tree.
  */
 const effectPipe = (...fns) => {
-    return (start) => fns.reduce(chain, Success(start));
+    return (start) => {
+        const effect = fns.reduce(chain, Success(start));
+        effect.initialInput = start;
+        return effect;
+    };
 };
 
+/** @typedef {(name: string, type: string, op: function) => Promise<any>} StepRunner */
+/** @type StepRunner */
+const defaultStepRunner = async (name, type, op) => await op();
+
+/** @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;
+
 /**
- * The Interpreter
- * Iterates through the Effect tree, executing Commands and handling async flow.
+ * @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 {Effect} effect - The Effect tree returned by a pipeline
- * @returns {Promise<SuccessState | FailureState>}
+ * @param {EffectConfiguration} options - The configuration object for the effect pipeline.
  */
-async function runEffect(effect) {
-    while (effect.type === 'Command') {
-        try {
-            effect = effect.next(await effect.cmd());
-        } catch (e) {
-            return Failure(e);
-        }
-    }
-    return effect;
-}
+const configureEffect = (options) => {
+    stepRunner = options.onStep ? options.onStep : defaultStepRunner;
+    runWrapper = options.onRun ? options.onRun : defaultRunWrapper;
+    commandInterceptor = options.onBeforeCommand ? options.onBeforeCommand : defaultCommandInterceptor;
+};
+
+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;
+            },
+            context?.flowName || ''
+        );
+    };
 
-export { Success, Failure, Command, effectPipe, runEffect };
+export { Success, Failure, Command, effectPipe, runEffect, configureEffect };

package/opentelemetry-example.js

@@ -0,0 +1,91 @@
+// @ts-check
+
+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 { configureEffect } from './index.js';
+
+/** @import { RunWrapper, StepRunner } from "./index.js" */
+
+const traceExporter = new OTLPTraceExporter({
+    url: 'http://localhost:4318/v1/traces',
+});
+
+const sdk = new NodeSDK({
+    serviceName: 'pure-effect-test',
+    traceExporter,
+    spanProcessor: new SimpleSpanProcessor(traceExporter),
+    instrumentations: [],
+});
+
+sdk.start();
+
+process.on('SIGTERM', () => {
+    sdk.shutdown()
+        .then(() => console.log('Tracing terminated'))
+        .catch((error) => console.log('Error terminating tracing', error))
+        .finally(() => process.exit(0));
+});
+
+export function enableTelemetry() {
+    const tracer = trace.getTracer('pure-effect-test');
+    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 || '');
+
+                    const result = await pipeline();
+
+                    if (result.type === 'Failure') {
+                        rootSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: String(result.error),
+                        });
+                    } else {
+                        rootSpan.setStatus({ code: SpanStatusCode.OK });
+                    }
+
+                    return result;
+                } catch (/** @type any */ err) {
+                    rootSpan.recordException(err);
+                    rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+                    throw err;
+                } finally {
+                    rootSpan.end();
+                }
+            });
+        },
+        /** @type StepRunner */
+        onStep: (name, type, op) => {
+            return tracer.startActiveSpan(name, async (span) => {
+                span.setAttribute('effect.type', type);
+                try {
+                    const result = await op();
+                    try {
+                        if (result !== undefined) {
+                            const outputString = typeof result === 'object' ? JSON.stringify(result) : String(result);
+                            span.setAttribute('effect.output', outputString);
+                        }
+                    } catch (serializationError) {
+                        span.setAttribute('effect.output', '[Circular or Non-Serializable Data]');
+                    }
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    return result;
+                } catch (/** @type any */ err) {
+                    span.recordException(err);
+                    span.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: err.message,
+                    });
+                    throw err;
+                } finally {
+                    span.end();
+                }
+            });
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pure-effect",
-    "version": "0.2.0",
+    "version": "0.4.0",
     "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript without mocks.",
     "type": "module",
     "exports": "./index.js",
@@ -11,6 +11,7 @@
     "homepage": "https://github.com/aycangulez/pure-effect",
     "license": "MIT",
     "devDependencies": {
+        "@opentelemetry/sdk-node": "^0.211.0",
         "@types/mocha": "^10.0.10",
         "@types/node": "^24.10.1",
         "mocha": "^11.7.5"

package/test/all.js

@@ -1,7 +1,10 @@
 // @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 */
 
@@ -56,14 +59,14 @@ const registerUserFlow = (/** @type {User} */ input) =>
     )(input);
 
 async function registerUser(/** @type {User} */ input) {
-    return await runEffect(registerUserFlow(input));
+    return await runEffect(registerUserFlow(input), { flowName: 'registerUser' });
 }
 
 describe('Pure Effect', function () {
     it('should return Failure when e-mail is invalid', async function () {
-        const input = { email: 'bad-email', password: '123' };
-        const effect = await registerUser(input);
-        assert.deepEqual(effect, Failure('Invalid email format.'));
+        const badInput = { email: 'bad-email', password: '123' };
+        const result = registerUserFlow(badInput);
+        assert.deepEqual(result, Failure('Invalid email format.', badInput));
     });
 
     it('should walk through the call tree', async function () {
@@ -76,4 +79,27 @@ describe('Pure Effect', function () {
         assert.equal(step2.type, 'Command');
         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);
+        assert.equal(result.type, 'Success');
+    });
+
+    it('should return Success after runEffect with telemetry enabled', async function () {
+        enableTelemetry();
+        const input = { email: 'test-telemetry@test.com', password: 'password123' };
+        const result = await registerUser(input);
+        assert.equal(result.type, 'Success');
+    });
 });