@graphrefly/graphrefly 0.25.0 → 0.27.0

package/dist/sugar-CCOxXK1e.d.ts

@@ -0,0 +1,201 @@
+import { a as NodeOptions, F as FnCtx, N as Node, t as NodeActions, x as NodeFnCleanup } from './node-BmerH3kS.js';
+
+/**
+ * Sugar constructors over the raw `node()` primitive.
+ *
+ * Each factory wraps a user-friendly function into the canonical
+ * `NodeFn = (data, actions, ctx) => cleanup | void` shape, then calls
+ * `node(...)`. This is the only place `actions.emit(...)` is invoked
+ * on behalf of the user — if you need finer control (multi-emission,
+ * raw `actions.down` / `actions.up`, cleanup return), use the raw
+ * `node()` factory from `./node.js` directly.
+ *
+ * See SESSION-foundation-redesign.md §8.5 + §10.6 for the rewrite.
+ */
+
+/**
+ * Creates a manual source node. Drive it with `state.emit(v)` (framed,
+ * diamond-safe) or `state.down([[DATA, v]])` (raw compat path).
+ *
+ * @param initial - Starting cached value. Pass `undefined` or `null`
+ *   explicitly to cache that value; omit to leave the node in `"sentinel"`.
+ * @param opts - Optional {@link NodeOptions} (excluding `initial`).
+ */
+declare function state<T>(initial: T, opts?: Omit<NodeOptions<T>, "initial">): Node<T>;
+/**
+ * User-level producer compute: runs once on first-subscriber activation.
+ * Receives `actions` for imperative emission and `ctx` for FnCtx (typically
+ * only `store` is useful on a producer — no deps means `prevData` and
+ * `terminalDeps` are empty).
+ */
+type ProducerFn = (actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
+/**
+ * Creates a producer node with no deps; `fn` runs once when the first
+ * subscriber connects. Return a cleanup function (`() => void`) or
+ * `{ deactivation: () => void }` to register teardown.
+ *
+ * @example
+ * ```ts
+ * const ticker = producer((actions) => {
+ *   const id = setInterval(() => actions.emit(Date.now()), 1000);
+ *   return () => clearInterval(id);
+ * });
+ * ```
+ */
+declare function producer<T = unknown>(fn: ProducerFn, opts?: NodeOptions<T>): Node<T>;
+/**
+ * User-level derived compute: receives the latest DATA from each dep and
+ * returns the new value. The sugar wraps it with `actions.emit(fn(...))`
+ * so the return value flows through the framed emit pipeline.
+ *
+ * For derived nodes that need to inspect `ctx.prevData` / `ctx.terminalDeps`
+ * / `ctx.store`, accept the optional second parameter.
+ */
+type DerivedFn<T> = (data: readonly unknown[], ctx: FnCtx) => T | undefined | null;
+/**
+ * Creates a derived node that computes **one output per wave** from the latest
+ * value of each dependency — **snapshot / combine semantics**.
+ *
+ * `fn` receives one scalar per dep (the last DATA value seen this wave, or the
+ * prior-wave value as fallback). It is called once per settled wave and emits
+ * a single value via `actions.emit`. The equals check then suppresses the
+ * emission as `RESOLVED` if the output has not changed.
+ *
+ * **Not for streaming one-to-one transforms.** If each DATA value in a batch
+ * must produce a corresponding output (e.g. transforming every item emitted by
+ * `fromIter` individually), use {@link map} or raw `node()` with full batch
+ * iteration instead. `derived` only sees the *last* value per dep when a batch
+ * carries multiple DATAs.
+ *
+ * @example
+ * ```ts
+ * const a = state(1);
+ * const b = derived([a], ([x]) => (x as number) * 2);
+ * ```
+ */
+declare function derived<T = unknown>(deps: readonly Node[], fn: DerivedFn<T>, opts?: NodeOptions<T> & {
+    partial?: boolean;
+}): Node<T>;
+/**
+ * User-level effect compute: fires when deps settle. Return value is NOT
+ * auto-emitted — use `actions.emit(v)` / `actions.down(msgs)` explicitly if
+ * the effect also wants to produce downstream messages. Return a cleanup
+ * function or `{ deactivation }` to register teardown.
+ */
+type EffectFn = (data: readonly unknown[], actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
+/**
+ * Runs a side-effect when deps settle. Return value is not auto-emitted.
+ *
+ * @example
+ * ```ts
+ * effect([source], ([v]) => {
+ *   console.log(v);
+ * });
+ * ```
+ */
+declare function effect(deps: readonly Node[], fn: EffectFn, opts?: NodeOptions<unknown> & {
+    partial?: boolean;
+}): Node<unknown>;
+/**
+ * Proxy handed to a {@link DynamicFn}. `track(dep)` returns the dep's
+ * latest DATA payload, as delivered through the protocol. Reading from
+ * `track` does NOT bypass the message protocol — it reads the internal
+ * `DepRecord.prevData` (the stable end-of-previous-wave value) that
+ * `_onDepMessage` already populated. If a dep has not yet sent DATA,
+ * `track` returns `undefined`.
+ */
+type TrackFn = (dep: Node) => unknown;
+/** User-level dynamicNode compute. */
+type DynamicFn<T> = (track: TrackFn, ctx: FnCtx) => T | undefined | null;
+/**
+ * Sugar over `derived(...)` that exposes dep values via a `track(dep)`
+ * proxy instead of positional `data[i]`. All declared `allDeps` participate
+ * in wave tracking, so the first fn run waits for every dep to settle.
+ * Unused deps that update just re-run fn; `equals` absorbs unchanged
+ * outputs as RESOLVED.
+ *
+ * P3-compliant: `track(dep)` reads from the framework-managed
+ * `DepRecord.prevData` populated by the protocol, never from
+ * `dep.cache`.
+ *
+ * @example
+ * ```ts
+ * const a = state(1);
+ * const b = state(10);
+ * const sum = dynamicNode([a, b], (track) => (track(a) as number) + (track(b) as number));
+ * ```
+ */
+declare function dynamicNode<T = unknown>(allDeps: readonly Node[], fn: DynamicFn<T>, opts?: NodeOptions<T> & {
+    partial?: boolean;
+}): Node<T>;
+/**
+ * Like {@link dynamicNode} but deps are discovered at runtime via `track()`
+ * calls — no upfront `allDeps` array needed. Designed for pull-based compat
+ * layers (Jotai atoms, TC39 Signals) where deps are unknown until fn runs.
+ *
+ * **Two-phase discovery:**
+ * 1. fn runs. Each `track(dep)` for an unknown dep: subscribes immediately
+ *    via `_addDep`, returns `dep.cache` as a stub (P3 boundary exception).
+ *    Result is discarded (discovery run).
+ * 2. New deps settle (DATA from subscribe handshake). Wave machinery
+ *    re-triggers fn. `track(dep)` now returns protocol-delivered `data[i]`.
+ *    If MORE unknown deps appear, repeat step 1.
+ * 3. Converges when no new deps found → real run → `actions.emit(result)`.
+ *
+ * P3 violation is limited to discovery runs. Once all deps are known,
+ * subsequent waves use protocol-delivered values exclusively.
+ *
+ * Re-entrance safety: `_addDep` subscribes immediately. If the dep delivers
+ * DATA synchronously during fn execution, `_execFn`'s re-entrance guard
+ * defers the re-run to after the current fn returns.
+ *
+ * @param opts - Optional {@link AutoTrackOptions}. Pass `{ partial: true }` to
+ *   allow fn to run before all known deps have delivered their first value
+ *   (useful for optional/secondary deps).
+ *
+ * @example
+ * ```ts
+ * const a = state(1), b = state(2);
+ * const sum = autoTrackNode((track) => track(a) + track(b));
+ * // deps [a, b] discovered automatically on first run
+ * ```
+ */
+/**
+ * Options for {@link autoTrackNode}.
+ */
+interface AutoTrackOptions<T> extends NodeOptions<T> {
+    /**
+     * When `true`, fn may run before all known deps have delivered their first
+     * DATA. Unknown deps return `undefined` via `track()`, which the fn must
+     * handle explicitly. Useful when some deps are "nice-to-have" — e.g. a
+     * primary computation should continue while a secondary dep is still
+     * initialising.
+     *
+     * When `false` (default), fn is held until every known dep has delivered at
+     * least one DATA value — a RESOLVED is emitted for the wave instead.
+     * This matches `derived()` semantics and is the correct default for
+     * pull-based compat layers (Signals, Jotai) where all deps must be
+     * initialised before the computation is meaningful.
+     *
+     * @default false
+     */
+    partial?: boolean;
+}
+declare function autoTrackNode<T = unknown>(fn: (track: TrackFn, ctx: FnCtx) => T | undefined | null, opts?: AutoTrackOptions<T>): Node<T>;
+/** Unary operator used by {@link pipe}. */
+type PipeOperator = (n: Node) => Node;
+/**
+ * Composes unary operators left-to-right; returns the final node.
+ *
+ * @example
+ * ```ts
+ * const out = pipe(
+ *   source,
+ *   (n) => map(n, (x) => x + 1),
+ *   (n) => filter(n, (x) => x > 0),
+ * );
+ * ```
+ */
+declare function pipe(source: Node, ...ops: PipeOperator[]): Node;
+
+export { type AutoTrackOptions as A, type DerivedFn as D, type EffectFn as E, type PipeOperator as P, type TrackFn as T, type DynamicFn as a, type ProducerFn as b, autoTrackNode as c, derived as d, dynamicNode as e, effect as f, producer as g, pipe as p, state as s };

package/dist/sugar-D02n5JjF.d.cts

@@ -0,0 +1,201 @@
+import { a as NodeOptions, F as FnCtx, N as Node, t as NodeActions, x as NodeFnCleanup } from './node-BmerH3kS.cjs';
+
+/**
+ * Sugar constructors over the raw `node()` primitive.
+ *
+ * Each factory wraps a user-friendly function into the canonical
+ * `NodeFn = (data, actions, ctx) => cleanup | void` shape, then calls
+ * `node(...)`. This is the only place `actions.emit(...)` is invoked
+ * on behalf of the user — if you need finer control (multi-emission,
+ * raw `actions.down` / `actions.up`, cleanup return), use the raw
+ * `node()` factory from `./node.js` directly.
+ *
+ * See SESSION-foundation-redesign.md §8.5 + §10.6 for the rewrite.
+ */
+
+/**
+ * Creates a manual source node. Drive it with `state.emit(v)` (framed,
+ * diamond-safe) or `state.down([[DATA, v]])` (raw compat path).
+ *
+ * @param initial - Starting cached value. Pass `undefined` or `null`
+ *   explicitly to cache that value; omit to leave the node in `"sentinel"`.
+ * @param opts - Optional {@link NodeOptions} (excluding `initial`).
+ */
+declare function state<T>(initial: T, opts?: Omit<NodeOptions<T>, "initial">): Node<T>;
+/**
+ * User-level producer compute: runs once on first-subscriber activation.
+ * Receives `actions` for imperative emission and `ctx` for FnCtx (typically
+ * only `store` is useful on a producer — no deps means `prevData` and
+ * `terminalDeps` are empty).
+ */
+type ProducerFn = (actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
+/**
+ * Creates a producer node with no deps; `fn` runs once when the first
+ * subscriber connects. Return a cleanup function (`() => void`) or
+ * `{ deactivation: () => void }` to register teardown.
+ *
+ * @example
+ * ```ts
+ * const ticker = producer((actions) => {
+ *   const id = setInterval(() => actions.emit(Date.now()), 1000);
+ *   return () => clearInterval(id);
+ * });
+ * ```
+ */
+declare function producer<T = unknown>(fn: ProducerFn, opts?: NodeOptions<T>): Node<T>;
+/**
+ * User-level derived compute: receives the latest DATA from each dep and
+ * returns the new value. The sugar wraps it with `actions.emit(fn(...))`
+ * so the return value flows through the framed emit pipeline.
+ *
+ * For derived nodes that need to inspect `ctx.prevData` / `ctx.terminalDeps`
+ * / `ctx.store`, accept the optional second parameter.
+ */
+type DerivedFn<T> = (data: readonly unknown[], ctx: FnCtx) => T | undefined | null;
+/**
+ * Creates a derived node that computes **one output per wave** from the latest
+ * value of each dependency — **snapshot / combine semantics**.
+ *
+ * `fn` receives one scalar per dep (the last DATA value seen this wave, or the
+ * prior-wave value as fallback). It is called once per settled wave and emits
+ * a single value via `actions.emit`. The equals check then suppresses the
+ * emission as `RESOLVED` if the output has not changed.
+ *
+ * **Not for streaming one-to-one transforms.** If each DATA value in a batch
+ * must produce a corresponding output (e.g. transforming every item emitted by
+ * `fromIter` individually), use {@link map} or raw `node()` with full batch
+ * iteration instead. `derived` only sees the *last* value per dep when a batch
+ * carries multiple DATAs.
+ *
+ * @example
+ * ```ts
+ * const a = state(1);
+ * const b = derived([a], ([x]) => (x as number) * 2);
+ * ```
+ */
+declare function derived<T = unknown>(deps: readonly Node[], fn: DerivedFn<T>, opts?: NodeOptions<T> & {
+    partial?: boolean;
+}): Node<T>;
+/**
+ * User-level effect compute: fires when deps settle. Return value is NOT
+ * auto-emitted — use `actions.emit(v)` / `actions.down(msgs)` explicitly if
+ * the effect also wants to produce downstream messages. Return a cleanup
+ * function or `{ deactivation }` to register teardown.
+ */
+type EffectFn = (data: readonly unknown[], actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
+/**
+ * Runs a side-effect when deps settle. Return value is not auto-emitted.
+ *
+ * @example
+ * ```ts
+ * effect([source], ([v]) => {
+ *   console.log(v);
+ * });
+ * ```
+ */
+declare function effect(deps: readonly Node[], fn: EffectFn, opts?: NodeOptions<unknown> & {
+    partial?: boolean;
+}): Node<unknown>;
+/**
+ * Proxy handed to a {@link DynamicFn}. `track(dep)` returns the dep's
+ * latest DATA payload, as delivered through the protocol. Reading from
+ * `track` does NOT bypass the message protocol — it reads the internal
+ * `DepRecord.prevData` (the stable end-of-previous-wave value) that
+ * `_onDepMessage` already populated. If a dep has not yet sent DATA,
+ * `track` returns `undefined`.
+ */
+type TrackFn = (dep: Node) => unknown;
+/** User-level dynamicNode compute. */
+type DynamicFn<T> = (track: TrackFn, ctx: FnCtx) => T | undefined | null;
+/**
+ * Sugar over `derived(...)` that exposes dep values via a `track(dep)`
+ * proxy instead of positional `data[i]`. All declared `allDeps` participate
+ * in wave tracking, so the first fn run waits for every dep to settle.
+ * Unused deps that update just re-run fn; `equals` absorbs unchanged
+ * outputs as RESOLVED.
+ *
+ * P3-compliant: `track(dep)` reads from the framework-managed
+ * `DepRecord.prevData` populated by the protocol, never from
+ * `dep.cache`.
+ *
+ * @example
+ * ```ts
+ * const a = state(1);
+ * const b = state(10);
+ * const sum = dynamicNode([a, b], (track) => (track(a) as number) + (track(b) as number));
+ * ```
+ */
+declare function dynamicNode<T = unknown>(allDeps: readonly Node[], fn: DynamicFn<T>, opts?: NodeOptions<T> & {
+    partial?: boolean;
+}): Node<T>;
+/**
+ * Like {@link dynamicNode} but deps are discovered at runtime via `track()`
+ * calls — no upfront `allDeps` array needed. Designed for pull-based compat
+ * layers (Jotai atoms, TC39 Signals) where deps are unknown until fn runs.
+ *
+ * **Two-phase discovery:**
+ * 1. fn runs. Each `track(dep)` for an unknown dep: subscribes immediately
+ *    via `_addDep`, returns `dep.cache` as a stub (P3 boundary exception).
+ *    Result is discarded (discovery run).
+ * 2. New deps settle (DATA from subscribe handshake). Wave machinery
+ *    re-triggers fn. `track(dep)` now returns protocol-delivered `data[i]`.
+ *    If MORE unknown deps appear, repeat step 1.
+ * 3. Converges when no new deps found → real run → `actions.emit(result)`.
+ *
+ * P3 violation is limited to discovery runs. Once all deps are known,
+ * subsequent waves use protocol-delivered values exclusively.
+ *
+ * Re-entrance safety: `_addDep` subscribes immediately. If the dep delivers
+ * DATA synchronously during fn execution, `_execFn`'s re-entrance guard
+ * defers the re-run to after the current fn returns.
+ *
+ * @param opts - Optional {@link AutoTrackOptions}. Pass `{ partial: true }` to
+ *   allow fn to run before all known deps have delivered their first value
+ *   (useful for optional/secondary deps).
+ *
+ * @example
+ * ```ts
+ * const a = state(1), b = state(2);
+ * const sum = autoTrackNode((track) => track(a) + track(b));
+ * // deps [a, b] discovered automatically on first run
+ * ```
+ */
+/**
+ * Options for {@link autoTrackNode}.
+ */
+interface AutoTrackOptions<T> extends NodeOptions<T> {
+    /**
+     * When `true`, fn may run before all known deps have delivered their first
+     * DATA. Unknown deps return `undefined` via `track()`, which the fn must
+     * handle explicitly. Useful when some deps are "nice-to-have" — e.g. a
+     * primary computation should continue while a secondary dep is still
+     * initialising.
+     *
+     * When `false` (default), fn is held until every known dep has delivered at
+     * least one DATA value — a RESOLVED is emitted for the wave instead.
+     * This matches `derived()` semantics and is the correct default for
+     * pull-based compat layers (Signals, Jotai) where all deps must be
+     * initialised before the computation is meaningful.
+     *
+     * @default false
+     */
+    partial?: boolean;
+}
+declare function autoTrackNode<T = unknown>(fn: (track: TrackFn, ctx: FnCtx) => T | undefined | null, opts?: AutoTrackOptions<T>): Node<T>;
+/** Unary operator used by {@link pipe}. */
+type PipeOperator = (n: Node) => Node;
+/**
+ * Composes unary operators left-to-right; returns the final node.
+ *
+ * @example
+ * ```ts
+ * const out = pipe(
+ *   source,
+ *   (n) => map(n, (x) => x + 1),
+ *   (n) => filter(n, (x) => x > 0),
+ * );
+ * ```
+ */
+declare function pipe(source: Node, ...ops: PipeOperator[]): Node;
+
+export { type AutoTrackOptions as A, type DerivedFn as D, type EffectFn as E, type PipeOperator as P, type TrackFn as T, type DynamicFn as a, type ProducerFn as b, autoTrackNode as c, derived as d, dynamicNode as e, effect as f, producer as g, pipe as p, state as s };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@graphrefly/graphrefly",
-	"version": "0.25.0",
+	"version": "0.27.0",
 	"packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319",
 	"description": "Reactive harness layer for agent workflows. Describe automations in plain language, trace every decision, enforce policies, persist checkpoints. Zero dependencies.",
 	"repository": {
@@ -47,6 +47,16 @@
 				"default": "./dist/extra/index.cjs"
 			}
 		},
+		"./extra/sources": {
+			"import": {
+				"types": "./dist/extra/sources.d.ts",
+				"default": "./dist/extra/sources.js"
+			},
+			"require": {
+				"types": "./dist/extra/sources.d.cts",
+				"default": "./dist/extra/sources.cjs"
+			}
+		},
 		"./graph": {
 			"import": {
 				"types": "./dist/graph/index.d.ts",
@@ -77,6 +87,16 @@
 				"default": "./dist/compat/jotai/index.cjs"
 			}
 		},
+		"./compat/nanostores": {
+			"import": {
+				"types": "./dist/compat/nanostores/index.d.ts",
+				"default": "./dist/compat/nanostores/index.js"
+			},
+			"require": {
+				"types": "./dist/compat/nanostores/index.d.cts",
+				"default": "./dist/compat/nanostores/index.cjs"
+			}
+		},
 		"./compat/zustand": {
 			"import": {
 				"types": "./dist/compat/zustand/index.d.ts",
@@ -137,7 +157,7 @@
 				"default": "./dist/compat/nestjs/index.cjs"
 			}
 		},
-		"./reactive-layout": {
+		"./patterns/reactive-layout": {
 			"import": {
 				"types": "./dist/patterns/reactive-layout/index.d.ts",
 				"default": "./dist/patterns/reactive-layout/index.js"
@@ -146,6 +166,46 @@
 				"types": "./dist/patterns/reactive-layout/index.d.cts",
 				"default": "./dist/patterns/reactive-layout/index.cjs"
 			}
+		},
+		"./patterns/demo-shell": {
+			"import": {
+				"types": "./dist/patterns/demo-shell.d.ts",
+				"default": "./dist/patterns/demo-shell.js"
+			},
+			"require": {
+				"types": "./dist/patterns/demo-shell.d.cts",
+				"default": "./dist/patterns/demo-shell.cjs"
+			}
+		},
+		"./patterns/memory": {
+			"import": {
+				"types": "./dist/patterns/memory.d.ts",
+				"default": "./dist/patterns/memory.js"
+			},
+			"require": {
+				"types": "./dist/patterns/memory.d.cts",
+				"default": "./dist/patterns/memory.cjs"
+			}
+		},
+		"./patterns/ai": {
+			"import": {
+				"types": "./dist/patterns/ai.d.ts",
+				"default": "./dist/patterns/ai.js"
+			},
+			"require": {
+				"types": "./dist/patterns/ai.d.cts",
+				"default": "./dist/patterns/ai.cjs"
+			}
+		},
+		"./patterns/audit": {
+			"import": {
+				"types": "./dist/patterns/audit.d.ts",
+				"default": "./dist/patterns/audit.js"
+			},
+			"require": {
+				"types": "./dist/patterns/audit.d.cts",
+				"default": "./dist/patterns/audit.cjs"
+			}
 		}
 	},
 	"files": [
@@ -157,7 +217,7 @@
 	},
 	"scripts": {
 		"docs:dev": "pnpm --dir website dev",
-		"docs:build": "pnpm --dir website build && pnpm --dir demos/compat-matrix build && pnpm --dir demos/reactive-layout build && cp -r demos/compat-matrix/dist/. website/dist/demos/compat-matrix/ && cp -r demos/reactive-layout/dist/. website/dist/demos/reactive-layout/",
+		"docs:build": "pnpm build && pnpm --dir website build && pnpm --dir demos/compat-matrix build && pnpm --dir demos/reactive-layout build && pnpm --dir demos/knowledge-graph build && cp -r demos/compat-matrix/dist/. website/dist/demos/compat-matrix/ && cp -r demos/reactive-layout/dist/. website/dist/demos/reactive-layout/ && cp -r demos/knowledge-graph/dist/. website/dist/demos/knowledge-graph/",
 		"docs:preview": "pnpm --dir website preview",
 		"build": "tsup",
 		"test": "vitest run",