@zoijs/core 1.3.1 → 1.4.0

package/src/devtools.d.ts

@@ -0,0 +1,56 @@
+// Type surface for `@zoijs/core/devtools` — the read-only reactive-graph
+// inspection hook (RFC 0005). This is dev-tooling, NOT part of the stable
+// nine-function API; it lives behind its own subpath so the learnable surface
+// stays frozen. See `src/reactivity/devtools.js`.
+
+/** What a node is. */
+export type NodeKind = "state" | "computed" | "effect";
+
+/**
+ * A reactive graph node. Treat it as an opaque identity with a few read-only
+ * fields — never mutate it. `sources` / `observers` let an inspector walk the
+ * graph on demand (so reads stay un-instrumented). `fn` is present on
+ * computeds/effects, absent on states.
+ */
+export interface ReactiveNode {
+  readonly value?: unknown;
+  readonly fn?: Function | null;
+  readonly sources?: ReadonlySet<ReactiveNode>;
+  readonly observers: ReadonlySet<ReactiveNode>;
+  readonly disposed?: boolean;
+}
+
+/**
+ * A tag the renderer attaches to a binding node, naming the DOM it updates:
+ * a text slot, an attribute, or a keyed list. Lets an inspector show *which DOM
+ * node each signal updates*.
+ */
+export interface NodeLabel {
+  kind: "text" | "attr" | "list";
+  el: Node;
+  name?: string;
+}
+
+/**
+ * Implement this to observe the reactive graph. Every callback is read-only and
+ * fires only in dev mode while attached. `onCreate` is called once per node;
+ * `onRun` each time a computed/effect recomputes; `onWrite` each time a state
+ * actually changes; `onDispose` when a computed/effect leaves the graph.
+ */
+export interface Inspector {
+  onAttach?(): void;
+  onCreate(node: ReactiveNode, kind: NodeKind, label?: NodeLabel): void;
+  onRun(node: ReactiveNode): void;
+  onWrite(node: ReactiveNode): void;
+  onDispose(node: ReactiveNode): void;
+}
+
+/**
+ * Attach a read-only inspector; returns a detach function. A no-op (returns a
+ * no-op) under `configure({ dev: false })`, so an inspector can never run
+ * against an app shipped in production mode.
+ */
+export function attachInspector(inspector: Inspector): () => void;
+
+/** True while an inspector is attached. */
+export function inspecting(): boolean;

package/src/index.d.ts

@@ -1,185 +1,185 @@
-// Type definitions for Zoijs.
-//
-// Zoijs is authored in plain JavaScript; these declarations add editor
-// autocomplete and optional type-checking WITHOUT converting the project to
-// TypeScript. Using them is entirely opt-in — JS users are unaffected.
-
-/** A reactive value created by {@link createState}. */
-export interface State<T> {
-  /** Read the current value. Inside a binding/effect this subscribes to it. */
-  get(): T;
-  /** Write a new value. Dependents update only if the value actually changed. */
-  set(next: T): void;
-  /** Read the current value WITHOUT subscribing. */
-  peek(): T;
-}
-
-/** A lazy, cached, value-gated derived value created by {@link computed}. */
-export interface Computed<T> {
-  /** Read the current value. Recomputes only if a dependency changed. */
-  get(): T;
-  /** Read without subscribing. */
-  peek(): T;
-}
-
-declare const templateBrand: unique symbol;
-/**
- * The result of an `html` template. Pass it to {@link mount}, return it from a
- * component, or place it in another template. Treat it as opaque.
- */
-export interface TemplateResult {
-  readonly [templateBrand]: true;
-}
-
-declare const eachBrand: unique symbol;
-/** The result of {@link each}. Place it in a template's child position. */
-export interface EachResult {
-  readonly [eachBrand]: true;
-}
-
-/** A component is a function that returns an `html` template. */
-export type Component = () => TemplateResult;
-
-/**
- * A callback ref. Place it on an element as `ref=${fn}`; it receives the real DOM
- * element once the surrounding render has been inserted (deferred one microtask,
- * so `focus()` / `scrollIntoView()` / `getBoundingClientRect()` work). It may
- * return a cleanup function, which runs on unmount or list-item removal. It runs
- * once and is not reactive.
- *
- * ```ts
- * html`<input ref=${(el: HTMLInputElement) => el.focus()} />`
- * html`<div ref=${(el) => { const c = chart(el); return () => c.destroy(); }}></div>`
- * ```
- */
-export type Ref<E extends Element = Element> = (element: E) => void | (() => void);
-
-/**
- * Tagged-template function — write your markup as HTML.
- *
- * ```js
- * html`<button onclick=${() => count.set(count.get() + 1)}>${() => count.get()}</button>`
- * ```
- *
- * To reach the rendered DOM element, add a callback `ref` (see {@link Ref}):
- * `html\`<input ref=${(el) => el.focus()} />\``.
- */
-export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
-
-/**
- * Render a component (or a template) into a DOM element or CSS selector.
- * Returns an `unmount()` that detaches the DOM and disposes all reactivity.
- */
-export function mount(component: Component | TemplateResult, target: Element | string): () => void;
-
-/**
- * Create a reactive value.
- *
- * ```ts
- * const count = createState(0);        // State<number>
- * const name = createState<string>(""); // explicit
- * ```
- */
-export function createState<T>(initial: T, equals?: (a: T, b: T) => boolean): State<T>;
-
-/**
- * Create a lazy, cached derived value.
- *
- * ```ts
- * const fullName = computed(() => `${first.get()} ${last.get()}`); // Computed<string>
- * ```
- */
-export function computed<T>(fn: () => T, equals?: (a: T, b: T) => boolean): Computed<T>;
-
-/** A disposable handle returned by {@link effect}. */
-export interface EffectHandle {
-  /** Dispose the effect now. It also auto-disposes with its owner (component/list item). */
-  dispose(): void;
-}
-
-/**
- * Run a side effect that re-runs whenever a reactive value it reads changes.
- * Runs once immediately, then again (batched on a microtask) on any change.
- * Dependencies are tracked automatically — there is no dependency array.
- *
- * The function may return a cleanup function (same convention as a `ref`); it
- * runs **before the next run** and **on dispose**. Use the return value for
- * per-run teardown — `onCleanup` is component-scoped (fires on unmount), not
- * per-run.
- *
- * Created inside a component or list item, it auto-disposes with that scope;
- * created at module top level, it lives until you call `dispose()`.
- *
- * ```ts
- * // persist on change
- * effect(() => localStorage.setItem("theme", theme.get()));
- *
- * // per-run cleanup
- * effect(() => {
- *   const id = setInterval(() => poll(query.get()), 1000);
- *   return () => clearInterval(id);
- * });
- * ```
- *
- * For reactive *content on screen*, use a binding (`${() => …}`), not an effect.
- */
-export function effect(fn: () => void | (() => void)): EffectHandle;
-
-/**
- * Keyed list rendering. `items` may be a reactive function or a plain array;
- * `keyFn` returns a stable unique key; `renderFn` returns the template for one item.
- *
- * ```ts
- * each(() => todos.get(), (t) => t.id, (t) => html`<li>${() => t.text}</li>`)
- * ```
- */
-export function each<T>(
-  items: () => readonly T[],
-  keyFn: (item: T) => unknown,
-  renderFn: (item: T) => TemplateResult
-): EachResult;
-export function each<T>(
-  items: readonly T[],
-  keyFn: (item: T) => unknown,
-  renderFn: (item: T) => TemplateResult
-): EachResult;
-
-/**
- * Render `child`; if it **throws synchronously while building its markup** (a
- * setup/render error that would otherwise break the whole `mount`), tear down the
- * partial work and render `fallback` instead. Place the call in a template slot.
- *
- * Catches synchronous setup/render throws only. Errors in reactive *updates* are
- * already contained per binding by the core; *async* errors belong to
- * `@zoijs/resource` / `@zoijs/action`'s `error()` state. It renders once (no reset
- * — re-mount the subtree to retry), logs in dev, and is silent in production.
- *
- * ```ts
- * html`<section>
- *   ${boundary(() => RiskyWidget(), (err) => html`<p>Couldn't load this.</p>`)}
- * </section>`
- * ```
- */
-export function boundary<C, F>(
-  child: (() => C) | C,
-  fallback: ((error: unknown) => F) | F
-): C | F;
-
-/** Toggle development warnings (default: `dev` is `true`). */
-export function configure(options: { dev?: boolean }): void;
-
-/**
- * Register a teardown function for the current component or list item. It runs
- * when that component is unmounted or that list item is removed. Use it for
- * timers, subscriptions, or third-party widgets created during setup.
- *
- * ```ts
- * function Clock() {
- *   const now = createState(Date.now());
- *   const id = setInterval(() => now.set(Date.now()), 1000);
- *   onCleanup(() => clearInterval(id));
- *   return html`<time>${() => now.get()}</time>`;
- * }
- * ```
- */
-export function onCleanup(fn: () => void): void;
+// Type definitions for Zoijs.
+//
+// Zoijs is authored in plain JavaScript; these declarations add editor
+// autocomplete and optional type-checking WITHOUT converting the project to
+// TypeScript. Using them is entirely opt-in — JS users are unaffected.
+
+/** A reactive value created by {@link createState}. */
+export interface State<T> {
+  /** Read the current value. Inside a binding/effect this subscribes to it. */
+  get(): T;
+  /** Write a new value. Dependents update only if the value actually changed. */
+  set(next: T): void;
+  /** Read the current value WITHOUT subscribing. */
+  peek(): T;
+}
+
+/** A lazy, cached, value-gated derived value created by {@link computed}. */
+export interface Computed<T> {
+  /** Read the current value. Recomputes only if a dependency changed. */
+  get(): T;
+  /** Read without subscribing. */
+  peek(): T;
+}
+
+declare const templateBrand: unique symbol;
+/**
+ * The result of an `html` template. Pass it to {@link mount}, return it from a
+ * component, or place it in another template. Treat it as opaque.
+ */
+export interface TemplateResult {
+  readonly [templateBrand]: true;
+}
+
+declare const eachBrand: unique symbol;
+/** The result of {@link each}. Place it in a template's child position. */
+export interface EachResult {
+  readonly [eachBrand]: true;
+}
+
+/** A component is a function that returns an `html` template. */
+export type Component = () => TemplateResult;
+
+/**
+ * A callback ref. Place it on an element as `ref=${fn}`; it receives the real DOM
+ * element once the surrounding render has been inserted (deferred one microtask,
+ * so `focus()` / `scrollIntoView()` / `getBoundingClientRect()` work). It may
+ * return a cleanup function, which runs on unmount or list-item removal. It runs
+ * once and is not reactive.
+ *
+ * ```ts
+ * html`<input ref=${(el: HTMLInputElement) => el.focus()} />`
+ * html`<div ref=${(el) => { const c = chart(el); return () => c.destroy(); }}></div>`
+ * ```
+ */
+export type Ref<E extends Element = Element> = (element: E) => void | (() => void);
+
+/**
+ * Tagged-template function — write your markup as HTML.
+ *
+ * ```js
+ * html`<button onclick=${() => count.set(count.get() + 1)}>${() => count.get()}</button>`
+ * ```
+ *
+ * To reach the rendered DOM element, add a callback `ref` (see {@link Ref}):
+ * `html\`<input ref=${(el) => el.focus()} />\``.
+ */
+export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
+
+/**
+ * Render a component (or a template) into a DOM element or CSS selector.
+ * Returns an `unmount()` that detaches the DOM and disposes all reactivity.
+ */
+export function mount(component: Component | TemplateResult, target: Element | string): () => void;
+
+/**
+ * Create a reactive value.
+ *
+ * ```ts
+ * const count = createState(0);        // State<number>
+ * const name = createState<string>(""); // explicit
+ * ```
+ */
+export function createState<T>(initial: T, equals?: (a: T, b: T) => boolean): State<T>;
+
+/**
+ * Create a lazy, cached derived value.
+ *
+ * ```ts
+ * const fullName = computed(() => `${first.get()} ${last.get()}`); // Computed<string>
+ * ```
+ */
+export function computed<T>(fn: () => T, equals?: (a: T, b: T) => boolean): Computed<T>;
+
+/** A disposable handle returned by {@link effect}. */
+export interface EffectHandle {
+  /** Dispose the effect now. It also auto-disposes with its owner (component/list item). */
+  dispose(): void;
+}
+
+/**
+ * Run a side effect that re-runs whenever a reactive value it reads changes.
+ * Runs once immediately, then again (batched on a microtask) on any change.
+ * Dependencies are tracked automatically — there is no dependency array.
+ *
+ * The function may return a cleanup function (same convention as a `ref`); it
+ * runs **before the next run** and **on dispose**. Use the return value for
+ * per-run teardown — `onCleanup` is component-scoped (fires on unmount), not
+ * per-run.
+ *
+ * Created inside a component or list item, it auto-disposes with that scope;
+ * created at module top level, it lives until you call `dispose()`.
+ *
+ * ```ts
+ * // persist on change
+ * effect(() => localStorage.setItem("theme", theme.get()));
+ *
+ * // per-run cleanup
+ * effect(() => {
+ *   const id = setInterval(() => poll(query.get()), 1000);
+ *   return () => clearInterval(id);
+ * });
+ * ```
+ *
+ * For reactive *content on screen*, use a binding (`${() => …}`), not an effect.
+ */
+export function effect(fn: () => void | (() => void)): EffectHandle;
+
+/**
+ * Keyed list rendering. `items` may be a reactive function or a plain array;
+ * `keyFn` returns a stable unique key; `renderFn` returns the template for one item.
+ *
+ * ```ts
+ * each(() => todos.get(), (t) => t.id, (t) => html`<li>${() => t.text}</li>`)
+ * ```
+ */
+export function each<T>(
+  items: () => readonly T[],
+  keyFn: (item: T) => unknown,
+  renderFn: (item: T) => TemplateResult
+): EachResult;
+export function each<T>(
+  items: readonly T[],
+  keyFn: (item: T) => unknown,
+  renderFn: (item: T) => TemplateResult
+): EachResult;
+
+/**
+ * Render `child`; if it **throws synchronously while building its markup** (a
+ * setup/render error that would otherwise break the whole `mount`), tear down the
+ * partial work and render `fallback` instead. Place the call in a template slot.
+ *
+ * Catches synchronous setup/render throws only. Errors in reactive *updates* are
+ * already contained per binding by the core; *async* errors belong to
+ * `@zoijs/resource` / `@zoijs/action`'s `error()` state. It renders once (no reset
+ * — re-mount the subtree to retry), logs in dev, and is silent in production.
+ *
+ * ```ts
+ * html`<section>
+ *   ${boundary(() => RiskyWidget(), (err) => html`<p>Couldn't load this.</p>`)}
+ * </section>`
+ * ```
+ */
+export function boundary<C, F>(
+  child: (() => C) | C,
+  fallback: ((error: unknown) => F) | F
+): C | F;
+
+/** Toggle development warnings (default: `dev` is `true`). */
+export function configure(options: { dev?: boolean }): void;
+
+/**
+ * Register a teardown function for the current component or list item. It runs
+ * when that component is unmounted or that list item is removed. Use it for
+ * timers, subscriptions, or third-party widgets created during setup.
+ *
+ * ```ts
+ * function Clock() {
+ *   const now = createState(Date.now());
+ *   const id = setInterval(() => now.set(Date.now()), 1000);
+ *   onCleanup(() => clearInterval(id));
+ *   return html`<time>${() => now.get()}</time>`;
+ * }
+ * ```
+ */
+export function onCleanup(fn: () => void): void;

package/src/reactivity/core.js

@@ -16,6 +16,7 @@
 
 import { onCleanup } from "./owner.js";
 import { isDev } from "./env.js";
+import { reportCreate, reportRun, reportWrite, reportDispose } from "./devtools.js";
 
 const CLEAN = 0;
 const CHECK = 1;
@@ -70,6 +71,7 @@ function readNode(node) {
 function writeNode(node, next) {
   if (node.equals(node.value, next)) return; // equality-gated
   node.value = next;
+  reportWrite(node); // devtools: only fires on an actual change (dev + attached)
   for (const observer of [...node.observers]) markStale(observer, DIRTY);
 }
 
@@ -120,6 +122,7 @@ function runComputation(node) {
   } finally {
     currentObserver = previousObserver;
   }
+  reportRun(node); // devtools: this node actually recomputed (dev + attached)
   if (node.isEffect) {
     // An effect may return a cleanup function (same convention as a ref): it runs
     // before the next run and on dispose. Anything else is ignored.
@@ -156,6 +159,7 @@ function disposeNode(node) {
   node.disposed = true;
   cleanupSources(node);
   if (node.isEffect) runEffectCleanup(node); // final cleanup on dispose
+  reportDispose(node); // devtools: node left the graph (dev + attached)
 }
 
 const warned = new WeakSet();
@@ -169,6 +173,7 @@ function warnOnce(node, message) {
 
 export function createState(initial, equals = Object.is) {
   const node = { value: initial, observers: new Set(), equals, fn: null };
+  reportCreate(node, "state");
   return {
     get: () => readNode(node),
     set: (next) => writeNode(node, next),
@@ -188,6 +193,7 @@ export function computed(fn, equals = Object.is) {
     equals,
   };
   onCleanup(() => disposeNode(node)); // disposed with its owner scope
+  reportCreate(node, "computed");
   return {
     get: () => readNode(node),
     peek: () => {
@@ -209,6 +215,7 @@ export function effect(fn) {
     cleanup: null,
   };
   onCleanup(() => disposeNode(node)); // disposed with its owner scope
+  reportCreate(node, "effect"); // before its first run, so the run is attributed
   runComputation(node);
   node.state = CLEAN;
   return { dispose: () => disposeNode(node) };

package/src/reactivity/devtools.js

@@ -0,0 +1,77 @@
+// devtools.js — read-only inspection hook for the reactive graph (RFC 0005).
+//
+// This is the ONE seam between the engine and an external inspector
+// (@zoijs/devtools, or a browser extension). It is, by construction:
+//
+//   • Off by default. Until something attaches, every report below is a single
+//     `if (!inspector) return` — so an un-inspected app (every production app)
+//     pays no measurable cost and exposes nothing.
+//   • Read-light. The HOT path — readNode, run on every `.get()` — is NOT
+//     instrumented. Only lifecycle points are (create / run / write / dispose).
+//     The inspector reads a node's `sources` / `observers` on demand for the
+//     graph view, so even an *attached* inspector adds no per-read cost.
+//   • Dev-only. attachInspector() is a no-op under configure({ dev:false }), so
+//     an inspector can never run against an app shipped in production mode.
+//   • Read-only. The engine hands the inspector raw nodes to OBSERVE; it never
+//     reads a value back from the inspector or lets it mutate the graph.
+//
+// Not part of the learnable nine-function surface — reached through the dedicated
+// subpath `@zoijs/core/devtools`, by tooling, never by application code.
+
+import { isDev } from "./env.js";
+
+let inspector = null;
+
+// A small stack lets the renderer tag the node(s) created while it wires a DOM
+// binding with the DOM they update (e.g. { kind:"text", el }); see labelNext.
+const labels = [];
+
+/**
+ * Attach a read-only inspector and start receiving reports. Returns a detach
+ * function. No-op (returns a no-op) in production mode or with a falsy inspector.
+ */
+export function attachInspector(next) {
+  if (!isDev() || !next) return () => {};
+  inspector = next;
+  if (inspector.onAttach) inspector.onAttach();
+  return () => {
+    if (inspector === next) inspector = null;
+  };
+}
+
+/** True while an inspector is attached — a cheap guard for optional extra work. */
+export function inspecting() {
+  return inspector !== null;
+}
+
+// ---- engine-side reports — each a no-op unless an inspector is attached -------
+
+export function reportCreate(node, kind) {
+  if (!inspector) return;
+  inspector.onCreate(node, kind, labels.length ? labels[labels.length - 1] : undefined);
+}
+export function reportRun(node) {
+  if (inspector) inspector.onRun(node);
+}
+export function reportWrite(node) {
+  if (inspector) inspector.onWrite(node);
+}
+export function reportDispose(node) {
+  if (inspector) inspector.onDispose(node);
+}
+
+/**
+ * Tag the node(s) created while `run` executes with `label` — used by the
+ * renderer to attribute a binding effect to the DOM node it updates. The label is
+ * only ever read inside reportCreate, so this costs one null-check when no
+ * inspector is attached.
+ */
+export function labelNext(label, run) {
+  if (!inspector) return run();
+  labels.push(label);
+  try {
+    return run();
+  } finally {
+    labels.pop();
+  }
+}