pure-effect 0.20.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;
@@ -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>>;

package/index.js

@@ -312,7 +312,7 @@ const checkOptions = (options, source, rules, raise = (message) => new TypeError
         const value = options[name];
         if (rule === null || value === undefined || rule[0](value)) continue;
         const [, takes, advice] = rule;
-        const message = `${source} '${name}' must be ${takes}, received ${describeArgument(value)}.`;
+        const message = `${source} '${name}' must be ${takes}, received ${describeOption(value)}.`;
         throw raise(advice ? `${message} ${advice}` : message, value);
     }
 };
@@ -332,7 +332,11 @@ const retryOptionRules = {
         "To handle an outcome without retrying, branch on it as data in the Command's next, or isolate a failing " +
             "branch with Parallel's settled option."
     ],
-    delay: [isFiniteNonNegative, 'a finite number of 0 or more'],
+    delay: [
+        isFiniteNonNegative,
+        'a finite number of 0 or more',
+        'To wait as long as a server asks, return its answer as data and wait in a Command.'
+    ],
     backoff: [isFiniteNonNegative, 'a finite number of 0 or more'],
     onExhausted: [isFunction, 'a function that returns the fallback']
 };
@@ -375,6 +379,14 @@ const describeValue = (value) => {
 const describeArgument = (value) =>
     value === undefined ? 'undefined' : isEffect(value) ? `an Effect of type '${value.type}'` : describeValue(value);
 
+/**
+ * Describes an option's value for an error message. A function there is a callback in the wrong place, not a flow
+ * missing its input.
+ * @param {any} value
+ * @returns {string}
+ */
+const describeOption = (value) => (typeof value === 'function' ? 'a function' : describeArgument(value));
+
 /**
  * Marks an error as the harness failing rather than the flow: a malformed flow, or a trace that cannot answer a
  * step. The interpreter rethrows it rather than folding it into a `Failure`, so nothing that handles a domain
@@ -2375,7 +2387,7 @@ const fromTrace = (traceLog, options = {}) => {
 
 /**
  * The outcome a recorded entry hands its step. An entry the recorder could not record stops the replay rather than
- * run live under `onMissing`, since production ran the step.
+ * run live under `onMissing`, since the recorded run ran the step.
  * @param {TraceEntry} entry
  * @param {ReplayStep} step
  * @returns {ReplayOutcome}
@@ -2385,7 +2397,7 @@ const recordedOutcome = (entry, step) => {
         throw unrecordedError(
             `outcome for '${step.name}' at path '${step.path}'`,
             entry.unrecorded,
-            "Production ran the step, so onMissing: 'execute' does not run it either. To replay past it,",
+            "The recorded run ran the step, so onMissing: 'execute' does not run it again. To replay past it,",
             { command: step.name, index: step.index, path: step.path }
         );
     }
@@ -2540,25 +2552,28 @@ const resolveInOrder = (entries, answerFrom) => {
 };
 
 /**
- * The error for a step a replay has no recorded outcome for, which it refuses to run live. It says whether a cap
- * may have dropped the step or production may never have run it, since the fix differs.
+ * The error for a step a replay has no outcome for, which it refuses to run live. For a trace it says whether a cap
+ * may have dropped the step or the recorded run may never have reached it, since the fix differs. A Resolver is
+ * usually a test's answers, so for one it names the step to answer.
  * @param {ReplayStep} step
  * @param {((step: ReplayStep) => string) | undefined} describe - `fromTrace`'s `missing`; a Resolver has none
  * @param {number} droppedEntries - How many entries the trace dropped under `maxEntries`
  * @returns {Error}
  */
 const missingStepError = (step, describe, droppedEntries) => {
-    const what = describe ? describe(step) : `No recorded outcome for '${step.name}' at step ${step.index}`;
-    const why =
-        droppedEntries > 0
-            ? `The trace dropped ${droppedEntries} entries under maxEntries, so production may have run ` +
-              'this step and the recorder not kept it; record the flow with a higher maxEntries to ' +
-              'replay past it.'
-            : 'Production may never have run it: a Command an onBeforeCommand hook vetoed leaves no ' +
-              'entry, and neither does a step the flow reaches now that it did not then, such as one added ' +
-              "past the end of the recording. onMissing: 'execute' runs such a step for real, and every step " +
-              'after it that the trace also lacks, so pass it only where every Command the flow can still ' +
-              'reach goes to a test double or only reads.';
+    const what = describe ? describe(step) : `The Resolver has no answer for '${step.name}' at path '${step.path}'`;
+    const lacking = describe ? 'the trace also lacks' : 'the Resolver has no answer for either';
+    const runsLive =
+        `onMissing: 'execute' runs such a step for real, and every step after it that ${lacking}, so pass it ` +
+        'only where every Command the flow can still reach goes to a test double or only reads.';
+    const why = !describe
+        ? `Give the Resolver an answer for this step. ${runsLive}`
+        : droppedEntries > 0
+          ? `The trace dropped ${droppedEntries} entries under maxEntries, so the recorded run may have reached ` +
+            'this step and the recorder not kept it; record the flow with a higher maxEntries to replay past it.'
+          : 'The recorded run may never have reached it: a Command an onBeforeCommand hook vetoed leaves no ' +
+            'entry, and neither does a step the flow reaches now that it did not then, such as one added ' +
+            `past the end of the recording. ${runsLive}`;
     return replayError(`${what}; refusing to run the real Command. ${why}`, {
         command: step.name,
         index: step.index,
@@ -2691,7 +2706,7 @@ const replayContext = (traceLog, given) => {
 };
 
 /**
- * How many entries a trace dropped under `maxEntries`. A capped trace lacks steps production ran, so it refuses
+ * How many entries a trace dropped under `maxEntries`. A capped trace lacks steps the recorded run ran, so it refuses
  * `onMissing: 'execute'`, which could run one of them again.
  * @param {TraceLog | undefined} traceLog
  * @param {'throw' | 'execute'} onMissing
@@ -2703,7 +2718,7 @@ const droppedEntriesOf = (traceLog, onMissing) => {
     if (capped && onMissing === 'execute') {
         throw replayError(
             `The trace dropped ${dropped} entries under maxEntries, so a step it lacks may be one ` +
-                "production ran, and onMissing: 'execute' would run it again. Replay without it to stop at the " +
+                "the recorded run reached, and onMissing: 'execute' would run it again. Replay without it to stop at the " +
                 'first missing step, or record the flow with a higher maxEntries.'
         );
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pure-effect",
-    "version": "0.20.0",
+    "version": "0.20.1",
     "description": "Records what your business logic did in production and replays it anywhere: time-travel debugging for JavaScript and TypeScript, with zero dependencies. Business logic is plain data you can test without mocks.",
     "keywords": [
         "effect",
@@ -20,6 +20,7 @@
     "files": [
         "index.js",
         "index.d.ts",
+        "RULES.md",
         "CHANGELOG.md",
         "examples"
     ],
@@ -31,8 +32,8 @@
         "test": "mocha && tsd && tsc -p jsconfig.json",
         "test:ts-minimum": "npx --yes -p typescript@5.1 tsc -p test/tsconfig.minimum.json",
         "test:fuzz": "FUZZ_SCALE=20 mocha test/fuzz.js",
-        "generate": "node scripts/effect-pipe-overloads.js",
-        "format": "prettier --write index.js index.d.ts examples/*.js scripts/*.js test/*.js test/types.test-d.ts README.md CLAUDE.md DESIGN.md CHANGELOG.md CONTRIBUTING.md"
+        "generate": "node scripts/effect-pipe-overloads.js && node scripts/rules-file.js",
+        "format": "prettier --write index.js index.d.ts examples/*.js scripts/*.js test/*.js test/types.test-d.ts README.md CLAUDE.md DESIGN.md CHANGELOG.md CONTRIBUTING.md RULES.md"
     },
     "tsd": {
         "directory": "test",