pure-effect 0.11.0 → 0.13.0

package/index.d.ts

@@ -27,14 +27,19 @@ export type CommandState<R, T, E = unknown, Ctx = unknown> = {
      * `Parallel` no argument is passed at all.
      */
     cmd: (signal?: AbortSignal) => Promise<R> | R;
-    next: (result: R) => Effect<T, E, Ctx>;
+    /**
+     * Method syntax, not a function-typed property, on every state's `next`: `strictFunctionTypes`
+     * checks a property's parameter contravariantly, which made a `CommandState<never, ...>` (a `cmd`
+     * that only throws) unassignable to `Effect`. Method parameters are bivariant, so it is accepted.
+     */
+    next(result: R): Effect<T, E, Ctx>;
     meta?: CommandMeta;
     initialInput?: unknown;
 };
 
 export type AskState<T, E = unknown, Ctx = unknown> = {
     type: 'Ask';
-    next: (context: Ctx) => Effect<T, E, Ctx>;
+    next(context: Ctx): Effect<T, E, Ctx>;
     initialInput?: unknown;
 };
 
@@ -53,7 +58,7 @@ export type RetryState<T, E = unknown, Ctx = unknown> = {
     type: 'Retry';
     effect: Effect<T, any, Ctx>;
     options: RetryOptions & { onExhausted?: (error: RetryExhaustedError<any>) => Effect<T, any, Ctx> };
-    next: (value: T) => Effect<T, E, Ctx>;
+    next(value: T): Effect<T, E, Ctx>;
     initialInput?: unknown;
 };
 
@@ -66,7 +71,7 @@ export type RetryExhaustedError<E = unknown> = {
 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>;
+    next(values: [...T]): Effect<R, E, Ctx>;
     initialInput?: unknown;
 };
 
@@ -291,22 +296,26 @@ export interface EffectConfiguration {
 }
 
 /**
- * Configures the global runner. Several configurations can be passed and are merged, which is how
- * independent concerns share the one slot each hook has: `onStep` and `onRun` nest with the first
- * outermost, `onBeforeCommand` interceptors all run in order, and `retry` merges with later winning.
- * Merging does not accumulate across calls: a later call replaces the previous wiring, and calling
- * this with nothing resets every slot to its default.
- *
- * Returns a function that puts back whatever was installed when this call was made, so a caller can
- * install hooks without owning the global wiring forever. Restoring is a snapshot rather than a stack:
- * if a later call has run since, restoring reverts to the older snapshot and discards the newer one.
+ * Adds a layer to the global runner's wiring and returns a function that removes it. Layers merge:
+ * `onStep` and `onRun` nest with the earliest layer outermost, `onBeforeCommand` interceptors all run
+ * in the order installed, and `retry` merges with later layers winning. Several configurations passed
+ * to one call form one layer, which is the same as installing them in separate calls. Calling with no
+ * arguments at all removes every layer; a call whose arguments are all `undefined` adds and removes nothing.
  */
 export declare function configureEffect(...configs: (EffectConfiguration | undefined)[]): () => void;
 
+/**
+ * A per-call configuration for `runEffect`. With `inherit: true` (default) the call's hooks are added to
+ * the wiring `configureEffect` installed: where both define a hook the two nest, global outermost, and
+ * `retry` merges with the call winning. With `inherit: false` the global wiring is ignored, so unset
+ * slots fall back to the library defaults.
+ */
+export type CallConfiguration = EffectConfiguration & { inherit?: boolean };
+
 export declare function runEffect<T, E = unknown, Ctx = unknown>(
     effect: Effect<T, E, Ctx>,
     context?: Ctx,
-    callConfig?: EffectConfiguration
+    callConfig?: CallConfiguration
 ): Promise<SuccessState<T> | FailureState<E>>;
 
 export type ReplayStep = {
@@ -397,7 +406,10 @@ export interface ReplayOptions<Ctx = unknown> {
     context?: Ctx;
     /** Strip `Retry` delays so a replay does not wait out production backoff (default `true`). */
     fastRetry?: boolean;
-    /** Allow configured `onRun` / `onBeforeCommand` to fire (default `false`). */
+    /**
+     * Run the replay inside the global hooks, resolver innermost, so configured hooks observe it
+     * (default `false`, which ignores the global hooks). Global `retry` defaults apply either way.
+     */
     hooks?: boolean;
     /**
      * What to do when the Resolver has no recording for a step.
@@ -406,29 +418,45 @@ export interface ReplayOptions<Ctx = unknown> {
      */
     onMissing?: 'throw' | 'execute';
     onResolved?: (step: ReplayStep, outcome: ReplayOutcome | undefined) => void;
-    /**
-     * Legacy matching mode, used only for a trace whose entries carry no `path`. `true` (default)
-     * consumes entries positionally and raises a `TimeParadox` on divergence; `false` matches
-     * per-Command FIFO queues, which used to be required for flows containing `Parallel`. Ignored
-     * for a trace carrying paths, which is matched by path, and when a Resolver is supplied, since
-     * that Resolver has already chosen how it matches.
-     */
-    strict?: boolean;
+}
+
+/**
+ * What a replay returns: the flow's own outcome and, for a trace, the recorded entries the flow
+ * never asked for. A flow that stops issuing Commands early mismatches nothing, so `result` can be a
+ * `Success` with steps left over; `unreached` is where that shows. It is absent for a Resolver,
+ * since only a trace knows what it holds.
+ */
+export interface Replay<T, E = unknown> {
+    result: SuccessState<T> | FailureState<E>;
+    unreached: TraceEntry[];
 }
 
 /**
  * Pass a trace to replay it directly, or a Resolver when traces are stored in some other
  * shape. To observe a replay rather than change how it resolves, use `onResolved`.
  * A malformed trace rejects with a `ReplayError`.
+ *
+ * Three overloads: a trace yields `unreached`, a Resolver yields none, and a source only known
+ * as the union of the two (a wrapper forwarding whatever it was handed) yields it as optional.
  */
+export declare function replayEffect<T, E = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
+    trace: TraceLog | TraceEntry[],
+    options?: ReplayOptions<Ctx>
+): Promise<Replay<T, E>>;
+export declare function replayEffect<T, E = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
+    resolver: Resolver,
+    options?: ReplayOptions<Ctx>
+): Promise<Omit<Replay<T, E>, 'unreached'>>;
 export declare function replayEffect<T, E = unknown, Ctx = unknown>(
     effect: Effect<T, E, Ctx>,
     traceOrResolver: Resolver | TraceLog | TraceEntry[],
     options?: ReplayOptions<Ctx>
-): Promise<SuccessState<T> | FailureState<E>>;
+): Promise<Omit<Replay<T, E>, 'unreached'> & { unreached?: TraceEntry[] }>;
 
 export declare function timeTravel<T, E = unknown, Ctx = unknown>(
     flowFn: (input: any) => Effect<T, E, Ctx>,
     traceLog: TraceLog,
-    options?: { strict?: boolean; log?: (...args: any[]) => void; context?: Ctx; version?: string }
+    options?: { log?: (...args: any[]) => void; context?: Ctx; version?: string }
 ): Promise<SuccessState<T> | FailureState<E>>;