pure-effect 0.12.0 → 0.13.0

package/examples/opentelemetry-example.js

@@ -1,164 +0,0 @@
-// @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

@@ -1,104 +0,0 @@
-// @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/jsconfig.json

@@ -1,13 +0,0 @@
-{
-    "compilerOptions": {
-        "allowJs": true,
-        "checkJs": true,
-        "strict": true,
-        "noEmit": true,
-        "target": "es2022",
-        "module": "nodenext",
-        "moduleResolution": "nodenext",
-        "lib": ["es2022", "dom"]
-    },
-    "include": ["index.js", "test/all.js", "test/types.test-d.ts", "examples/*.js"]
-}