pure-effect 0.5.0 → 0.7.0

package/test/all.js

@@ -1,7 +1,7 @@
 // @ts-check
 
 import { strict as assert } from 'assert';
-import { Success, Failure, Command, effectPipe, runEffect, configureEffect } from '../index.js';
+import { Success, Failure, Command, Ask, Retry, effectPipe, runEffect, configureEffect } from '../index.js';
 import { enableTelemetry } from '../opentelemetry-example.js';
 
 /** @import { CommandInterceptor } from "../index.js" */
@@ -17,7 +17,7 @@ const db = {
         const u = { ...user, id: Date.now() };
         this.users.set(user.email, u);
         return u;
-    },
+    }
 };
 
 function validateRegistration(/** @type {User} */ input) {
@@ -81,13 +81,150 @@ 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 });
+        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 () {
+        /** @type {any} */
+        let capturedCtx;
+        const step = () =>
+            Ask((ctx) => {
+                capturedCtx = ctx;
+                return Success(null);
+            });
+        await runEffect(step(), { env: 'test' });
+        assert.equal(capturedCtx.env, 'test');
+    });
+
+    it('should work with Ask at any point in the pipeline', async function () {
+        const flow = effectPipe(
+            () =>
+                Command(
+                    () => 'value',
+                    (r) => Success(r)
+                ),
+            (value) => Ask((/** @type {any} */ ctx) => Success({ value, env: ctx.env }))
+        );
+        const result = await runEffect(flow(null), { env: 'test' });
+        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 Success after runEffect with telemetry disabled', async function () {

package/test/types.test-d.ts

@@ -1,9 +1,23 @@
 import { expectType, expectError } from 'tsd';
-import { Success, Failure, Command, effectPipe, runEffect } from '../index.js';
-import type { SuccessState, FailureState, CommandState, Effect } from '../index.js';
-
-interface User { email: string; password: string; }
-interface SavedUser { id: number; email: string; }
+import { Success, Failure, Command, Ask, Retry, effectPipe, runEffect } from '../index.js';
+import type {
+    SuccessState,
+    FailureState,
+    CommandState,
+    AskState,
+    RetryState,
+    RetryExhaustedError,
+    Effect
+} from '../index.js';
+
+interface User {
+    email: string;
+    password: string;
+}
+interface SavedUser {
+    id: number;
+    email: string;
+}
 
 // --- Success ---
 
@@ -19,15 +33,22 @@ expectType<FailureState<string>>(f);
 // --- Command ---
 
 const cmd = Command(
-    async () => ({ id: 1, email: 'a@b.com' } as SavedUser),
-    (saved) => { expectType<SavedUser>(saved); return Success(saved); }
+    async () => ({ id: 1, email: 'a@b.com' }) as SavedUser,
+    (saved) => {
+        expectType<SavedUser>(saved);
+        return Success(saved);
+    }
 );
 expectType<CommandState<SavedUser, SavedUser, unknown>>(cmd);
 
 // --- effectPipe type propagation ---
 
 const step1 = (input: User) => Success(input);
-const step2 = (user: User) => Command(async () => ({ id: 1, ...user } as SavedUser), (s) => Success(s));
+const step2 = (user: User) =>
+    Command(
+        async () => ({ id: 1, ...user }) as SavedUser,
+        (s) => Success(s)
+    );
 
 const flow = effectPipe(step1, step2);
 expectType<Effect<SavedUser>>(flow({ email: 'a@b.com', password: 'secret123' }));
@@ -51,3 +72,62 @@ if (result.type === 'Success') {
 const failFlow = effectPipe((input: User): Effect<User, string> => Failure<string>('bad'));
 const failResult = await runEffect(failFlow({ email: 'a@b.com', password: 'x' }));
 expectType<SuccessState<User> | FailureState<string>>(failResult);
+
+// --- Ask ---
+
+const ask = Ask((ctx) => Success(ctx as User));
+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);