@graphrefly/graphrefly 0.1.0

package/dist/index-Bvy_6CaN.d.ts

@@ -0,0 +1,452 @@
+import { i as Messages, N as Node, j as NodeDescribeKind, k as NodeGuard, a as NodeOptions, a0 as NodeInspectorHook, m as NodeStatus, A as Actor, n as NodeTransportOptions, l as NodeSink, S as SubscribeHints, c as NodeFn, C as COMPLETE, D as DATA, d as DEFAULT_ACTOR, e as DIRTY, f as DescribeNodeOutput, E as ERROR, G as GuardAction, g as GuardDenied, h as GuardDeniedDetails, H as HashFn, I as INVALIDATE, M as Message, b as NodeActions, o as NodeVersionInfo, O as OnMessageHandler, P as PAUSE, p as PolicyAllow, q as PolicyDeny, r as PolicyRuleData, R as RESOLVED, s as RESUME, T as TEARDOWN, V as V0, t as V1, u as VersioningLevel, v as VersioningOptions, w as accessHintForGuard, x as advanceVersion, y as createVersioning, z as defaultHash, B as describeNode, F as isKnownMessageType, J as isPhase2Message, K as isTerminalMessage, L as isV1, Q as knownMessageTypes, U as messageTier, W as metaSnapshot, X as node, Y as normalizeActor, Z as policy, _ as policyFromRules, $ as propagatesToMeta } from './meta-BsF6Sag9.js';
+
+/**
+ * Returns whether the current call stack is inside a batch scope **or** while
+ * deferred phase-2 work is draining.
+ *
+ * Matching Python's `is_batching()` semantics: nested emissions during drain
+ * are deferred until the current drain pass completes, preventing ordering
+ * bugs when callbacks trigger further DATA/RESOLVED.
+ *
+ * @returns `true` while inside `batch()` or while the drain loop is running.
+ *
+ * @example
+ * ```ts
+ * import { batch, isBatching } from "@graphrefly/graphrefly-ts";
+ *
+ * batch(() => {
+ *   console.log(isBatching()); // true
+ * });
+ * ```
+ *
+ * @category core
+ */
+declare function isBatching(): boolean;
+/**
+ * Runs `fn` inside a batch scope. Nested `batch()` calls share one deferral queue.
+ * If `fn` throws (including from a nested `batch`), deferred DATA/RESOLVED for
+ * that **outer** `batch` frame are discarded — phase-2 is not flushed after an
+ * error. While the drain loop is running (`flushInProgress`), a nested `batch`
+ * that throws must **not** clear the global queue (cross-language decision A4).
+ *
+ * During the drain loop, `isBatching()` remains true so nested `emitWithBatch`
+ * calls still defer phase-2 messages. The drain loop runs until the queue is
+ * quiescent (no pending work remains). Per-emission try/catch ensures one
+ * throwing callback does not orphan remaining emissions; the first error is
+ * re-thrown after all emissions drain. Callbacks that ran before the throw may
+ * have applied phase-2 — partial graph state is intentional (decision C1).
+ *
+ * @param fn — Synchronous work that may call `emitWithBatch` / `node.down()`.
+ * @returns `void` — all side-effects happen through `emitWithBatch` and the
+ *   phase-2 drain that runs after `fn` returns.
+ *
+ * @example
+ * ```ts
+ * import { core } from "@graphrefly/graphrefly-ts";
+ *
+ * core.batch(() => {
+ *   core.emitWithBatch(sink, [[core.DATA, 1]]);
+ * });
+ * ```
+ *
+ * @category core
+ */
+declare function batch(fn: () => void): void;
+/**
+ * Splits a message array into three groups by signal tier (see `messages.ts`):
+ *
+ * - **immediate** — tier 0–1: DIRTY, INVALIDATE, PAUSE, RESUME, TEARDOWN, unknown
+ * - **deferred** — tier 2: DATA, RESOLVED (phase-2, deferred inside `batch()`)
+ * - **terminal** — tier 3: COMPLETE, ERROR (delivered after phase-2)
+ *
+ * Order within each group is preserved.
+ *
+ * @param messages — One `down()` payload.
+ * @returns Three groups in canonical delivery order.
+ *
+ * @example
+ * ```ts
+ * import { DATA, DIRTY, COMPLETE, partitionForBatch } from "@graphrefly/graphrefly-ts";
+ *
+ * partitionForBatch([[DIRTY], [DATA, 1], [COMPLETE]]);
+ * // { immediate: [[DIRTY]], deferred: [[DATA, 1]], terminal: [[COMPLETE]] }
+ * ```
+ *
+ * @category core
+ */
+declare function partitionForBatch(messages: Messages): {
+    immediate: Messages;
+    deferred: Messages;
+    terminal: Messages;
+};
+/**
+ * Delivers messages through `emit`, applying batch semantics and canonical
+ * tier-based ordering (see `messages.ts`):
+ *
+ * 1. **Immediate** (tier 0–1, 4): DIRTY, INVALIDATE, PAUSE, RESUME, TEARDOWN,
+ *    unknown — emitted synchronously.
+ * 2. **Phase-2** (tier 2): DATA, RESOLVED — deferred while `isBatching()`.
+ * 3. **Terminal** (tier 3): COMPLETE, ERROR — always delivered after phase-2.
+ *    When batching, terminal is queued after deferred phase-2 in the pending list.
+ *    When not batching, terminal is emitted after phase-2 synchronously.
+ *
+ * This ordering prevents the "COMPLETE-before-DATA" class of bugs: terminal
+ * signals never make a node terminal before phase-2 values reach sinks,
+ * regardless of how the source assembled the message array.
+ *
+ * @param emit — Sink callback. May be called up to three times per invocation
+ *   (immediate, deferred, terminal) when not batching.
+ * @param messages — Full `[[Type, Data?], ...]` array for one emission.
+ * @returns `void` — delivery is performed through `emit` callbacks, synchronously
+ *   or deferred into the active batch queue.
+ *
+ * @example
+ * ```ts
+ * import { core } from "@graphrefly/graphrefly-ts";
+ *
+ * core.emitWithBatch((msgs) => console.log(msgs), [[core.DIRTY], [core.DATA, 42]]);
+ * ```
+ *
+ * @category core
+ */
+declare function emitWithBatch(emit: (messages: Messages) => void, messages: Messages, phase?: 2 | 3): void;
+
+/**
+ * Centralised timestamp utilities.
+ *
+ * Convention: all graphrefly-ts timestamps use nanoseconds (`_ns` suffix).
+ *
+ * - {@link monotonicNs} — monotonic clock (ordering, durations, timeline events).
+ * - {@link wallClockNs} — wall-clock (mutation attribution, cron emission).
+ *
+ * **Precision limits (JS platform):**
+ *
+ * - `monotonicNs`: effective ~microsecond precision. `performance.now()` returns
+ *   milliseconds with ~5µs resolution; the last 3 digits of the nanosecond value
+ *   are always zero. Python's `time.monotonic_ns()` gives true nanoseconds.
+ *
+ * - `wallClockNs`: ~256ns precision loss at current epoch. `Date.now() * 1e6`
+ *   produces values around 1.8×10¹⁸ which exceed IEEE 754's 2⁵³ safe integer
+ *   limit. Python's `time.time_ns()` (arbitrary-precision `int`) has no loss.
+ *   In practice this is irrelevant — JS is single-threaded, so sub-microsecond
+ *   timestamp collisions cannot occur.
+ */
+/** Monotonic nanosecond timestamp via `performance.now()`. */
+declare function monotonicNs(): number;
+/** Wall-clock nanosecond timestamp via `Date.now()`. */
+declare function wallClockNs(): number;
+
+/**
+ * `dynamicNode` — runtime dep tracking with diamond resolution (Phase 0.3b).
+ *
+ * Unlike `node()` where deps are fixed at construction, `dynamicNode` discovers
+ * deps at runtime via a tracking `get()` proxy. After each recompute, deps are
+ * diffed: new deps are connected, removed deps are disconnected, and bitmasks
+ * are rebuilt. Kept deps retain their subscriptions (no teardown/reconnect churn).
+ *
+ * This ports callbag-recharge's `dynamicDerived` pattern to GraphReFly's protocol.
+ */
+
+/**
+ * The tracking `get` function passed to `dynamicNode`'s compute function.
+ * Each call to `get(dep)` reads the dep's current value and records it as a dependency.
+ */
+type DynGet = <V>(dep: Node<V>) => V | undefined;
+/**
+ * Compute function for `dynamicNode`. Receives a tracking `get` proxy.
+ * Deps are discovered by which nodes are passed to `get()` during execution.
+ */
+type DynamicNodeFn<T> = (get: DynGet) => T;
+/** Options for `dynamicNode`. */
+type DynamicNodeOptions = Pick<NodeOptions, "name" | "equals" | "meta" | "resubscribable" | "resetOnTeardown" | "guard" | "onMessage" | "onResubscribe" | "completeWhenDepsComplete" | "describeKind">;
+/**
+ * Creates a node with runtime dep tracking. Deps are discovered each time the
+ * compute function runs by tracking which nodes are passed to the `get()` proxy.
+ *
+ * After each recompute:
+ * - New deps (not in previous set) are subscribed
+ * - Removed deps (not in current set) are unsubscribed
+ * - Kept deps retain their existing subscriptions
+ * - Bitmasks are rebuilt to match the new dep set
+ *
+ * The node participates fully in diamond resolution via the standard two-phase
+ * DIRTY/RESOLVED protocol across all dynamically-tracked deps.
+ *
+ * @param fn - Compute function receiving a tracking `get` proxy.
+ * @param opts - Optional configuration.
+ * @returns `Node<T>` with dynamic dep tracking.
+ *
+ * @example
+ * ```ts
+ * import { dynamicNode, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const cond = state(true);
+ * const a = state(1);
+ * const b = state(2);
+ *
+ * // Deps change based on cond's value
+ * const d = dynamicNode((get) => {
+ *   const useA = get(cond);
+ *   return useA ? get(a) : get(b);
+ * });
+ * ```
+ *
+ * @category core
+ */
+declare function dynamicNode<T = unknown>(fn: DynamicNodeFn<T>, opts?: DynamicNodeOptions): Node<T>;
+/** @internal — exported for {@link describeNode} `instanceof` check. */
+declare class DynamicNodeImpl<T = unknown> implements Node<T> {
+    private readonly _optsName;
+    private _registryName;
+    readonly _describeKind: NodeDescribeKind | undefined;
+    readonly meta: Record<string, Node>;
+    private readonly _fn;
+    private readonly _equals;
+    private readonly _resubscribable;
+    private readonly _resetOnTeardown;
+    private readonly _autoComplete;
+    private readonly _onMessage;
+    private readonly _onResubscribe;
+    /** @internal — read by {@link describeNode} for `accessHintForGuard`. */
+    readonly _guard: NodeGuard | undefined;
+    private _lastMutation;
+    private _inspectorHook;
+    private _sinkCount;
+    private _singleDepSinkCount;
+    private _singleDepSinks;
+    private readonly _actions;
+    private readonly _boundEmitToSinks;
+    private _cached;
+    private _status;
+    private _terminal;
+    private _connected;
+    private _rewiring;
+    private _deps;
+    private _depUnsubs;
+    private _depIndexMap;
+    private _dirtyBits;
+    private _settledBits;
+    private _completeBits;
+    private _sinks;
+    constructor(fn: DynamicNodeFn<T>, opts: DynamicNodeOptions);
+    get name(): string | undefined;
+    /** @internal */
+    _assignRegistryName(localName: string): void;
+    /**
+     * @internal Attach/remove inspector hook for graph-level observability.
+     * Returns a disposer that restores the previous hook.
+     */
+    _setInspectorHook(hook?: NodeInspectorHook): () => void;
+    get status(): NodeStatus;
+    get lastMutation(): Readonly<{
+        actor: Actor;
+        timestamp_ns: number;
+    }> | undefined;
+    /** Versioning not yet supported on DynamicNodeImpl. */
+    get v(): undefined;
+    hasGuard(): boolean;
+    allowsObserve(actor: Actor): boolean;
+    get(): T | undefined;
+    down(messages: Messages, options?: NodeTransportOptions): void;
+    private _downInternal;
+    private _canSkipDirty;
+    subscribe(sink: NodeSink, hints?: SubscribeHints): () => void;
+    up(messages: Messages, options?: NodeTransportOptions): void;
+    unsubscribe(): void;
+    private _emitToSinks;
+    private _handleLocalLifecycle;
+    /** Propagate a signal to all companion meta nodes (best-effort). */
+    private _propagateToMeta;
+    private _emitAutoValue;
+    private _connect;
+    private _disconnect;
+    private _runFn;
+    private _rewire;
+    private _handleDepMessages;
+    private _allDirtySettled;
+}
+
+/**
+ * Creates a manual source with no upstream deps. Emit values with {@link Node.down}.
+ *
+ * Spec: `state(initial, opts?)` is `node([], { initial, ...opts })` (GRAPHREFLY-SPEC §2.7).
+ *
+ * @param initial - Initial cached value.
+ * @param opts - Optional {@link NodeOptions} (excluding `initial`).
+ * @returns `Node<T>` - Stateful node you drive imperatively.
+ *
+ * @example
+ * ```ts
+ * import { DATA, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = state(0);
+ * n.down([[DATA, 1]]);
+ * ```
+ *
+ * @category core
+ */
+declare function state<T>(initial: T, opts?: Omit<NodeOptions, "initial">): Node<T>;
+/**
+ * Creates a producer node with no deps; `fn` runs when the first subscriber connects.
+ *
+ * @param fn - Receives deps (empty) and {@link NodeActions}; use `emit` / `down` to push.
+ * @param opts - Optional {@link NodeOptions}.
+ * @returns `Node<T>` - Producer node.
+ *
+ * @example
+ * ```ts
+ * import { producer } from "@graphrefly/graphrefly-ts";
+ *
+ * const tick = producer((_d, a) => {
+ *   a.emit(1);
+ * });
+ * ```
+ *
+ * @category core
+ */
+declare function producer<T = unknown>(fn: NodeFn<T>, opts?: NodeOptions): Node<T>;
+/**
+ * Creates a derived node from dependencies and a compute function (same primitive as operators).
+ *
+ * @param deps - Upstream nodes.
+ * @param fn - Compute function; return value is emitted, or use `actions` explicitly.
+ * @param opts - Optional {@link NodeOptions}.
+ * @returns `Node<T>` - Derived node.
+ *
+ * @example
+ * ```ts
+ * import { derived, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const a = state(1);
+ * const b = derived([a], ([x]) => (x as number) * 2);
+ * ```
+ *
+ * @category core
+ */
+declare function derived<T = unknown>(deps: readonly Node[], fn: NodeFn<T>, opts?: NodeOptions): Node<T>;
+/**
+ * Runs a side-effect when deps settle; return value is not auto-emitted.
+ *
+ * @param deps - Nodes to watch.
+ * @param fn - Side-effect body.
+ * @returns `Node<unknown>` - Effect node.
+ *
+ * @example
+ * ```ts
+ * import { effect, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = state(1);
+ * effect([n], ([v]) => {
+ *   console.log(v);
+ * });
+ * ```
+ *
+ * @category core
+ */
+declare function effect(deps: readonly Node[], fn: NodeFn<unknown>): Node<unknown>;
+/** Unary transform used by {@link pipe} (typically returns a new node wrapping `n`). */
+type PipeOperator = (n: Node) => Node;
+/**
+ * Composes unary operators left-to-right; returns the final node. Does not register a {@link Graph}.
+ *
+ * @param source - Starting node.
+ * @param ops - Each operator maps `Node` to `Node` (curried operators from `extra` use a factory pattern — wrap or use direct calls).
+ * @returns `Node` - Result of the last operator.
+ *
+ * @example
+ * ```ts
+ * import { filter, map, pipe, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const src = state(1);
+ * const out = pipe(
+ *   src,
+ *   (n) => map(n, (x) => x + 1),
+ *   (n) => filter(n, (x) => x > 0),
+ * );
+ * ```
+ *
+ * @category core
+ */
+declare function pipe(source: Node, ...ops: PipeOperator[]): Node;
+
+/**
+ * Core layer: message protocol, node primitive, lifecycle (Phase 0).
+ */
+
+declare const index_Actor: typeof Actor;
+declare const index_COMPLETE: typeof COMPLETE;
+declare const index_DATA: typeof DATA;
+declare const index_DEFAULT_ACTOR: typeof DEFAULT_ACTOR;
+declare const index_DIRTY: typeof DIRTY;
+declare const index_DescribeNodeOutput: typeof DescribeNodeOutput;
+type index_DynGet = DynGet;
+type index_DynamicNodeFn<T> = DynamicNodeFn<T>;
+type index_DynamicNodeImpl<T = unknown> = DynamicNodeImpl<T>;
+declare const index_DynamicNodeImpl: typeof DynamicNodeImpl;
+type index_DynamicNodeOptions = DynamicNodeOptions;
+declare const index_ERROR: typeof ERROR;
+declare const index_GuardAction: typeof GuardAction;
+declare const index_GuardDenied: typeof GuardDenied;
+declare const index_GuardDeniedDetails: typeof GuardDeniedDetails;
+declare const index_HashFn: typeof HashFn;
+declare const index_INVALIDATE: typeof INVALIDATE;
+declare const index_Message: typeof Message;
+declare const index_Messages: typeof Messages;
+declare const index_Node: typeof Node;
+declare const index_NodeActions: typeof NodeActions;
+declare const index_NodeDescribeKind: typeof NodeDescribeKind;
+declare const index_NodeFn: typeof NodeFn;
+declare const index_NodeGuard: typeof NodeGuard;
+declare const index_NodeOptions: typeof NodeOptions;
+declare const index_NodeSink: typeof NodeSink;
+declare const index_NodeStatus: typeof NodeStatus;
+declare const index_NodeTransportOptions: typeof NodeTransportOptions;
+declare const index_NodeVersionInfo: typeof NodeVersionInfo;
+declare const index_OnMessageHandler: typeof OnMessageHandler;
+declare const index_PAUSE: typeof PAUSE;
+type index_PipeOperator = PipeOperator;
+declare const index_PolicyAllow: typeof PolicyAllow;
+declare const index_PolicyDeny: typeof PolicyDeny;
+declare const index_PolicyRuleData: typeof PolicyRuleData;
+declare const index_RESOLVED: typeof RESOLVED;
+declare const index_RESUME: typeof RESUME;
+declare const index_SubscribeHints: typeof SubscribeHints;
+declare const index_TEARDOWN: typeof TEARDOWN;
+declare const index_V0: typeof V0;
+declare const index_V1: typeof V1;
+declare const index_VersioningLevel: typeof VersioningLevel;
+declare const index_VersioningOptions: typeof VersioningOptions;
+declare const index_accessHintForGuard: typeof accessHintForGuard;
+declare const index_advanceVersion: typeof advanceVersion;
+declare const index_batch: typeof batch;
+declare const index_createVersioning: typeof createVersioning;
+declare const index_defaultHash: typeof defaultHash;
+declare const index_derived: typeof derived;
+declare const index_describeNode: typeof describeNode;
+declare const index_dynamicNode: typeof dynamicNode;
+declare const index_effect: typeof effect;
+declare const index_emitWithBatch: typeof emitWithBatch;
+declare const index_isBatching: typeof isBatching;
+declare const index_isKnownMessageType: typeof isKnownMessageType;
+declare const index_isPhase2Message: typeof isPhase2Message;
+declare const index_isTerminalMessage: typeof isTerminalMessage;
+declare const index_isV1: typeof isV1;
+declare const index_knownMessageTypes: typeof knownMessageTypes;
+declare const index_messageTier: typeof messageTier;
+declare const index_metaSnapshot: typeof metaSnapshot;
+declare const index_monotonicNs: typeof monotonicNs;
+declare const index_node: typeof node;
+declare const index_normalizeActor: typeof normalizeActor;
+declare const index_partitionForBatch: typeof partitionForBatch;
+declare const index_pipe: typeof pipe;
+declare const index_policy: typeof policy;
+declare const index_policyFromRules: typeof policyFromRules;
+declare const index_producer: typeof producer;
+declare const index_propagatesToMeta: typeof propagatesToMeta;
+declare const index_state: typeof state;
+declare const index_wallClockNs: typeof wallClockNs;
+declare namespace index {
+  export { index_Actor as Actor, index_COMPLETE as COMPLETE, index_DATA as DATA, index_DEFAULT_ACTOR as DEFAULT_ACTOR, index_DIRTY as DIRTY, index_DescribeNodeOutput as DescribeNodeOutput, type index_DynGet as DynGet, type index_DynamicNodeFn as DynamicNodeFn, index_DynamicNodeImpl as DynamicNodeImpl, type index_DynamicNodeOptions as DynamicNodeOptions, index_ERROR as ERROR, index_GuardAction as GuardAction, index_GuardDenied as GuardDenied, index_GuardDeniedDetails as GuardDeniedDetails, index_HashFn as HashFn, index_INVALIDATE as INVALIDATE, index_Message as Message, index_Messages as Messages, index_Node as Node, index_NodeActions as NodeActions, index_NodeDescribeKind as NodeDescribeKind, index_NodeFn as NodeFn, index_NodeGuard as NodeGuard, index_NodeOptions as NodeOptions, index_NodeSink as NodeSink, index_NodeStatus as NodeStatus, index_NodeTransportOptions as NodeTransportOptions, index_NodeVersionInfo as NodeVersionInfo, index_OnMessageHandler as OnMessageHandler, index_PAUSE as PAUSE, type index_PipeOperator as PipeOperator, index_PolicyAllow as PolicyAllow, index_PolicyDeny as PolicyDeny, index_PolicyRuleData as PolicyRuleData, index_RESOLVED as RESOLVED, index_RESUME as RESUME, index_SubscribeHints as SubscribeHints, index_TEARDOWN as TEARDOWN, index_V0 as V0, index_V1 as V1, index_VersioningLevel as VersioningLevel, index_VersioningOptions as VersioningOptions, index_accessHintForGuard as accessHintForGuard, index_advanceVersion as advanceVersion, index_batch as batch, index_createVersioning as createVersioning, index_defaultHash as defaultHash, index_derived as derived, index_describeNode as describeNode, index_dynamicNode as dynamicNode, index_effect as effect, index_emitWithBatch as emitWithBatch, index_isBatching as isBatching, index_isKnownMessageType as isKnownMessageType, index_isPhase2Message as isPhase2Message, index_isTerminalMessage as isTerminalMessage, index_isV1 as isV1, index_knownMessageTypes as knownMessageTypes, index_messageTier as messageTier, index_metaSnapshot as metaSnapshot, index_monotonicNs as monotonicNs, index_node as node, index_normalizeActor as normalizeActor, index_partitionForBatch as partitionForBatch, index_pipe as pipe, index_policy as policy, index_policyFromRules as policyFromRules, index_producer as producer, index_propagatesToMeta as propagatesToMeta, index_state as state, index_wallClockNs as wallClockNs };
+}
+
+export { type DynGet as D, type PipeOperator as P, type DynamicNodeFn as a, DynamicNodeImpl as b, type DynamicNodeOptions as c, batch as d, derived as e, dynamicNode as f, effect as g, emitWithBatch as h, index as i, isBatching as j, pipe as k, producer as l, monotonicNs as m, partitionForBatch as p, state as s, wallClockNs as w };