@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/base/sources/index.d.ts

@@ -0,0 +1,357 @@
+import { Node, NodeOptions } from '@graphrefly/pure-ts/core';
+import { NodeInput, AsyncSourceOpts } from '@graphrefly/pure-ts/extra';
+export { CronSchedule, FromCronOptions, fromCron, matchesCron, parseCron } from './event/index.js';
+
+/**
+ * Async sources, sinks, and multicast — presentation layer.
+ *
+ * `fromPromise`, `fromAsyncIter`, `fromAny` are substrate primitives; they are
+ * re-exported here from `@graphrefly/pure-ts` for ergonomic single-import use.
+ * This file owns the presentation-only async utilities: `defer`, `forEach`,
+ * `toArray`, `share`, `replay`, `cached`, `shareReplay`.
+ *
+ * `singleFromAny` and `singleNodeFromAny` (keyed singleflight) live in
+ * `base/composition/single-from-any.ts`.
+ */
+
+/** Options for presentation-layer async operators: NodeOptions without `describeKind`. */
+type ExtraOpts = Omit<NodeOptions, "describeKind">;
+/**
+ * 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>;
+/**
+ * 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;
+
+/**
+ * Settled/signal helpers.
+ *
+ * Moved from extra/sources/settled.ts during cleave A2.
+ * `keepalive` is substrate — it lives at `@graphrefly/pure-ts`
+ * (`packages/pure-ts/src/extra/sources/_keepalive.ts`), not here.
+ */
+/**
+ * Settled / signal helpers — boundary primitives for converting reactive
+ * sources into Promise/AbortSignal endpoints.
+ *
+ * - {@link firstValueFrom} / {@link firstWhere} — Promise of the first
+ *   matching DATA.
+ * - {@link awaitSettled} — composition over `firstWhere` + reactive
+ *   `timeout` from `extra/resilience` (lazy import to avoid a
+ *   resilience → sources cycle).
+ * - {@link nodeSignal} — `Node<boolean>` → `AbortSignal` bridge.
+ * - {@link reactiveCounter} — capped counter exposed as a `Node<number>`.
+ */
+
+/**
+ * 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.snapshot, 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;
+    kick?: () => void;
+}): Promise<T>;
+declare function awaitSettled<T>(source: Node<T>, opts?: {
+    predicate?: (value: T) => boolean;
+    timeoutMs?: number;
+    skipCurrent?: boolean;
+    /**
+     * Lock 3.A (Phase 13.6.B): fired AFTER subscribe is in place but
+     * BEFORE the helper's async boundary is exposed to the caller.
+     * Subscribe-before-kick is structurally enforced — the kick's
+     * synchronous wave reaches `sink` before control returns. Replaces
+     * the prior load-bearing-comment pattern (M.20-load-bearing) with
+     * a misuse-impossible API shape.
+     *
+     * Common pattern:
+     *   await awaitSettled(node, {
+     *     skipCurrent: true,
+     *     kick: () => producer.emit(value),
+     *   });
+     *
+     * Omit `kick` for external-trigger cases where the wave is fired
+     * by code outside the helper's caller; subscribe still lands
+     * synchronously inside the helper body so the next external wave
+     * is not lost.
+     */
+    kick?: () => void;
+}): 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;
+};
+/** 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 ReactiveCounterBundle, awaitSettled, cached, defer, firstValueFrom, firstWhere, forEach, nodeSignal, reactiveCounter, replay, share, shareReplay, toArray };

package/dist/base/sources/index.js

@@ -0,0 +1,42 @@
+import "../../chunk-T5BN5KG7.js";
+import "../../chunk-W2BOPXTI.js";
+import {
+  fromCron,
+  matchesCron,
+  parseCron
+} from "../../chunk-7EGRP2VX.js";
+import {
+  cached,
+  defer,
+  forEach,
+  replay,
+  share,
+  shareReplay,
+  toArray
+} from "../../chunk-DKNHAICT.js";
+import {
+  awaitSettled,
+  firstValueFrom,
+  firstWhere,
+  nodeSignal,
+  reactiveCounter
+} from "../../chunk-O3MT7DYI.js";
+import "../../chunk-AZDQPQ3V.js";
+export {
+  awaitSettled,
+  cached,
+  defer,
+  firstValueFrom,
+  firstWhere,
+  forEach,
+  fromCron,
+  matchesCron,
+  nodeSignal,
+  parseCron,
+  reactiveCounter,
+  replay,
+  share,
+  shareReplay,
+  toArray
+};
+//# sourceMappingURL=index.js.map

package/dist/base/sources/index.js.map

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