pure-effect 0.6.0 → 0.8.0

package/test/all.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 import { strict as assert } from 'assert';
-import { Success, Failure, Command, Ask, effectPipe, runEffect, configureEffect } from '../index.js';
+import { Success, Failure, Command, Ask, Retry, Parallel, effectPipe, runEffect, configureEffect } from '../index.js';
 import { enableTelemetry } from '../opentelemetry-example.js';
 
 /** @import { CommandInterceptor } from "../index.js" */
@@ -81,26 +81,15 @@ describe('Pure Effect', function () {
     });
 
     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);
-        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');
+        await runEffect(
+            registerUserFlow(input),
+            { env: 'test' },
+            {
+                onBeforeCommand: /** @type CommandInterceptor */ async (command, context) =>
+                    assert.equal(context.env, 'test')
+            }
+        );
     });
 
     it('should access context through Ask', async function () {
@@ -128,4 +117,191 @@ describe('Pure Effect', function () {
         assert.equal(result.type, 'Success');
         assert.deepEqual(result.value, { value: 'value', env: 'test' });
     });
+
+    it('should return a Retry data structure', function () {
+        const inner = Command(
+            () => 'x',
+            (r) => Success(r)
+        );
+        const effect = Retry(inner, { attempts: 5 });
+        assert.equal(effect.type, 'Retry');
+        assert.deepEqual(effect.options, { attempts: 5 });
+        assert.strictEqual(effect.effect, inner);
+        assert.equal(typeof effect.next, 'function');
+    });
+
+    it('should succeed after transient failures', async function () {
+        let calls = 0;
+        const effect = Retry(
+            Command(
+                function flakyCmd() {
+                    if (++calls < 3) throw new Error('transient');
+                    return 'ok';
+                },
+                (r) => Success(r)
+            ),
+            { attempts: 3, delay: 0 }
+        );
+        const result = await runEffect(effect);
+        assert.equal(result.type, 'Success');
+        assert.equal(result.value, 'ok');
+        assert.equal(calls, 3);
+    });
+
+    it('should return rich Failure when retries are exhausted', async function () {
+        const effect = Retry(
+            Command(
+                function alwaysFails() {
+                    throw new Error('boom');
+                    return /** @type {any} */ (null);
+                },
+                (/** @type {any} */ r) => Success(r)
+            ),
+            { attempts: 2, delay: 0 }
+        );
+        const result = await runEffect(effect);
+        assert.equal(result.type, 'Failure');
+        if (result.type !== 'Failure') throw new Error('expected Failure');
+        const error = /** @type {import('../index.js').RetryExhaustedError<Error>} */ (result.error);
+        assert.equal(error.retryExhausted, true);
+        assert.equal(error.attempts, 2);
+        assert.equal(error.lastError.message, 'boom');
+    });
+
+    it('should apply delay and backoff between retries', async function () {
+        this.timeout(2000);
+        let calls = 0;
+        const start = Date.now();
+        const effect = Retry(
+            Command(
+                function flakyCmd() {
+                    if (++calls < 3) throw new Error('transient');
+                    return 'ok';
+                },
+                (r) => Success(r)
+            ),
+            { attempts: 3, delay: 30, backoff: 1 }
+        );
+        const result = await runEffect(effect);
+        const elapsed = Date.now() - start;
+        assert.equal(result.type, 'Success');
+        // 2 retries × 30 ms = at least 55 ms (5 ms margin for timing variance)
+        assert.ok(elapsed >= 55, `Expected ≥ 55 ms elapsed, got ${elapsed} ms`);
+    });
+
+    it('should merge per-use Retry options with call-level defaults', async function () {
+        // Call-level: attempts 1 (would exhaust on 2nd try)
+        // Per-use: attempts 3 (overrides call-level — should succeed on 3rd try)
+        let calls = 0;
+        const effect = Retry(
+            Command(
+                function flakyCmd() {
+                    if (++calls < 3) throw new Error('x');
+                    return 'ok';
+                },
+                (r) => Success(r)
+            ),
+            { attempts: 3 }
+        );
+        const result = await runEffect(effect, {}, { retry: { attempts: 1, delay: 0, backoff: 1 } });
+        assert.equal(result.type, 'Success');
+        assert.equal(calls, 3);
+    });
+
+    it('should work at any step inside effectPipe', async function () {
+        const flow = effectPipe(
+            (input) =>
+                Retry(
+                    Command(
+                        function fetchCmd() {
+                            return input.toUpperCase();
+                        },
+                        (r) => Success(r)
+                    ),
+                    { attempts: 2, delay: 0 }
+                ),
+            (upper) => Success(`${upper}!`)
+        );
+        const result = await runEffect(flow('hello'));
+        assert.equal(result.type, 'Success');
+        assert.equal(result.value, 'HELLO!');
+    });
+
+    it('should return a Parallel data structure', () => {
+        const e1 = Success(1);
+        const e2 = Success(2);
+        const next = (/** @type {any[]} */ values) => Success(values);
+        const result = Parallel([e1, e2], next);
+        assert.equal(result.type, 'Parallel');
+        assert.deepEqual(result.effects, [e1, e2]);
+        assert.equal(result.next, next);
+    });
+
+    it('should run effects concurrently and pass results to next', async () => {
+        const e1 = Command(
+            async () => 'a',
+            (v) => Success(v)
+        );
+        const e2 = Command(
+            async () => 'b',
+            (v) => Success(v)
+        );
+        const flow = Parallel([e1, e2], ([a, b]) => Success({ a, b }));
+        const result = await runEffect(flow);
+        assert.equal(result.type, 'Success');
+        assert.deepEqual(result.value, { a: 'a', b: 'b' });
+    });
+
+    it('should return Failure if any parallel effect fails', async () => {
+        const e1 = Success('ok');
+        const e2 = Failure('oops');
+        const flow = Parallel([e1, e2], ([a, b]) => Success({ a, b }));
+        const result = await runEffect(flow);
+        assert.equal(result.type, 'Failure');
+        assert.equal(result.error, 'oops');
+    });
+
+    it('should work inside effectPipe', async () => {
+        const flow = effectPipe((input) =>
+            Parallel(
+                [
+                    Command(
+                        async () => input.a,
+                        (v) => Success(v)
+                    ),
+                    Command(
+                        async () => input.b,
+                        (v) => Success(v)
+                    )
+                ],
+                ([a, b]) => Success({ a, b })
+            )
+        );
+        const result = await runEffect(flow({ a: 1, b: 2 }));
+        assert.equal(result.type, 'Success');
+        assert.deepEqual(result.value, { a: 1, b: 2 });
+    });
+
+    it('should pass context to parallel branches via Ask', async () => {
+        const flow = Parallel(
+            [Ask((/** @type {any} */ ctx) => Success(ctx.x)), Ask((/** @type {any} */ ctx) => Success(ctx.y))],
+            ([x, y]) => Success({ x, y })
+        );
+        const result = await runEffect(flow, { x: 10, y: 20 });
+        assert.equal(result.type, 'Success');
+        assert.deepEqual(result.value, { x: 10, y: 20 });
+    });
+
+    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');
+    });
 });

package/test/types.test-d.ts

@@ -1,6 +1,19 @@
 import { expectType, expectError } from 'tsd';
-import { Success, Failure, Command, Ask, effectPipe, runEffect } from '../index.js';
-import type { SuccessState, FailureState, CommandState, AskState, Effect } from '../index.js';
+import { Success, Failure, Command, Ask, Retry, Parallel, effectPipe, runEffect, configureEffect } from '../index.js';
+import type {
+    SuccessState,
+    FailureState,
+    CommandState,
+    AskState,
+    RetryState,
+    ParallelState,
+    RetryExhaustedError,
+    Effect,
+    EffectConfiguration,
+    StepRunner,
+    RunWrapper,
+    CommandInterceptor
+} from '../index.js';
 
 interface User {
     email: string;
@@ -72,3 +85,136 @@ expectType<AskState<User, unknown>>(ask);
 
 const askFlow = effectPipe((input: User) => Ask((_ctx) => Success(input)));
 expectType<Effect<User>>(askFlow({ email: 'a@b.com', password: 'secret123' }));
+
+// --- Retry ---
+
+const innerCmd = Command(
+    async () => 42,
+    (n) => Success(n)
+);
+
+// Retry with options preserves T
+const retried = Retry(innerCmd, { attempts: 3 });
+expectType<RetryState<number, unknown>>(retried);
+
+// Retry without options is valid
+const retriedNoOpts = Retry(innerCmd);
+expectType<RetryState<number, unknown>>(retriedNoOpts);
+
+// Retry in effectPipe preserves type flow
+const retryFlow = effectPipe((input: User) =>
+    Retry(
+        Command(
+            async () => ({ id: 1, ...input }) as SavedUser,
+            (s) => Success(s)
+        ),
+        { attempts: 2 }
+    )
+);
+expectType<Effect<SavedUser>>(retryFlow({ email: 'a@b.com', password: 'secret123' }));
+
+// RetryExhaustedError shape is usable for narrowing exhaustion failures
+const exhaustedErr: RetryExhaustedError<Error> = {
+    retryExhausted: true,
+    lastError: new Error('boom'),
+    attempts: 3
+};
+expectType<true>(exhaustedErr.retryExhausted);
+expectType<Error>(exhaustedErr.lastError);
+expectType<number>(exhaustedErr.attempts);
+
+// --- error channel union across effectPipe steps ---
+
+type ValidationError = 'invalid_email' | 'weak_password';
+type DbError = 'db_connection' | 'duplicate_key';
+
+const validateStep = (_input: User): Effect<User, ValidationError> => Failure<ValidationError>('invalid_email');
+const saveStep = (_user: User): Effect<SavedUser, DbError> => Failure<DbError>('db_connection');
+
+const typedFlow = effectPipe(validateStep, saveStep);
+expectType<Effect<SavedUser, ValidationError | DbError>>(typedFlow({ email: 'a@b.com', password: 'secret123' }));
+
+const typedResult = await runEffect(typedFlow({ email: 'a@b.com', password: 'secret123' }));
+expectType<SuccessState<SavedUser> | FailureState<ValidationError | DbError>>(typedResult);
+
+// --- Parallel ---
+
+// Values tuple is correctly typed
+const par = Parallel([Success(42), Success('hello')], ([n, s]) => {
+    expectType<number>(n);
+    expectType<string>(s);
+    return Success({ n, s });
+});
+expectType<ParallelState<[number, string], { n: number; s: string }>>(par);
+
+// Parallel in effectPipe preserves type flow
+const parallelFlow = effectPipe((input: User) =>
+    Parallel([Success(input.email), Success(input.password)], ([email, password]) => Success({ email, password }))
+);
+expectType<Effect<{ email: string; password: string }>>(parallelFlow({ email: 'a@b.com', password: 'secret123' }));
+
+// runEffect return type flows through Parallel
+const parallelResult = await runEffect(Parallel([Success(1), Success('x')], ([n, s]) => Success({ n, s })));
+expectType<SuccessState<{ n: number; s: string }> | FailureState<unknown>>(parallelResult);
+
+// --- Ctx (context type) ---
+
+interface AppCtx {
+    db: string;
+}
+
+// Ask infers Ctx from callback parameter type
+const askWithCtx = Ask((ctx: AppCtx) => Success(ctx.db));
+expectType<AskState<string, unknown, AppCtx>>(askWithCtx);
+
+// effectPipe propagates Ctx through steps
+const ctxFlow = effectPipe((input: User) => Ask((ctx: AppCtx) => Success({ ...input, conn: ctx.db })));
+expectType<Effect<{ email: string; password: string; conn: string }, unknown, AppCtx>>(
+    ctxFlow({ email: 'a@b.com', password: 'secret123' })
+);
+
+// runEffect enforces context argument matches Ctx
+const ctxResult = await runEffect(ctxFlow({ email: 'a@b.com', password: 'secret123' }), { db: 'conn' });
+expectType<SuccessState<{ email: string; password: string; conn: string }> | FailureState<unknown>>(ctxResult);
+
+// wrong context shape should error
+expectError(runEffect(ctxFlow({ email: 'a@b.com', password: 'secret123' }), { wrong: 'thing' }));
+
+// --- configureEffect / EffectConfiguration ---
+
+// accepts full configuration
+configureEffect({
+    onStep: async (_name, _type, op) => op(),
+    onRun: async (_effect, op, _flowName) => op(),
+    onBeforeCommand: async (_cmd, _ctx) => {},
+    retry: { attempts: 3, delay: 100, backoff: 2 }
+});
+
+// accepts partial configuration
+configureEffect({ retry: { attempts: 5 } });
+configureEffect({});
+
+// rejects invalid shapes
+expectError(configureEffect({ onStep: 'not-a-function' }));
+expectError(configureEffect({ retry: { attempts: 'three' } }));
+
+// hook types are correctly shaped
+const myStep: StepRunner = async (name, type, op) => {
+    expectType<string>(name);
+    expectType<string>(type);
+    return op();
+};
+
+const myRun: RunWrapper = async (effect, op, flowName) => {
+    expectType<Effect<unknown>>(effect);
+    expectType<string | undefined>(flowName);
+    return op();
+};
+
+const myInterceptor: CommandInterceptor = async (cmd, _ctx) => {
+    expectType<CommandState<unknown, unknown>>(cmd);
+};
+
+// EffectConfiguration is a usable type
+const config: EffectConfiguration = { onStep: myStep, onRun: myRun, onBeforeCommand: myInterceptor };
+expectType<EffectConfiguration>(config);