pure-effect 0.10.0 → 0.12.0

package/test/types.test-d.ts

@@ -1,5 +1,16 @@
-import { expectType, expectError } from 'tsd';
-import { Success, Failure, Command, Ask, Retry, Parallel, effectPipe, runEffect, configureEffect } from '../index.js';
+import { expectType, expectAssignable } from 'tsd';
+import {
+    Success,
+    Failure,
+    Command,
+    Ask,
+    Retry,
+    Parallel,
+    effectPipe,
+    runEffect,
+    configureEffect,
+    replayEffect
+} from '../index.js';
 import type {
     SuccessState,
     FailureState,
@@ -12,7 +23,12 @@ import type {
     EffectConfiguration,
     StepRunner,
     RunWrapper,
-    CommandInterceptor
+    CommandInterceptor,
+    TraceEntry,
+    TraceLog,
+    Resolver,
+    ReplayOptions,
+    Replay
 } from '../index.js';
 
 interface User {
@@ -28,7 +44,8 @@ interface SavedUser {
 
 const s = Success(42);
 expectType<SuccessState<number>>(s);
-expectError(Success()); // missing argument
+// @ts-expect-error missing argument
+Success();
 
 // --- Failure ---
 
@@ -46,7 +63,8 @@ expectType<CommandState<number, string>>(
     )
 );
 Command(() => 42, undefined, { name: 'readRow' });
-expectError(Command());
+// @ts-expect-error missing cmd
+Command();
 
 const cmd = Command(
     async () => ({ id: 1, email: 'a@b.com' }) as SavedUser,
@@ -57,6 +75,18 @@ const cmd = Command(
 );
 expectType<CommandState<SavedUser, SavedUser, unknown>>(cmd);
 
+// A cmd that only throws, or returns Promise.reject, infers R as never. That has to stay assignable
+// to Effect under strictFunctionTypes, which is why every state's `next` is a method signature
+// (bivariant parameter) rather than a function-typed property (contravariant, so `never` could not
+// widen to the `any` in `Effect`'s CommandState member).
+const throwing = Command(() => {
+    throw new Error('boom');
+});
+expectAssignable<Effect<never>>(throwing);
+expectAssignable<Effect<never>>(Command(() => Promise.reject(new Error('down'))));
+expectAssignable<Effect<never>>(Retry(throwing));
+expectAssignable<Effect<never>>(effectPipe(() => throwing)(null));
+
 // --- effectPipe type propagation ---
 
 const step1 = (input: User) => Success(input);
@@ -68,7 +98,8 @@ const step2 = (user: User) =>
 
 const flow = effectPipe(step1, step2);
 expectType<Effect<SavedUser>>(flow({ email: 'a@b.com', password: 'secret123' }));
-expectError(flow({ email: 'a@b.com' })); // missing password
+// @ts-expect-error missing password
+flow({ email: 'a@b.com' });
 
 // --- runEffect return type ---
 
@@ -104,13 +135,14 @@ const innerCmd = Command(
     (n) => Success(n)
 );
 
-// Retry with options preserves T
+// Retry with options preserves T; the error type is the exhaustion failure, not the inner error,
+// because the interpreter wraps the last inner error rather than letting it escape
 const retried = Retry(innerCmd, { attempts: 3 });
-expectType<RetryState<number, unknown>>(retried);
+expectType<RetryState<number, RetryExhaustedError<unknown>>>(retried);
 
 // Retry without options is valid
 const retriedNoOpts = Retry(innerCmd);
-expectType<RetryState<number, unknown>>(retriedNoOpts);
+expectType<RetryState<number, RetryExhaustedError<unknown>>>(retriedNoOpts);
 
 // Retry in effectPipe preserves type flow
 const retryFlow = effectPipe((input: User) =>
@@ -122,7 +154,36 @@ const retryFlow = effectPipe((input: User) =>
         { attempts: 2 }
     )
 );
-expectType<Effect<SavedUser>>(retryFlow({ email: 'a@b.com', password: 'secret123' }));
+expectType<Effect<SavedUser, RetryExhaustedError<unknown>>>(retryFlow({ email: 'a@b.com', password: 'secret123' }));
+
+// The inner error type survives inside the exhaustion failure, so lastError is typed
+const retriedTyped = Retry(Success(1) as Effect<number, 'net_down'>);
+expectType<RetryState<number, RetryExhaustedError<'net_down'>>>(retriedTyped);
+
+const retryResult = await runEffect(Retry(Success(1) as Effect<number, 'flaky'>, { attempts: 1 }));
+if (retryResult.type === 'Failure') {
+    expectType<RetryExhaustedError<'flaky'>>(retryResult.error);
+    expectType<'flaky'>(retryResult.error.lastError);
+}
+
+// onExhausted consumes the exhaustion, so the fallback's error type is what remains
+const recovered = Retry(Success(1) as Effect<number, 'flaky'>, {
+    attempts: 1,
+    onExhausted: (err) => {
+        expectType<RetryExhaustedError<'flaky'>>(err);
+        return Success(0) as Effect<number, 'cache_miss'>;
+    }
+});
+expectType<RetryState<number, 'cache_miss'>>(recovered);
+
+const recoveredResult = await runEffect(recovered);
+if (recoveredResult.type === 'Failure') {
+    expectType<'cache_miss'>(recoveredResult.error);
+}
+
+// onExhausted is per-use only: global retry defaults cannot carry a fallback
+// @ts-expect-error onExhausted is not a global retry default
+configureEffect({ retry: { attempts: 2, onExhausted: () => Success(1) } });
 
 // RetryExhaustedError shape is usable for narrowing exhaustion failures
 const exhaustedErr: RetryExhaustedError<Error> = {
@@ -168,6 +229,14 @@ expectType<Effect<{ email: string; password: string }>>(parallelFlow({ email: 'a
 const parallelResult = await runEffect(Parallel([Success(1), Success('x')], ([n, s]) => Success({ n, s })));
 expectType<SuccessState<{ n: number; s: string }> | FailureState<unknown>>(parallelResult);
 
+// With next omitted, the Parallel resolves to the values tuple itself
+const parBare = Parallel([Success(42), Success('hello')]);
+expectType<ParallelState<[number, string], [number, string]>>(parBare);
+const parBareResult = await runEffect(parBare);
+if (parBareResult.type === 'Success') {
+    expectType<[number, string]>(parBareResult.value);
+}
+
 // --- Ctx (context type) ---
 
 interface AppCtx {
@@ -189,7 +258,8 @@ const ctxResult = await runEffect(ctxFlow({ email: 'a@b.com', password: 'secret1
 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' }));
+// @ts-expect-error context does not match Ctx
+runEffect(ctxFlow({ email: 'a@b.com', password: 'secret123' }), { wrong: 'thing' });
 
 // --- configureEffect / EffectConfiguration ---
 
@@ -206,8 +276,10 @@ configureEffect({ retry: { attempts: 5 } });
 configureEffect({});
 
 // rejects invalid shapes
-expectError(configureEffect({ onStep: 'not-a-function' }));
-expectError(configureEffect({ retry: { attempts: 'three' } }));
+// @ts-expect-error onStep must be a function
+configureEffect({ onStep: 'not-a-function' });
+// @ts-expect-error attempts must be a number
+configureEffect({ retry: { attempts: 'three' } });
 
 // hook types are correctly shaped
 const myStep: StepRunner = async (name, type, op) => {
@@ -229,3 +301,35 @@ const myInterceptor: CommandInterceptor = async (cmd, _ctx) => {
 // EffectConfiguration is a usable type
 const config: EffectConfiguration = { onStep: myStep, onRun: myRun, onBeforeCommand: myInterceptor };
 expectType<EffectConfiguration>(config);
+
+// replayEffect returns the flow's outcome beside the unreached entries for a trace, and no unreached for a Resolver
+const traceLog: TraceLog = { trace: [{ command: 'cmdRead', path: '0', result: 1 }] };
+const readRow = Command(() => 42);
+const replayOptions: ReplayOptions = {
+    onResolved: (step, outcome) => {
+        expectType<string>(step.name);
+        expectType<number>(step.index);
+    }
+};
+expectType<Promise<Replay<number, unknown>>>(replayEffect(readRow, traceLog, replayOptions));
+expectType<Promise<Replay<number, unknown>>>(replayEffect(readRow, traceLog.trace));
+(async () => {
+    const { result, unreached } = await replayEffect(readRow, traceLog);
+    expectType<SuccessState<number> | FailureState<unknown>>(result);
+    expectType<TraceEntry[]>(unreached);
+    const fromResolver = await replayEffect(readRow, () => ({ result: 42 }));
+    expectType<SuccessState<number> | FailureState<unknown>>(fromResolver.result);
+    // @ts-expect-error a Resolver cannot know what was left unreached
+    fromResolver.unreached;
+})();
+// A source typed as the union (a wrapper forwarding whatever it was handed) still type-checks, with unreached optional
+declare const traceOrResolver: TraceLog | TraceEntry[] | Resolver;
+(async () => {
+    const forwarded = await replayEffect(readRow, traceOrResolver);
+    expectType<SuccessState<number> | FailureState<unknown>>(forwarded.result);
+    expectType<TraceEntry[] | undefined>(forwarded.unreached);
+})();
+// @ts-expect-error strict was removed: paths make it unnecessary
+replayEffect(readRow, traceLog, { strict: false });
+// @ts-expect-error unreached is returned, not observed
+replayEffect(readRow, traceLog, { onUnreached: () => {} });

package/.claude/settings.local.json

@@ -1,17 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm test *)",
-      "Bash(npm view *)",
-      "Bash(npx mocha *)",
-      "Bash(echo \"exit: $?\")",
-      "Bash(npx prettier *)",
-      "Bash(echo \"npm test exit: $?\")",
-      "Bash(npx tsc *)",
-      "Bash(echo \"tsc exit: $?\")",
-      "Read(//tmp/**)",
-      "Bash(npx esbuild *)",
-      "Bash(gzip -9)"
-    ]
-  }
-}