pure-effect 0.6.0 → 0.8.0

package/index.d.ts

@@ -10,96 +10,213 @@ 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 AskState<T, E = unknown> = {
+export type AskState<T, E = unknown, Ctx = unknown> = {
     type: 'Ask';
-    next: (context: unknown) => Effect<T, E>;
+    next: (context: Ctx) => Effect<T, E, Ctx>;
     initialInput?: unknown;
 };
 
-export type Effect<T, E = unknown> = SuccessState<T> | FailureState<E> | CommandState<any, T, E> | AskState<T, E>;
+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 ParallelState<T extends readonly unknown[], R, E = unknown, Ctx = unknown> = {
+    type: 'Parallel';
+    effects: { [K in keyof T]: Effect<T[K], E, Ctx> };
+    next: (values: [...T]) => Effect<R, E, Ctx>;
+    initialInput?: unknown;
+};
+
+export type Effect<T, E = unknown, Ctx = unknown> =
+    | SuccessState<T>
+    | FailureState<E>
+    | CommandState<any, T, E, Ctx>
+    | AskState<T, E, Ctx>
+    | RetryState<T, E, Ctx>
+    | ParallelState<any, 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 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 Ask<T, E = unknown>(next: (context: unknown) => Effect<T, E>): AskState<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>>;
+): 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 Parallel<T extends readonly unknown[], R, E = unknown, Ctx = unknown>(
+    effects: { [K in keyof T]: Effect<T[K], E, Ctx> },
+    next: (values: [...T]) => Effect<R, E, Ctx>
+): ParallelState<[...T], R, 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>;
 
@@ -115,6 +232,13 @@ 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

@@ -19,9 +19,28 @@
  * }} AskState
  */
 
+/**
+ * @typedef {{
+ *   type: 'Retry',
+ *   effect: Effect,
+ *   options: { attempts?: number, delay?: number, backoff?: number },
+ *   next: (value: any) => Effect,
+ *   initialInput?: any
+ * }} RetryState
+ */
+
+/**
+ * @typedef {{
+ *   type: 'Parallel',
+ *   effects: Effect[],
+ *   next: (values: any[]) => Effect,
+ *   initialInput?: any
+ * }} ParallelState
+ */
+
 /**
  * The Union type for all possible states
- * @typedef {SuccessState | FailureState | CommandState | AskState} Effect
+ * @typedef {SuccessState | FailureState | CommandState | AskState | RetryState | ParallelState} Effect
  */
 
 /**
@@ -59,27 +78,68 @@ const Command = (cmd, next, meta) => ({ type: 'Command', cmd, next, meta });
  */
 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)
+});
+
+/**
+ * Runs multiple Effect trees concurrently. If any effect fails, returns the first Failure by array order and skips next.
+ * @param {Effect[]} effects - Array of Effect trees to run concurrently
+ * @param {(values: any[]) => Effect} next - Receives array of success values in order, returns next Effect
+ * @returns {ParallelState}
+ */
+const Parallel = (effects, next) => ({ type: 'Parallel', effects, next });
+
 /**
  * Connects an Effect to the next function in the pipeline.
- * Handles the branching logic for Success, Failure, Command, and Ask.
+ * 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;
+            return withII(effect);
         case 'Command': {
-            const next = (/** @type {any} */ result) => chain(effect.next(result), fn);
-            return Command(effect.cmd, next, effect.meta);
+            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);
-            return Ask(next);
+            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 });
+        }
+        case 'Parallel': {
+            const next = (/** @type {any} */ result) => chain(effect.next(result), fn, initialInput);
+            return withII({ ...effect, next });
         }
     }
 };
@@ -93,9 +153,8 @@ const chain = (effect, fn) => {
  */
 const effectPipe = (...fns) => {
     return (start) => {
-        const effect = fns.reduce(chain, /** @type {Effect} */ (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)));
     };
 };
 
@@ -115,11 +174,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.
  */
 
 /**
@@ -131,6 +194,7 @@ 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 =
@@ -139,34 +203,76 @@ const runEffect =
      * 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 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' || effect.type === 'Ask') {
-                    if (effect.type === 'Ask') {
-                        effect = effect.next(context);
-                        continue;
+    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' || eff.type === 'Parallel') {
+                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;
                     }
-                    const cmdName = effect.cmd.name || 'anonymous';
-                    const initialInput = effect.initialInput;
-                    try {
-                        await commandInterceptor(effect, context);
-                        const result = await stepRunner(cmdName, 'Command', effect.cmd);
-                        effect = effect.next(result);
-                    } catch (e) {
-                        return Failure(e, initialInput);
+
+                    if (!succeeded) {
+                        return Failure({ retryExhausted: true, lastError, attempts }, eff.initialInput);
                     }
+                    continue;
                 }
+                if (eff.type === 'Parallel') {
+                    const results = await Promise.all(eff.effects.map((e) => execute(e)));
+                    const failure = results.find((r) => r.type === 'Failure');
+                    if (failure) return failure;
+                    eff = eff.next(results.map((r) => /** @type {SuccessState} */ (r).value));
+                    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, Ask, effectPipe, runEffect, configureEffect };
+export { Success, Failure, Command, Ask, Retry, Parallel, effectPipe, runEffect, configureEffect };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "pure-effect",
-    "version": "0.6.0",
-    "description": "A tiny, zero-dependency effect system for writing pure, testable JavaScript/TypeScript without mocks.",
+    "version": "0.8.0",
+    "description": "A zero-dependency effect library for JavaScript and TypeScript with built-in support for dependency injection, retry, and OpenTelemetry where business logic is plain data you can test without mocks.",
     "type": "module",
     "exports": "./index.js",
     "types": "./index.d.ts",