@graphrefly/graphrefly 0.27.0 → 0.28.0

package/dist/extra/operators.d.ts

@@ -0,0 +1,910 @@
+import { N as NodeOptions, a as Node, M as Message } from '../node-Cc1TniY8.js';
+import { NodeInput } from './sources.js';
+
+/**
+ * Tier 1 sync operators (roadmap §2.1) and Tier 2 async/dynamic operators (roadmap §2.2) —
+ * each returns a {@link Node} built with {@link node} (or {@link producer} for cold sources).
+ *
+ * v5 foundation redesign: all operators use `actions.emit()` for value emission,
+ * `ctx.store` for persistent state, `ctx.terminalDeps` for terminal handling,
+ * and `data[i]` batch shape for DATA vs RESOLVED discrimination. `onMessage`
+ * and `onResubscribe` are removed.
+ */
+
+type ExtraOpts = Omit<NodeOptions<unknown>, "describeKind">;
+/**
+ * Maps each settled value from `source` through `project`.
+ *
+ * @param source - Upstream node.
+ * @param project - Transform for each value.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<R>` - Derived node emitting mapped values.
+ *
+ * @example
+ * ```ts
+ * import { map, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = map(state(2), (x) => x * 3);
+ * ```
+ *
+ * @category extra
+ */
+declare function map<T, R>(source: Node<T>, project: (value: T) => R, opts?: ExtraOpts): Node<R>;
+/**
+ * Forwards values that satisfy `predicate`; otherwise emits `RESOLVED` with no `DATA` (two-phase semantics).
+ *
+ * @param source - Upstream node.
+ * @param predicate - Inclusion test.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Filtered node.
+ *
+ * @example
+ * ```ts
+ * import { filter, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = filter(state(1), (x) => x > 0);
+ * ```
+ *
+ * @category extra
+ */
+declare function filter<T>(source: Node<T>, predicate: (value: T) => boolean, opts?: ExtraOpts): Node<T>;
+/**
+ * Folds each upstream value into an accumulator; emits the new accumulator every time.
+ *
+ * Unlike RxJS, `seed` is always required — there is no seedless mode where the first
+ * value silently becomes the accumulator.
+ *
+ * @param source - Upstream node.
+ * @param reducer - `(acc, value) => nextAcc`.
+ * @param seed - Initial accumulator (required).
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<R>` - Scan node.
+ *
+ * @example
+ * ```ts
+ * import { scan, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = scan(state(1), (a, x) => a + x, 0);
+ * ```
+ *
+ * @category extra
+ */
+declare function scan<T, R>(source: Node<T>, reducer: (acc: R, value: T) => R, seed: R, opts?: ExtraOpts): Node<R>;
+/**
+ * Reduces to one value emitted when `source` completes; if no `DATA` arrived, emits `seed`.
+ *
+ * Unlike RxJS, `seed` is always required. If the source completes without emitting
+ * DATA, the seed value is emitted (RxJS would throw without a seed).
+ *
+ * @param source - Upstream node.
+ * @param reducer - `(acc, value) => nextAcc`.
+ * @param seed - Empty-completion default and initial accumulator (required).
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<R>` - Node that emits once on completion.
+ *
+ * @example
+ * ```ts
+ * import { reduce, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = reduce(state(1), (a, x) => a + x, 0);
+ * ```
+ *
+ * @category extra
+ */
+declare function reduce<T, R>(source: Node<T>, reducer: (acc: R, value: T) => R, seed: R, opts?: ExtraOpts): Node<R>;
+/**
+ * Emits at most `count` **`DATA`** values, then **`COMPLETE`**. `RESOLVED` does not advance the counter.
+ *
+ * @param source - Upstream node.
+ * @param count - Maximum `DATA` emissions (≤0 completes immediately).
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Limited stream.
+ *
+ * @example
+ * ```ts
+ * import { take, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = take(state(0), 3);
+ * ```
+ *
+ * @category extra
+ */
+declare function take<T>(source: Node<T>, count: number, opts?: ExtraOpts): Node<T>;
+/**
+ * Skips the first `count` **`DATA`** emissions. `RESOLVED` does not advance the counter.
+ *
+ * @param source - Upstream node.
+ * @param count - Number of `DATA` values to drop.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Skipped stream.
+ *
+ * @example
+ * ```ts
+ * import { skip, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = skip(state(0), 2);
+ * ```
+ *
+ * @category extra
+ */
+declare function skip<T>(source: Node<T>, count: number, opts?: ExtraOpts): Node<T>;
+/**
+ * Emits while `predicate` holds; on first false, sends **`COMPLETE`**.
+ *
+ * @param source - Upstream node.
+ * @param predicate - Continuation test.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Truncated stream.
+ *
+ * @example
+ * ```ts
+ * import { takeWhile, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = takeWhile(state(1), (x) => x < 10);
+ * ```
+ *
+ * @category extra
+ */
+declare function takeWhile<T>(source: Node<T>, predicate: (value: T) => boolean, opts?: ExtraOpts): Node<T>;
+/**
+ * Forwards `source` until `notifier` matches `predicate` (default: notifier **`DATA`**), then **`COMPLETE`**.
+ *
+ * @param source - Main upstream.
+ * @param notifier - Triggers completion when `predicate(msg)` is true.
+ * @param opts - Optional {@link NodeOptions}, plus `predicate` for custom notifier matching.
+ * @returns `Node<T>` - Truncated stream.
+ *
+ * @example
+ * ```ts
+ * import { producer, takeUntil, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const src = state(1);
+ * const stop = producer((_d, a) => a.emit(undefined));
+ * const n = takeUntil(src, stop);
+ * ```
+ *
+ * @category extra
+ */
+declare function takeUntil<T>(source: Node<T>, notifier: Node, opts?: ExtraOpts & {
+    predicate?: (msg: Message) => boolean;
+}): Node<T>;
+/**
+ * Emits the first **`DATA`** then **`COMPLETE`** (same as `take(source, 1)`).
+ *
+ * @param source - Upstream node.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Single-value stream.
+ *
+ * @example
+ * ```ts
+ * import { first, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = first(state(42));
+ * ```
+ *
+ * @category extra
+ */
+declare function first<T>(source: Node<T>, opts?: ExtraOpts): Node<T>;
+/**
+ * Buffers values and emits the last **`DATA`** on **`COMPLETE`**; optional `defaultValue` if none arrived.
+ *
+ * @param source - Upstream node.
+ * @param options - Optional {@link NodeOptions} and `defaultValue` when empty.
+ * @returns `Node<T>` - Last-or-default node.
+ *
+ * @example
+ * ```ts
+ * import { last, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = last(state(1), { defaultValue: 0 });
+ * ```
+ *
+ * @category extra
+ */
+declare function last<T>(source: Node<T>, options?: ExtraOpts & {
+    defaultValue?: T;
+}): Node<T>;
+/**
+ * Emits the first value matching `predicate`, then **`COMPLETE`**.
+ *
+ * @param source - Upstream node.
+ * @param predicate - Match test.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - First-match stream.
+ *
+ * @example
+ * ```ts
+ * import { find, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = find(state(1), (x) => x > 0);
+ * ```
+ *
+ * @category extra
+ */
+declare function find<T>(source: Node<T>, predicate: (value: T) => boolean, opts?: ExtraOpts): Node<T>;
+/**
+ * Emits the `index`th **`DATA`** (zero-based), then **`COMPLETE`**.
+ *
+ * @param source - Upstream node.
+ * @param index - Zero-based emission index.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Single indexed value.
+ *
+ * @example
+ * ```ts
+ * import { elementAt, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = elementAt(state(0), 2);
+ * ```
+ *
+ * @category extra
+ */
+declare function elementAt<T>(source: Node<T>, index: number, opts?: ExtraOpts): Node<T>;
+/**
+ * Observer shape for {@link tap} — side effects for data, error, and/or complete.
+ */
+type TapObserver<T> = {
+    data?: (value: T) => void;
+    error?: (err: unknown) => void;
+    complete?: () => void;
+};
+/**
+ * Invokes side effects; values pass through unchanged.
+ *
+ * Accepts either a function (called on each DATA) or an observer object
+ * `{ data?, error?, complete? }` for lifecycle-aware side effects.
+ *
+ * @param source - Upstream node.
+ * @param fnOrObserver - Side effect function or observer object.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Passthrough node.
+ *
+ * @example
+ * ```ts
+ * import { tap, state } from "@graphrefly/graphrefly-ts";
+ *
+ * // Function form (DATA only)
+ * tap(state(1), (x) => console.log(x));
+ *
+ * // Observer form (DATA + ERROR + COMPLETE)
+ * tap(state(1), { data: console.log, error: console.error, complete: () => console.log("done") });
+ * ```
+ *
+ * @category extra
+ */
+declare function tap<T>(source: Node<T>, fnOrObserver: ((value: T) => void) | TapObserver<T>, opts?: ExtraOpts): Node<T>;
+/**
+ * Suppresses adjacent duplicates using `equals` (default `Object.is`).
+ *
+ * @param source - Upstream node.
+ * @param equals - Optional equality for consecutive values.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Deduped stream.
+ *
+ * @example
+ * ```ts
+ * import { distinctUntilChanged, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = distinctUntilChanged(state(1));
+ * ```
+ *
+ * @category extra
+ */
+declare function distinctUntilChanged<T>(source: Node<T>, equals?: (a: T, b: T) => boolean, opts?: ExtraOpts): Node<T>;
+/**
+ * Emits `[previous, current]` pairs starting after the second value (first pair uses `RESOLVED` only).
+ *
+ * @param source - Upstream node.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<readonly [T, T]>` - Pair stream.
+ *
+ * @example
+ * ```ts
+ * import { pairwise, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = pairwise(state(0));
+ * ```
+ *
+ * @category extra
+ */
+declare function pairwise<T>(source: Node<T>, opts?: ExtraOpts): Node<readonly [T, T]>;
+/**
+ * Combines the latest value from each dependency whenever any dep settles (combineLatest).
+ *
+ * @param sources - Nodes to combine (variadic).
+ * @returns `Node<T>` - Tuple of latest values.
+ *
+ * @example
+ * ```ts
+ * import { combine, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = combine(state(1), state("a"));
+ * ```
+ *
+ * @remarks
+ * Unlike RxJS `combineLatest`, this is named `combine`. Use the {@link combineLatest} alias
+ * if you prefer the RxJS name. Seed is always required for `scan`/`reduce` (no seedless mode).
+ *
+ * @category extra
+ */
+declare function combine<const T extends readonly unknown[]>(...sources: {
+    [K in keyof T]: Node<T[K]>;
+}): Node<T>;
+/**
+ * When `primary` settles, emits `[primary, latestSecondary]`. `secondary` alone updates cache only.
+ *
+ * @param primary - Main stream.
+ * @param secondary - Latest value is paired on each primary emission.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<readonly [A, B]>` - Paired stream.
+ *
+ * @example
+ * ```ts
+ * import { state, withLatestFrom } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = withLatestFrom(state(1), state("x"));
+ * ```
+ *
+ * @category extra
+ */
+declare function withLatestFrom<A, B>(primary: Node<A>, secondary: Node<B>, opts?: ExtraOpts): Node<readonly [A, B]>;
+/**
+ * Merges **`DATA`** from any source with correct two-phase dirty tracking. **`COMPLETE`** after **all** sources complete (spec §1.3.5).
+ *
+ * @param sources - Nodes to merge (variadic; empty completes immediately).
+ * @returns `Node<T>` - Merged stream.
+ *
+ * @remarks
+ * **Ordering:** DIRTY/RESOLVED rules follow multi-source semantics in `~/src/graphrefly/GRAPHREFLY-SPEC.md`.
+ *
+ * @example
+ * ```ts
+ * import { merge, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = merge(state(1), state(2));
+ * ```
+ *
+ * @category extra
+ */
+declare function merge<T>(...sources: readonly Node<T>[]): Node<T>;
+/**
+ * Zips one **`DATA`** from each source per cycle into a tuple. Only **`DATA`** enqueues (spec §1.3.3).
+ *
+ * @param sources - Nodes to zip (variadic).
+ * @returns `Node<T>` - Zipped tuples.
+ *
+ * @example
+ * ```ts
+ * import { state, zip } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = zip(state(1), state(2));
+ * ```
+ *
+ * @category extra
+ */
+declare function zip<const T extends readonly unknown[]>(...sources: {
+    [K in keyof T]: Node<T[K]>;
+}): Node<T>;
+/**
+ * Plays all of `firstSrc`, then all of `secondSrc`. **`DATA`** from `secondSrc` during phase one is buffered until handoff.
+ *
+ * @param firstSrc - First segment.
+ * @param secondSrc - Second segment.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Concatenated stream.
+ *
+ * @example
+ * ```ts
+ * import { concat, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = concat(state(1), state(2));
+ * ```
+ *
+ * @category extra
+ */
+declare function concat<T>(firstSrc: Node<T>, secondSrc: Node<T>, opts?: ExtraOpts): Node<T>;
+/**
+ * First source to emit **`DATA`** wins; later traffic follows only the winner (Rx-style `race`).
+ *
+ * @param sources - Contestants (variadic; empty completes immediately; one node is identity).
+ * @returns `Node<T>` - Winning stream.
+ *
+ * @example
+ * ```ts
+ * import { race, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = race(state(1), state(2));
+ * ```
+ *
+ * @category extra
+ */
+declare function race<T>(...sources: readonly Node<T>[]): Node<T>;
+/**
+ * Maps each settled value to an inner node; unsubscribes the previous inner (Rx-style `switchMap`).
+ *
+ * @param source - Upstream node.
+ * @param project - Maps each outer value to an inner source shape (`Node`, scalar, `PromiseLike`, `Iterable`, or `AsyncIterable`) coerced via {@link fromAny}.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<R>` - Emissions from the active inner subscription.
+ * @example
+ * ```ts
+ * import { switchMap, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const src = state(0);
+ * switchMap(src, (n) => state((n as number) * 2));
+ * ```
+ *
+ * @category extra
+ */
+declare function switchMap<T, R>(source: Node<T>, project: (value: T) => NodeInput<R>, opts?: ExtraOpts): Node<R>;
+/**
+ * Like {@link switchMap}, but ignores outer `DATA` while an inner subscription is active (`exhaustMap`).
+ *
+ * @param source - Upstream node.
+ * @param project - Maps each outer value to an inner source shape (`Node`, scalar, `PromiseLike`, `Iterable`, or `AsyncIterable`) coerced via {@link fromAny}.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<R>` - Emissions from the active inner while it runs.
+ * @example
+ * ```ts
+ * import { exhaustMap, state } from "@graphrefly/graphrefly-ts";
+ *
+ * exhaustMap(state(0), () => state(1));
+ * ```
+ *
+ * @category extra
+ */
+declare function exhaustMap<T, R>(source: Node<T>, project: (value: T) => NodeInput<R>, opts?: ExtraOpts): Node<R>;
+/**
+ * Enqueues each outer value and subscribes to inners one at a time (`concatMap`).
+ *
+ * @param source - Upstream node.
+ * @param project - Maps each outer value to an inner source shape (`Node`, scalar, `PromiseLike`, `Iterable`, or `AsyncIterable`) coerced via {@link fromAny}.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<R>` - Sequential concatenation of inner streams.
+ * @example
+ * ```ts
+ * import { concatMap, state } from "@graphrefly/graphrefly-ts";
+ *
+ * concatMap(state(0), (n) => state((n as number) + 1));
+ * ```
+ *
+ * @category extra
+ */
+declare function concatMap<T, R>(source: Node<T>, project: (value: T) => NodeInput<R>, opts?: ExtraOpts & {
+    maxBuffer?: number;
+}): Node<R>;
+/** Options for {@link mergeMap}. */
+type MergeMapOptions = ExtraOpts & {
+    /** Maximum number of concurrent inner subscriptions. Default: `Infinity` (unbounded). */
+    concurrent?: number;
+};
+/**
+ * Subscribes to inner nodes in parallel (up to `concurrent`) and merges outputs (`mergeMap` / `flatMap`).
+ *
+ * @param source - Upstream node.
+ * @param project - Maps each outer value to an inner source shape (`Node`, scalar, `PromiseLike`, `Iterable`, or `AsyncIterable`) coerced via {@link fromAny}.
+ * @param opts - Optional options including `concurrent` limit.
+ * @returns `Node<R>` - Merged output of all active inners; completes when the outer and every inner complete.
+ *
+ * @remarks
+ * **ERROR handling:** An `ERROR` from the outer source cancels all active inner
+ * subscriptions and propagates the error downstream. An `ERROR` from an inner
+ * subscription propagates downstream immediately but does **not** cancel sibling
+ * inner subscriptions — other active inners continue until they complete or the
+ * outer errors/completes. This is intentional: for parallel work, isolating
+ * failures per-inner is more useful than Rx-style "first error cancels all."
+ *
+ * @example
+ * ```ts
+ * import { mergeMap, state } from "@graphrefly/graphrefly-ts";
+ *
+ * // Unbounded (default)
+ * mergeMap(state(0), (n) => state((n as number) + 1));
+ *
+ * // Limited concurrency
+ * mergeMap(state(0), (n) => state((n as number) + 1), { concurrent: 3 });
+ * ```
+ *
+ * @category extra
+ */
+declare function mergeMap<T, R>(source: Node<T>, project: (value: T) => NodeInput<R>, opts?: MergeMapOptions): Node<R>;
+/**
+ * RxJS-named alias for {@link mergeMap} — projects each `DATA` to an inner node and merges outputs.
+ *
+ * @param source - Upstream node.
+ * @param project - Returns an inner `Node<R>` per value.
+ * @param opts - Optional concurrency cap and node options (excluding `describeKind`).
+ * @returns Merged projection; behavior matches `mergeMap`.
+ *
+ * @example
+ * ```ts
+ * import { flatMap, state } from "@graphrefly/graphrefly-ts";
+ *
+ * flatMap(state(0), (n) => state(n));
+ * ```
+ *
+ * @category extra
+ */
+declare const flatMap: typeof mergeMap;
+/**
+ * Delays phase-2 emissions by `ms` (timers). `DIRTY` still forwards immediately.
+ *
+ * @param source - Upstream node.
+ * @param ms - Delay in milliseconds.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Same values, shifted in time.
+ * @example
+ * ```ts
+ * import { delay, state } from "@graphrefly/graphrefly-ts";
+ *
+ * delay(state(1), 100);
+ * ```
+ *
+ * @category extra
+ */
+declare function delay<T>(source: Node<T>, ms: number, opts?: ExtraOpts): Node<T>;
+/**
+ * Emits the latest value only after `ms` quiet time since the last trigger (`debounce`).
+ *
+ * @param source - Upstream node.
+ * @param ms - Quiet window in milliseconds.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Debounced stream.
+ * @example
+ * ```ts
+ * import { debounce, state } from "@graphrefly/graphrefly-ts";
+ *
+ * debounce(state(0), 50);
+ * ```
+ *
+ * @category extra
+ */
+declare function debounce<T>(source: Node<T>, ms: number, opts?: ExtraOpts): Node<T>;
+type ThrottleOptions = {
+    leading?: boolean;
+    trailing?: boolean;
+};
+/**
+ * Rate-limits emissions to at most once per `ms` window (`throttleTime`).
+ *
+ * @param source - Upstream node.
+ * @param ms - Minimum spacing in milliseconds.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`) plus `leading` / `trailing`.
+ * @returns `Node<T>` - Throttled stream.
+ * @example
+ * ```ts
+ * import { throttle, state } from "@graphrefly/graphrefly-ts";
+ *
+ * throttle(state(0), 1_000, { trailing: false });
+ * ```
+ *
+ * @category extra
+ */
+declare function throttle<T>(source: Node<T>, ms: number, opts?: ExtraOpts & ThrottleOptions): Node<T>;
+/**
+ * Emits the most recent source value whenever `notifier` emits `DATA` (`sample`).
+ *
+ * Source `COMPLETE` stops sampling (clears held value); notifier `COMPLETE` terminates the
+ * operator. `ERROR` from either dep terminates immediately. At most one terminal message is
+ * emitted downstream (latch). Supports `resubscribable` — `ctx.store` resets automatically.
+ *
+ * @param source - Node whose latest value is sampled.
+ * @param notifier - When this node emits `DATA`, a sample is taken.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Sampled snapshots of `source`.
+ * @example
+ * ```ts
+ * import { sample, state } from "@graphrefly/graphrefly-ts";
+ *
+ * sample(state(1), state(0));
+ * ```
+ *
+ * @category extra
+ */
+declare function sample<T>(source: Node<T>, notifier: Node<unknown>, opts?: ExtraOpts): Node<T>;
+/**
+ * After each source `DATA`, waits `ms` then emits the latest value if another `DATA` has not arrived (`auditTime` / trailing window).
+ *
+ * @param source - Upstream node.
+ * @param ms - Window in milliseconds after each `DATA`.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Trailing-edge sampled stream.
+ * @example
+ * ```ts
+ * import { audit, state } from "@graphrefly/graphrefly-ts";
+ *
+ * audit(state(0), 100);
+ * ```
+ *
+ * @category extra
+ */
+declare function audit<T>(source: Node<T>, ms: number, opts?: ExtraOpts): Node<T>;
+/**
+ * Errors if no `DATA` arrives within `ms` after subscribe or after the previous `DATA`.
+ *
+ * @param source - Upstream node.
+ * @param ms - Idle budget in milliseconds.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`) and `with` for a custom error payload.
+ * @returns `Node<T>` - Pass-through with idle watchdog.
+ * @example
+ * ```ts
+ * import { timeout, state } from "@graphrefly/graphrefly-ts";
+ *
+ * timeout(state(0), 5_000);
+ * ```
+ *
+ * @category extra
+ */
+declare function timeout<T>(source: Node<T>, ms: number, opts?: ExtraOpts & {
+    with?: unknown;
+}): Node<T>;
+/**
+ * Buffers source `DATA` values; flushes an array when `notifier` settles (`buffer`).
+ *
+ * @param source - Upstream node.
+ * @param notifier - Flush trigger on each settlement.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T[]>` - Emits buffered arrays (may be empty-handled via `RESOLVED` when nothing buffered).
+ * @example
+ * ```ts
+ * import { buffer, state } from "@graphrefly/graphrefly-ts";
+ *
+ * buffer(state(0), state(0));
+ * ```
+ *
+ * @category extra
+ */
+declare function buffer<T>(source: Node<T>, notifier: Node<unknown>, opts?: ExtraOpts): Node<T[]>;
+/**
+ * Batches consecutive `DATA` values into arrays of length `count` (`bufferCount` / `windowCount`).
+ *
+ * @param source - Upstream node.
+ * @param count - Buffer size before emit; must be > 0.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T[]>` - Emits fixed-size arrays; remainder flushes on `COMPLETE`.
+ * @example
+ * ```ts
+ * import { bufferCount, state } from "@graphrefly/graphrefly-ts";
+ *
+ * bufferCount(state(0), 3);
+ * ```
+ *
+ * @category extra
+ */
+declare function bufferCount<T>(source: Node<T>, count: number, opts?: ExtraOpts): Node<T[]>;
+/**
+ * Splits source `DATA` into sub-nodes of `count` values each. Each sub-node completes after `count` items or when source completes.
+ *
+ * @param source - Upstream node.
+ * @param count - Items per window.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<Node<T>>` - Each emission is a sub-node carrying that window's values.
+ *
+ * @example
+ * ```ts
+ * import { windowCount, state } from "@graphrefly/graphrefly-ts";
+ *
+ * windowCount(state(0), 3);
+ * ```
+ *
+ * @category extra
+ */
+declare function windowCount<T>(source: Node<T>, count: number, opts?: ExtraOpts): Node<Node<T>>;
+/**
+ * Flushes buffered `DATA` values every `ms` (`bufferTime` / `windowTime`).
+ *
+ * @param source - Upstream node.
+ * @param ms - Flush interval in milliseconds.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T[]>` - Time-windowed batches.
+ * @example
+ * ```ts
+ * import { bufferTime, state } from "@graphrefly/graphrefly-ts";
+ *
+ * bufferTime(state(0), 250);
+ * ```
+ *
+ * @category extra
+ */
+declare function bufferTime<T>(source: Node<T>, ms: number, opts?: ExtraOpts): Node<T[]>;
+/**
+ * Splits source `DATA` into time-windowed sub-nodes; each window lasts `ms`.
+ *
+ * @param source - Upstream node.
+ * @param ms - Window duration in milliseconds.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<Node<T>>` - Each emission is a sub-node carrying that window's values.
+ *
+ * @example
+ * ```ts
+ * import { windowTime, state } from "@graphrefly/graphrefly-ts";
+ *
+ * windowTime(state(0), 500);
+ * ```
+ *
+ * @category extra
+ */
+declare function windowTime<T>(source: Node<T>, ms: number, opts?: ExtraOpts): Node<Node<T>>;
+/**
+ * Splits source `DATA` into sub-nodes, opening a new window each time `notifier` emits `DATA`.
+ *
+ * @param source - Upstream node.
+ * @param notifier - Each `DATA` from `notifier` closes the current window and opens a new one.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<Node<T>>` - Each emission is a sub-node carrying that window's values.
+ *
+ * @example
+ * ```ts
+ * import { state, window } from "@graphrefly/graphrefly-ts";
+ *
+ * window(state(0), state(0));
+ * ```
+ *
+ * @category extra
+ */
+declare function window<T>(source: Node<T>, notifier: Node<unknown>, opts?: ExtraOpts): Node<Node<T>>;
+/**
+ * Increments on each tick (`interval`); uses `setInterval` via {@link producer}.
+ *
+ * @param periodMs - Time between ticks.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<number>` - Emits `0`, `1`, `2`, … while subscribed.
+ * @example
+ * ```ts
+ * import { interval } from "@graphrefly/graphrefly-ts";
+ *
+ * interval(1_000);
+ * ```
+ *
+ * @category extra
+ */
+declare function interval(periodMs: number, opts?: ExtraOpts): Node<number>;
+/**
+ * Subscribes to `source` repeatedly (`count` times, sequentially). Best with a fresh or `resubscribable` source.
+ *
+ * @param source - Upstream node to replay.
+ * @param count - Number of subscription rounds.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Forwards each round then completes after the last inner `COMPLETE`.
+ * @example
+ * ```ts
+ * import { repeat, state } from "@graphrefly/graphrefly-ts";
+ *
+ * repeat(state(1, { resubscribable: true }), 2);
+ * ```
+ *
+ * @category extra
+ */
+declare function repeat<T>(source: Node<T>, count: number, opts?: ExtraOpts): Node<T>;
+/**
+ * Identity passthrough — `pausable()` has been promoted to default node behavior in v5 (§4).
+ *
+ * @deprecated Default node behavior now handles PAUSE/RESUME. This operator is a no-op
+ * identity passthrough kept only for migration compatibility.
+ *
+ * @param source - Upstream node.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Pass-through (identity).
+ * @example
+ * ```ts
+ * import { pausable, state } from "@graphrefly/graphrefly-ts";
+ *
+ * // No longer needed — default nodes handle PAUSE/RESUME.
+ * const s = state(0);
+ * pausable(s); // identity passthrough
+ * ```
+ *
+ * @category extra
+ */
+declare function pausable<T>(source: Node<T>, opts?: ExtraOpts): Node<T>;
+/**
+ * Replaces an upstream `ERROR` with a recovered value (`catchError`-style).
+ *
+ * @param source - Upstream node.
+ * @param recover - Maps the error payload to a replacement value; if it throws, `ERROR` is forwarded.
+ * @param opts - Optional {@link NodeOptions} (excluding `describeKind`).
+ * @returns `Node<T>` - Recovered stream.
+ * @example
+ * ```ts
+ * import { rescue, state } from "@graphrefly/graphrefly-ts";
+ *
+ * rescue(state(0), () => 0);
+ * ```
+ *
+ * @category extra
+ */
+declare function rescue<T>(source: Node<T>, recover: (err: unknown) => T, opts?: ExtraOpts): Node<T>;
+/**
+ * Forwards upstream `DATA` only while `control.get()` is truthy; when closed, emits `RESOLVED`
+ * instead of repeating the last value (value-level valve). For protocol pause/resume, use default
+ * node PAUSE/RESUME behavior.
+ *
+ * @param source - Upstream value node.
+ * @param control - Boolean node; when falsy, output stays "closed" for that tick.
+ * @param opts - Optional node options (excluding `describeKind`).
+ * @returns `Node<T>` gated by `control`.
+ *
+ * @example
+ * ```ts
+ * import { valve, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const data = state(1);
+ * const open = state(true);
+ * valve(data, open);
+ * ```
+ *
+ * @category extra
+ */
+declare function valve<T>(source: Node<T>, control: Node<boolean>, opts?: ExtraOpts): Node<T>;
+/**
+ * RxJS-named alias for {@link combine} — emits when any dep updates with latest tuple of values.
+ *
+ * @param sources - Upstream nodes as separate arguments (same calling shape as `combine`).
+ * @returns Combined node; signature matches `combine`.
+ *
+ * @example
+ * ```ts
+ * import { combineLatest, state } from "@graphrefly/graphrefly-ts";
+ *
+ * const n = combineLatest(state(1), state("a"));
+ * ```
+ *
+ * @category extra
+ */
+declare const combineLatest: typeof combine;
+/**
+ * RxJS-named alias for {@link debounce} — drops rapid `DATA` until `ms` of quiet.
+ *
+ * @param source - Upstream node.
+ * @param ms - Quiet period in milliseconds.
+ * @param opts - Optional node options (excluding `describeKind`).
+ * @returns Debounced node; behavior matches `debounce`.
+ *
+ * @example
+ * ```ts
+ * import { debounceTime, state } from "@graphrefly/graphrefly-ts";
+ *
+ * debounceTime(state(0), 100);
+ * ```
+ *
+ * @category extra
+ */
+declare const debounceTime: typeof debounce;
+/**
+ * RxJS-named alias for {@link throttle} — emits on leading/trailing edges within `ms`.
+ *
+ * @param source - Upstream node.
+ * @param ms - Minimum spacing in milliseconds.
+ * @param opts - Optional throttle shape (`leading` / `trailing`) and node options.
+ * @returns Throttled node; behavior matches `throttle`.
+ *
+ * @example
+ * ```ts
+ * import { throttleTime, state } from "@graphrefly/graphrefly-ts";
+ *
+ * throttleTime(state(0), 100);
+ * ```
+ *
+ * @category extra
+ */
+declare const throttleTime: typeof throttle;
+/**
+ * RxJS-named alias for {@link rescue} — replaces upstream `ERROR` with a recovered value.
+ *
+ * @param source - Upstream node.
+ * @param recover - Maps error payload to replacement value.
+ * @param opts - Optional node options (excluding `describeKind`).
+ * @returns Recovered stream; behavior matches `rescue`.
+ *
+ * @example
+ * ```ts
+ * import { catchError, state } from "@graphrefly/graphrefly-ts";
+ *
+ * catchError(state(0), () => 0);
+ * ```
+ *
+ * @category extra
+ */
+declare const catchError: typeof rescue;
+
+export { type MergeMapOptions, type TapObserver, type ThrottleOptions, audit, buffer, bufferCount, bufferTime, catchError, combine, combineLatest, concat, concatMap, debounce, debounceTime, delay, distinctUntilChanged, elementAt, exhaustMap, filter, find, first, flatMap, interval, last, map, merge, mergeMap, pairwise, pausable, race, reduce, repeat, rescue, sample, scan, skip, switchMap, take, takeUntil, takeWhile, tap, throttle, throttleTime, timeout, valve, window, windowCount, windowTime, withLatestFrom, zip };