pure-effect 0.8.0 → 0.10.0

package/examples/opentelemetry-example.js

@@ -0,0 +1,164 @@
+// @ts-check
+
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+import { configureEffect } from '../index.js';
+
+/** @import { Tracer } from "@opentelemetry/api" */
+/** @import { EffectConfiguration, RunWrapper, StepRunner } from "../index.js" */
+
+/**
+ * Reference wiring for OpenTelemetry spans
+ *
+ * `onRun` opens one span per `runEffect` call and `onStep` opens a child span per Command,
+ * which is the whole integration: the hooks already sit exactly where spans want to start
+ * and end.
+ *
+ * Importing this file does nothing on its own. Call `startTelemetrySdk()` to stand up an
+ * exporter, and `enableTelemetry()` to install the hooks, or `telemetryHooks()` to get them
+ * as a configuration you can merge with others.
+ *
+ * No Command input or output is put on a span, deliberately. Spans carry names, timings, and
+ * status; values belong in a trace, where `recorder`'s `redact` strips them before they leave the
+ * process and what remains can be replayed. Copying values onto spans would duplicate them into
+ * the one place they cannot be redacted after the fact, and an initial input routinely holds a
+ * password, a token, or a card number.
+ *
+ * These hooks use the raw `onStep` and `onRun` rather than `observe`, because a span has to wrap
+ * `op`: `startActiveSpan` is what makes each Command span a child of the run's span. An integration
+ * that only watches, such as metrics or logging, should use `observe` instead and cannot break a
+ * flow by throwing.
+ */
+
+/**
+ * @typedef {Object} TelemetryOptions
+ * @property {string} [tracerName] - Defaults to `'pure-effect'`.
+ * @property {Tracer} [tracer] - Supply a tracer directly instead of resolving one by name. Useful in tests.
+ */
+
+/**
+ * A span status message, without putting a Command's data on the span.
+ *
+ * Only a string error or an Error's message is used. A structured error object can hold the very
+ * values this file keeps off spans, and `String(someObject)` would say nothing useful anyway.
+ *
+ * @param {any} error
+ * @returns {string | undefined}
+ */
+const statusMessage = (error) =>
+    error instanceof Error ? error.message : typeof error === 'string' ? error : undefined;
+
+/**
+ * Builds the tracing hooks without installing them.
+ *
+ * Returning a configuration rather than calling `configureEffect` is what lets tracing coexist with
+ * recording: there is one slot per hook, so both concerns go into a single `configureEffect` call,
+ * which merges them. A helper that installed itself would silently replace whatever was there.
+ *
+ * @param {TelemetryOptions} [options]
+ * @returns {EffectConfiguration}
+ */
+export function telemetryHooks(options = {}) {
+    const { tracerName = 'pure-effect', tracer = trace.getTracer(tracerName) } = options;
+
+    /**
+     * The root span is named after the flow, so traces are distinguishable in a UI. Every span
+     * ends in a `finally`, so a thrown Command cannot leak one.
+     * @type {RunWrapper}
+     */
+    const onRun = (effect, pipeline, flowName) =>
+        tracer.startActiveSpan(flowName || 'Effect Pipeline', async (rootSpan) => {
+            rootSpan.setAttribute('effect.flow', flowName || '');
+            try {
+                const result = await pipeline();
+                if (result.type === 'Failure') {
+                    rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: statusMessage(result.error) });
+                } else {
+                    rootSpan.setStatus({ code: SpanStatusCode.OK });
+                }
+                return result;
+            } catch (/** @type any */ err) {
+                rootSpan.recordException(err);
+                rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
+                throw err;
+            } finally {
+                rootSpan.end();
+            }
+        });
+
+    /**
+     * `op` has to be awaited and its result returned. Returning a value without calling `op` is how
+     * replay suppresses I/O, so a hook that forgot to call it would silently stop every Command.
+     * @type {StepRunner}
+     */
+    const onStep = (name, type, op) =>
+        tracer.startActiveSpan(name, async (span) => {
+            span.setAttribute('effect.type', type);
+            try {
+                const result = await op();
+                span.setStatus({ code: SpanStatusCode.OK });
+                return result;
+            } catch (/** @type any */ err) {
+                span.recordException(err);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
+                throw err;
+            } finally {
+                span.end();
+            }
+        });
+
+    return { onRun, onStep };
+}
+
+/**
+ * Installs tracing on its own. Pass `telemetryHooks()` to `configureEffect` alongside anything else
+ * that needs the hooks instead, since a bare call here replaces whatever was configured before.
+ *
+ * @param {TelemetryOptions} [options]
+ */
+export function enableTelemetry(options) {
+    configureEffect(telemetryHooks(options));
+}
+
+/**
+ * Starts a Node SDK exporting over OTLP, and returns it so a caller can shut it down.
+ *
+ * Kept out of module scope on purpose: importing a reference file should not open exporters, spawn
+ * background work, or register process handlers. The SDK is imported dynamically so the hooks above
+ * stay usable wherever `@opentelemetry/api` runs, without pulling the Node SDK in behind them.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.serviceName]
+ * @param {string} [options.url] - OTLP HTTP endpoint.
+ * @param {boolean} [options.handleSigterm] - Flush and exit on SIGTERM. Off by default, since
+ *          installing a process handler is the application's decision, not a library's.
+ */
+export async function startTelemetrySdk(options = {}) {
+    const { serviceName = 'pure-effect', url = 'http://localhost:4318/v1/traces', handleSigterm = false } = options;
+    const [{ NodeSDK }, { OTLPTraceExporter }, { SimpleSpanProcessor }] = await Promise.all([
+        import('@opentelemetry/sdk-node'),
+        import('@opentelemetry/exporter-trace-otlp-proto'),
+        import('@opentelemetry/sdk-trace-base')
+    ]);
+
+    const traceExporter = new OTLPTraceExporter({ url });
+    // `spanProcessors` replaced the deprecated singular `spanProcessor`, and passing an exporter
+    // alongside a processor that already wraps it was redundant.
+    const sdk = new NodeSDK({
+        serviceName,
+        spanProcessors: [new SimpleSpanProcessor(traceExporter)],
+        instrumentations: []
+    });
+
+    sdk.start();
+
+    if (handleSigterm) {
+        process.on('SIGTERM', () => {
+            sdk.shutdown()
+                .then(() => console.log('Tracing terminated'))
+                .catch((error) => console.log('Error terminating tracing', error))
+                .finally(() => process.exit(0));
+        });
+    }
+
+    return sdk;
+}

package/examples/recording-example.js

@@ -0,0 +1,104 @@
+// @ts-check
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { configureEffect, recorder } from '../index.js';
+
+/** @import { EffectConfiguration, RunWrapper, StepRunner, CommandInterceptor, TraceLog, SuccessState, FailureState } from "../index.js" */
+
+/**
+ * Example wiring for recording every run of an application.
+ * `recordEffect` covers tests and scripts, where one call site holds the whole run. This
+ * exists for the other case: recording without touching any call site.
+ */
+
+/**
+ * @typedef {Object} RecordingStore
+ * @property {ReturnType<typeof recorder>} rec
+ * @property {string} [flowName]
+ * @property {any} initialInput
+ * @property {any} context
+ */
+
+/**
+ * @typedef {Object} RecordingOptions
+ * @property {(trace: TraceLog) => Promise<void> | void} [sink] - Receives a finished trace. Writing to
+ *           S3 or a database fit here. Prefer not to await slow I/O inside
+ *           a request: hand the trace to a queue or a background task instead.
+ * @property {(value: any, name: string, kind: string) => any} [redact] - Runs before any value enters the
+ *           trace, so nothing sensitive reaches the sink even in memory. It sees results, serialized errors,
+ *           and the `initialInput` and `context` the trace stores, distinguished by `kind`.
+ * @property {number} [maxEntries] - Caps trace length; the overflow count 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. Defaults to failures only. Return `true` always to keep everything, or
+ *           sample successes with a probability check.
+ */
+
+/**
+ * Builds the three hooks that record each run, without installing them.
+ *
+ * Returning a configuration rather than calling `configureEffect` is what lets recording coexist
+ * with tracing: there is one slot per hook, so both concerns go into a single `configureEffect` call,
+ * which merges them. A helper that installed itself would silently replace whatever was there.
+ *
+ * @param {RecordingOptions} [options]
+ * @returns {EffectConfiguration}
+ */
+export function recordingHooks(options = {}) {
+    const {
+        sink = async () => {},
+        redact,
+        maxEntries = 500,
+        stack,
+        keep = (result) => result.type === 'Failure'
+    } = options;
+    /** @type {AsyncLocalStorage<RecordingStore>} */
+    const scope = new AsyncLocalStorage();
+
+    /**
+     * One recorder per run, held in async-local scope so `onStep` can find the right one without a
+     * recorder being threaded through any business-logic signature. A single module-level recorder
+     * would interleave the steps of concurrent runs into one trace.
+     * @type {RunWrapper}
+     */
+    const onRun = async (effect, pipeline, flowName) => {
+        const rec = recorder({ redact, maxEntries, stack });
+        /** @type {RecordingStore} */
+        const store = { rec, flowName, initialInput: /** @type {any} */ (effect).initialInput, context: undefined };
+        return scope.run(store, async () => {
+            const result = await pipeline();
+            if (keep(result)) await sink(rec.toTrace(store));
+            return result;
+        });
+    };
+
+    /**
+     * Outside a recorded run there is no store, so the Command runs untouched.
+     * @type {StepRunner}
+     */
+    const onStep = async (name, type, op) => {
+        const store = scope.getStore();
+        return store ? await store.rec.onStep(name, type, op) : await op();
+    };
+
+    /**
+     * `onRun` never sees the context, so it is captured from the first Command of the run.
+     * @type {CommandInterceptor}
+     */
+    const onBeforeCommand = async (command, context) => {
+        const store = scope.getStore();
+        if (store && store.context === undefined) store.context = context;
+    };
+
+    return { onRun, onStep, onBeforeCommand };
+}
+
+/**
+ * Installs recording on its own. Pass `recordingHooks()` to `configureEffect` alongside anything else
+ * that needs the hooks instead, since a bare call here replaces whatever was configured before.
+ *
+ * @param {RecordingOptions} [options]
+ */
+export function enableRecording(options) {
+    configureEffect(recordingHooks(options));
+}

package/index.d.ts

@@ -10,11 +10,25 @@ export type FailureState<E = unknown> = {
     initialInput?: unknown;
 };
 
+/**
+ * Metadata attached to a Command. A string `name` is read by the interpreter as the Command's
+ * identity for traces, replay matching, and telemetry spans; every other key is carried through
+ * untouched for `onBeforeCommand`.
+ */
+export type CommandMeta = { name?: string } & Record<string, unknown>;
+
 export type CommandState<R, T, E = unknown, Ctx = unknown> = {
     type: 'Command';
-    cmd: () => Promise<R> | R;
+    /**
+     * Performs the side effect. Inside a `Parallel` branch it receives an `AbortSignal` that fires when a
+     * sibling branch fails; forward it to `fetch`, a driver, or an `AbortController`-aware client to have
+     * the work cancelled in flight. Ignoring it is fine and is what every thunk written before this did:
+     * the interpreter still refuses to start any *later* Command in a cancelled branch. Outside a
+     * `Parallel` no argument is passed at all.
+     */
+    cmd: (signal?: AbortSignal) => Promise<R> | R;
     next: (result: R) => Effect<T, E, Ctx>;
-    meta?: unknown;
+    meta?: CommandMeta;
     initialInput?: unknown;
 };
 
@@ -63,10 +77,16 @@ export declare function Success<T>(value: T): SuccessState<T>;
 
 export declare function Failure<E = unknown>(error: E, initialInput?: unknown): FailureState<E>;
 
-export declare function Command<R, T, E = unknown, Ctx = unknown>(
-    cmd: () => Promise<R> | R,
-    next: (result: R) => Effect<T, E, Ctx>,
-    meta?: unknown
+/**
+ * `next` is optional and defaults to `(result) => Success(result)`, which is what most Commands want.
+ *
+ * A `meta.name` becomes this Command's identity, which keeps it independent of how `cmd` was declared
+ * and immune to minification. Without one the identity falls back to `cmd.name`, then to 'anonymous'.
+ */
+export declare function Command<R, T = R, E = unknown, Ctx = unknown>(
+    cmd: (signal?: AbortSignal) => Promise<R> | R,
+    next?: (result: R) => Effect<T, E, Ctx>,
+    meta?: CommandMeta
 ): CommandState<R, T, E, Ctx>;
 
 export declare function Ask<T, E = unknown, Ctx = unknown>(
@@ -218,7 +238,12 @@ export declare function effectPipe<
     f8: (i: I) => Effect<J, E8, Ctx>
 ): (start: A) => Effect<J, E1 | E2 | E3 | E4 | E5 | E6 | E7 | E8, Ctx>;
 
-export type StepRunner = (name: string, type: string, op: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Wraps one Command execution. `path` is the Command's position in the Effect tree rather than its
+ * position in completion order, so it is the same in a replay as in the recorded run even when
+ * `Parallel` branches finish in a different order. Hooks that take three parameters are unaffected.
+ */
+export type StepRunner = (name: string, type: string, op: () => Promise<unknown>, path?: string) => Promise<unknown>;
 
 export type RunWrapper = (
     effect: Effect<unknown>,
@@ -235,10 +260,145 @@ export interface EffectConfiguration {
     retry?: RetryOptions;
 }
 
-export declare function configureEffect(options: EffectConfiguration): void;
+/**
+ * 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.
+ */
+export declare function configureEffect(...configs: (EffectConfiguration | undefined)[]): () => void;
 
 export declare function runEffect<T, E = unknown, Ctx = unknown>(
     effect: Effect<T, E, Ctx>,
     context?: Ctx,
     callConfig?: EffectConfiguration
 ): Promise<SuccessState<T> | FailureState<E>>;
+
+export type ReplayStep = {
+    /**
+     * Zero-based position in this run's completion order. Not stable for a flow containing `Parallel`,
+     * whose branches finish in whatever order they finish in. Prefer `path`.
+     */
+    index: number;
+    /** `cmd.name`, or 'anonymous'. */
+    name: string;
+    /** Always 'Command' today; reserved. */
+    type: string;
+    /**
+     * The Command's position in the Effect tree, stable across runs: steps are numbered within a
+     * subtree, and each `Parallel` branch and `Retry` attempt opens its own prefix. This is what a
+     * replay matches on, and what a Resolver should key off. Absent on traces recorded before paths.
+     */
+    path?: string;
+};
+
+/**
+ * What production observed for a step. `{ result }` feeds the Command's `next`;
+ * `{ error }` is thrown so the interpreter produces a Failure. A Resolver returning
+ * `undefined` means "not recorded", which is distinct from `{ result: undefined }`.
+ */
+export type ReplayOutcome = { result: unknown } | { error: unknown };
+
+export type Resolver = (step: ReplayStep) => ReplayOutcome | undefined;
+
+export type TraceEntry = {
+    command: string;
+    /**
+     * The Command's position in the Effect tree. Order-independent, so a replay lines a recorded step
+     * up with the step that asked for it even when `Parallel` branches finish out of order.
+     */
+    path?: string;
+    result?: unknown;
+    error?: unknown;
+    /** How long the Command took in production, rounded to microseconds. */
+    durationMs?: number;
+};
+
+/** The reference trace format. A convenience, not a contract: write a Resolver for any other shape. */
+export type TraceLog = {
+    flowName?: string;
+    version?: string;
+    initialInput?: unknown;
+    context?: unknown;
+    dropped?: number;
+    trace: TraceEntry[];
+};
+
+export interface RecorderOptions {
+    /**
+     * Scrubs every value a trace holds: each Command's result, each serialized error, and the
+     * `initialInput` and `context` stored on the trace itself. `kind` is `'result'`, `'error'`,
+     * `'initialInput'`, or `'context'`; `name` is the Command's name for the first two and the kind for
+     * the last two. This is the single place PII is kept out of a trace, which is why it sees all four.
+     */
+    redact?: (value: unknown, name: string, kind: 'result' | 'error' | 'initialInput' | 'context') => unknown;
+    /** Cap trace length; further steps are counted in `dropped`, not stored. */
+    maxEntries?: number;
+    /** Record stack traces for thrown errors. Off by default. */
+    stack?: boolean;
+}
+
+export interface TraceMeta {
+    initialInput?: unknown;
+    flowName?: string;
+    context?: unknown;
+    version?: string;
+}
+
+export declare function recorder(options?: RecorderOptions): {
+    onStep: StepRunner;
+    entries: TraceEntry[];
+    toTrace(meta?: TraceMeta): TraceLog;
+};
+
+export declare function recordEffect<T, E = unknown, Ctx = unknown>(
+    flowFn: (input: any) => Effect<T, E, Ctx>,
+    initialInput: any,
+    options?: RecorderOptions & { context?: Ctx; version?: string }
+): Promise<{ result: SuccessState<T> | FailureState<E>; trace: TraceLog }>;
+
+export interface ReplayOptions<Ctx = unknown> {
+    /** Context for `Ask`. Pass the recorded context to reproduce a run faithfully. */
+    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`). */
+    hooks?: boolean;
+    /**
+     * What to do when the Resolver has no recording for a step.
+     * `'throw'` (default) fails the replay, making side effects impossible.
+     * `'execute'` runs the real Command: recorded prefix, live tail.
+     */
+    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;
+}
+
+/**
+ * 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`.
+ */
+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>>;
+
+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 }
+): Promise<SuccessState<T> | FailureState<E>>;