@graphrefly/graphrefly 0.44.0 → 0.45.0

package/dist/extra/sources.d.cts

@@ -1,584 +1 @@
-import { a as NodeOptions, N as Node } from '../node-kK3CvTrR.cjs';
-
-/**
- * Core reactive sources, sinks, and utilities (roadmap §2.3).
- *
- * Each API returns a {@link Node} built with {@link node}, {@link producer},
- * {@link derived}, or {@link effect} — no second protocol.
- *
- * Protocol/system/ingest adapters (fromHTTP, fromWebSocket, fromKafka, etc.)
- * live in {@link ./adapters.ts}.
- */
-
-type ExtraOpts = Omit<NodeOptions<unknown>, "describeKind">;
-/** Options for {@link fromTimer} / {@link fromPromise} / {@link fromAsyncIter}. */
-type AsyncSourceOpts = ExtraOpts & {
-    signal?: AbortSignal;
-};
-/**
- * Values accepted by {@link fromAny}.
- *
- * @category extra
- */
-type NodeInput<T> = Node<T> | PromiseLike<T> | AsyncIterable<T> | Iterable<T> | T;
-/** Options for {@link fromCron}. */
-type FromCronOptions = ExtraOpts & {
-    /** Polling interval in ms. Default `60_000`. */
-    tickMs?: number;
-    /** Output format: `"timestamp_ns"` (default) emits wall-clock nanoseconds; `"date"` emits a `Date` object. */
-    output?: "timestamp_ns" | "date";
-};
-/** DOM-style event target (browser or `node:events`). */
-type EventTargetLike = {
-    addEventListener(type: string, listener: (ev: unknown) => void, options?: boolean | {
-        capture?: boolean;
-        passive?: boolean;
-        once?: boolean;
-    }): void;
-    removeEventListener(type: string, listener: (ev: unknown) => void, options?: boolean | {
-        capture?: boolean;
-        passive?: boolean;
-        once?: boolean;
-    }): void;
-};
-/** @internal Shared with adapters.ts and sources-fs.ts for glob matching. */
-declare function escapeRegexChar(ch: string): string;
-/** @internal */
-declare function globToRegExp(glob: string): RegExp;
-/** @internal */
-declare function matchesAnyPattern(path: string, patterns: RegExp[]): boolean;
-/**
- * Builds a timer-driven source: one-shot (first tick then `COMPLETE`) or periodic (`0`, `1`, `2`, …).
- *
- * @param ms - Milliseconds before the first emission.
- * @param opts - Producer options plus optional `period` for repeating ticks and optional `signal` (`AbortSignal`) to cancel with `ERROR`.
- * @returns `Node<number>` — tick counter from `0`; teardown clears timers.
- *
- * @example
- * ```ts
- * import { fromTimer } from "@graphrefly/graphrefly-ts";
- *
- * fromTimer(250, { period: 1_000 });
- * ```
- *
- * @category extra
- */
-declare function fromTimer(ms: number, opts?: AsyncSourceOpts & {
-    period?: number;
-}): Node<number>;
-/**
- * Animation-frame-driven source. Emits on every `requestAnimationFrame` tick,
- * yielding the frame timestamp (DOMHighResTimeStamp, ms since navigation).
- *
- * Use instead of `fromTimer({ period: 16 })` when animation smoothness matters.
- * In a real browser, `requestAnimationFrame` synchronizes with the display
- * refresh. The source keeps ticking even when the tab is hidden — it
- * transparently switches to `setTimeout` while the tab is backgrounded (so
- * downstream state updates continue) and returns to `requestAnimationFrame`
- * when the tab regains focus.
- *
- * When `requestAnimationFrame` is unavailable (Node test environments, SSR),
- * this falls back to `setTimeout(~16ms)` unconditionally. Abortable via
- * `signal` (emits `ERROR`).
- *
- * @example
- * ```ts
- * import { fromRaf, derived } from "@graphrefly/graphrefly-ts";
- *
- * const frame = fromRaf();
- * const bouncingX = derived([frame], ([t]) => 50 + 40 * Math.sin((t as number) * 0.001));
- * ```
- *
- * @category extra
- */
-declare function fromRaf(opts?: AsyncSourceOpts): Node<number>;
-/**
- * Polls on an interval; when the current minute matches a 5-field cron expression, emits once (see {@link parseCron}).
- *
- * @param expr - Cron string (`min hour dom month dow`).
- * @param opts - Producer options plus `tickMs` (default `60_000`) and `output` (`timestamp_ns` default, or `date` for `Date` values).
- * @returns `Node<number>` (nanosecond timestamp) or `Node<Date>` when `output: "date"`.
- *
- * @example
- * ```ts
- * import { fromCron } from "@graphrefly/graphrefly-ts";
- *
- * fromCron("0 9 * * 1");
- * ```
- *
- * @category extra
- */
-declare function fromCron(expr: string, opts?: FromCronOptions & {
-    output: "date";
-}): Node<Date>;
-declare function fromCron(expr: string, opts?: FromCronOptions): Node<number>;
-/**
- * Wraps a DOM-style `addEventListener` target; each event becomes a `DATA` emission.
- *
- * @param target - Object with `addEventListener` / `removeEventListener`.
- * @param type - Event name (e.g. `"click"`).
- * @param opts - Producer options plus listener options (`capture`, `passive`, `once`).
- * @returns `Node<T>` — event payloads; teardown removes the listener.
- *
- * @example
- * ```ts
- * import { fromEvent } from "@graphrefly/graphrefly-ts";
- *
- * fromEvent(document.body, "click");
- * ```
- *
- * @category extra
- */
-declare function fromEvent<T = unknown>(target: EventTargetLike, type: string, opts?: ExtraOpts & {
-    capture?: boolean;
-    passive?: boolean;
-    once?: boolean;
-}): Node<T>;
-/**
- * Drains a synchronous iterable; each item is `DATA`, then `COMPLETE`, or `ERROR` if iteration throws.
- *
- * @param iterable - Values to emit in order.
- * @param opts - Optional producer options.
- * @returns `Node<T>` — one emission per element.
- *
- * @example
- * ```ts
- * import { fromIter } from "@graphrefly/graphrefly-ts";
- *
- * fromIter([1, 2, 3]);
- * ```
- *
- * @category extra
- */
-declare function fromIter<T>(iterable: Iterable<T>, opts?: ExtraOpts): Node<T>;
-/**
- * Lifts a Promise (or thenable) to a single-value stream: one `DATA` then `COMPLETE`, or `ERROR` on rejection.
- *
- * @param p - Promise to await.
- * @param opts - Producer options plus optional `signal` for abort → `ERROR` with reason.
- * @returns `Node<T>` — settles once.
- *
- * @example
- * ```ts
- * import { fromPromise } from "@graphrefly/graphrefly-ts";
- *
- * fromPromise(Promise.resolve(42));
- * ```
- *
- * @category extra
- */
-declare function fromPromise<T>(p: Promise<T> | PromiseLike<T>, opts?: AsyncSourceOpts): Node<T>;
-/**
- * Reads an async iterable; each `next()` value becomes `DATA`; `COMPLETE` when done; `ERROR` on failure.
- *
- * @param iterable - Async source (`for await` shape).
- * @param opts - Producer options plus optional `signal` to abort the pump.
- * @returns `Node<T>` — async pull stream.
- *
- * @example
- * ```ts
- * import { fromAsyncIter } from "@graphrefly/graphrefly-ts";
- *
- * async function* gen() {
- *   yield 1;
- * }
- * fromAsyncIter(gen());
- * ```
- *
- * @category extra
- */
-declare function fromAsyncIter<T>(iterable: AsyncIterable<T>, opts?: AsyncSourceOpts): Node<T>;
-/**
- * Coerces a value to a `Node` by shape: existing `Node` passthrough, thenable → {@link fromPromise},
- * async iterable → {@link fromAsyncIter}, sync iterable → {@link fromIter}, else scalar → {@link of}.
- *
- * @param input - Any value to wrap.
- * @param opts - Passed through when a Promise/async path is chosen.
- * @returns `Node` of the inferred element type.
- *
- * @example
- * ```ts
- * import { fromAny, state } from "@graphrefly/graphrefly-ts";
- *
- * fromAny(state(1));
- * fromAny(Promise.resolve(2));
- * ```
- *
- * @category extra
- */
-declare function fromAny<T>(input: NodeInput<T>, opts?: AsyncSourceOpts): Node<T>;
-/**
- * Emits each argument as `DATA` in order, then `COMPLETE` (implemented via {@link fromIter}).
- *
- * @param values - Values to emit.
- * @returns `Node<T>` — finite sequence.
- *
- * @example
- * ```ts
- * import { of } from "@graphrefly/graphrefly-ts";
- *
- * of(1, 2, 3);
- * ```
- *
- * @category extra
- */
-declare function of<T>(...values: T[]): Node<T>;
-/**
- * Completes immediately with no `DATA` (cold `EMPTY` analogue).
- *
- * @param opts - Optional producer options.
- * @returns `Node<T>` — terminal `COMPLETE` only.
- *
- * @example
- * ```ts
- * import { empty } from "@graphrefly/graphrefly-ts";
- *
- * empty();
- * ```
- *
- * @category extra
- */
-declare function empty<T = never>(opts?: ExtraOpts): Node<T>;
-/**
- * Never emits and never completes until teardown (cold `NEVER` analogue).
- *
- * @param opts - Optional producer options.
- * @returns `Node<T>` — silent until unsubscribed.
- *
- * @example
- * ```ts
- * import { never } from "@graphrefly/graphrefly-ts";
- *
- * never();
- * ```
- *
- * @category extra
- */
-declare function never<T = never>(opts?: ExtraOpts): Node<T>;
-/**
- * Emits `ERROR` as soon as the producer starts (cold error source).
- *
- * @param err - Error payload forwarded as `ERROR` data.
- * @param opts - Optional producer options.
- * @returns `Node<never>` — terminates with `ERROR`.
- *
- * @example
- * ```ts
- * import { throwError } from "@graphrefly/graphrefly-ts";
- *
- * throwError(new Error("fail"));
- * ```
- *
- * @category extra
- */
-declare function throwError(err: unknown, opts?: ExtraOpts): Node<never>;
-/**
- * Lazily constructs a {@link Node} from a thunk that runs at **activation
- * time** (first subscriber after a teardown to zero sinks), not factory time.
- *
- * **Resubscribable by default.** Diverges from `fromPromise` / `fromIter` /
- * `fromAsyncIter` (which are single-shot — second subscriber sees the cached
- * terminal value). `defer`'s contract matches RxJS `defer`: every fresh
- * activation cycle re-runs the thunk. To opt out and get one-shot semantics,
- * pass `{ resubscribable: false }`.
- *
- * **Sharing across overlapping subscribers.** The thunk only re-runs on a
- * fresh activation cycle (zero → one sink). Overlapping subscribers share
- * the single activation; the thunk does NOT re-run for each subscriber. If
- * the thunk returns an existing `Node`, that Node is shared across activations
- * — `defer` will subscribe to it on each activation but does not isolate state
- * across subscribers. For per-subscriber isolation, the thunk must construct
- * a fresh source (`state(...)`, `fromPromise(fetch(...))`, etc.) on each call.
- *
- * **Use cases:**
- * - Lazy upstream construction (avoid eager evaluation of expensive factories
- *   at module load — the thunk runs only when something subscribes).
- * - Per-activation resource construction (open a connection / file handle on
- *   subscribe, when paired with full teardown between sessions).
- * - Bridging non-Node inputs (Promise, AsyncIterable, Iterable, scalar) into
- *   the graph behind a lazy boundary.
- *
- * The thunk's return value is bridged via {@link fromAny}. Errors thrown by
- * the thunk surface as a single `[[ERROR, err]]` on the output (with `err`
- * coerced to a non-`undefined` value to satisfy spec §1.3 — bare `throw` and
- * `throw undefined` are wrapped in a `defer: thunk threw undefined` Error).
- *
- * Upstream messages are forwarded transparently (DIRTY / DATA / RESOLVED /
- * COMPLETE / ERROR / INVALIDATE / PAUSE / RESUME / TEARDOWN), preserving
- * batch boundaries. The producer's own `START` handshake is delivered to
- * subscribers automatically; the upstream's `START` is filtered.
- *
- * @param thunk - Called on each activation; returns the upstream input.
- * @param opts - Forwarded to `fromAny` (e.g. `signal` for async inputs).
- *   `signal` is only consumed by `fromAny` for async input shapes (Promise,
- *   AsyncIterable); it does NOT abort a Node-input or scalar-input defer.
- * @returns `Node<T>` — lazy upstream-on-activation.
- *
- * @example
- * ```ts
- * import { defer } from "@graphrefly/graphrefly-ts";
- *
- * // Lazy fetch — runs on the first activation, NOT at factory time.
- * // Each fresh activation cycle (after teardown) re-runs the thunk →
- * // a new fetch. Overlapping subscribers share the single activation.
- * const live = defer(() => fetch("/api/feed").then((r) => r.json()));
- * ```
- *
- * @category extra
- */
-declare function defer<T>(thunk: () => NodeInput<T>, opts?: AsyncSourceOpts): Node<T>;
-/**
- * Subscribes immediately and runs `fn` for each upstream `DATA`; returns unsubscribe.
- *
- * @param source - Upstream node.
- * @param fn - Side effect per value.
- * @param opts - Effect node options.
- * @returns Unsubscribe function (idempotent).
- *
- * @example
- * ```ts
- * import { forEach, state } from "@graphrefly/graphrefly-ts";
- *
- * const u = forEach(state(1), (v) => console.log(v));
- * u();
- * ```
- *
- * @category extra
- */
-declare function forEach<T>(source: Node<T>, fn: (value: T) => void, opts?: ExtraOpts): () => void;
-/**
- * Buffers every `DATA`; on upstream `COMPLETE` emits one `DATA` with the full array then `COMPLETE`.
- *
- * @param source - Upstream node.
- * @param opts - Optional node options (derived describe kind).
- * @returns `Node<T[]>` — single array emission before completion.
- *
- * @example
- * ```ts
- * import { of, toArray } from "@graphrefly/graphrefly-ts";
- *
- * toArray(of(1, 2, 3));
- * ```
- *
- * @category extra
- */
-declare function toArray<T>(source: Node<T>, opts?: ExtraOpts): Node<T[]>;
-/**
- * Multicasts upstream: one subscription to `source` while this wrapper has subscribers (via {@link producer}).
- *
- * @param source - Upstream node to share.
- * @param opts - Producer options; `initial` seeds from `source.cache` when set by factory.
- * @returns `Node<T>` — hot ref-counted bridge.
- *
- * @example
- * ```ts
- * import { share, state } from "@graphrefly/graphrefly-ts";
- *
- * share(state(0));
- * ```
- *
- * @category extra
- */
-declare function share<T>(source: Node<T>, opts?: ExtraOpts): Node<T>;
-/**
- * Like {@link share} with a bounded replay buffer: new subscribers receive the last `bufferSize`
- * `DATA` payloads (as separate batches) before live updates.
- *
- * @param source - Upstream node.
- * @param bufferSize - Maximum past values to replay (≥ 1).
- * @param opts - Producer options.
- * @returns `Node<T>` — multicast with replay on subscribe.
- *
- * @example
- * ```ts
- * import { replay, state } from "@graphrefly/graphrefly-ts";
- *
- * replay(state(0), 3);
- * ```
- *
- * @category extra
- */
-declare function replay<T>(source: Node<T>, bufferSize: number, opts?: ExtraOpts): Node<T>;
-/**
- * {@link replay} with `bufferSize === 1` — replays the latest `DATA` to new subscribers.
- *
- * @param source - Upstream node.
- * @param opts - Producer options.
- * @returns `Node<T>` — share + last-value replay.
- *
- * @example
- * ```ts
- * import { cached, state } from "@graphrefly/graphrefly-ts";
- *
- * cached(state(0));
- * ```
- *
- * @category extra
- */
-declare function cached<T>(source: Node<T>, opts?: ExtraOpts): Node<T>;
-/**
- * Converts the first `DATA` on `source` into a Promise; rejects on `ERROR` or `COMPLETE` without data.
- *
- * **Important:** This subscribes and waits for a **future** emission. Data that
- * has already flowed is gone and will not be seen. Call this *before* the upstream
- * emits, or use `source.cache` / `source.status` for already-cached state.
- * See COMPOSITION-GUIDE §2 (subscription ordering).
- *
- * @param source - Node to read once.
- * @returns Promise of the first value.
- *
- * @example
- * ```ts
- * import { firstValueFrom, of } from "@graphrefly/graphrefly-ts";
- *
- * await firstValueFrom(of(42));
- * ```
- *
- * @category extra
- */
-declare function firstValueFrom<T>(source: Node<T>): Promise<T>;
-/**
- * Wait for the first DATA value from `source` that satisfies `predicate`.
- *
- * Subscribes directly and resolves on the first DATA value where
- * `predicate` returns true. Reactive, no polling. Use in tests and
- * bridging code where you need a single matching value as a Promise.
- *
- * **Important:** This only captures **future** emissions — data that has
- * already flowed through the node is gone. Call this *before* the upstream
- * emits. For already-cached values, use `source.cache` / `source.status`.
- * See COMPOSITION-GUIDE §2 (subscription ordering).
- *
- * ```ts
- * const val = await firstWhere(strategy.node, snap => snap.size > 0);
- * ```
- *
- * @param source - Upstream node to observe.
- * @param predicate - Returns `true` for the value to resolve on.
- * @param opts - `{ skipCurrent?: boolean }`. When `skipCurrent: true`, any DATA
- *   delivered during the synchronous `subscribe()` call (push-on-subscribe §2.2
- *   replay of the cached value) is ignored — the promise resolves only on the
- *   next future emission. Useful when the caller wants to await the next
- *   settlement event after an imperative action (e.g. `run()` minting a new
- *   runVersion, where the currently-cached value belongs to the previous run).
- *
- * @category extra
- */
-declare function firstWhere<T>(source: Node<T>, predicate: (value: T) => boolean, opts?: {
-    skipCurrent?: boolean;
-}): Promise<T>;
-declare function awaitSettled<T>(source: Node<T>, opts?: {
-    predicate?: (value: T) => boolean;
-    timeoutMs?: number;
-    skipCurrent?: boolean;
-}): Promise<NonNullable<T>>;
-/**
- * Converts a reactive `Node<boolean>` into a browser-standard `AbortSignal`
- * that fires when the node settles on `true`. Useful for threading a reactive
- * "cancel" flag into any async boundary that accepts a signal (fetch, LLM SDK
- * calls, child-process APIs, timers).
- *
- * **Contract.**
- * - `signal.abort(reason)` fires exactly once, on the first DATA emission with
- *   a truthy value. Subsequent emissions are ignored (AbortSignal is
- *   single-shot).
- * - Null / `false` / sentinel values are ignored. Push-on-subscribe will
- *   check the currently-cached value on subscribe and abort immediately if
- *   it's already `true`.
- * - `reason` defaults to `"cancelled via nodeSignal"`; pass `opts.reason` to
- *   override (`DOMException`, `Error`, or any value accepted by
- *   `AbortController.abort`).
- *
- * **Lifecycle.**
- * - Returns a `{signal, dispose}` bundle. Call `dispose()` when you're done
- *   with the signal (e.g. in a `finally` after the async operation completes).
- *   `dispose()` unsubscribes from the node and is a no-op once the signal has
- *   fired.
- * - **Memory note:** without `dispose()` the subscription keeps the reactive
- *   node alive for the lifetime of the process. For bridge calls inside a
- *   `switchMap` project fn, the switchMap supersede tears the inner subgraph
- *   down, which is usually the right lifetime — but still call `dispose()`
- *   from the caller's `finally` for clarity.
- *
- * @example
- * ```ts
- * const aborted = state(false);
- * const { signal, dispose } = nodeSignal(aborted);
- * try {
- *   const resp = await adapter.invoke(msgs, { signal });
- *   return resp;
- * } finally {
- *   dispose();
- * }
- * ```
- *
- * @category extra
- */
-declare function nodeSignal(source: Node<boolean>, opts?: {
-    reason?: unknown;
-}): {
-    signal: AbortSignal;
-    dispose: () => void;
-};
-/**
- * RxJS-named alias for {@link replay} — multicast with a replay buffer of size `bufferSize`.
- *
- * @param source - Upstream node.
- * @param bufferSize - Replay depth (≥ 1).
- * @param opts - Producer options.
- * @returns Same behavior as `replay`.
- *
- * @example
- * ```ts
- * import { shareReplay, state } from "@graphrefly/graphrefly-ts";
- *
- * shareReplay(state(0), 5);
- * ```
- *
- * @category extra
- */
-declare const shareReplay: typeof replay;
-/**
- * Activate a compute node's upstream wiring without a real sink.
- *
- * Derived/effect nodes are lazy — they don't compute until at least one
- * subscriber exists (COMPOSITION-GUIDE §5). `keepalive` subscribes with an
- * empty sink so the node stays wired for `.cache` and upstream propagation.
- *
- * Returns the unsubscribe handle. Common usage:
- * `graph.addDisposer(keepalive(node))`.
- *
- * @category extra
- */
-declare function keepalive(n: Node<unknown>): () => void;
-/** Bundle returned by {@link reactiveCounter}. */
-type ReactiveCounterBundle = {
-    /** Reactive node holding the current count. */
-    readonly node: Node<number>;
-    /** Increment by 1. Returns `false` if cap would be exceeded. */
-    increment(): boolean;
-    /** Current count (synchronous read). */
-    get(): number;
-    /** Whether the counter has reached its cap. */
-    atCap(): boolean;
-};
-/**
- * Reactive counter with a cap — the building block for circuit breakers.
- *
- * Wraps a `state(0)` node with `increment()` that respects a maximum.
- * The `node` is subscribable and composable like any reactive node. When
- * the cap is reached, `increment()` returns `false`.
- *
- * ```ts
- * const retries = reactiveCounter(10);
- * retries.increment(); // true — count is now 1
- * retries.node.subscribe(...); // reactive updates
- * retries.atCap(); // false
- * ```
- *
- * @param cap - Maximum value (inclusive). 0 = no increments allowed.
- * @category extra
- */
-declare function reactiveCounter(cap: number): ReactiveCounterBundle;
-
-export { type AsyncSourceOpts, type EventTargetLike, type FromCronOptions, type NodeInput, type ReactiveCounterBundle, awaitSettled, cached, defer, empty, escapeRegexChar, firstValueFrom, firstWhere, forEach, fromAny, fromAsyncIter, fromCron, fromEvent, fromIter, fromPromise, fromRaf, fromTimer, globToRegExp, keepalive, matchesAnyPattern, never, nodeSignal, of, reactiveCounter, replay, share, shareReplay, throwError, toArray };
+export * from '@graphrefly/pure-ts/extra/sources';