@shadow-js/devtools 0.0.0-stage → 1.0.0

package/dist/dev/model.d.ts

@@ -0,0 +1,418 @@
+import { WireEvent } from "./protocol.js";
+import { RingBuffer } from "./ring.js";
+//#region src/model.d.ts
+/**
+ * The kinds of node the inspector tracks: an owner, a signal, a memo, an effect, a resource or a store.
+ *
+ * @since 1.0.0
+ */
+export type NodeType = "owner" | "signal" | "memo" | "effect" | "resource" | "store";
+/**
+ * Everything the model knows about one node. Live nodes are in {@link InspectorModel.nodes}; disposed
+ * ones are kept in {@link InspectorModel.graveyard} for a while.
+ *
+ * @since 1.0.0
+ */
+export interface NodeRecord {
+  /** Id assigned by the agent. Never {@link NO_ID}. */
+  id: number;
+  /** What kind of node this is. */
+  type: NodeType;
+  /**
+   * How the node is labeled: `owner` or `root` for owners, `memo` or `effect` for computations,
+   * `signal`, `resource` or `store`, and `component` once a component was mounted on the owner.
+   */
+  label: string;
+  /** The name the code gave the node, or `undefined`. */
+  name: string | undefined;
+  /** Owner id, or {@link NO_ID} for roots and detached nodes. */
+  parent: number;
+  /** False once the node left the live set: disposed, cascaded from its owner, or garbage collected. */
+  alive: boolean;
+  /** Sequence number of the event that created the node. */
+  createdSeq: number;
+  /** Time of the creation event, in milliseconds on the agent's clock. */
+  createdAt: number;
+  /** Sequence number of the event that removed the node, or 0 while it is alive. */
+  disposedSeq: number;
+  /** Computations: created in the render phase (the runtime's render flag). False otherwise. */
+  render: boolean;
+  /** True once a component was mounted on this owner. */
+  isComponent: boolean;
+  /** Time the component was mounted (agent clock, in milliseconds), or 0 when it never was. */
+  mountedAt: number;
+  /** Computations: ids of the nodes read by the last run. Empty for other nodes. */
+  sources: number[];
+  /** Ids of the computations that currently read this node. `null` when none ever did. */
+  observers: Set<number> | null;
+  /** Number of runs recorded. 0 for nodes that never run. */
+  runs: number;
+  /** Sum of the durations of all runs, in milliseconds. */
+  totalDuration: number;
+  /** Duration of the last run, in milliseconds. */
+  lastDuration: number;
+  /** Start of the last run, in milliseconds as the runtime reported it. */
+  lastStart: number;
+  /** Sequence number of the last run, or 0 when it never ran. */
+  lastRunSeq: number;
+  /**
+   * Sequence number of the last change: a write for a signal, a run that changed the value for a
+   * computation, or a state report for a resource. 0 when there was none.
+   */
+  lastChangeSeq: number;
+  /** Signals: a short text of the current value. Empty for other nodes. */
+  preview: string;
+  /** Number of writes to a signal. 0 for other nodes. */
+  writes: number;
+  /** Sequence number of the last write, or 0 when never written. */
+  lastWriteSeq: number;
+  /**
+   * Id of the computation that performed the last write, or {@link NO_ID} for a write from outside
+   * any computation (an event handler, for example) and when the node was never written.
+   */
+  lastWriter: number;
+  /** Resources: the last reported state, for example `"pending"` or `"ready"`. Empty for other nodes. */
+  state: string;
+}
+/**
+ * Why a computation ran. A run has one cause per source that changed since the computation's previous
+ * run; see {@link RunRecord.causes}.
+ *
+ * @since 1.0.0
+ */
+export interface Cause {
+  /**
+   * `write` when the source is a signal that was written, `run` when the source is a memo or a
+   * resource that changed, `initial` for the first run, and `unknown` when no recorded source changed.
+   */
+  kind: "write" | "run" | "initial" | "unknown";
+  /** The source that changed: a signal or memo ({@link NO_ID} for `initial` and `unknown`). */
+  id: number;
+  /**
+   * Sequence number of that change: the write or the run of the source, the creation for `initial`,
+   * or the last run for `unknown`.
+   */
+  seq: number;
+}
+/**
+ * One run of an effect or a memo, as recorded.
+ *
+ * @since 1.0.0
+ */
+export interface RunRecord {
+  /** Sequence number of the run event. */
+  seq: number;
+  /** Time the event was received (agent clock, in milliseconds). */
+  t: number;
+  /** The computation that ran. */
+  id: number;
+  /** When the run started, in milliseconds as the runtime reported it. */
+  start: number;
+  /** How long the run took, in milliseconds. */
+  duration: number;
+  /** True when the computation's value changed. */
+  changed: boolean;
+  /** Sequence number of the flush it belongs to ({@link FlushRecord.seq}), or 0 when it ran outside a flush. */
+  flush: number;
+  /** Why it ran: see {@link Cause}. */
+  causes: Cause[];
+}
+/**
+ * One signal write, as recorded.
+ *
+ * @since 1.0.0
+ */
+export interface WriteRecord {
+  /** Sequence number of the write event. */
+  seq: number;
+  /** Time the event was received (agent clock, in milliseconds). */
+  t: number;
+  /** The signal that was written. */
+  id: number;
+  /** A short text of the value written. */
+  preview: string;
+  /** Computation that wrote ({@link NO_ID}: outside code such as an event handler). */
+  writer: number;
+  /** Ids of the computations that read the signal when it was written. */
+  observers: number[];
+}
+/**
+ * One flush of the effect queues. A flush is recorded only when at least one of its runs is recorded.
+ *
+ * @since 1.0.0
+ */
+export interface FlushRecord {
+  /** Sequence number of the flush-start event. */
+  seq: number;
+  /** The same value as {@link FlushRecord.seq}: the sequence number of the flush-start event. */
+  startSeq: number;
+  /** When the flush started (agent clock, in milliseconds). */
+  start: number;
+  /** When the flush ended (agent clock, in milliseconds). Equal to `start` while the flush is open. */
+  end: number;
+  /** Effects in the render queue when the flush started. */
+  render: number;
+  /** Effects in the user queue when the flush started. */
+  user: number;
+  /**
+   * Runs recorded during the flush. The model counts them itself, so runs the agent ignored (the
+   * tools' own) are not included. 0 while the flush is open.
+   */
+  runs: number;
+  /** True until the flush-end event arrives. */
+  open: boolean;
+}
+/**
+ * An error the runtime reported.
+ *
+ * @since 1.0.0
+ */
+export interface ErrorRecord {
+  /** Sequence number of the error event. */
+  seq: number;
+  /** Time the event was received (agent clock, in milliseconds). */
+  t: number;
+  /** The node the error came from, or {@link NO_ID} when it had no known owner. */
+  id: number;
+  /** The thrown value as text (see `errorMessage`). */
+  message: string;
+  /** A diagnostic code the runtime attached, for example `WRITE_IN_MEMO`, or `undefined`. */
+  code: string | undefined;
+}
+/**
+ * A hydration mismatch the runtime reported.
+ *
+ * @since 1.0.0
+ */
+export interface HydrationRecord {
+  /** Sequence number of the mismatch event. */
+  seq: number;
+  /** Time the event was received (agent clock, in milliseconds). */
+  t: number;
+  /** What the runtime reported, as text. */
+  message: string;
+  /** The expected side, as text: a string, or the HTML of an element. Cut to 200 characters. */
+  expected: string;
+  /** The actual side, as text: a string, or the HTML of an element. Cut to 200 characters. */
+  actual: string;
+}
+/**
+ * Capacities of the model's bounded buffers. When passed to the constructor each field is optional;
+ * the values left out are the defaults in {@link DEFAULT_LIMITS}.
+ *
+ * @since 1.0.0
+ */
+export interface ModelLimits {
+  /**
+   * Run records kept for timelines and causal chains.
+   *
+   * @default 20000
+   */
+  runs: number;
+  /**
+   * Write records kept for causal chains.
+   *
+   * @default 10000
+   */
+  writes: number;
+  /**
+   * Flush records kept.
+   *
+   * @default 1000
+   */
+  flushes: number;
+  /**
+   * Error records kept, and hydration records kept (each buffer on its own).
+   *
+   * @default 200
+   */
+  errors: number;
+  /**
+   * Disposed nodes kept so that old runs can still be named.
+   *
+   * @default 4000
+   */
+  graveyard: number;
+  /**
+   * Live nodes tracked. A node created beyond this count is counted in {@link InspectorModel.overflow}
+   * and ignored; later events about it count as unknown.
+   *
+   * @default 100000
+   */
+  maxNodes: number;
+}
+/**
+ * The default capacities of the model's buffers, used for each limit that the caller leaves out.
+ *
+ * @example
+ * import { DEFAULT_LIMITS, foldEvents } from "@shadow-js/devtools";
+ * import type { WireEvent } from "@shadow-js/devtools";
+ *
+ * const events: WireEvent[] = [];
+ * const model = foldEvents(events, { ...DEFAULT_LIMITS, runs: 500 });
+ * @since 1.0.0
+ */
+export declare const DEFAULT_LIMITS: Readonly<ModelLimits>;
+/**
+ * The JSON-safe state of a model: what the agent's `state()` returns (for a remote panel) and what
+ * {@link InspectorModel.importState} accepts.
+ *
+ * @since 1.0.0
+ */
+export interface ModelState {
+  /** Sequence number of the last applied event. */
+  lastSeq: number;
+  /** Nodes ignored because `maxNodes` was reached. */
+  overflow: number;
+  /** Events that referred to a node the model does not know. */
+  unknown: number;
+  /** Live nodes, in insertion order, with observers as arrays. */
+  nodes: Array<Omit<NodeRecord, "observers"> & {
+    observers: number[];
+  }>;
+  /** Disposed nodes, oldest first, with observers as arrays. */
+  graveyard: Array<Omit<NodeRecord, "observers"> & {
+    observers: number[];
+  }>;
+  /** Run records, oldest first. */
+  runs: RunRecord[];
+  /** Write records, oldest first. */
+  writes: WriteRecord[];
+  /** Flush records, oldest first. */
+  flushes: FlushRecord[];
+  /** Error records, oldest first. */
+  errors: ErrorRecord[];
+  /** Hydration records, oldest first. */
+  hydration: HydrationRecord[];
+}
+/**
+ * The inspector's incremental model of the reactive graph: a pure fold over {@link WireEvent}s. The
+ * same events always produce the same state, on the page or in a remote panel. `apply` is O(1) for
+ * most events and O(sources) for a run; memory is bounded by {@link ModelLimits}.
+ *
+ * A development tool: its events come from the dev hook, which exists only in development builds.
+ *
+ * @example
+ * import { InspectorModel, snapshotOf } from "@shadow-js/devtools";
+ * import type { WireEvent } from "@shadow-js/devtools";
+ *
+ * const events: WireEvent[] = [];
+ * const model = new InspectorModel();
+ * for (const event of events) model.apply(event);
+ * snapshotOf(model).counts.nodes;
+ * @since 1.0.0
+ */
+export declare class InspectorModel {
+  /** The capacities in effect: the defaults with the constructor's overrides applied. */
+  readonly limits: Readonly<ModelLimits>;
+  /** Live nodes by id. */
+  readonly nodes: Map<number, NodeRecord>;
+  /**
+   * Recently disposed nodes, oldest first, kept so that history can still be named. Holds at most
+   * `limits.graveyard` nodes.
+   */
+  readonly graveyard: Map<number, NodeRecord>;
+  /** Run records, the newest kept (capacity `limits.runs`). */
+  readonly runs: RingBuffer<RunRecord>;
+  /** Write records, the newest kept (capacity `limits.writes`). */
+  readonly writes: RingBuffer<WriteRecord>;
+  /** Flush records, the newest kept (capacity `limits.flushes`). */
+  readonly flushes: RingBuffer<FlushRecord>;
+  /** Error records, the newest kept (capacity `limits.errors`). */
+  readonly errors: RingBuffer<ErrorRecord>;
+  /** Hydration records, the newest kept (capacity `limits.errors`). */
+  readonly hydration: RingBuffer<HydrationRecord>;
+  /** Sequence number of the last applied event. */
+  lastSeq: number;
+  /** Nodes ignored because `maxNodes` was reached. */
+  overflow: number;
+  /** Events that referred to a node the model does not know. */
+  unknown: number;
+  /**
+   * Changes whenever a component is mounted, unmounted or disposed. Cached component lookups from an
+   * older epoch are recomputed.
+   */
+  componentEpoch: number;
+  /** Entries in the component lookup cache. Never more than `limits.maxNodes` after a lookup. */
+  get componentCacheSize(): number;
+  /**
+   * Called once for every node that leaves the live set, after it moved to the graveyard: when it is
+   * disposed, or when its owner is disposed (cascade). The agent uses it to drop its own references.
+   */
+  onBury: ((record: NodeRecord) => void) | undefined;
+  private openFlush;
+  private flushRuns;
+  /** Signals, stores and resources by owner: they have no lifecycle event of their own. */
+  private readonly leaves;
+  private readonly componentCache;
+  /**
+   * @param limits Overrides for the buffer capacities. Values left out take the defaults in
+   * {@link DEFAULT_LIMITS}.
+   */
+  constructor(limits?: Partial<ModelLimits>);
+  /**
+   * The node with this id: alive, or recently disposed (in the graveyard).
+   *
+   * @param id The node id.
+   * @returns The record, or `undefined` when the model does not know the id.
+   */
+  node(id: number): NodeRecord | undefined;
+  private create;
+  /** Remembers that a leaf node (signal, store, resource) belongs to `owner`. */
+  private addLeaf;
+  private bury;
+  private setSources;
+  /**
+   * Applies one event. Events must arrive in `seq` order: an event whose `seq` is not greater than
+   * {@link InspectorModel.lastSeq} is ignored, so a remote panel can receive events it already holds.
+   * An event about a node the model does not know is counted in `unknown`. A node created beyond
+   * `maxNodes` is counted in `overflow` and ignored.
+   *
+   * @param event The event, with the sequence number and time the agent gave it.
+   */
+  apply(event: WireEvent): void;
+  /** Why a computation is about to run again: sources that changed since its last run. */
+  private causesOf;
+  /**
+   * The nearest component that owns `id`: the node itself when it is a component, otherwise the first
+   * component above it in the owner chain (the graveyard included). The answer is cached until the next
+   * component mount, unmount or disposal.
+   *
+   * @param id The node id.
+   * @returns The component's id, or {@link NO_ID} when no component owns the node.
+   */
+  componentOf(id: number): number;
+  /**
+   * A serializable copy of the whole state, safe to send as JSON. {@link InspectorModel.importState}
+   * rebuilds an equal model from it.
+   *
+   * @returns The state.
+   */
+  exportState(): ModelState;
+  /**
+   * Replaces the whole state with `state`. A remote panel does this with the agent's state, and the
+   * agent does it with an empty state to implement `clear`. The capacities of this model do not change:
+   * when `state` holds more records than a buffer can keep, the newest are kept.
+   *
+   * @param state The state to load.
+   */
+  importState(state: ModelState): void;
+}
+/**
+ * Builds a model from a finished event stream. A pure function: the same input always gives the same
+ * model. A development tool, like {@link InspectorModel}.
+ *
+ * @param events Events in `seq` order.
+ * @param limits Buffer capacities. Values left out take the defaults in {@link DEFAULT_LIMITS}.
+ * @returns The folded model.
+ * @example
+ * import { foldEvents } from "@shadow-js/devtools";
+ * import type { WireEvent } from "@shadow-js/devtools";
+ *
+ * const events: WireEvent[] = [];
+ * const model = foldEvents(events, { runs: 1000 });
+ * @since 1.0.0
+ */
+export declare function foldEvents(events: Iterable<WireEvent>, limits?: Partial<ModelLimits>): InspectorModel;
+//#endregion
+//# sourceMappingURL=model.d.ts.map