@graphrefly/ts 0.0.1 → 0.0.3

package/dist/{index-Bmxeu0nK.d.ts → index-DzJni3_6.d.ts}

@@ -1,5 +1,5 @@
-import { N as Node, n as NodeOptions, h as HttpResponse, g as HttpRequest, x as ProcessResult, z as SseEvent, A as SseRequest, J as WebSocketEvent, M as WebSocketRequest, X as WebhookEvent, Y as WebhookRegistration, w as ProcessCommand } from './types-BsJvElYZ.js';
-import { L as Operator } from './graph-D-1-SQeC.js';
+import { N as Node, n as NodeOptions, h as HttpResponse, g as HttpRequest, x as ProcessResult, z as SseEvent, A as SseRequest, J as WebSocketEvent, M as WebSocketRequest, X as WebhookEvent, Y as WebhookRegistration, w as ProcessCommand } from './types-DChxk1vK.js';
+import { L as Operator } from './graph-CS0b4V9B.js';
 
 /**
  * Async + sync sources (binding-layer sugar, D43 / D40 / feedback_async_sources_binding_layer).
@@ -44,6 +44,16 @@ interface TimerSourceOpts extends AsyncSourceOpts {
 interface FromCronOptions extends AsyncSourceOpts {
     /** Cron matcher polling interval in milliseconds. Default: 60_000. */
     tickMs?: number;
+    /** IANA timezone used for wall-clock cron matching. Defaults to the host-local timezone. */
+    timezone?: string;
+    /**
+     * DST policy for timezone-aware matching. Current D484 defaults are explicit: nonexistent
+     * wall-clock minutes are skipped, and repeated wall-clock minutes fire at most once.
+     */
+    dst?: {
+        readonly nonexistent?: "skip";
+        readonly repeated?: "once";
+    };
     /**
      * Emitted value shape. `timestamp_ns` is a decimal string so it cannot lose precision as a
      * JavaScript number; use `timestamp_ms` when numeric millisecond precision is enough.
@@ -74,8 +84,12 @@ type PushUnsubscribe = () => void;
 type PushRegister<T> = (deliver: (payload: T) => void) => PushUnsubscribe | undefined;
 /** Parse a standard five-field cron expression. */
 declare function parseCron(expr: string): CronSchedule;
-/** Test whether a local Date matches a parsed cron schedule. */
-declare function matchesCron(schedule: CronSchedule, date: Date): boolean;
+interface CronMatchOptions {
+    /** IANA timezone used for wall-clock projection. Defaults to the host-local timezone. */
+    timezone?: string;
+}
+/** Test whether a Date matches a parsed cron schedule in host-local time or an IANA timezone. */
+declare function matchesCron(schedule: CronSchedule, date: Date, opts?: CronMatchOptions): boolean;
 declare function fromCron(expr: string, opts: FromCronOptions & {
     output: "date";
 }): Operator<never, Date>;
@@ -101,38 +115,165 @@ declare function fromWebhookWithOptions(registration: WebhookRegistration): Oper
  * Timer source: one-shot (first tick then COMPLETE) or periodic (`{period}` → 0, 1, 2, …).
  * sync pool + pausable:false (a timer keeps producing through PAUSE, R-pause-modes). Emits the
  * tick counter from 0; deactivation clears the timers.
+ *
+ * @param ms - Delay before the first tick in milliseconds.
+ * @param opts - Optional period and source options.
+ * @returns A source operator that emits tick counters.
+ * @example
+ * ```ts
+ * import { graph, timer } from "@graphrefly/ts";
+ *
+ * const tick = graph().initNode(timer(100), []);
+ * ```
+ * @category sources
  */
 declare function timer(ms: number, opts?: TimerSourceOpts): Operator<never, number>;
-/** Frozen pure-ts name for {@link timer}; preserves the real factory name in describe(). */
+/**
+ * Create a timer source with the legacy `fromTimer` factory name.
+ *
+ * @param ms - Delay before the first tick in milliseconds.
+ * @param opts - Optional period and source options.
+ * @returns A source operator that emits tick counters.
+ * @example
+ * ```ts
+ * import { fromTimer, graph } from "@graphrefly/ts";
+ *
+ * const tick = graph().initNode(fromTimer(100), []);
+ * ```
+ * @remarks **Factory name:** This preserves the real `fromTimer` factory name in `describe()`.
+ * @category sources
+ */
 declare function fromTimer(ms: number, opts?: TimerSourceOpts): Operator<never, number>;
-/** interval: periodic ticks (0, 1, 2, …), first at `ms`, then every `ms` (RxJS semantics). */
+/**
+ * Emit periodic tick counters.
+ *
+ * @param ms - Delay before the first tick and between later ticks in milliseconds.
+ * @returns A source operator that emits `0`, `1`, `2`, and so on.
+ * @example
+ * ```ts
+ * import { graph, interval } from "@graphrefly/ts";
+ *
+ * const ticks = graph().initNode(interval(1000), []);
+ * ```
+ * @category sources
+ */
 declare function interval(ms: number): Operator<never, number>;
 /**
  * Lift a Promise (or thenable) to a single-value stream: one DATA then COMPLETE, or ERROR on
  * rejection. async pool (default pausable → a paused source buffers its late emit). Optional
  * `signal` aborts to ERROR.
+ *
+ * @param p - Promise or thenable to lift into the graph.
+ * @param opts - Optional abort signal and async source options.
+ * @returns A source operator that emits one DATA value and COMPLETE, or ERROR on rejection/abort.
+ * @example
+ * ```ts
+ * import { fromPromise, graph } from "@graphrefly/ts";
+ *
+ * const user = graph().initNode(fromPromise(fetch("/user").then((res) => res.json())), []);
+ * ```
+ * @category sources
  */
 declare function fromPromise<T>(p: Promise<T> | PromiseLike<T>, opts?: AsyncSourceOpts): Operator<never, T>;
 /**
  * Read an async iterable: each value → DATA; COMPLETE when done; ERROR on failure. async pool.
  * Optional `signal` aborts the pump.
+ *
+ * @param iterable - Async iterable to pump into the graph.
+ * @param opts - Optional abort signal and async source options.
+ * @returns A source operator that emits every iterable value and then COMPLETE.
+ * @example
+ * ```ts
+ * import { fromAsyncIter, graph } from "@graphrefly/ts";
+ *
+ * const stream = graph().initNode(fromAsyncIter(events()), []);
+ * ```
+ * @category sources
  */
 declare function fromAsyncIter<T>(iterable: AsyncIterable<T>, opts?: AsyncSourceOpts): Operator<never, T>;
 /**
  * of: synchronous values — each argument as DATA, then COMPLETE. `of()` is the EMPTY source.
+ *
+ * @param values - Values to emit synchronously on activation.
+ * @returns A source operator that emits each value and then COMPLETE.
+ * @example
+ * ```ts
+ * import { graph, of } from "@graphrefly/ts";
+ *
+ * const values = graph().initNode(of(1, 2, 3), []);
+ * ```
+ * @category sources
  */
 declare function of<T = never>(...values: T[]): Operator<never, T>;
-/** fromIter: a sync iterable — each value → DATA (in order), then COMPLETE, on activation. */
+/**
+ * Emit every value from a synchronous iterable.
+ *
+ * @param iterable - Iterable whose values are emitted in order.
+ * @returns A source operator that emits every iterable value and then COMPLETE.
+ * @example
+ * ```ts
+ * import { fromIter, graph } from "@graphrefly/ts";
+ *
+ * const values = graph().initNode(fromIter([1, 2, 3]), []);
+ * ```
+ * @category sources
+ */
 declare function fromIter<T>(iterable: Iterable<T>): Operator<never, T>;
-/** EMPTY analogue: complete immediately with no DATA. */
+/**
+ * Complete immediately without emitting DATA.
+ *
+ * @returns A source operator that emits COMPLETE on activation.
+ * @example
+ * ```ts
+ * import { empty, graph } from "@graphrefly/ts";
+ *
+ * const done = graph().initNode(empty(), []);
+ * ```
+ * @category sources
+ */
 declare function empty<T = never>(): Operator<never, T>;
-/** NEVER analogue: activate and remain silent until deactivation. */
+/**
+ * Activate and remain silent until deactivation.
+ *
+ * @returns A source operator that never emits DATA or terminal messages by itself.
+ * @example
+ * ```ts
+ * import { graph, never } from "@graphrefly/ts";
+ *
+ * const quiet = graph().initNode(never(), []);
+ * ```
+ * @category sources
+ */
 declare function never<T = never>(): Operator<never, T>;
-/** Error source: terminate with ERROR on activation, coercing invalid host-language payloads. */
+/**
+ * Terminate with ERROR on activation.
+ *
+ * @param err - Host-language error payload to normalize into a protocol ERROR payload.
+ * @returns A source operator that emits ERROR.
+ * @example
+ * ```ts
+ * import { graph, throwError } from "@graphrefly/ts";
+ *
+ * const failed = graph().initNode(throwError(new Error("boom")), []);
+ * ```
+ * @category sources
+ */
 declare function throwError(err: unknown): Operator<never, never>;
 /**
  * Wrap a DOM-style event target. Each event becomes DATA; deactivation removes the listener.
  * External callbacks are source boundaries (D43), so no polling or operator-level async leaks in.
+ *
+ * @param target - Event target implementing `addEventListener` and `removeEventListener`.
+ * @param type - Event type to subscribe to.
+ * @param opts - Optional listener options and source options.
+ * @returns A source operator that emits each event as DATA.
+ * @example
+ * ```ts
+ * import { fromEvent, graph } from "@graphrefly/ts";
+ *
+ * const clicks = graph().initNode(fromEvent<MouseEvent>(button, "click"), []);
+ * ```
+ * @category sources
  */
 declare function fromEvent<T = unknown>(target: EventTargetLike, type: string, opts?: FromEventOptions): Operator<never, T>;
 /**