@ersbeth/picoflow 2.3.2 → 3.0.0

package/dist/inspect.d.ts

@@ -0,0 +1,252 @@
+/// <reference lib="esnext.disposable" preserve="true" />
+import { d as FlowEffect, h as ObserverStatus, m as ObservableStatus, n as FlowValue } from "./shared.js";
+import { t as FlowSignal } from "./shared2.js";
+//#region src/core/base/disposable.d.ts
+/**
+ * Which primitive a node came from. Declared with the engine that carries it, and surfaced to
+ * consumers by the inspection layer (#50, A2-DX-2).
+ *
+ * `unknown` is what a core built on its own reports — the kind is a property of the primitive a
+ * facade makes of it, not of the engine.
+ *
+ * @public
+ */
+type FlowNodeKind = "constant" | "constantAsync" | "derivation" | "derivationAsync" | "state" | "stateAsync" | "writableDerivation" | "writableDerivationAsync" | "array" | "map" | "action" | "signal" | "effect" | "unknown";
+//#endregion
+//#region src/core/base/traceHub.d.ts
+/**
+ * The moments in a node's life a trace can record (#50, A2-DX-2).
+ *
+ * Between them they spell out one propagation: a write notifies its dependents, each is queued for
+ * the coming flush, the flush executes them, each settles, and the effects run last.
+ *
+ * Declared here, where the engine emits them, and re-exported by the inspection layer rather than
+ * aliased there: an alias would leave the name TypeDoc documents pointing at a declaration outside
+ * every entry point, and an internal-tagged one would be stripped from the published declarations
+ * while the public alias still referenced it. The same shape as `ObserverStatus`, declared in
+ * `observer.ts` and re-exported by the API layer, prefix included since this is a public name.
+ *
+ * @public
+ */
+type FlowTraceEventType = "notify" | "queue-pending" | "queue-effect" | "execute" | "resolve" | "reject" | "effect-run" | "cycle-error";
+//#endregion
+//#region src/core/inspect/snapshot.d.ts
+/**
+ * How a node is named in a dump, and everything needed to recognise it — the shape used both for a
+ * node itself and for each of its neighbours.
+ *
+ * @public
+ */
+interface FlowNodeRef {
+  /**
+   * Identity of this node, assigned at creation and never reused. Two dumps taken at different
+   * moments describe the same node under the same `id`, which is what lets a diff of them mean
+   * something.
+   */
+  id: number;
+  /** Which primitive this is — the factory it came from, or `"effect"` for a subscription. */
+  kind: FlowNodeKind;
+  /** The `name` option given at creation, absent when none was. */
+  name?: string;
+  /** How to display this node: its `name` when it has one, `kind#id` otherwise. */
+  label: string;
+  /** The node's current status, always reported — including `"disposed"`. */
+  status: ObservableStatus | ObserverStatus;
+}
+/**
+ * A node and its edges at one instant.
+ *
+ * Edges are a snapshot, not a fixture: a computation rebuilds its dependency set from scratch on
+ * every run, so this describes the graph as of each node's last computation.
+ *
+ * @public
+ */
+interface FlowNodeSnapshot extends FlowNodeRef {
+  /** The sources this node currently reads. */
+  dependencies: FlowNodeRef[];
+  /** The observers currently registered on this node. */
+  dependents: FlowNodeRef[];
+  /**
+   * The node's value, rendered as a short string — present only when `status` is `"resolved"`,
+   * mirroring the discrimination of the public `value` snapshot. A pending, dirty or disposed node
+   * has no value worth reporting, and a stale cached one would be actively misleading.
+   */
+  value?: string;
+  /** The error's message — present only when `status` is `"error"`. */
+  error?: string;
+  /** Present and `true` only on a derivation created with `eager: true`. */
+  eager?: boolean;
+}
+/**
+ * Describes one primitive and its immediate neighbours, without touching the reactive system (#50,
+ * A2-DX-2).
+ *
+ * Strictly passive: it reads `status` and the passive value snapshot, and iterates the dependency
+ * registries. It never calls `get()`, `pick()`, `watch()` or `subscribe()`, so it computes nothing,
+ * registers no dependency and moves no node — inspecting a graph cannot change what that graph then
+ * does. Inspecting a disposed primitive is fine too, and reports `status: "disposed"`.
+ *
+ * One consequence is worth stating plainly: a lazy derivation that has never been read has never
+ * computed, so it has **no dependencies yet** and reports `status: "dirty"` with no value. That is
+ * the truth about the graph, not a gap in the report — exercise the application first, or create the
+ * derivations you mean to watch with `eager: true`.
+ *
+ * @param target - The primitive to describe: a value, a signal, or the effect `subscribe()` returned
+ * @returns A serialisable description of that node
+ *
+ * @public
+ */
+export declare function inspect(target: FlowValue<unknown> | FlowEffect | FlowSignal): FlowNodeSnapshot;
+//#endregion
+//#region src/core/inspect/graph.d.ts
+/**
+ * Options accepted by {@link graphSnapshot}.
+ *
+ * @public
+ */
+export interface FlowGraphOptions {
+  /**
+   * Include nodes already disposed. Off by default: a disposed node is inert and its edges are
+   * gone, so it is noise in an ordinary dump — but seeing one still listed means something holds a
+   * reference to it, which is worth knowing when hunting a retained object.
+   */
+  includeDisposed?: boolean;
+}
+/**
+ * Counts that describe the graph at a glance.
+ *
+ * @public
+ */
+export interface FlowGraphSummary {
+  /** How many nodes the snapshot covers — the length of {@link FlowGraphSnapshot.nodes}. */
+  total: number;
+  /** How many nodes of each {@link FlowNodeKind} — keys are absent rather than zero. */
+  byKind: Record<string, number>;
+  /** How many nodes in each status — keys are absent rather than zero. */
+  byStatus: Record<string, number>;
+  /**
+   * Nodes with no edge at all, in either direction.
+   *
+   * The number to watch: a primitive nothing reads and that reads nothing is either a lazy
+   * derivation not yet exercised, or a node that outlived its purpose and was never disposed. A
+   * count that grows as an application runs is the visible form of a leak.
+   */
+  orphans: number;
+}
+/**
+ * The whole graph at one instant.
+ *
+ * Every field is a plain number, string or array, so the snapshot survives `JSON.stringify` intact —
+ * it can be logged, sent to a bug report, or handed to a tool that compares two of them by node id.
+ *
+ * @public
+ */
+export interface FlowGraphSnapshot {
+  /** Every node the snapshot covers, in creation order. */
+  nodes: FlowNodeSnapshot[];
+  /** Counts over {@link FlowGraphSnapshot.nodes}, for reading the shape without walking it. */
+  summary: FlowGraphSummary;
+}
+/**
+ * Describes every reactive node alive in this process, without touching the reactive system (#50,
+ * A2-DX-2).
+ *
+ * There is no way to name where to start, and that is the point: the graph has no roots, and the
+ * nodes worth finding — the ones leaked because nothing disposed them — are exactly the ones no
+ * handle points at any more. So the dump comes from a census kept as nodes are created, held weakly:
+ * a node the garbage collector has taken is gone from it, and one that lingers shows up as an orphan.
+ *
+ * Passivity is the same contract as {@link inspect}: statuses are read, registries iterated, nothing
+ * computed. In particular a lazy derivation never read has no dependencies yet and appears as an
+ * orphan — see {@link inspect} for what to do about it.
+ *
+ * @param options - See {@link FlowGraphOptions}
+ * @returns Every node, in creation order, with a {@link FlowGraphSummary}
+ *
+ * @public
+ */
+export declare function graphSnapshot(options?: FlowGraphOptions): FlowGraphSnapshot;
+//#endregion
+//#region src/core/inspect/format.d.ts
+/**
+ * Renders a graph as readable text (#50, A2-DX-2).
+ *
+ * The intended use is a developer with the browser console open, mid-session, asking what the graph
+ * looks like right now: `console.log(formatGraph())`. It returns a string rather than printing one,
+ * so the same call works in a terminal, in a test, or pasted into a bug report — and so the library
+ * never writes to anyone's console on its own.
+ *
+ * One block per node: a line naming it, its kind and its status, followed by its value when it has
+ * one (`= …`) or its error (`! …`), then an indented line of edges — `←` for what it reads, `→` for
+ * what reads it. Nodes with no edges at all are gathered at the end under `orphans`, where a leak
+ * shows up as a list that keeps growing.
+ *
+ * @param graph - A snapshot to render; taken with {@link graphSnapshot} when omitted
+ * @returns The rendered listing
+ *
+ * @public
+ */
+export declare function formatGraph(graph?: FlowGraphSnapshot): string;
+//#endregion
+//#region src/core/inspect/trace.d.ts
+/**
+ * One recorded moment: what happened, to which node, and where it falls in the order.
+ *
+ * @public
+ */
+export interface FlowTraceEvent {
+  /** Position in the trace, counted from the moment tracing started. Never reused. */
+  seq: number;
+  /** What the engine did — see {@link FlowTraceEventType} for the vocabulary. */
+  type: FlowTraceEventType;
+  /** The node it happened to, described as of the moment it was recorded. */
+  node: FlowNodeRef;
+}
+/**
+ * A running trace. Stop it with `dispose()` — a trace left on keeps recording for the life of the
+ * process, which is fine while debugging and waste afterwards.
+ *
+ * @public
+ */
+export interface FlowTrace {
+  /** What has been recorded, oldest first, up to the capacity given at creation. */
+  readonly events: readonly FlowTraceEvent[];
+  /** Forgets everything recorded so far, without stopping the trace. */
+  clear(): void;
+  /** Stops recording. */
+  dispose(): void;
+}
+/**
+ * Options accepted by {@link enableTrace}.
+ *
+ * @public
+ */
+export interface FlowTraceOptions {
+  /**
+   * How many events to keep. Older ones are dropped as newer arrive, so memory is bounded however
+   * long the trace runs — and what remains is the end of the story, which is the part that
+   * explains the symptom. Defaults to 500.
+   */
+  capacity?: number;
+}
+/**
+ * Records what the engine does, so that a question about *time* can be answered (#50, A2-DX-2).
+ *
+ * `inspect()` and `graphSnapshot()` describe the graph's shape at an instant; some questions are not
+ * about shape. "I wrote to `$count` and my effect never ran" is answered by reading the sequence: a
+ * `notify` on `$count` with no `queue-effect` behind it means the edge was never there, while a
+ * `queue-effect` with no `effect-run` means the flush never reached it. A feedback loop reads as an
+ * alternation of `notify` and `effect-run` ending in `cycle-error`, which is how the nodes involved
+ * get named — the error alone names neither.
+ *
+ * Tracing is off until this is called, and costs one boolean check per engine event while it is.
+ * Recording does not change what the engine does: events are observed as they pass, never injected.
+ *
+ * @param options - See {@link FlowTraceOptions}
+ * @returns The running trace; call `dispose()` on it to stop
+ *
+ * @public
+ */
+export declare function enableTrace(options?: FlowTraceOptions): FlowTrace;
+//#endregion
+export type { FlowNodeKind, FlowNodeRef, FlowNodeSnapshot, FlowTraceEventType };

package/dist/inspect.js

@@ -0,0 +1,300 @@
+import { a as ReadableNode, c as Observable, d as TraceHub, f as LiveNodeRegistry, h as PicoFlowError, l as Observer, o as EffectNode, s as Node, t as ValueCore } from "./shared.js";
+import { t as SignalNode } from "./shared3.js";
+
+//#region src/core/inspect/renderValue.ts
+/** Longest rendering kept; anything past this is cut and marked with an ellipsis. */
+const MAX_LENGTH = 80;
+/** How deep the renderer descends before collapsing a nested value to `{…}` / `[…]`. */
+const MAX_DEPTH = 2;
+/** How many entries of an array, map or set are rendered before the rest is elided. */
+const MAX_ENTRIES = 10;
+/**
+* Renders a value for an inspection dump: short, safe, and never a hazard of its own (#50).
+*
+* A dump must survive whatever a graph happens to hold — a megabyte of data, a cyclic object, a
+* getter that throws — so this is deliberately not `JSON.stringify`. Depth and entry count are
+* bounded (which is also what makes a cycle harmless, without the false "[Circular]" a seen-set
+* reports for a merely repeated object), the result is truncated, and anything unexpected degrades
+* to a placeholder rather than throwing inside the debugging tool.
+* @internal
+*/
+function renderValue(data) {
+	let text;
+	try {
+		text = render(data, MAX_DEPTH);
+	} catch {
+		text = "[unrenderable]";
+	}
+	return text.length > MAX_LENGTH ? `${text.slice(0, 79)}…` : text;
+}
+function render(data, depth) {
+	switch (typeof data) {
+		case "string": return JSON.stringify(data);
+		case "number":
+		case "boolean": return String(data);
+		case "undefined": return "undefined";
+		case "bigint": return `${data}n`;
+		case "symbol": return data.toString();
+		case "function": return data.name ? `[Function ${data.name}]` : "[Function]";
+	}
+	if (data === null) return "null";
+	if (data instanceof Error) return `${data.name}: ${data.message}`;
+	if (data instanceof Date) return data.toISOString();
+	const isArray = Array.isArray(data);
+	const isMap = data instanceof Map;
+	const isSet = data instanceof Set;
+	if (depth === 0) return isArray ? "[…]" : "{…}";
+	if (isArray) return `[${list(data, (item) => render(item, depth - 1))}]`;
+	if (isSet) return `Set(${data.size}) {${list([...data], (item) => render(item, depth - 1))}}`;
+	if (isMap) {
+		const entries = list([...data], ([key, value]) => `${render(key, depth - 1)} => ${render(value, depth - 1)}`);
+		return `Map(${data.size}) {${entries}}`;
+	}
+	return `{${list(Object.entries(data), ([key, value]) => `${key}: ${render(value, depth - 1)}`)}}`;
+}
+/** Joins at most {@link MAX_ENTRIES} rendered items, marking the elided tail. */
+function list(items, renderItem) {
+	const shown = items.slice(0, MAX_ENTRIES).map(renderItem);
+	if (items.length > MAX_ENTRIES) shown.push(`…${items.length - MAX_ENTRIES} more`);
+	return shown.join(", ");
+}
+
+//#endregion
+//#region src/core/inspect/snapshot.ts
+/**
+* Describes one primitive and its immediate neighbours, without touching the reactive system (#50,
+* A2-DX-2).
+*
+* Strictly passive: it reads `status` and the passive value snapshot, and iterates the dependency
+* registries. It never calls `get()`, `pick()`, `watch()` or `subscribe()`, so it computes nothing,
+* registers no dependency and moves no node — inspecting a graph cannot change what that graph then
+* does. Inspecting a disposed primitive is fine too, and reports `status: "disposed"`.
+*
+* One consequence is worth stating plainly: a lazy derivation that has never been read has never
+* computed, so it has **no dependencies yet** and reports `status: "dirty"` with no value. That is
+* the truth about the graph, not a gap in the report — exercise the application first, or create the
+* derivations you mean to watch with `eager: true`.
+*
+* @param target - The primitive to describe: a value, a signal, or the effect `subscribe()` returned
+* @returns A serialisable description of that node
+*
+* @public
+*/
+function inspect(target) {
+	return snapshotOf(participantOf(target));
+}
+/**
+* Resolves a public handle to the node that actually sits in the graph.
+*
+* A value primitive is a facade owning a {@link ValueCore}, so the map built at construction is the
+* way across; a signal and an effect are their own graph node. Nothing else is accepted — in
+* particular not the tracker a compute function receives, even though reading it would be harmless:
+* introspection stays outside the reactive system, and an entry point that takes a tracker would
+* suggest otherwise.
+*/
+function participantOf(target) {
+	if (target instanceof ReadableNode) return target._core;
+	if (target instanceof EffectNode || target instanceof SignalNode) return target;
+	throw new PicoFlowError("[PicoFlow] inspect() expects a primitive, a signal or an effect — not the tracker a compute function receives");
+}
+/** Builds the full description of a graph participant. @internal */
+function snapshotOf(participant) {
+	const snapshot = {
+		...refOf(participant),
+		dependencies: [],
+		dependents: []
+	};
+	if (participant instanceof Node || participant instanceof Observer) participant._forEachDependency((dependency) => {
+		snapshot.dependencies.push(refOf(dependency));
+	});
+	if (participant instanceof Observable) participant._forEachDependent((dependent) => {
+		snapshot.dependents.push(refOf(dependent));
+	});
+	if (participant instanceof ValueCore) {
+		const value = participant.snapshot();
+		if (value.status === "resolved") snapshot.value = renderValue(value.data);
+		if (value.status === "error") snapshot.error = value.error.message;
+		if (participant._isEager) snapshot.eager = true;
+	}
+	return snapshot;
+}
+/** Builds the short form: what a node is called, and where it stands. @internal */
+function refOf(participant) {
+	const kind = participant._kind;
+	const name = participant._inspectName;
+	const status = statusOf(participant);
+	const ref = {
+		id: participant._id,
+		kind,
+		label: name ?? `${kind}#${participant._id}`,
+		status
+	};
+	if (name !== void 0) ref.name = name;
+	return ref;
+}
+/** `status` is the one reading every participant offers, and it never computes nor throws. */
+function statusOf(participant) {
+	if (participant instanceof Observable) return participant.status;
+	return participant.status;
+}
+
+//#endregion
+//#region src/core/inspect/graph.ts
+/**
+* Describes every reactive node alive in this process, without touching the reactive system (#50,
+* A2-DX-2).
+*
+* There is no way to name where to start, and that is the point: the graph has no roots, and the
+* nodes worth finding — the ones leaked because nothing disposed them — are exactly the ones no
+* handle points at any more. So the dump comes from a census kept as nodes are created, held weakly:
+* a node the garbage collector has taken is gone from it, and one that lingers shows up as an orphan.
+*
+* Passivity is the same contract as {@link inspect}: statuses are read, registries iterated, nothing
+* computed. In particular a lazy derivation never read has no dependencies yet and appears as an
+* orphan — see {@link inspect} for what to do about it.
+*
+* @param options - See {@link FlowGraphOptions}
+* @returns Every node, in creation order, with a {@link FlowGraphSummary}
+*
+* @public
+*/
+function graphSnapshot(options) {
+	const includeDisposed = options?.includeDisposed ?? false;
+	const nodes = [];
+	LiveNodeRegistry.forEach((participant) => {
+		const snapshot = snapshotOf(participant);
+		if (!includeDisposed && snapshot.status === "disposed") return;
+		nodes.push(snapshot);
+	});
+	const byKind = {};
+	const byStatus = {};
+	let orphans = 0;
+	for (const node of nodes) {
+		byKind[node.kind] = (byKind[node.kind] ?? 0) + 1;
+		byStatus[node.status] = (byStatus[node.status] ?? 0) + 1;
+		if (node.dependencies.length === 0 && node.dependents.length === 0) orphans++;
+	}
+	return {
+		nodes,
+		summary: {
+			total: nodes.length,
+			byKind,
+			byStatus,
+			orphans
+		}
+	};
+}
+
+//#endregion
+//#region src/core/inspect/format.ts
+/** Widest a column is padded to; a longer label simply pushes its own line out. */
+const MAX_COLUMN = 24;
+/**
+* Renders a graph as readable text (#50, A2-DX-2).
+*
+* The intended use is a developer with the browser console open, mid-session, asking what the graph
+* looks like right now: `console.log(formatGraph())`. It returns a string rather than printing one,
+* so the same call works in a terminal, in a test, or pasted into a bug report — and so the library
+* never writes to anyone's console on its own.
+*
+* One block per node: a line naming it, its kind and its status, followed by its value when it has
+* one (`= …`) or its error (`! …`), then an indented line of edges — `←` for what it reads, `→` for
+* what reads it. Nodes with no edges at all are gathered at the end under `orphans`, where a leak
+* shows up as a list that keeps growing.
+*
+* @param graph - A snapshot to render; taken with {@link graphSnapshot} when omitted
+* @returns The rendered listing
+*
+* @public
+*/
+function formatGraph(graph = graphSnapshot()) {
+	const { nodes, summary } = graph;
+	const counts = Object.entries(summary.byStatus).map(([status, count]) => `${status}:${count}`);
+	if (summary.orphans > 0) counts.push(`orphans:${summary.orphans}`);
+	const header = `picoflow graph — ${summary.total} node${summary.total === 1 ? "" : "s"}${counts.length > 0 ? ` · ${counts.join(" · ")}` : ""}`;
+	if (nodes.length === 0) return header;
+	const connected = nodes.filter((node) => node.dependencies.length > 0 || node.dependents.length > 0);
+	const orphans = nodes.filter((node) => node.dependencies.length === 0 && node.dependents.length === 0);
+	const labelWidth = width(nodes, (node) => node.label);
+	const kindWidth = width(nodes, (node) => node.kind);
+	const lines = [header, ""];
+	for (const node of connected) lines.push(...block(node, labelWidth, kindWidth));
+	if (orphans.length > 0) {
+		if (connected.length > 0) lines.push("");
+		lines.push("orphans — no edges:");
+		for (const node of orphans) lines.push(...block(node, labelWidth, kindWidth));
+	}
+	return lines.join("\n");
+}
+/** The node's own line, plus its edge line when it has any. */
+function block(node, labelWidth, kindWidth) {
+	const status = node.eager ? `${node.status} (eager)` : node.status;
+	let line = `${pad(node.label, labelWidth)}  ${pad(node.kind, kindWidth)}  ${pad(status, 8)}`;
+	if (node.value !== void 0) line += `  = ${node.value}`;
+	if (node.error !== void 0) line += `  ! ${node.error}`;
+	const lines = [line.trimEnd()];
+	const edges = [];
+	if (node.dependencies.length > 0) edges.push(`← ${node.dependencies.map((ref) => ref.label).join(", ")}`);
+	if (node.dependents.length > 0) edges.push(`→ ${node.dependents.map((ref) => ref.label).join(", ")}`);
+	if (edges.length > 0) lines.push(`  ${edges.join("   ")}`);
+	return lines;
+}
+function width(nodes, of) {
+	return Math.min(MAX_COLUMN, Math.max(...nodes.map((node) => of(node).length)));
+}
+function pad(text, to) {
+	return text.length >= to ? text : text + " ".repeat(to - text.length);
+}
+
+//#endregion
+//#region src/core/inspect/trace.ts
+/**
+* Records what the engine does, so that a question about *time* can be answered (#50, A2-DX-2).
+*
+* `inspect()` and `graphSnapshot()` describe the graph's shape at an instant; some questions are not
+* about shape. "I wrote to `$count` and my effect never ran" is answered by reading the sequence: a
+* `notify` on `$count` with no `queue-effect` behind it means the edge was never there, while a
+* `queue-effect` with no `effect-run` means the flush never reached it. A feedback loop reads as an
+* alternation of `notify` and `effect-run` ending in `cycle-error`, which is how the nodes involved
+* get named — the error alone names neither.
+*
+* Tracing is off until this is called, and costs one boolean check per engine event while it is.
+* Recording does not change what the engine does: events are observed as they pass, never injected.
+*
+* @param options - See {@link FlowTraceOptions}
+* @returns The running trace; call `dispose()` on it to stop
+*
+* @public
+*/
+function enableTrace(options) {
+	const capacity = Math.max(1, Math.trunc(options?.capacity ?? 500));
+	let buffer = [];
+	let next = 0;
+	let seq = 0;
+	const listener = (type, node) => {
+		const event = {
+			seq: seq++,
+			type,
+			node: refOf(node)
+		};
+		if (buffer.length < capacity) buffer.push(event);
+		else buffer[next] = event;
+		next = (next + 1) % capacity;
+	};
+	TraceHub.listen(listener);
+	return {
+		get events() {
+			return buffer.length < capacity ? [...buffer] : [...buffer.slice(next), ...buffer.slice(0, next)];
+		},
+		clear() {
+			buffer = [];
+			next = 0;
+		},
+		dispose() {
+			TraceHub.unlisten(listener);
+		}
+	};
+}
+
+//#endregion
+export { enableTrace, formatGraph, graphSnapshot, inspect };