pure-effect 0.3.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,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.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,6 +1,6 @@
 {
     "name": "pure-effect",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript without mocks.",
     "type": "module",
     "exports": "./index.js",

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);