pure-effect 0.16.0 → 0.18.0

package/examples/recording-example.js

@@ -3,7 +3,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { configureEffect, recorder, Failure } from 'pure-effect';
 
-/** @import { Effect, EffectConfiguration, RunWrapper, StepRunner, CommandInterceptor, TraceEntry, TraceLog, SuccessState, FailureState } from "pure-effect" */
+/** @import { EffectConfiguration, RunWrapper, StepRunner, CommandInterceptor, TraceEntry, TraceLog, SuccessState, FailureState } from "pure-effect" */
 
 /**
  * Records every run of an application without touching any call site, one trace per run. `recordEffect` covers
@@ -23,7 +23,8 @@ import { configureEffect, recorder, Failure } from 'pure-effect';
  *           database. Hand slow writes to a queue rather than awaiting them inside a request.
  * @property {(value: any, name: string, kind: string) => any} [redact] - Scrubs every value before it enters the
  *           trace: results, serialized errors, and the stored `initialInput` and `context`, told apart by `kind`.
- *           It receives a copy, so changing it in place never reaches the run.
+ *           It receives a copy, so changing it in place never reaches the run. A value it throws on is left out of
+ *           the trace, which marks where, as is one the recorder cannot copy.
  * @property {number} [maxEntries] - Caps trace length, 500 by default; the overflow is reported as `dropped`.
  * @property {boolean} [stack] - Records stack traces for thrown errors.
  * @property {(result: SuccessState<any> | FailureState<any>) => boolean} [keep] - Decides which runs reach the sink:
@@ -32,8 +33,8 @@ import { configureEffect, recorder, Failure } from 'pure-effect';
  * @property {(error: unknown, flowName?: string) => void} [onSinkError] - Receives an error thrown by `keep` or
  *           `sink`. Defaults to `console.error`.
  * @property {(message: string, flowName?: string) => void} [onWarning] - Receives a warning, once per flow, about a
- *           kept trace that will not replay as recorded: it has no input, `maxEntries` cut it short, or some of its
- *           steps are named 'anonymous'. Defaults to `console.warn`.
+ *           kept trace that will not replay as recorded: it has no input, `maxEntries` cut it short, some of its values
+ *           could not be recorded, or some of its steps are named 'anonymous'. Defaults to `console.warn`.
  */
 
 /**
@@ -60,10 +61,12 @@ export function recordingHooks(options = {}) {
     const warned = new Set();
 
     /** @type {RunWrapper} */
-    const onRun = async (effect, pipeline, flowName) => {
+    const onRun = async (effect, pipeline, flowName, initialInput) => {
         const rec = recorder({ redact, maxEntries, stack });
         // Packaged before the run, so a Command that changes its input cannot rewrite what the trace says it received.
-        const head = rec.toTrace({ flowName, initialInput: effect.initialInput });
+        // `toTrace` never throws, which matters here, where a throw would stop the run before it started: an input it
+        // cannot record is left out and named in the trace's `unrecorded`.
+        const head = rec.toTrace({ flowName, initialInput });
         return scope.run({ rec, head, contextCaptured: false }, async () => {
             /** @type {{ result: SuccessState<any> | FailureState<any> } | { error: unknown }} */
             let outcome;
@@ -78,7 +81,10 @@ export function recordingHooks(options = {}) {
             try {
                 if (keep(result)) {
                     const { dropped = 0, trace } = rec.toTrace();
-                    warnAboutReplay(flowName, effect, dropped, trace);
+                    const unrecorded =
+                        Object.keys(head.unrecorded ?? {}).length +
+                        trace.filter((e) => e.unrecorded !== undefined).length;
+                    warnAboutReplay(flowName, initialInput, dropped, trace, unrecorded);
                     await sink({ ...head, dropped, trace });
                 }
             } catch (error) {
@@ -92,17 +98,18 @@ export function recordingHooks(options = {}) {
     /**
      * Warns, once per flow, about a kept trace that will not replay as recorded.
      * @param {string} flowName
-     * @param {Effect<any, any, any>} effect
+     * @param {unknown} initialInput
      * @param {number} dropped
      * @param {TraceEntry[]} trace
+     * @param {number} unrecorded - How many values the trace leaves out because they could not be recorded
      */
-    const warnAboutReplay = (flowName, effect, dropped, trace) => {
+    const warnAboutReplay = (flowName, initialInput, dropped, trace, unrecorded) => {
         const warnOnce = (/** @type {string} */ kind, /** @type {string} */ message) => {
             if (warned.has(`${kind}:${flowName}`)) return;
             warned.add(`${kind}:${flowName}`);
             onWarning(`Recording '${flowName || 'flow'}': ${message}`, flowName);
         };
-        if (effect.initialInput === undefined) {
+        if (initialInput === undefined) {
             warnOnce(
                 'input',
                 'the flow carries no input, so its traces hold none and timeTravel rebuilds it from undefined. ' +
@@ -116,6 +123,14 @@ export function recordingHooks(options = {}) {
                     'the first step it lacks. Raise maxEntries for this flow to replay whole runs.'
             );
         }
+        if (unrecorded > 0) {
+            warnOnce(
+                'unrecorded',
+                `${unrecorded} of the values a kept trace holds could not be recorded, because redact threw on them or ` +
+                    'they could not be copied, so it replays only up to the first of them. Make redact handle every ' +
+                    "value it is given, null included, and keep Commands' results to plain data."
+            );
+        }
         const anonymous = trace.filter((entry) => entry.command === 'anonymous').length;
         if (anonymous > 0) {
             warnOnce(
@@ -146,14 +161,18 @@ export function recordingHooks(options = {}) {
 
     /**
      * `onRun` never sees the context, so it is copied from the run's first Command, before that Command can change
-     * it. A run that stops before any Command records none.
+     * it. A run that stops before any Command records none. `toTrace` never throws, which matters here, where a throw
+     * would veto the Command.
      * @type {CommandInterceptor}
      */
     const onBeforeCommand = async (command, context) => {
         const store = scope.getStore();
         if (!store || store.contextCaptured) return;
         store.contextCaptured = true;
-        store.head.context = store.rec.toTrace({ context }).context;
+        const withContext = store.rec.toTrace({ context });
+        store.head.context = withContext.context;
+        // A context it could not record is left out, and the trace the run started with has to say so too.
+        if (withContext.unrecorded) store.head.unrecorded = { ...store.head.unrecorded, ...withContext.unrecorded };
     };
 
     return { onRun, onStep, onBeforeCommand };

package/index.d.ts

@@ -1,13 +1,11 @@
 export type SuccessState<T> = {
     type: 'Success';
     value: T;
-    initialInput?: unknown;
 };
 
 export type FailureState<E = unknown> = {
     type: 'Failure';
     error: E;
-    initialInput?: unknown;
 };
 
 /**
@@ -27,22 +25,21 @@ export type CommandState<R, T, E = unknown, Ctx = unknown> = {
     /** Receives `cmd`'s result and returns the next step. */
     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>;
-    initialInput?: unknown;
 };
 
+// Every optional option and hook takes `undefined`, which keeps its default, under `exactOptionalPropertyTypes` too.
 export type RetryOptions = {
     /** Tries after the first, so `2` makes at most 3 calls. A positive integer, 3 by default. */
-    attempts?: number;
+    attempts?: number | undefined;
     /** Milliseconds before the first retry, 100 by default. */
-    delay?: number;
+    delay?: number | undefined;
     /** Multiplies the wait before each later retry, so `2` doubles it. 1 by default, the same wait each time. */
-    backoff?: number;
+    backoff?: number | undefined;
 };
 
 /**
@@ -52,9 +49,9 @@ export type RetryOptions = {
 export type RetryState<T, E = unknown, Ctx = unknown, R = T> = {
     type: 'Retry';
     effect: Effect<R, any, Ctx>;
-    options: RetryOptions & { onExhausted?: (error: RetryExhaustedError) => Effect<R, any, Ctx> };
+    /** A frozen copy of the options the `Retry` was built with. */
+    options: Readonly<RetryOptions & { onExhausted?: (error: RetryExhaustedError) => Effect<R, any, Ctx> }>;
     next(value: R): Effect<T, E, Ctx>;
-    initialInput?: unknown;
 };
 
 /** The error a `Retry` fails with once every attempt has thrown. `lastError` is what the last attempt threw. */
@@ -67,9 +64,9 @@ export type RetryExhaustedError<Thrown = unknown> = {
 
 export type ParallelOptions = {
     /** Most branches in flight at once. Results and paths stay in array order regardless. */
-    limit?: number;
+    limit?: number | undefined;
     /** Hand every branch's outcome to `next` instead of failing on the first one. */
-    settled?: boolean;
+    settled?: boolean | undefined;
 };
 
 /** `V` is what `next` receives: the branch values, or their outcomes under `settled`. `BranchError` types `effects`. */
@@ -84,8 +81,8 @@ export type ParallelState<
     type: 'Parallel';
     effects: { [K in keyof T]: Effect<T[K], BranchError, Ctx> };
     next(values: [...V]): Effect<R, E, Ctx>;
-    options?: ParallelOptions;
-    initialInput?: unknown;
+    /** A frozen copy of the options the `Parallel` was built with. */
+    options?: Readonly<ParallelOptions>;
 };
 
 export type Effect<T, E = unknown, Ctx = unknown> =
@@ -161,11 +158,14 @@ export type ParallelContext<B extends readonly unknown[]> = {
     ? Ctx
     : unknown;
 
-/** Wraps a value for the next step. */
+/**
+ * Wraps a value for the next step. A string in an object widens to `string`, as in any object literal; write
+ * `Success<T>(...)` where a later step tells values apart by it.
+ */
 export declare function Success<T>(value: T): SuccessState<T>;
 
 /** Stops the pipeline with `error`. A literal keeps its exact type, and an object or array error is readonly. */
-export declare function Failure<const E = unknown>(error: E, initialInput?: unknown): FailureState<E>;
+export declare function Failure<const E = unknown>(error: E): FailureState<E>;
 
 /**
  * Defers a side effect: `cmd` makes the call and `next` decides what follows; without `next` the result passes through.
@@ -217,7 +217,7 @@ export declare function Retry<T, E = never, Ctx = unknown>(
     options?: RetryOptions
 ): RetryState<T, E | RetryExhaustedError, Ctx>;
 
-// `settled?: false` keeps a `settled` known only as boolean from matching; `| []` infers tuples on TypeScript 5.1.
+// `settled?: false | undefined` keeps a `settled` typed boolean from matching; `| []` infers tuples on TypeScript 5.1.
 /**
  * Runs the branches at the same time and hands `next` their values in order. The first to fail cancels the rest, unless
  * `settled`, which hands `next` every outcome.
@@ -249,13 +249,13 @@ export declare function Parallel<B extends readonly unknown[] | [], N extends An
 
 export declare function Parallel<B extends readonly unknown[] | []>(
     effects: ParallelBranches<B>,
-    options?: ParallelOptions & { settled?: false }
+    options?: ParallelOptions & { settled?: false | undefined }
 ): ParallelState<ParallelValues<B>, ParallelValues<B>, EffectError<B[number]>, ParallelContext<B>>;
 
 export declare function Parallel<B extends readonly unknown[] | [], N extends AnyEffect = never>(
     effects: ParallelBranches<B>,
     next: (values: ParallelValues<B>) => N,
-    options?: ParallelOptions & { settled?: false }
+    options?: ParallelOptions & { settled?: false | undefined }
 ): ParallelState<
     ParallelValues<B>,
     EffectValue<N>,
@@ -1255,14 +1255,23 @@ export type StepRunner = (
     path: string
 ) => Promise<unknown>;
 
-/** Which branch, if any, cancelled a `Parallel`; `branch: null` means an enclosing one did. */
-export type ParallelDecision = { cancelled: false } | { cancelled: true; branch: number | null };
+/**
+ * Which branch, if any, cancelled a `Parallel`, and how many branches it had; `branch: null` means an enclosing one
+ * did. A replay refuses a `Parallel` whose count differs, and a decision without one is not checked.
+ */
+export type ParallelDecision =
+    | { cancelled: false; branches?: number | undefined }
+    | { cancelled: true; branch: number | null; branches?: number | undefined };
 
-/** `flowName` is `context.flowName`, or `''` when the context has none; the interpreter always passes it. */
+/**
+ * `flowName` is `context.flowName`, or `''` when the context has none. `initialInput` is what the flow was called with
+ * when `effectPipe` built it, and `undefined` otherwise. A hook that calls another passes both on.
+ */
 export type RunWrapper = (
     effect: Effect<unknown>,
     op: () => Promise<SuccessState<unknown> | FailureState<unknown>>,
-    flowName: string
+    flowName: string,
+    initialInput: unknown
 ) => Promise<SuccessState<unknown> | FailureState<unknown>>;
 
 // A union, so a JSDoc `@type` on an async function fits it too.
@@ -1272,26 +1281,34 @@ export type CommandInterceptor =
     | ((command: CommandState<unknown, unknown>, context?: any) => void);
 
 export interface EffectConfiguration {
-    onStep?: StepRunner;
-    onRun?: RunWrapper;
-    onBeforeCommand?: CommandInterceptor;
+    onStep?: StepRunner | undefined;
+    onRun?: RunWrapper | undefined;
+    onBeforeCommand?: CommandInterceptor | undefined;
 }
 
 /** Adds a layer of hooks and returns a function that removes it. With no arguments, removes every layer. */
 export declare function configureEffect(...configs: (EffectConfiguration | undefined)[]): () => void;
 
 /** Hooks for one `runEffect` call, inside the installed ones; `inherit: false` leaves those out. */
-export type CallConfiguration = EffectConfiguration & { inherit?: boolean };
+export type CallConfiguration = EffectConfiguration & { inherit?: boolean | undefined };
 
 /** The context a run is given: what the flow reads, and a `flowName` naming the run in traces and spans. */
-export type RunContext<Ctx> = unknown extends Ctx ? Ctx : Ctx extends object ? Ctx & { flowName?: string } : Ctx;
+export type RunContext<Ctx> = unknown extends Ctx
+    ? Ctx
+    : Ctx extends object
+      ? Ctx & { flowName?: string | undefined }
+      : Ctx;
+
+// TypeScript 5.1's stand-in for NoInfer: it defers this indexed access, so it infers nothing from it.
+/** A context checked against the one the flow reads, and never inferred from. */
+type CheckedContext<T> = [T][T extends any ? 0 : never];
 
 /** Runs a flow and returns its `Success` or `Failure`. A flow that reads a context requires one. */
 export declare function runEffect<T, E = unknown, Ctx = unknown>(
     effect: Effect<T, E, Ctx>,
     ...args: unknown extends Ctx
-        ? [context?: Ctx, callConfig?: CallConfiguration]
-        : [context: RunContext<Ctx>, callConfig?: CallConfiguration]
+        ? [context?: CheckedContext<Ctx>, callConfig?: CallConfiguration]
+        : [context: RunContext<CheckedContext<Ctx>>, callConfig?: CallConfiguration]
 ): Promise<SuccessState<T> | FailureState<E>>;
 
 export type ReplayStep = {
@@ -1311,6 +1328,7 @@ export type ReplayStep = {
  */
 export type ReplayOutcome = { result: unknown } | { error: unknown };
 
+/** Answers a step from a recording. Any other answer than an outcome or `undefined`, or a throw, rejects the replay. */
 export type Resolver = (step: ReplayStep) => ReplayOutcome | undefined;
 
 /** One recorded step: a Command's result or error, or a `Parallel`'s decision. */
@@ -1322,6 +1340,8 @@ export type TraceEntry = {
     /** Marks a step that threw; `false` is the same as leaving it out. */
     threw?: boolean;
     error?: unknown;
+    /** Why the entry holds no value: `'redact'` threw on it, or copying it threw (`'copy'`). A replay stops there. */
+    unrecorded?: string;
     /** How long the Command took in production, rounded to microseconds. */
     durationMs?: number;
 };
@@ -1332,6 +1352,8 @@ export type TraceLog<I = unknown, C = unknown> = {
     version?: string;
     initialInput?: I;
     context?: C;
+    /** Why the trace holds no `initialInput` or `context`, as an entry's `unrecorded` says it for a step. */
+    unrecorded?: { initialInput?: string; context?: string };
     dropped?: number;
     trace: TraceEntry[];
 };
@@ -1340,17 +1362,17 @@ export interface RecorderOptions {
     /**
      * Scrubs each value before it enters a trace; `kind` says which. It gets a copy, so editing it in place is safe.
      */
-    redact?: (value: any, name: string, kind: 'result' | 'error' | 'initialInput' | 'context') => unknown;
+    redact?: ((value: any, name: string, kind: 'result' | 'error' | 'initialInput' | 'context') => unknown) | undefined;
     /** Cap trace length; further steps are counted in `dropped`, not stored. */
-    maxEntries?: number;
+    maxEntries?: number | undefined;
     /** Record stack traces for thrown errors. Off by default. */
-    stack?: boolean;
+    stack?: boolean | undefined;
 }
 
 /** The trace's own fields, as `toTrace` takes them; the returned trace keeps the input's and context's types. */
 export interface TraceMeta<I = unknown, C = unknown> {
     initialInput?: I;
-    flowName?: string;
+    flowName?: string | undefined;
     context?: C;
     /** Accepts `undefined`, so `process.env.BUILD_ID` passes under `exactOptionalPropertyTypes`. */
     version?: string | undefined;
@@ -1365,32 +1387,35 @@ export declare function recorder(options?: RecorderOptions): {
 
 /** `recordEffect`'s options: recorder options, plus the context the run gets and a build id. */
 export type RecordOptions<Ctx = unknown> = RecorderOptions & {
-    context?: RunContext<Ctx>;
+    context?: RunContext<Ctx> | undefined;
     version?: string | undefined;
 };
 
-/** Runs a flow for real and returns its outcome with a trace, which keeps the input's type for the replay. */
+/**
+ * Runs a flow for real and returns its outcome with a trace, which keeps the input's type for the replay. That type is
+ * wrong when `redact` changes the input, or the trace marks it `unrecorded`.
+ */
 export declare function recordEffect<I, T, E = unknown, Ctx = unknown>(
     flowFn: (input: I) => Effect<T, E, Ctx>,
     initialInput: I,
     ...options: unknown extends Ctx
-        ? [options?: RecordOptions<Ctx>]
-        : [options: RecordOptions<Ctx> & { context: RunContext<Ctx> }]
+        ? [options?: RecordOptions<CheckedContext<Ctx>>]
+        : [options: RecordOptions<CheckedContext<Ctx>> & { context: RunContext<CheckedContext<Ctx>> }]
 ): Promise<{ result: SuccessState<T> | FailureState<E>; trace: TraceLog<I, Ctx> & { initialInput: I } }>;
 
 export interface ReplayOptions<Ctx = unknown> {
     /** Context for `Ask`; defaults to the one the trace recorded. */
-    context?: RunContext<Ctx>;
+    context?: RunContext<Ctx> | undefined;
     /** Strip `Retry` delays so a replay does not wait out production backoff (default `true`). */
-    fastRetry?: boolean;
+    fastRetry?: boolean | undefined;
     /** Runs the replay inside the installed hooks, so they see it. Off by default. */
-    hooks?: boolean;
+    hooks?: boolean | undefined;
     /**
      * `'throw'` (default) fails on a step the trace lacks. `'execute'` runs it for real: use it only against test
      * doubles.
      */
-    onMissing?: 'throw' | 'execute';
-    onResolved?: (step: ReplayStep, outcome: ReplayOutcome | undefined) => void;
+    onMissing?: 'throw' | 'execute' | undefined;
+    onResolved?: ((step: ReplayStep, outcome: ReplayOutcome | undefined) => void) | undefined;
 }
 
 /** The replay's outcome and, for a trace, the recorded steps the flow never asked for. */
@@ -1399,26 +1424,37 @@ export interface Replay<T, E = unknown> {
     unreached: TraceEntry[];
 }
 
-/** Replays a flow from a trace, or from a Resolver for other storage, with no I/O. */
+/**
+ * Replays a flow from a trace, or from a Resolver for other storage, with no I/O. A Resolver holds no context, so a
+ * flow that reads one needs `context` passed.
+ */
 export declare function replayEffect<T, E = unknown, Ctx = unknown>(
     effect: Effect<T, E, Ctx>,
     trace: TraceLog | TraceEntry[],
-    options?: ReplayOptions<Ctx>
+    options?: ReplayOptions<CheckedContext<Ctx>>
 ): Promise<Replay<T, E>>;
 export declare function replayEffect<T, E = unknown, Ctx = unknown>(
     effect: Effect<T, E, Ctx>,
     resolver: Resolver,
-    options?: ReplayOptions<Ctx>
+    ...options: unknown extends Ctx
+        ? [options?: ReplayOptions<CheckedContext<Ctx>>]
+        : [options: ReplayOptions<CheckedContext<Ctx>> & { context: RunContext<CheckedContext<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>
+    ...options: unknown extends Ctx
+        ? [options?: ReplayOptions<CheckedContext<Ctx>>]
+        : [options: ReplayOptions<CheckedContext<Ctx>> & { context: RunContext<CheckedContext<Ctx>> }]
 ): Promise<Omit<Replay<T, E>, 'unreached'> & { unreached?: TraceEntry[] }>;
 
 /** Replays a trace and logs each step with its recorded timing, warning about what will not replay as recorded. */
 export declare function timeTravel<T, E = unknown, Ctx = unknown>(
     flowFn: (input: any) => Effect<T, E, Ctx>,
     traceLog: TraceLog,
-    options?: { log?: (...args: any[]) => void; context?: RunContext<Ctx>; version?: string | undefined }
+    options?: {
+        log?: ((...args: any[]) => void) | undefined;
+        context?: RunContext<CheckedContext<Ctx>> | undefined;
+        version?: string | undefined;
+    }
 ): Promise<SuccessState<T> | FailureState<E>>;