pure-effect 0.5.0 → 0.7.0

package/index.d.ts

@@ -10,102 +10,202 @@ export type FailureState<E = unknown> = {
     initialInput?: unknown;
 };
 
-export type CommandState<R, T, E = unknown> = {
+export type CommandState<R, T, E = unknown, Ctx = unknown> = {
     type: 'Command';
     cmd: () => Promise<R> | R;
-    next: (result: R) => Effect<T, E>;
+    next: (result: R) => Effect<T, E, Ctx>;
     meta?: unknown;
     initialInput?: unknown;
 };
 
-export type Effect<T, E = unknown> =
+export type AskState<T, E = unknown, Ctx = unknown> = {
+    type: 'Ask';
+    next: (context: Ctx) => Effect<T, E, Ctx>;
+    initialInput?: unknown;
+};
+
+export type RetryOptions = {
+    attempts?: number;
+    delay?: number;
+    backoff?: number;
+};
+
+export type RetryState<T, E = unknown, Ctx = unknown> = {
+    type: 'Retry';
+    effect: Effect<T, E, Ctx>;
+    options: RetryOptions;
+    next: (value: T) => Effect<T, E, Ctx>;
+    initialInput?: unknown;
+};
+
+export type RetryExhaustedError<E = unknown> = {
+    retryExhausted: true;
+    lastError: E;
+    attempts: number;
+};
+
+export type Effect<T, E = unknown, Ctx = unknown> =
     | SuccessState<T>
     | FailureState<E>
-    | CommandState<any, T, E>;
+    | CommandState<any, T, E, Ctx>
+    | AskState<T, E, Ctx>
+    | RetryState<T, E, Ctx>;
 
 export declare function Success<T>(value: T): SuccessState<T>;
 
-export declare function Failure<E = unknown>(
-    error: E,
-    initialInput?: unknown
-): FailureState<E>;
+export declare function Failure<E = unknown>(error: E, initialInput?: unknown): FailureState<E>;
 
-export declare function Command<R, T, E = unknown>(
+export declare function Command<R, T, E = unknown, Ctx = unknown>(
     cmd: () => Promise<R> | R,
-    next: (result: R) => Effect<T, E>,
+    next: (result: R) => Effect<T, E, Ctx>,
     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>;
+): CommandState<R, T, E, Ctx>;
+
+export declare function Ask<T, E = unknown, Ctx = unknown>(
+    next: (context: Ctx) => Effect<T, E, Ctx>
+): AskState<T, E, Ctx>;
+
+export declare function Retry<T, E = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
+    options?: RetryOptions
+): RetryState<T, E, Ctx>;
+
+export declare function effectPipe<A, B, E1 = unknown, Ctx = unknown>(
+    f1: (a: A) => Effect<B, E1, Ctx>
+): (start: A) => Effect<B, E1, Ctx>;
+
+export declare function effectPipe<A, B, C, E1 = unknown, E2 = unknown, Ctx = unknown>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>
+): (start: A) => Effect<C, E1 | E2, Ctx>;
+
+export declare function effectPipe<A, B, C, D, E1 = unknown, E2 = unknown, E3 = unknown, Ctx = unknown>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>
+): (start: A) => Effect<D, E1 | E2 | E3, Ctx>;
+
+export declare function effectPipe<
+    A,
+    B,
+    C,
+    D,
+    F,
+    E1 = unknown,
+    E2 = unknown,
+    E3 = unknown,
+    E4 = unknown,
+    Ctx = unknown
+>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>,
+    f4: (d: D) => Effect<F, E4, Ctx>
+): (start: A) => Effect<F, E1 | E2 | E3 | E4, Ctx>;
+
+export declare function effectPipe<
+    A,
+    B,
+    C,
+    D,
+    F,
+    G,
+    E1 = unknown,
+    E2 = unknown,
+    E3 = unknown,
+    E4 = unknown,
+    E5 = unknown,
+    Ctx = unknown
+>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>,
+    f4: (d: D) => Effect<F, E4, Ctx>,
+    f5: (f: F) => Effect<G, E5, Ctx>
+): (start: A) => Effect<G, E1 | E2 | E3 | E4 | E5, Ctx>;
+
+export declare function effectPipe<
+    A,
+    B,
+    C,
+    D,
+    F,
+    G,
+    H,
+    E1 = unknown,
+    E2 = unknown,
+    E3 = unknown,
+    E4 = unknown,
+    E5 = unknown,
+    E6 = unknown,
+    Ctx = unknown
+>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>,
+    f4: (d: D) => Effect<F, E4, Ctx>,
+    f5: (f: F) => Effect<G, E5, Ctx>,
+    f6: (g: G) => Effect<H, E6, Ctx>
+): (start: A) => Effect<H, E1 | E2 | E3 | E4 | E5 | E6, Ctx>;
+
+export declare function effectPipe<
+    A,
+    B,
+    C,
+    D,
+    F,
+    G,
+    H,
+    I,
+    E1 = unknown,
+    E2 = unknown,
+    E3 = unknown,
+    E4 = unknown,
+    E5 = unknown,
+    E6 = unknown,
+    E7 = unknown,
+    Ctx = unknown
+>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>,
+    f4: (d: D) => Effect<F, E4, Ctx>,
+    f5: (f: F) => Effect<G, E5, Ctx>,
+    f6: (g: G) => Effect<H, E6, Ctx>,
+    f7: (h: H) => Effect<I, E7, Ctx>
+): (start: A) => Effect<I, E1 | E2 | E3 | E4 | E5 | E6 | E7, Ctx>;
+
+export declare function effectPipe<
+    A,
+    B,
+    C,
+    D,
+    F,
+    G,
+    H,
+    I,
+    J,
+    E1 = unknown,
+    E2 = unknown,
+    E3 = unknown,
+    E4 = unknown,
+    E5 = unknown,
+    E6 = unknown,
+    E7 = unknown,
+    E8 = unknown,
+    Ctx = unknown
+>(
+    f1: (a: A) => Effect<B, E1, Ctx>,
+    f2: (b: B) => Effect<C, E2, Ctx>,
+    f3: (c: C) => Effect<D, E3, Ctx>,
+    f4: (d: D) => Effect<F, E4, Ctx>,
+    f5: (f: F) => Effect<G, E5, Ctx>,
+    f6: (g: G) => Effect<H, E6, Ctx>,
+    f7: (h: H) => Effect<I, E7, Ctx>,
+    f8: (i: I) => Effect<J, E8, Ctx>
+): (start: A) => Effect<J, E1 | E2 | E3 | E4 | E5 | E6 | E7 | E8, Ctx>;
+
+export type StepRunner = (name: string, type: string, op: () => Promise<unknown>) => Promise<unknown>;
 
 export type RunWrapper = (
     effect: Effect<unknown>,
@@ -113,15 +213,19 @@ export type RunWrapper = (
     flowName?: string
 ) => Promise<SuccessState<unknown> | FailureState<unknown>>;
 
-export type CommandInterceptor = (
-    command: CommandState<unknown, unknown>,
-    context?: any
-) => Promise<void>;
+export type CommandInterceptor = (command: CommandState<unknown, unknown>, context?: any) => Promise<void>;
 
 export interface EffectConfiguration {
     onStep?: StepRunner;
     onRun?: RunWrapper;
     onBeforeCommand?: CommandInterceptor;
+    retry?: RetryOptions;
 }
 
 export declare function configureEffect(options: EffectConfiguration): void;
+
+export declare function runEffect<T, E = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
+    context?: Ctx,
+    callConfig?: EffectConfiguration
+): Promise<SuccessState<T> | FailureState<E>>;

package/index.js

@@ -11,10 +11,27 @@
  *   initialInput?: any
  * }} CommandState
  */
+/**
+ * @typedef {{
+ *   type: 'Ask',
+ *   next: (context: any) => Effect,
+ *   initialInput?: any
+ * }} AskState
+ */
+
+/**
+ * @typedef {{
+ *   type: 'Retry',
+ *   effect: Effect,
+ *   options: { attempts?: number, delay?: number, backoff?: number },
+ *   next: (value: any) => Effect,
+ *   initialInput?: any
+ * }} RetryState
+ */
 
 /**
  * The Union type for all possible states
- * @typedef {SuccessState | FailureState | CommandState} Effect
+ * @typedef {SuccessState | FailureState | CommandState | AskState | RetryState} Effect
  */
 
 /**
@@ -30,7 +47,11 @@ const Success = (value) => ({ type: 'Success', value });
  * @param {any} [initialInput] - initial input passed to the flow (optional)
  * @returns {FailureState}
  */
-const Failure = (error, initialInput) => ({ type: 'Failure', error, initialInput });
+const Failure = (error, initialInput) => ({
+    type: 'Failure',
+    error,
+    initialInput
+});
 
 /**
  * Represents a side effect to be executed later
@@ -41,23 +62,64 @@ const Failure = (error, initialInput) => ({ type: 'Failure', error, initialInput
  */
 const Command = (cmd, next, meta) => ({ type: 'Command', cmd, next, meta });
 
+/**
+ * Reads the context object from the current `runEffect` call.
+ * @param {(context: any) => Effect} next - Receives the context and returns the next Effect
+ * @returns {AskState}
+ */
+const Ask = (next) => ({ type: 'Ask', next });
+
+/**
+ * Wraps an Effect tree with retry-on-failure semantics.
+ * @param {Effect} effect - The inner Effect tree to retry
+ * @param {Object} [options] - Per-use retry options; merged over global defaults at runtime
+ * @param {number} [options.attempts] - Max retries (not counting first try)
+ * @param {number} [options.delay] - Ms before first retry
+ * @param {number} [options.backoff] - Multiplier applied to delay on each subsequent retry
+ * @returns {RetryState}
+ */
+const Retry = (effect, options = {}) => ({
+    type: 'Retry',
+    effect,
+    options,
+    next: (value) => Success(value)
+});
+
 /**
  * Connects an Effect to the next function in the pipeline.
- * Handles the branching logic for Success, Failure, and Command.
+ * Handles the branching logic for Success, Failure, Command, Ask, and Retry.
  *
  * @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) => {
+/**
+ * @param {Effect} effect
+ * @param {(value: any) => Effect} fn
+ * @param {any} [initialInput]
+ * @returns {Effect}
+ */
+const chain = (effect, fn, initialInput) => {
+    const withII = (/** @type {Effect} */ e) =>
+        initialInput !== undefined && e.initialInput === undefined ? { ...e, initialInput } : e;
+
     switch (effect.type) {
         case 'Success':
-            return fn(effect.value);
+            return withII(fn(effect.value));
         case 'Failure':
-            return effect;
-        case 'Command':
-            const next = (/** @type {Effect} */ result) => chain(effect.next(result), fn);
-            return Command(effect.cmd, next, effect.meta);
+            return withII(effect);
+        case 'Command': {
+            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput);
+            return withII(Command(effect.cmd, next, effect.meta));
+        }
+        case 'Ask': {
+            const next = (/** @type {any} */ ctx) => chain(effect.next(ctx), fn, initialInput);
+            return withII(Ask(next));
+        }
+        case 'Retry': {
+            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput);
+            return withII({ ...effect, next });
+        }
     }
 };
 
@@ -65,14 +127,13 @@ const chain = (effect, fn) => {
  * 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.
+ * @param {...(input: any) => Effect} fns - Functions that return Success, Failure, Command, or Ask.
  * @returns {(start: any) => Effect} A function that accepts an initial input and returns the final Effect tree.
  */
 const effectPipe = (...fns) => {
     return (start) => {
-        const effect = fns.reduce(chain, Success(start));
-        effect.initialInput = start;
-        return effect;
+        const chainWithII = (/** @type {Effect} */ eff, /** @type {(v: any) => Effect} */ fn) => chain(eff, fn, start);
+        return fns.reduce(chainWithII, /** @type {Effect} */ (Success(start)));
     };
 };
 
@@ -92,11 +153,15 @@ let stepRunner = defaultStepRunner;
 let runWrapper = defaultRunWrapper;
 let commandInterceptor = defaultCommandInterceptor;
 
+const defaultRetryOptions = { attempts: 3, delay: 100, backoff: 1 };
+let retryDefaults = { ...defaultRetryOptions };
+
 /**
  * @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.
+ * @property {{ attempts?: number, delay?: number, backoff?: number }} [retry] - Global Retry defaults; merged under per-use options.
  */
 
 /**
@@ -108,36 +173,78 @@ const configureEffect = (options) => {
     stepRunner = options.onStep ? options.onStep : defaultStepRunner;
     runWrapper = options.onRun ? options.onRun : defaultRunWrapper;
     commandInterceptor = options.onBeforeCommand ? options.onBeforeCommand : defaultCommandInterceptor;
+    retryDefaults = options.retry ? { ...defaultRetryOptions, ...options.retry } : defaultRetryOptions;
 };
 
 const runEffect =
     /**
      * The Interpreter
      * Iterates through the Effect tree, executing Commands and handling async flow.
+     * Ask effects are resolved synchronously with the context object.
+     *
+     * Per-call config takes precedence over global configureEffect defaults.
+     * onRun fires exactly once per runEffect call — Retry attempts run inside that
+     * single span rather than spawning their own, keeping telemetry non-duplicated.
      *
      * @param {Effect} effect - The Effect tree returned by a pipeline
-     * @param {any} [context] - Optional context object passed to the Command Interceptor
+     * @param {any} [context] - Optional context object. Passed to Ask continuations and the Command Interceptor.
+     * @param {EffectConfiguration} [callConfig] - Per-call overrides; merged over global configureEffect defaults.
      * @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);
+    async function runEffect(effect, context = {}, callConfig = {}) {
+        const localStepRunner = callConfig.onStep ? callConfig.onStep : stepRunner;
+        const localRunWrapper = callConfig.onRun ? callConfig.onRun : runWrapper;
+        const localCommandInterceptor = callConfig.onBeforeCommand ? callConfig.onBeforeCommand : commandInterceptor;
+        const localRetryDefaults = callConfig.retry ? { ...retryDefaults, ...callConfig.retry } : retryDefaults;
+
+        /**
+         * @param {Effect} eff
+         * @returns {Promise<SuccessState | FailureState>}
+         */
+        async function execute(eff) {
+            while (eff.type === 'Command' || eff.type === 'Ask' || eff.type === 'Retry') {
+                if (eff.type === 'Ask') {
+                    eff = eff.next(context);
+                    continue;
+                }
+                if (eff.type === 'Retry') {
+                    const opts = { ...localRetryDefaults, ...eff.options };
+                    const { attempts } = opts;
+                    let lastError;
+                    let succeeded = false;
+
+                    for (let attempt = 0; attempt <= attempts; attempt++) {
+                        if (attempt > 0) {
+                            await new Promise((r) => setTimeout(r, opts.delay * Math.pow(opts.backoff, attempt - 1)));
+                        }
+                        const result = await execute(eff.effect);
+                        if (result.type === 'Success') {
+                            eff = eff.next(result.value);
+                            succeeded = true;
+                            break;
+                        }
+                        lastError = result.error;
                     }
+
+                    if (!succeeded) {
+                        return Failure({ retryExhausted: true, lastError, attempts }, eff.initialInput);
+                    }
+                    continue;
+                }
+                const cmdName = eff.cmd.name || 'anonymous';
+                const initialInput = eff.initialInput;
+                try {
+                    await localCommandInterceptor(eff, context);
+                    const result = await localStepRunner(cmdName, 'Command', eff.cmd);
+                    eff = eff.next(result);
+                } catch (e) {
+                    return Failure(e, initialInput);
                 }
+            }
+            return eff;
+        }
 
-                return effect;
-            },
-            context?.flowName || ''
-        );
+        return localRunWrapper(effect, () => execute(effect), context?.flowName || '');
     };
 
-export { Success, Failure, Command, effectPipe, runEffect, configureEffect };
+export { Success, Failure, Command, Ask, Retry, effectPipe, runEffect, configureEffect };

package/opentelemetry-example.js

@@ -9,14 +9,14 @@ import { configureEffect } from './index.js';
 /** @import { RunWrapper, StepRunner } from "./index.js" */
 
 const traceExporter = new OTLPTraceExporter({
-    url: 'http://localhost:4318/v1/traces',
+    url: 'http://localhost:4318/v1/traces'
 });
 
 const sdk = new NodeSDK({
     serviceName: 'pure-effect-test',
     traceExporter,
     spanProcessor: new SimpleSpanProcessor(traceExporter),
-    instrumentations: [],
+    instrumentations: []
 });
 
 sdk.start();
@@ -43,7 +43,7 @@ export function enableTelemetry() {
                     if (result.type === 'Failure') {
                         rootSpan.setStatus({
                             code: SpanStatusCode.ERROR,
-                            message: String(result.error),
+                            message: String(result.error)
                         });
                     } else {
                         rootSpan.setStatus({ code: SpanStatusCode.OK });
@@ -79,13 +79,13 @@ export function enableTelemetry() {
                     span.recordException(err);
                     span.setStatus({
                         code: SpanStatusCode.ERROR,
-                        message: err.message,
+                        message: err.message
                     });
                     throw err;
                 } finally {
                     span.end();
                 }
             });
-        },
+        }
     });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "pure-effect",
-    "version": "0.5.0",
-    "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript/TypeScript without mocks.",
+    "version": "0.7.0",
+    "description": "A TypeScript effect library where effects are plain objects you can inspect, test, and reason about. Learn the whole API in an afternoon. Tiny footprint, zero dependencies, works with plain JavaScript too.",
     "type": "module",
     "exports": "./index.js",
     "types": "./index.d.ts",