effect-inspect 0.1.1 → 0.3.0

package/dist/trace/Timing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Span timing derived the same way for the chart, the tooltip, the log, the
+ * drawer and the headless query core.
+ */
+import type { TraceSpan, TraceStore } from './TraceStore.ts';
+/**
+ * Total and self time for a span, in millis.
+ *
+ * Self time is the span's own duration minus the time covered by its direct
+ * children. `from`/`to` clip both to a time window, which is how the
+ * aggregation tabs follow the viewport the way Chrome does: a span half inside
+ * the window contributes only its visible half, and only the child time that
+ * overlaps that half is subtracted.
+ */
+export declare const timings: (store: TraceStore, span: TraceSpan, now: number, from?: number, to?: number) => {
+    readonly total: number;
+    readonly self: number;
+};

package/dist/trace/Timing.js

@@ -0,0 +1,57 @@
+/** A span's end, or `now` while it is still open. */
+const spanEnd = (span, now) => span.end ?? now;
+/**
+ * Time covered by the union of `span`'s direct children, clipped to `[from, to]`.
+ *
+ * A **union**, not a sum: two children running concurrently for 10ms each
+ * occupy 10ms of their parent, not 20ms. Summing would make a heavily
+ * concurrent span's self time read as zero (or negative, and clamp to zero),
+ * which is exactly the number the aggregation tabs are built to show.
+ *
+ * Children are sorted by start and swept once, so this is O(k log k) in the
+ * number of direct children — not in the subtree, and never in the trace.
+ */
+const childUnion = (store, span, now, from, to) => {
+    const intervals = [];
+    for (const id of span.children) {
+        const child = store.spans.get(id);
+        if (child === undefined)
+            continue;
+        const lo = Math.max(child.start, from);
+        const hi = Math.min(spanEnd(child, now), to);
+        if (hi > lo)
+            intervals.push([lo, hi]);
+    }
+    if (intervals.length === 0)
+        return 0;
+    intervals.sort((a, b) => a[0] - b[0]);
+    let covered = 0;
+    let [runStart, runEnd] = intervals[0];
+    for (let i = 1; i < intervals.length; i++) {
+        const [lo, hi] = intervals[i];
+        if (lo > runEnd) {
+            covered += runEnd - runStart;
+            runStart = lo;
+            runEnd = hi;
+        }
+        else if (hi > runEnd)
+            runEnd = hi;
+    }
+    return covered + (runEnd - runStart);
+};
+/**
+ * Total and self time for a span, in millis.
+ *
+ * Self time is the span's own duration minus the time covered by its direct
+ * children. `from`/`to` clip both to a time window, which is how the
+ * aggregation tabs follow the viewport the way Chrome does: a span half inside
+ * the window contributes only its visible half, and only the child time that
+ * overlaps that half is subtracted.
+ */
+export const timings = (store, span, now, from = -Infinity, to = Infinity) => {
+    const lo = Math.max(span.start, from);
+    const hi = Math.min(spanEnd(span, now), to);
+    if (hi <= lo)
+        return { total: 0, self: 0 };
+    return { total: hi - lo, self: Math.max(hi - lo - childUnion(store, span, now, lo, hi), 0) };
+};

package/dist/trace/TraceFile.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Saving a trace to a file and loading it back.
+ *
+ * The file **is** the protocol message stream: line 1 is a
+ * {@link Protocol.TraceFileHeader}, every line after it is a `ClientMessage`
+ * exactly as `clientCodec` writes it on the wire. So a new protocol message
+ * variant is carried by a saved trace for free — the format version only moves
+ * if the header or the line layout changes, never because the protocol grew.
+ *
+ * Parsing is deliberately lenient about the *tail* and strict about the
+ * *head*: a header that will not decode means this is not a trace file and
+ * there is nothing to show, while a truncated last line means the writer died
+ * mid-save and everything before it is still a real trace worth rendering.
+ */
+import { Result } from 'effect';
+import { type ClientMessage, type Session, type TraceCapture, type TraceFileHeader } from '../protocol/Schema.ts';
+/** File extension for a saved trace. */
+export declare const traceFileExtension = ".eitrace";
+/** Why a file could not be read as a trace. `message` is shown to the user verbatim. */
+export interface TraceFileError {
+    readonly _tag: 'TraceFileError';
+    readonly message: string;
+}
+/** A parsed trace file: its header, its messages, and what was lost at the tail. */
+export interface LoadedTrace {
+    readonly header: TraceFileHeader;
+    readonly messages: ReadonlyArray<ClientMessage>;
+    /**
+     * Trailing lines that would not decode, almost always a truncated save.
+     *
+     * Non-zero is surfaced in the UI rather than thrown: the spans before the cut
+     * are real, and a partial trace beats a blank chart.
+     */
+    readonly truncatedLines: number;
+}
+/**
+ * Serializes a session and its messages to trace-file text.
+ *
+ * `messages` is the raw protocol stream in arrival order — not a re-derivation
+ * from the rendered trace model, which would silently drop every message the
+ * model does not draw. `capture` is written only when the caller knows the
+ * collector's loss counters; omitting it marks completeness as unknown.
+ */
+export declare const serializeTraceFile: (session: Session, messages: Iterable<ClientMessage>, savedAtEpochMillis: number, capture?: TraceCapture) => string;
+/**
+ * Parses trace-file text.
+ *
+ * Fails only when the file is not a trace file at all — an unreadable header,
+ * a format version from the future, or a body whose *interior* is corrupt. A
+ * bad line that is not the last one means the file was edited or mangled, not
+ * merely cut short, and rendering a trace with a hole in the middle would be a
+ * lie; a bad final line is reported as {@link LoadedTrace.truncatedLines}.
+ */
+export declare const parseTraceFile: (text: string) => Result.Result<LoadedTrace, TraceFileError>;

package/dist/trace/TraceFile.js

@@ -0,0 +1,86 @@
+/**
+ * Saving a trace to a file and loading it back.
+ *
+ * The file **is** the protocol message stream: line 1 is a
+ * {@link Protocol.TraceFileHeader}, every line after it is a `ClientMessage`
+ * exactly as `clientCodec` writes it on the wire. So a new protocol message
+ * variant is carried by a saved trace for free — the format version only moves
+ * if the header or the line layout changes, never because the protocol grew.
+ *
+ * Parsing is deliberately lenient about the *tail* and strict about the
+ * *head*: a header that will not decode means this is not a trace file and
+ * there is nothing to show, while a truncated last line means the writer died
+ * mid-save and everything before it is still a real trace worth rendering.
+ */
+import { Result } from 'effect';
+import { clientCodec, traceFileHeaderCodec } from '../protocol/Codec.js';
+import { protocolVersion, traceFileFormatVersion, } from '../protocol/Schema.js';
+/** File extension for a saved trace. */
+export const traceFileExtension = '.eitrace';
+const fail = (message) => Result.fail({ _tag: 'TraceFileError', message });
+/**
+ * Serializes a session and its messages to trace-file text.
+ *
+ * `messages` is the raw protocol stream in arrival order — not a re-derivation
+ * from the rendered trace model, which would silently drop every message the
+ * model does not draw. `capture` is written only when the caller knows the
+ * collector's loss counters; omitting it marks completeness as unknown.
+ */
+export const serializeTraceFile = (session, messages, savedAtEpochMillis, capture) => {
+    const header = traceFileHeaderCodec.encode({
+        _tag: 'TraceFileHeader',
+        formatVersion: traceFileFormatVersion,
+        protocolVersion,
+        session,
+        savedAtEpochMillis,
+        ...(capture === undefined ? {} : { capture }),
+    });
+    const body = [];
+    for (const message of messages)
+        body.push(clientCodec.encode(message));
+    return header + body.join('');
+};
+/**
+ * Parses trace-file text.
+ *
+ * Fails only when the file is not a trace file at all — an unreadable header,
+ * a format version from the future, or a body whose *interior* is corrupt. A
+ * bad line that is not the last one means the file was edited or mangled, not
+ * merely cut short, and rendering a trace with a hole in the middle would be a
+ * lie; a bad final line is reported as {@link LoadedTrace.truncatedLines}.
+ */
+export const parseTraceFile = (text) => {
+    const lines = text.split('\n');
+    const headerLine = lines[0];
+    if (headerLine === undefined || headerLine.trim() === '') {
+        return fail('The file is empty.');
+    }
+    const headerResult = traceFileHeaderCodec.decode(headerLine);
+    if (Result.isFailure(headerResult)) {
+        return fail('This is not an effect-inspect trace file: its header could not be read.');
+    }
+    const header = headerResult.success;
+    if (header.formatVersion > traceFileFormatVersion) {
+        return fail(`This trace file is format version ${header.formatVersion}; this build understands up to ${traceFileFormatVersion}.`);
+    }
+    const messages = [];
+    let truncatedLines = 0;
+    for (let index = 1; index < lines.length; index++) {
+        const line = lines[index];
+        if (line.trim() === '')
+            continue;
+        const decoded = clientCodec.decode(line);
+        if (Result.isSuccess(decoded)) {
+            messages.push(decoded.success);
+            continue;
+        }
+        // Only the final line may be a casualty of a truncated write; a bad line
+        // with good lines after it means the file is corrupt, not cut short.
+        const isLast = lines.slice(index + 1).every((rest) => rest.trim() === '');
+        if (!isLast) {
+            return fail(`This trace file is corrupt: line ${index + 1} could not be read.`);
+        }
+        truncatedLines = 1;
+    }
+    return Result.succeed({ header, messages, truncatedLines });
+};

package/dist/trace/TraceStore.d.ts

@@ -0,0 +1,202 @@
+/**
+ * The in-memory trace model for one session.
+ *
+ * This is deliberately **not** React state and **not** an atom. A dense trace
+ * is 10k+ spans and the flame chart redraws on every pan/zoom frame; putting a
+ * span in React state would cost a reconciliation per span, and putting one in
+ * an atom would cost a subscription per span. Instead the store is a plain
+ * mutable structure that the canvas renderer reads directly during its draw
+ * call, and React only ever learns that *something* changed — via
+ * {@link TraceStore.version} — never what.
+ *
+ * The shapes here are tuned for the renderer's access pattern: it walks spans
+ * in depth-then-start order once per frame, so `rows` is maintained
+ * incrementally rather than rebuilt, and every field the renderer touches is a
+ * number rather than a `bigint` (see {@link TraceSpan.start}).
+ */
+import type { Attributes, Json, LogLevel, SpanKind, SpanOutcome } from '../protocol/Schema.ts';
+import type { ClientMessage } from '../protocol/Schema.ts';
+/**
+ * A span in renderer-facing form.
+ *
+ * Times are **milliseconds relative to the session's first observed event**,
+ * as `number`, not the protocol's absolute `bigint` nanos. The renderer does
+ * arithmetic on these every frame and `bigint` maths is both slower and
+ * unusable in canvas coordinates; the conversion happens once, here, at ingest.
+ * {@link TraceStore.epochOrigin} keeps the absolute anchor for display.
+ */
+export interface TraceSpan {
+    readonly spanId: string;
+    readonly traceId: string;
+    readonly name: string;
+    readonly kind: SpanKind;
+    /** Parent span id, or `undefined` for a root (or externally-parented) span. */
+    readonly parentId: string | undefined;
+    /** Milliseconds since {@link TraceStore.origin}. */
+    readonly start: number;
+    /** Milliseconds since {@link TraceStore.origin}, or `undefined` while open. */
+    end: number | undefined;
+    /** Nesting depth; 0 for a root span. */
+    depth: number;
+    /** Set once `SpanEnd` arrives. */
+    outcome: SpanOutcome | undefined;
+    /** `SpanStart` attributes merged with the late ones from `SpanEnd`. */
+    attributes: Record<string, Json>;
+    /** Child span ids, in arrival order. */
+    readonly children: Array<string>;
+    /** Point-in-time events on this span, in arrival order. */
+    readonly events: Array<TraceSpanEvent>;
+    readonly fiberId: number | undefined;
+    /** True when the parent id was seen but the parent span has not arrived. */
+    orphaned: boolean;
+}
+/** A point-in-time event recorded against a span. */
+export interface TraceSpanEvent {
+    readonly name: string;
+    /** Milliseconds since {@link TraceStore.origin}. */
+    readonly time: number;
+    readonly attributes: Attributes;
+}
+/** A log record, kept in arrival order alongside the spans. */
+export interface TraceLog {
+    /** Milliseconds since {@link TraceStore.origin}. */
+    readonly time: number;
+    readonly level: LogLevel;
+    readonly message: Json;
+    readonly spanId: string | undefined;
+    readonly fiberId: number | undefined;
+    readonly annotations: Attributes;
+}
+/**
+ * One `process.memoryUsage()` reading, in the chart's time base.
+ *
+ * Figures stay in bytes; the track formats them. `time` is relative millis like
+ * everything else here, so the memory curve and the flame bars share an x-axis
+ * by construction rather than by two pieces of code agreeing.
+ */
+export interface TraceMemorySample {
+    /** Milliseconds since {@link TraceStore.origin}. */
+    readonly time: number;
+    readonly heapUsed: number;
+    readonly heapTotal: number;
+    readonly rss: number;
+    readonly external: number;
+}
+/** Cheap counters for the header, so the UI never walks the span map to count. */
+export interface TraceStats {
+    readonly spans: number;
+    readonly openSpans: number;
+    readonly errors: number;
+    readonly logs: number;
+    readonly events: number;
+    /** Milliseconds since {@link TraceStore.origin} of the latest observed time. */
+    readonly duration: number;
+}
+/**
+ * Mutable span index for one session.
+ *
+ * Ingest is `apply`, one protocol message at a time, in arrival order. Reads
+ * are direct field access — `spans`, `roots` and `rows` are live structures,
+ * not copies, so the renderer must treat them as read-only and must re-read
+ * them (not cache them) whenever {@link version} changes.
+ */
+export declare class TraceStore {
+    /** Every span seen, by span id. Includes spans that are still open. */
+    readonly spans: Map<string, TraceSpan>;
+    /** Root span ids in arrival order — the renderer's entry points. */
+    readonly roots: Array<string>;
+    /** Span ids that have no `SpanEnd` yet, so the renderer can draw them open-ended. */
+    readonly openSpans: Set<string>;
+    /** Logs in arrival order. */
+    readonly logs: Array<TraceLog>;
+    /**
+     * Memory samples in arrival order, which is also time order.
+     *
+     * A plain array rather than anything indexed: the track draws the whole
+     * series each frame by walking it once, and at the client's 100ms interval a
+     * ten-minute trace is 6,000 entries — a scan the renderer does not notice.
+     * ponytail: linear scan, swap for a binary search into the viewport if a
+     * trace ever runs long enough for it to show up in a frame budget.
+     */
+    readonly memory: Array<TraceMemorySample>;
+    /**
+     * Largest `heapUsed` seen — the memory track's y-axis top, kept here so the
+     * renderer never re-scans the series to scale a frame.
+     */
+    memoryPeak: number;
+    /** Smallest `heapUsed` seen — the memory track's y-axis floor. */
+    memoryTrough: number;
+    /** Largest `rss` seen; the secondary line has its own scale. */
+    memoryRssPeak: number;
+    /**
+     * Every message ingested, in arrival order — the source for saving to a file.
+     *
+     * The rendered model above is lossy on purpose (relative millis, merged
+     * attributes, `Metrics`/`FiberEvent` dropped), so a file written from it
+     * would quietly lose whatever the chart does not draw. Keeping the decoded
+     * messages costs one array slot each — they are already allocated — and
+     * makes save a copy rather than a re-derivation.
+     */
+    readonly raw: Array<ClientMessage>;
+    /**
+     * Span ids bucketed by depth: `rows[2]` is every span nested two levels deep.
+     *
+     * This is the flame chart's row layout. It is maintained incrementally on
+     * ingest so the renderer never has to traverse the tree to find a row, and
+     * so drawing a viewport means scanning only the rows it covers.
+     */
+    readonly rows: Array<Array<string>>;
+    /**
+     * Spans waiting on a parent that has not arrived, keyed by the missing
+     * parent id.
+     *
+     * A child can legitimately precede its parent: the backlog preserves arrival
+     * order, and a parent's `SpanStart` is emitted when it opens, which a
+     * concurrent fiber's child can beat to the wire. Rather than drop such a
+     * span, it is parked here and re-linked when the parent shows up.
+     */
+    private readonly pendingChildren;
+    /** Monotonic nanos of the first event seen; the zero point for `start`/`end`. */
+    origin: bigint | undefined;
+    /** Wall-clock millis matching {@link origin}, from the session's `Hello`. */
+    epochOrigin: number | undefined;
+    /**
+     * Bumped on every mutation.
+     *
+     * This is the *only* value React is allowed to observe. The renderer polls
+     * it per frame to decide whether to redraw; the UI mirrors it into an atom
+     * on a timer so counters update without a render per span.
+     */
+    version: number;
+    private spanCount;
+    private errorCount;
+    private eventCount;
+    private maxTime;
+    /** Snapshot of the counters — allocates, so call it per repaint, not per span. */
+    stats(): TraceStats;
+    /** Drops everything — used when switching sessions. */
+    clear(): void;
+    /** Ingests one client message. Unknown/undrawn variants are ignored, not errors. */
+    apply(message: ClientMessage): void;
+    /** Ingests a batch, bumping `version` once rather than per message. */
+    applyAll(messages: Iterable<ClientMessage>): void;
+    private anchor;
+    private relative;
+    private applySpanStart;
+    /** Re-links children that arrived before this span did. */
+    private adoptPending;
+    /**
+     * Moves a subtree to a new depth after a late parent arrives.
+     *
+     * Iterative rather than recursive: a deeply-nested Effect program can stack
+     * hundreds of spans and a blown call stack during ingest would take the
+     * whole webapp down.
+     */
+    private redepth;
+    private addToRow;
+    private removeFromRow;
+    private applySpanEnd;
+    private applySpanEvent;
+    private applyMemorySample;
+    private applyLog;
+}