pure-effect 0.19.0 → 0.20.1

package/RULES.md

@@ -0,0 +1,43 @@
+# Rules for Writing a Pure Effect Flow
+
+<!-- Generated by scripts/rules-file.js from README.md: edit those, then run npm run generate. -->
+
+The rules for writing a correct flow, and where the README covers each task.
+
+## Rules
+
+1. **Put every call that does I/O inside a Command, and keep its function to that one call:** `Command(() => db.findUser(email))`, never `step(db.findUser(email))`. Tests never run the function, so anything else in it goes untested. See [Testing Without Mocks](README.md#testing-without-mocks).
+2. **Name every Command,** with a named function such as `const cmdFindUser = () => ...`, or with `meta.name`. Traces, replay and telemetry use the name, and a minifier can strip a function's name. See [`Command`](README.md#commandcmdfn-nextfn-meta).
+3. **Put each decision in a step function** that receives one value and returns `Success`, `Failure` or the next Command, so a test can call it directly. See [Coming from async/await](README.md#coming-from-asyncawait).
+4. **Return an outcome the caller should see as `Failure(error)`; never throw it.** A `Failure` stops the flow, is never retried, and only the code that calls `runEffect` acts on it. See [Which Errors Are Data](README.md#which-errors-are-data).
+5. **A `catch` in a generator flow cannot recover.** It can log and rethrow, and it sees a `FlowStopped` error saying where the flow stopped, not the original. To handle an error, catch it inside the Command's function and return it as data. See [How a generator flow stops](README.md#how-a-generator-flow-stops).
+6. **Let a Command's function throw only when `Retry` should try again.** An error it catches and returns is data, and `Retry` never sees it. To retry some errors and not others, rethrow the first kind and return the second. A throw also skips any undo the Command's `next` would have run. See [Which Errors Are Data](README.md#which-errors-are-data).
+7. **Wrap only the Command that fails in `Retry`, and continue in a later step.** `Retry` runs everything it wraps again, the Command's `next` included. `retries: 2` means up to three calls, and `onExhausted` is where you give up. See [Retrying Transient Failures](README.md#retrying-transient-failures).
+8. **Write a loop as a step that gets the list, then `Parallel(list.map(f), { limit: 1 })`.** `limit` caps how many run at once, and `settled: true` keeps going past a failure. A generator flow can use a `for` loop with `yield*`. See [Writing Loops](README.md#writing-loops).
+9. **Get the time, random IDs and anything else that changes between runs from a Command.** A replay then gets the recorded value, and a generator body, which can run more than once, sees the same value each time. See [What runs once, and what runs again](README.md#what-runs-once-and-what-runs-again).
+10. **Return plain data from Commands, and keep the context to plain values.** A trace stores JSON, so a `Date` comes back as a string. Reach a service from the Command's function, and hand it to the function that builds the flow. See [Passing Runtime Context](README.md#passing-runtime-context).
+11. **Clean up in a `try`/`finally` around `runEffect`,** not inside the flow. See [How a generator flow stops](README.md#how-a-generator-flow-stops).
+12. **Check a replay's error, not only its type.** A replay of a flow that changed shape ends in a `Failure` holding a `TimeParadox`, the error naming where the flow and the trace part ways, so a test that only expects a `Failure` passes by accident. See [Time-Travel Debugging](README.md#time-travel-debugging).
+
+## Find It by Task
+
+- Test a decision or a branch without mocks: [Testing Without Mocks](README.md#testing-without-mocks)
+- Run a whole flow in a test, a retry that fails and then succeeds included: [Testing a whole flow](README.md#testing-a-whole-flow)
+- Write a flow that reads like `async` code: [Writing Flows as Generators](README.md#writing-flows-as-generators)
+- Port an `async` function, `try`/`catch` included: [Coming from async/await](README.md#coming-from-asyncawait), [Translating `try`/`catch`](README.md#translating-trycatch)
+- Read request values such as a tenant or a request ID: [Passing Runtime Context](README.md#passing-runtime-context)
+- Run a flow against fakes or a test database: [Passing Runtime Context](README.md#passing-runtime-context)
+- Retry a flaky call, or only some of its errors: [Retrying Transient Failures](README.md#retrying-transient-failures), [Which Errors Are Data](README.md#which-errors-are-data)
+- Wait as long as a server asks before trying again: [Waiting as long as the server asks](README.md#waiting-as-long-as-the-server-asks)
+- Run steps at the same time, with a limit: [Running Effects in Parallel](README.md#running-effects-in-parallel)
+- Undo what succeeded when a branch fails: [Undoing what succeeded when a branch fails](README.md#undoing-what-succeeded-when-a-branch-fails)
+- Loop over a list: [Writing Loops](README.md#writing-loops)
+- End a flow early with a result that isn't an error: [Ending a flow early without an error](README.md#ending-a-flow-early-without-an-error)
+- Record every run in production: [Recording in Production](README.md#recording-in-production)
+- Keep secrets out of a trace: [Keeping secrets out of a trace](README.md#keeping-secrets-out-of-a-trace)
+- Turn a production incident into a test: [Time-Travel Debugging](README.md#time-travel-debugging)
+- Prove a fix with a recorded trace: [Proving a fix that changes the flow's shape](README.md#proving-a-fix-that-changes-the-flows-shape)
+- Add telemetry: [Hooks](README.md#hooks)
+- Type a flow's errors and context: [TypeScript: Typed Errors and Context](README.md#typescript-typed-errors-and-context)
+- Handle every error a flow can end with, in TypeScript: [Handling every error](README.md#handling-every-error)
+- Test a flow in TypeScript: [Testing a flow in TypeScript](README.md#testing-a-flow-in-typescript)

package/examples/recording-example.js

@@ -3,7 +3,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { configureEffect, recorder, Failure } from 'pure-effect';
 
-/** @import { EffectConfiguration, RunWrapper, StepRunner, CommandInterceptor, TraceEntry, TraceLog, SuccessState, FailureState } from "pure-effect" */
+/** @import { EffectConfiguration, RunWrapper, StepRunner, CommandInterceptor, TraceEntry, TraceLog, SuccessState, FailureState, RecorderOptions } from "pure-effect" */
 
 /**
  * Records every run of an application without touching any call site, one trace per run. `recordEffect` covers
@@ -21,12 +21,14 @@ import { configureEffect, recorder, Failure } from 'pure-effect';
  * @typedef {Object} RecordingOptions
  * @property {(trace: TraceLog) => Promise<void> | void} [sink] - Receives each kept trace, to write to S3 or a
  *           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
+ * @property {RecorderOptions['redact']} [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. 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 {string | undefined} [version] - Commit or build id, attached to each trace, so `timeTravel` can warn
+ *           when it replays a trace against another build.
  * @property {(result: SuccessState<any> | FailureState<any>) => boolean} [keep] - Decides which runs reach the sink:
  *           failures only by default. Return `true` to keep everything, or sample. A run whose own code threw is
  *           offered as a Failure carrying the thrown error.
@@ -50,6 +52,7 @@ export function recordingHooks(options = {}) {
         redact,
         maxEntries = 500,
         stack,
+        version,
         keep = (result) => result.type === 'Failure',
         onSinkError = (error, flowName) => console.error(`Recording failed for '${flowName || 'flow'}':`, error),
         onWarning = (message) => console.warn(message)
@@ -66,7 +69,7 @@ export function recordingHooks(options = {}) {
         // Packaged before the run, so a Command that changes its input cannot rewrite what the trace says it received.
         // `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 });
+        const head = rec.toTrace({ flowName, initialInput, version });
         return scope.run({ rec, head, contextCaptured: false }, async () => {
             /** @type {{ result: SuccessState<any> | FailureState<any> } | { error: unknown }} */
             let outcome;

package/index.d.ts

@@ -1,3 +1,5 @@
+// Rules for writing a correct flow, and a task index: RULES.md in this package.
+
 export type SuccessState<T> = {
     type: 'Success';
     value: T;
@@ -35,7 +37,7 @@ export type AskState<T, E = unknown, Ctx = 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 | undefined;
+    retries?: number | undefined;
     /** Milliseconds before the first retry, 100 by default. */
     delay?: number | undefined;
     /** Multiplies the wait before each later retry, so `2` doubles it. 1 by default, the same wait each time. */
@@ -58,8 +60,8 @@ export type RetryState<T, E = unknown, Ctx = unknown, R = T> = {
 export type RetryExhaustedError<Thrown = unknown> = {
     retryExhausted: true;
     lastError: Thrown;
-    /** The `attempts` option: tries after the first, so the retried steps ran one more time than this. */
-    attempts: number;
+    /** The `retries` option, so the retried steps ran one more time than this. */
+    retries: number;
 };
 
 export type ParallelOptions = {
@@ -82,7 +84,7 @@ export type ParallelState<
     effects: { [K in keyof T]: Effect<T[K], BranchError, Ctx> };
     next(values: [...V]): Effect<R, E, Ctx>;
     /** A frozen copy of the options the `Parallel` was built with. */
-    options?: Readonly<ParallelOptions>;
+    options: Readonly<ParallelOptions>;
 };
 
 export type Effect<T, E = unknown, Ctx = unknown> =
@@ -197,7 +199,7 @@ export declare function commandName(command: CommandState<any, any, any, any>):
 /** Reads the context passed to `runEffect`. With no argument it succeeds with the context; name its type as `Ask<AppCtx>()`. */
 export declare function Ask<Ctx = unknown>(): AskState<Ctx, never, Ctx>;
 
-/** Reads the context passed to `runEffect`. Give the value, error and context types, or none. */
+/** Reads the context passed to `runEffect`. Give the value, error and context types, or none and annotate `ctx`. */
 export declare function Ask<T = never, E = never, Ctx = unknown, N extends AnyEffect = Effect<T, E, Ctx>>(
     next: (context: Ctx) => N
 ): AskState<EffectValue<N>, EffectError<N>, Ctx & EffectContext<N>>;
@@ -1300,7 +1302,7 @@ export declare function effectGen<I, Y extends Step<any, any>, R>(
  */
 export type StepRunner = (
     name: string,
-    type: string,
+    type: 'Command' | 'Parallel',
     op: (decision?: ParallelDecision) => Promise<unknown>,
     path: string
 ) => Promise<unknown>;
@@ -1367,7 +1369,7 @@ export type ReplayStep = {
     /** `meta.name`, `cmd.name`, or 'anonymous'; 'Parallel' for a `Parallel`'s step. */
     name: string;
     /** `'Command'`, or `'Parallel'` for a `Parallel`'s decision. */
-    type: string;
+    type: 'Command' | 'Parallel';
     /** The step's position in the flow, the same in every run; a Resolver should key off it. */
     path: string;
 };
@@ -1442,16 +1444,15 @@ export type RecordOptions<Ctx = unknown> = RecorderOptions & {
 };
 
 /**
- * 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`.
+ * Runs a flow for real and returns its outcome with a trace. The trace holds the flow's input when `effectPipe` or
+ * `effectGen` built it.
  */
-export declare function recordEffect<I, T, E = unknown, Ctx = unknown>(
-    flowFn: (input: I) => Effect<T, E, Ctx>,
-    initialInput: I,
+export declare function recordEffect<T, E = unknown, Ctx = unknown>(
+    effect: Effect<T, E, Ctx>,
     ...options: unknown extends 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 } }>;
+): Promise<{ result: SuccessState<T> | FailureState<E>; trace: TraceLog<unknown, Ctx> }>;
 
 export interface ReplayOptions<Ctx = unknown> {
     /** Context for `Ask`; defaults to the one the trace recorded. */
@@ -1498,16 +1499,24 @@ export declare function replayEffect<T, E = unknown, Ctx = unknown>(
         : [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 interface TimeTravelOptions<Ctx = unknown> {
+    /** Receives each narrated line; `console.log` by default. */
+    log?: ((...args: any[]) => void) | undefined;
+    /** Context for `Ask`; defaults to the one the trace recorded. */
+    context?: RunContext<Ctx> | undefined;
+    /** The build replaying the trace; a trace recorded at another build gets a warning. */
+    version?: string | undefined;
+}
+
+/**
+ * Replays a trace and logs each step with its recorded timing, warning about what will not replay as recorded. Returns
+ * what `replayEffect` returns for a trace.
+ */
 export declare function timeTravel<T, E = unknown, Ctx = unknown>(
     flowFn: (input: any) => Effect<T, E, Ctx>,
     traceLog: TraceLog,
-    options?: {
-        log?: ((...args: any[]) => void) | undefined;
-        context?: RunContext<CheckedContext<Ctx>> | undefined;
-        version?: string | undefined;
-    }
-): Promise<SuccessState<T> | FailureState<E>>;
+    options?: TimeTravelOptions<CheckedContext<Ctx>>
+): Promise<Replay<T, E>>;
 
 // Only the declarations marked `export` are public; without this, a declaration file exports every top-level one.
 export {};