pure-effect 0.1.2 → 0.3.0

package/README.md

@@ -4,6 +4,8 @@
 
 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.
+
 ## Installation
 
 ```bash
@@ -56,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);
@@ -75,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)
@@ -101,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)`
 
@@ -114,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`. 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.
 
-The interpreter. It takes an `effect` object, executes any nested Commands recursively using `async/await`, and returns the final `Success` or `Failure`.
+-   `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,7 +1,52 @@
+// @ts-check
+
+/** @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,
+ *   initialInput?: any
+ * }} CommandState
+ */
+
+/**
+ * The Union type for all possible states
+ * @typedef {SuccessState | FailureState | CommandState} Effect
+ */
+
+/**
+ * Represents a successful computation
+ * @param {any} value - The result value
+ * @returns {SuccessState}
+ */
 const Success = (value) => ({ type: 'Success', value });
-const Failure = (error) => ({ type: 'Failure', error });
+
+/**
+ * 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, 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
+ * @returns {CommandState}
+ */
 const Command = (cmd, next) => ({ type: 'Command', cmd, next });
 
+/**
+ * Connects an Effect to the next function in the pipeline.
+ * Handles the branching logic for Success, Failure, and Command.
+ *
+ * @param {Effect} effect - The current Effect object
+ * @param {(value: any) => Effect} fn - The next function to run if the current effect is a Success
+ * @returns {Effect} The composed Effect
+ */
 const chain = (effect, fn) => {
     switch (effect.type) {
         case 'Success':
@@ -9,24 +54,74 @@ const chain = (effect, fn) => {
         case 'Failure':
             return effect;
         case 'Command':
-            const next = (result) => chain(effect.next(result), fn);
+            const next = (/** @type {Effect} */ result) => chain(effect.next(result), fn);
             return Command(effect.cmd, next);
     }
 };
 
+/**
+ * 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.
+ * @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;
+    };
 };
 
-async function runEffect(effect) {
-    while (effect.type === 'Command') {
-        try {
-            effect = effect.next(await effect.cmd());
-        } catch (e) {
-            return Failure(e);
-        }
-    }
-    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;
+};
+
+/**
+ * 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);
+                }
+            }
+
+            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.1.2",
+    "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,9 @@
     "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,19 +1,24 @@
+// @ts-check
+
 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 */
 
 const db = {
     users: new Map(),
-    async findUserByEmail(email) {
+    async findUserByEmail(/** @type string */ email) {
         return this.users.get(email) || null;
     },
-    async saveUser(user) {
-        const u = { id: Date.now(), ...user };
+    async saveUser(/** @type {User} */ user) {
+        const u = { ...user, id: Date.now() };
         this.users.set(user.email, u);
         return u;
     },
 };
 
-function validateRegistration(input) {
+function validateRegistration(/** @type {User} */ input) {
     const { email, password } = input;
     if (!email?.includes('@')) {
         return Failure('Invalid email format.');
@@ -24,26 +29,26 @@ function validateRegistration(input) {
     return Success(input);
 }
 
-function findUserByEmail(email) {
+function findUserByEmail(/** @type string */ email) {
     const cmdFindUser = () => db.findUserByEmail(email);
-    const next = (foundUser) => Success(foundUser);
+    const next = (/** @type {User} */ foundUser) => Success(foundUser);
     return Command(cmdFindUser, next);
 }
 
-function ensureEmailIsAvailable(foundUser) {
+function ensureEmailIsAvailable(/** @type {User} */ foundUser) {
     return foundUser ? Failure('Email already in use.') : Success(true);
 }
 
-function saveUser(input) {
+function saveUser(/** @type {User} */ input) {
     const { email, password } = input;
     const hashedPassword = `hashed_${password}`;
     const userToSave = { email, password: hashedPassword };
     const cmdSaveUser = () => db.saveUser(userToSave);
-    const next = (savedUser) => Success(savedUser);
+    const next = (/** @type {User} */ savedUser) => Success(savedUser);
     return Command(cmdSaveUser, next);
 }
 
-const registerUserFlow = (input) =>
+const registerUserFlow = (/** @type {User} */ input) =>
     effectPipe(
         validateRegistration,
         () => findUserByEmail(input.email),
@@ -51,15 +56,15 @@ const registerUserFlow = (input) =>
         () => saveUser(input)
     )(input);
 
-async function registerUser(input) {
-    return await runEffect(registerUserFlow(input));
+async function registerUser(/** @type {User} */ 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 () {
@@ -72,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');
+    });
 });