@graphrefly/graphrefly 0.25.0 → 0.26.0

package/dist/extra/sources.d.ts

@@ -0,0 +1,465 @@
+import { a as NodeOptions, N as Node } from '../node-C_IBuvX2.js';
+
+/**
+ * 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>;
+/**
+ * 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);
+ * ```
+ *
+ * @category extra
+ */
+declare function firstWhere<T>(source: Node<T>, predicate: (value: T) => boolean): Promise<T>;
+/**
+ * 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, cached, empty, escapeRegexChar, firstValueFrom, firstWhere, forEach, fromAny, fromAsyncIter, fromCron, fromEvent, fromIter, fromPromise, fromRaf, fromTimer, globToRegExp, keepalive, matchesAnyPattern, never, of, reactiveCounter, replay, share, shareReplay, throwError, toArray };

package/dist/extra/sources.js

@@ -0,0 +1,57 @@
+import {
+  cached,
+  empty,
+  escapeRegexChar,
+  firstValueFrom,
+  firstWhere,
+  forEach,
+  fromAny,
+  fromAsyncIter,
+  fromCron,
+  fromEvent,
+  fromIter,
+  fromPromise,
+  fromRaf,
+  fromTimer,
+  globToRegExp,
+  keepalive,
+  matchesAnyPattern,
+  never,
+  of,
+  reactiveCounter,
+  replay,
+  share,
+  shareReplay,
+  throwError,
+  toArray
+} from "../chunk-BVZYTZ5H.js";
+import "../chunk-PHOUUNK7.js";
+import "../chunk-SX52TAR4.js";
+export {
+  cached,
+  empty,
+  escapeRegexChar,
+  firstValueFrom,
+  firstWhere,
+  forEach,
+  fromAny,
+  fromAsyncIter,
+  fromCron,
+  fromEvent,
+  fromIter,
+  fromPromise,
+  fromRaf,
+  fromTimer,
+  globToRegExp,
+  keepalive,
+  matchesAnyPattern,
+  never,
+  of,
+  reactiveCounter,
+  replay,
+  share,
+  shareReplay,
+  throwError,
+  toArray
+};
+//# sourceMappingURL=sources.js.map

package/dist/extra/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}