@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/{extra/sources.d.cts → base/sources/index.d.ts}

@@ -1,277 +1,21 @@
-import { a as NodeOptions, N as Node } from '../node-kK3CvTrR.cjs';
+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';
 
 /**
- * Core reactive sources, sinks, and utilities (roadmap §2.3).
+ * Async sources, sinks, and multicast — presentation layer.
  *
- * Each API returns a {@link Node} built with {@link node}, {@link producer},
- * {@link derived}, or {@link effect} — no second protocol.
+ * `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`.
  *
- * Protocol/system/ingest adapters (fromHTTP, fromWebSocket, fromKafka, etc.)
- * live in {@link ./adapters.ts}.
+ * `singleFromAny` and `singleNodeFromAny` (keyed singleflight) live in
+ * `base/composition/single-from-any.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>;
+/** 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.
@@ -416,6 +160,45 @@ declare function replay<T>(source: Node<T>, bufferSize: number, opts?: ExtraOpts
  * @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.
  *
@@ -450,7 +233,7 @@ declare function firstValueFrom<T>(source: Node<T>): Promise<T>;
  * See COMPOSITION-GUIDE §2 (subscription ordering).
  *
  * ```ts
- * const val = await firstWhere(strategy.node, snap => snap.size > 0);
+ * const val = await firstWhere(strategy.snapshot, snap => snap.size > 0);
  * ```
  *
  * @param source - Upstream node to observe.
@@ -466,11 +249,32 @@ declare function firstValueFrom<T>(source: Node<T>): Promise<T>;
  */
 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`
@@ -520,37 +324,6 @@ declare function nodeSignal(source: Node<boolean>, opts?: {
     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. */
@@ -581,4 +354,4 @@ type ReactiveCounterBundle = {
  */
 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 { 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":[]}