@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/sugar-DQjFmVqb.d.cts

@@ -1,399 +0,0 @@
-import { w as NodeDescribeKind, N as Node, A as Actor, F as FnCtx, c as NodeActions, y as NodeFnCleanup, a as NodeOptions } from './node-kK3CvTrR.cjs';
-
-/**
- * JSON-shaped slice of a node for `Graph.describe()`
- * (GRAPHREFLY-SPEC §3.6, Appendix B).
- */
-type DescribeNodeOutput = {
-    type: NodeDescribeKind;
-    status?: Node["status"];
-    deps: string[];
-    meta?: Record<string, unknown>;
-    name?: string;
-    value?: unknown;
-    /** True when the node is in `"sentinel"` state (no value ever). */
-    sentinel?: boolean;
-    v?: {
-        id: string;
-        version: number;
-        cid?: string;
-        prev?: string | null;
-    };
-    guard?: string;
-    lastMutation?: Readonly<{
-        actor: Actor;
-        timestamp_ns: number;
-    }>;
-    /**
-     * Latest annotation attached via `graph.trace(path, annotation)` or via
-     * `graph.add(node, { name: path, annotation })`, when present. Populated by
-     * `Graph.describe` only — `describeNode` has no graph context.
-     */
-    annotation?: string;
-};
-/**
- * Detail level for progressive disclosure (Phase 3.3b).
- *
- * - `"minimal"` — `type`, `deps` only.
- * - `"standard"` — minimal + `status`, `value`, `meta`, `v`.
- * - `"full"` — every field.
- * - `"spec"` — Tier 1.5.3 (Session A.1 lock + Phase 3 path (b)). Projects
- *   spec-relevant fields (`type`, `deps`, `meta` — including
- *   `meta.factory` / `meta.factoryArgs`) and strips runtime fields
- *   (`status`, `lastMutation`, `guard`, `sentinel`, `v`). **Retains
- *   `value` for state nodes only** so the seed initial value round-trips
- *   through `decompileSpec` → `compileSpec` without forcing every state
- *   constructor to spawn `meta.factory`/`factoryArgs` companion nodes.
- *   The output is structurally identical to the `GraphSpec` shape so
- *   `decompileSpec(g) === describe(g, { detail: "spec" })`.
- */
-type DescribeDetail = "minimal" | "standard" | "full" | "spec";
-/** Valid field names for `describe({ fields: [...] })`. */
-type DescribeField = "type" | "status" | "value" | "deps" | "meta" | "v" | "guard" | "lastMutation" | `meta.${string}`;
-/** Resolve which fields to include based on detail level or explicit field list. */
-declare function resolveDescribeFields(detail?: DescribeDetail, fields?: readonly DescribeField[]): Set<string> | null;
-/**
- * Walk an arbitrary value, replacing non-JSON-serializable fields with
- * descriptive string placeholders (Tier 1.5.3 Phase 2.5 — DG2=ii). Useful for
- * `Graph.prototype.tagFactory(name, args)` when the factory's options include
- * `LLMAdapter` instances, callbacks, or `Node`s that don't survive
- * serialization. Output preserves structure for documentation / audit value;
- * recipients of the spec see "<Node>" / "<function>" / etc. in place of the
- * unserializable bits.
- *
- * Heuristics:
- * - `null` / `undefined` / boolean / number / string — kept as-is.
- * - `function` — `"<function>"`.
- * - Object with `subscribe` method — `"<Node>"` (matches Node-shape duck check).
- * - Array — recursed.
- * - Plain object — recursed.
- * - Anything else — `"<unserializable>"`.
- *
- * **`undefined`-key caveat (DF11, 2026-04-29 doc lock).** Keys whose value
- * is `undefined` survive `placeholderArgs` (they are kept as-is per the
- * heuristic above). However, `JSON.stringify` DROPS such keys at the
- * serialization boundary, so a spec round-trip via `toJSONString` does
- * not preserve them. Callers that need `undefined` to round-trip must
- * substitute an explicit sentinel (e.g. `null`) before tagging — meta-
- * vs-spec disagreement at the JSON boundary is otherwise inevitable.
- */
-declare function placeholderArgs(opts: Record<string, unknown>): Record<string, unknown>;
-/**
- * Build a `meta` fragment that stamps a factory identifier and its construction
- * arguments onto a node, so `describe({ detail: "spec" })` exposes enough
- * information for `compileSpec` to recreate the node from the snapshot.
- *
- * Use inside node-producing factories at construction time:
- *
- * ```ts
- * import { factoryTag } from "@graphrefly/graphrefly";
- *
- * export function rateLimiter<T>(source: NodeInput<T>, opts: RateLimiterOptions): Node<T> {
- *   return derived([fromAny(source)], fn, {
- *     name: "rate-limiter",
- *     meta: { ...factoryTag("rateLimiter", opts), domain: "resilience" },
- *   });
- * }
- * ```
- *
- * `factoryArgs` should be JSON-serializable so the spec round-trips through
- * `decompileSpec → compileSpec`. Function-typed args break determinism — use
- * the {@link COMPOSITION-GUIDE} §39 `meta.fnId` pattern for those.
- *
- * Tier 1.5.3 (Session A.1 lock).
- */
-declare function factoryTag(factory: string, factoryArgs?: unknown): {
-    factory: string;
-    factoryArgs?: unknown;
-};
-
-/**
- * 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).
- *
- * **Sentinel form.** Omit `initial` (or pass `undefined`) to leave the
- * node in `"sentinel"` status — the canonical "no value yet" state.
- * Downstream `derived` first-run gate then waits for the first real DATA
- * before firing. Pass an explicit `null` to cache `null` as DATA — `null`
- * is a valid DATA value per spec §2.2 ("`T | null` is the only valid DATA
- * domain; `undefined` is reserved as the global SENTINEL").
- *
- * @example
- * ```ts
- * import { state, derived } from "@graphrefly/graphrefly";
- *
- * // Cached form — starts at 10, derived fires immediately on subscribe.
- * const counter = state(10);
- *
- * // Sentinel form — derived's first-run gate waits for the first emit.
- * const candidates = state<readonly string[]>();
- * const ready = derived([candidates], ([cands]) => cands.length > 0);
- * candidates.emit(["v1"]); // ready fires now
- * ```
- *
- * @param initial - Starting cached value (optional). Omit or pass
- *   `undefined` for the sentinel form; pass `null` to cache `null`.
- * @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` — fires on
- * every transition) or an object with granular hooks
- * (`{ beforeRun?, deactivate?, invalidate? }` — each hook fires on its named
- * transition only) to register teardown. See {@link NodeFnCleanup}.
- *
- * @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>): Node<T>;
-/**
- * Maps a tuple of `Node<V>`s to a tuple of `V`s. Used by {@link derivedT}
- * and {@link effectT} to propagate dep value types into the callback's
- * `data` parameter — eliminating per-callsite `as` casts.
- */
-type NodeValues<TDeps extends readonly Node<unknown>[]> = {
-    readonly [K in keyof TDeps]: TDeps[K] extends Node<infer V> ? V : never;
-};
-/**
- * Typed callback for {@link derivedT}. Each tuple element corresponds
- * positionally to the matching dep's value type.
- */
-type DerivedTFn<TDeps extends readonly Node<unknown>[], TOut> = (data: NodeValues<TDeps>, ctx: FnCtx) => TOut | undefined | null;
-/**
- * Typed callback for {@link effectT}. Each tuple element corresponds
- * positionally to the matching dep's value type.
- */
-type EffectTFn<TDeps extends readonly Node<unknown>[]> = (data: NodeValues<TDeps>, actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
-/**
- * Typed-tuple variant of {@link derived}. Use when the dep types matter at
- * the callback boundary — `data` is inferred as a tuple of dep value types
- * instead of `readonly unknown[]`.
- *
- * Same runtime semantics as {@link derived} (first-run gate, snapshot
- * combine semantics, equals substitution).
- *
- * **`partial: true` is rejected at the type level (qa F-E, 2026-04-29).**
- * Tuple slots in `NodeValues<TDeps>` resolve to `V` (never `V | undefined`),
- * but `partial: true` lets fn run before every dep has fired. The two are
- * unsound together — fn would receive `undefined` for an unfired dep but
- * see it typed as `V`. Callers needing partial firing keep using untyped
- * {@link derived} where `data` is `readonly unknown[]` and the
- * `=== undefined` guard is sanctioned (COMPOSITION-GUIDE §3 partial-true
- * exception).
- *
- * @example
- * ```ts
- * const a = state(1);
- * const b = state("hi");
- * // sum: number, label: string — no casts needed.
- * const out = derivedT([a, b], ([sum, label]) => `${label}:${sum * 2}`);
- * ```
- */
-declare function derivedT<TDeps extends readonly Node<unknown>[], TOut>(deps: TDeps, fn: DerivedTFn<TDeps, TOut>, opts?: Omit<NodeOptions<TOut>, "partial"> & {
-    partial?: false;
-}): Node<TOut>;
-/**
- * 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 (`() => void`) or an object with granular hooks
- * (`{ beforeRun?, deactivate?, invalidate? }`) to register teardown.
- * See {@link NodeFnCleanup}.
- */
-type EffectFn = (data: readonly unknown[], actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
-/**
- * Typed-tuple variant of {@link effect}. Use when the dep types matter at
- * the callback boundary — `data` is inferred as a tuple of dep value types
- * instead of `readonly unknown[]`.
- *
- * Same runtime semantics as {@link effect} (first-run gate, no auto-emit,
- * cleanup contract).
- *
- * **`partial: true` is rejected at the type level (qa F-E, 2026-04-29).**
- * See {@link derivedT} for the soundness rationale.
- *
- * @example
- * ```ts
- * const user = state<User | null>(null);
- * const cfg = state<Config>(defaultCfg);
- * effectT([user, cfg], ([u, c]) => {
- *   if (u != null) hydrate(u, c);
- * });
- * ```
- */
-declare function effectT<TDeps extends readonly Node<unknown>[]>(deps: TDeps, fn: EffectTFn<TDeps>, opts?: Omit<NodeOptions<unknown>, "partial"> & {
-    partial?: false;
-}): Node<unknown>;
-/**
- * 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>): 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 declared dep has delivered
-     * at least one DATA value — core's first-run gate (spec §2.7) handles this.
-     * Delegates to {@link NodeOptions.partial}; both semantics are aligned: the
-     * gate is first-run-only (`_hasCalledFnOnce`), so INVALIDATE on a dep does
-     * NOT re-gate after fn has fired once. Pull-based compat layers (Signals,
-     * Jotai) that rely on "consistent compute across INVALIDATE" should
-     * explicitly wrap their dep reads with null/undefined handling in fn.
-     *
-     * @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 DescribeNodeOutput as D, type EffectFn as E, type NodeValues as N, type PipeOperator as P, type TrackFn as T, type DerivedFn as a, type DerivedTFn as b, type DescribeDetail as c, type DescribeField as d, type DynamicFn as e, type EffectTFn as f, type ProducerFn as g, autoTrackNode as h, derived as i, derivedT as j, dynamicNode as k, effect as l, effectT as m, factoryTag as n, placeholderArgs as o, pipe as p, producer as q, resolveDescribeFields as r, state as s };