pure-effect 0.2.0 → 0.3.0

package/README.md

@@ -58,7 +58,7 @@ async function registerUser() {
     const logic = registerUserFlow(input);
 
     // runEffect performs the actual async work
-    const result = await runEffect(logic);
+    const result = await runEffect(logic, 'registerUser');
 
     if (result.type === 'Success') {
         console.log('User created:', result.value);
@@ -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,7 +103,7 @@ 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)`
 
@@ -116,6 +116,27 @@ Returns an object `{ type: 'Command', cmd, next }`.
 
 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, flowName = '')`
 
-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`. It also accepts an optional `flowName` that comes in handy for telemetry.
+
+---
+
+### `configureTelemetry(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** to see a quick example.
+
+-   `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.

package/index.js

@@ -1,12 +1,13 @@
 // @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,
+ *   initialInput?: any
  * }} CommandState
  */
 
@@ -25,9 +26,10 @@ 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
@@ -65,7 +67,31 @@ 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;
+    };
+};
+
+/** @type {(name: string, type: string, op: function) => Promise<any>} */
+const defaultStepRunner = async (name, type, op) => await op();
+
+/** @type {(effect: Effect, op: function, flowName?: string) => Promise<any>} */
+const defaultRunWrapper = async (effect, op, flowName) => await op();
+
+let stepRunner = defaultStepRunner;
+let runWrapper = defaultRunWrapper;
+
+/**
+ * Enables OpenTelemetry support if it receives an OpenTelemetry onStep option.
+ * Otherwise OpenTelemetry support is disabled.
+ *
+ * @param {any} options
+ */
+const configureTelemetry = (/** @type any **/ options) => {
+    stepRunner = options.onStep ? options.onStep : defaultStepRunner;
+    runWrapper = options.onRun ? options.onRun : defaultRunWrapper;
 };
 
 /**
@@ -73,17 +99,29 @@ const effectPipe = (...fns) => {
  * 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) {
-    while (effect.type === 'Command') {
-        try {
-            effect = effect.next(await effect.cmd());
-        } catch (e) {
-            return Failure(e);
-        }
-    }
-    return effect;
+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);
+                }
+            }
+
+            return effect;
+        },
+        flowName || ''
+    );
 }
 
-export { Success, Failure, Command, effectPipe, runEffect };
+export { Success, Failure, Command, effectPipe, runEffect, configureTelemetry };

package/opentelemetry-example.js

@@ -0,0 +1,88 @@
+// @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 { configureTelemetry } 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');
+    configureTelemetry({
+        onRun: (/** @type any */ effect, /** @type any */ pipeline, /** @type string */ 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();
+                }
+            });
+        },
+
+        onStep: (/** @type string */ name, /** @type string */ type, /** @type function */ 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.3.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

@@ -2,6 +2,7 @@
 
 import { strict as assert } from 'assert';
 import { Success, Failure, Command, effectPipe, runEffect } from '../index.js';
+import { enableTelemetry } from '../opentelemetry-example.js';
 
 /** @typedef {{id?: number, email: string, password: string}} User */
 
@@ -56,14 +57,14 @@ const registerUserFlow = (/** @type {User} */ input) =>
     )(input);
 
 async function registerUser(/** @type {User} */ input) {
-    return await runEffect(registerUserFlow(input));
+    return await runEffect(registerUserFlow(input), '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 +77,17 @@ describe('Pure Effect', function () {
         assert.equal(step2.type, 'Command');
         assert.equal(step2.cmd.name, 'cmdSaveUser');
     });
+
+    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');
+    });
 });