@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/rate-limiter-DpVbSYdH.d.cts

@@ -0,0 +1,559 @@
+import { Node, NodeOptions } from '@graphrefly/pure-ts/core';
+import { G as GateState } from './breaker-ugSdq54q.cjs';
+import { N as NodeOrValue } from './_internal-B23BagFd.cjs';
+
+/**
+ * Timeout — emits `ERROR` with `TimeoutError` if no `DATA` arrives within the deadline.
+ *
+ * §3.1c — caching, fallback & composition sugar. Uses
+ * `core/clock.js`-style nanoseconds and a `ResettableTimer` so the deadline
+ * resets on each DATA. Distinct from the `operators/control.ts` timeout
+ * (which forwards a caller-supplied error/value) — this one is the
+ * resilience family's "deadline → ERROR" primitive.
+ *
+ * **DS-13.5.B (locked 2026-05-01).** Pre-1.0 break: returns
+ * {@link TimeoutBundle} with `node` + `timeoutState` companion. Opts
+ * accept `Partial<TimeoutOptions>` or `Node<Partial<TimeoutOptions>>`
+ * (object-shape, replacing the old `NodeOrValue<number>` flat shape).
+ * State preservation across rebind: `ns` change does NOT reset the
+ * in-flight deadline — new `ns` applies to next attempt only.
+ */
+
+/**
+ * Thrown by {@link withTimeout} when no `DATA` arrives within the deadline.
+ *
+ * @category extra
+ */
+declare class TimeoutError extends Error {
+    name: string;
+    constructor(ns: number);
+}
+/**
+ * Options accepted by {@link withTimeout}.
+ *
+ * - `ns` — deadline in nanoseconds (must be `> 0`). Required at the
+ *   first opts settle; missing / non-positive values throw at
+ *   construction.
+ * - `meta` — optional metadata merged onto the result node's `meta`
+ *   for describe()/explain() introspection. Reactive `meta` updates
+ *   are picked up on the next attempt's emission.
+ *
+ * @category extra/resilience
+ */
+interface TimeoutOptions {
+    ns: number;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Lifecycle-shaped state companion emitted by {@link withTimeout}.
+ *
+ * Default `equals` dedups on the `status` field — subscribers don't
+ * re-fire on identical-shape transitions, but DO fire on every state
+ * transition AND on payload changes within the same status (e.g. when
+ * `running.startedAt_ns` advances on a fresh attempt).
+ *
+ * @category extra/resilience
+ */
+type TimeoutState = {
+    status: "pending";
+} | {
+    status: "running";
+    startedAt_ns: number;
+    deadline_ns: number;
+} | {
+    status: "completed";
+    settledAt_ns: number;
+} | {
+    status: "errored";
+    firedAt_ns: number;
+    deadline_ns: number;
+};
+/**
+ * Bundle returned by {@link withTimeout}: the timeout-wrapped output node and
+ * its lifecycle-shaped state companion.
+ *
+ * **Single-subscriber / pipeline-only contract (DS-13.5.B QA, N1, 2026-05-03).**
+ * The `timeoutState` companion is allocated once at factory time and shared
+ * across all subscribers to `node`. With one subscriber (the typical use
+ * case — wire `node` into your downstream chain, optionally observe
+ * `timeoutState` separately) the companion reflects a coherent timeline.
+ * With **two or more subscribers** to `node`, each subscriber re-runs the
+ * producer body and writes into the same `timeoutState`, which can flip
+ * between states from different in-flight machines. Don't fan out
+ * `node` to multiple subscribers and rely on `timeoutState` accuracy
+ * unless you use {@link keepalive} / {@link share}-style consolidation.
+ *
+ * @category extra/resilience
+ */
+interface TimeoutBundle<T> {
+    node: Node<T>;
+    timeoutState: Node<TimeoutState>;
+}
+interface TimeoutExtraOpts {
+    meta?: Record<string, unknown>;
+}
+/**
+ * Wrap `source` with a deadline. If no `DATA` arrives within `opts.ns`
+ * nanoseconds, the result node emits `[[ERROR, TimeoutError]]` and
+ * transitions `timeoutState` to `"errored"`.
+ *
+ * The timer starts on subscription and resets on each `DATA`. `DIRTY`
+ * does NOT reset the timer. Terminal messages (`COMPLETE` / `ERROR`)
+ * cancel the timer.
+ *
+ * **Reactive opts (DS-13.5.B, locked 2026-05-01).**
+ *
+ * - Static-form callers pass `Partial<TimeoutOptions>` (today's path).
+ *   `ns` is validated at construction; missing / non-positive throws
+ *   `RangeError`.
+ * - Reactive-form callers pass `Node<Partial<TimeoutOptions>>` — each
+ *   emission shallow-merges over the prior opts. Empty `{}` emissions
+ *   are no-ops (no rebind, no companion fire). Mid-flight opts swap
+ *   does NOT reset the in-flight deadline; new `ns` applies to the
+ *   next `startTimer()` call.
+ * - When the opts Node has `cache === undefined` (SENTINEL: no opts
+ *   emitted yet), the source is paused until the first valid opts
+ *   settle. The first valid settle must carry `ns > 0` or the timer
+ *   layer emits an ERROR (downstream observable) — distinct from the
+ *   construction-time `RangeError` thrown for static / cache-defined
+ *   invalid values.
+ *
+ * @param source - Upstream node.
+ * @param opts - `Partial<TimeoutOptions>` (static) or
+ *   `Node<Partial<TimeoutOptions>>` (reactive).
+ * @param extraOpts - Forwarded factory metadata (meta field merged
+ *   onto the result node).
+ * @returns {@link TimeoutBundle} with `node` and `timeoutState`.
+ *
+ * @throws {RangeError} when the first opts settle is missing or has
+ *   non-positive `ns`.
+ *
+ * @category extra
+ */
+declare function withTimeout<T>(source: Node<T>, opts: Partial<TimeoutOptions> | Node<Partial<TimeoutOptions>>, extraOpts?: TimeoutExtraOpts): TimeoutBundle<T>;
+
+/**
+ * `budgetGate` — numeric-constraint flow gate (Tier 2.2 promotion from
+ * `patterns/reduction/`).
+ *
+ * Lives alongside the other `extra/resilience/` flow controls (`retry`,
+ * `circuitBreaker`, `rateLimiter`, `tokenBucket`, `fallback`, `withStatus`).
+ *
+ * @module
+ */
+
+/** A reactive constraint for {@link budgetGate}. */
+type BudgetConstraint<T = unknown> = {
+    /** Constraint node whose value is checked. */
+    node: Node<T>;
+    /** Returns `true` when the constraint is satisfied (budget available). */
+    check: (value: T) => boolean;
+    /**
+     * Optional human-readable name for `BudgetGateState.constraintsSnapshot`.
+     * Defaults to the constraint Node's `.name` (or `""` when unset).
+     */
+    name?: string;
+};
+/** Options for {@link budgetGate}. */
+type BudgetGateOptions = Omit<NodeOptions<unknown>, "describeKind" | "name" | "meta"> & {
+    meta?: Record<string, unknown>;
+};
+/**
+ * Per-constraint snapshot inside {@link BudgetGateState}. The `value` field is
+ * typed as `unknown` because constraint values are generic — most callers
+ * carry numeric budgets but the gate doesn't enforce that. Cast at the
+ * subscriber site if you need a narrower type.
+ *
+ * @category extra/resilience
+ */
+interface BudgetConstraintSnapshot {
+    readonly name: string;
+    readonly satisfied: boolean;
+    readonly value: unknown;
+}
+/**
+ * Lifecycle-shaped state companion emitted by {@link budgetGate} (DS-13.5.B,
+ * locked 2026-05-01). `status` is `"open"` when every constraint's `check`
+ * returns true; `"closed"` otherwise. The `constraintsSnapshot` array
+ * preserves constraint ordering and reflects the most recent values seen
+ * via per-constraint reactive updates.
+ *
+ * @category extra/resilience
+ */
+interface BudgetGateState {
+    readonly status: GateState;
+    readonly constraintsSnapshot: ReadonlyArray<BudgetConstraintSnapshot>;
+}
+/**
+ * Bundle returned by {@link budgetGate}: the gated output node and its
+ * gate-state companion. Pre-1.0 break vs. the prior `Node<T>` return —
+ * unwrap via `.node` for downstream wiring.
+ *
+ * @category extra/resilience
+ */
+interface BudgetGateBundle<T> {
+    node: Node<T>;
+    budgetGateState: Node<BudgetGateState>;
+}
+/**
+ * Pass-through that respects reactive constraint nodes.
+ *
+ * DATA flows through when all constraints are satisfied. When any constraint
+ * is exceeded, `PAUSE` is sent upstream and DATA is buffered in a FIFO queue.
+ * When constraints relax, the queue drains in arrival order and `RESUME` is
+ * sent upstream.
+ *
+ * ## Invariants (do not refactor without preserving)
+ *
+ * 1. **Terminal force-flush.** On `COMPLETE` / `ERROR` arriving from `source`,
+ *    every buffered item is emitted downstream BEFORE the terminal message is
+ *    forwarded. The constraint is intentionally bypassed for the flush — once
+ *    upstream is done, the caller must see the buffered work, not lose it.
+ *    See COMPOSITION-GUIDE §19 (terminal-emission operators).
+ *
+ * 2. **PAUSE-release ordering.** When a constraint flips from saturated →
+ *    released, the queue drains in FIFO order downstream BEFORE `RESUME` is
+ *    sent upstream. Reversing the order (RESUME-then-drain) would let new
+ *    upstream DATA interleave with the queue tail, breaking arrival-order
+ *    delivery. See COMPOSITION-GUIDE §9, §9a (diamond + batch coalescing).
+ *
+ * 3. **Deferred RESOLVED.** A `RESOLVED` from `source` while the queue is
+ *    non-empty is held until the queue drains, then forwarded — so downstream
+ *    sees `[buffered DATA…, RESOLVED]` in causal order rather than
+ *    `[RESOLVED, buffered DATA…]`.
+ *
+ *    **Stall risk (qa D4):** if the constraint never relaxes AND no terminal
+ *    arrives from `source`, the deferred RESOLVED is held forever. Downstream
+ *    consumers that depend on `RESOLVED` for an `awaitSettled`-style
+ *    coordination wait stall in this case. PAUSE is sent upstream so source
+ *    backpressure stops further DATA, but the gate itself has no escape
+ *    hatch — by design (the producer-pattern is fire-and-forget; recovery
+ *    happens at the compositor level via timeout, retry, or cancellation).
+ *
+ * 4. **Constraint DIRTY suppression.** Constraint-node DIRTY does NOT
+ *    propagate downstream — only `source`-DIRTY does. The gate's downstream
+ *    semantics track `source`'s wave, not constraint waves.
+ *
+ * 5. **Lazy PAUSE (qa D3).** PAUSE is sent upstream ONLY when a `source` DATA
+ *    arrives that fails the constraint check (the first blocked item). A
+ *    constraint flipping closed BEFORE any source DATA arrives does NOT emit
+ *    a preemptive PAUSE — upstream may push DATA freely until the first
+ *    item is buffered. This matches the producer-pattern lazy-activation
+ *    philosophy (don't impose backpressure for hypothetical future blocks).
+ *    For eager-PAUSE semantics, wrap the gate in a compositor that watches
+ *    constraints + source independently.
+ *
+ * ## Queue
+ *
+ * The internal buffer is an unbounded {@link HeadIndexQueue} (O(1) push,
+ * O(1) shift, opportunistic compaction). It does NOT use {@link RingBuffer}
+ * because RingBuffer's drop-oldest eviction would silently lose buffered
+ * items between PAUSE and RESUME. Backpressure (PAUSE) is the upstream
+ * contract for bounding the queue, not capacity-driven eviction here.
+ *
+ * ## Producer-pattern: source edge is invisible to `describe()`
+ *
+ * `budgetGate` is constructed via `node([], fn)` and subscribes to `source`
+ * and the constraint nodes manually inside its activation fn. Because no
+ * dep is declared at construction, **`describe()` shows no edge from
+ * `source` (or any constraint) into the returned node** — the gate looks
+ * like a standalone leaf source. This is intentional (see COMPOSITION-GUIDE
+ * §24 "Edges are derived, not declared"): if you want the constraint /
+ * source dependency to appear in describe output, surface it at the
+ * compositor level (e.g. annotate via `meta.ai.upstream`, or wrap the gate
+ * in a parent factory that exposes the deps as constructor args).
+ *
+ * ## Reference equality + Tier 6.5 3.2.5 locked semantics
+ *
+ * **Constraint VALUES are reactive.** Each `BudgetConstraint.node` is
+ * subscribed at activation; per-value changes flip the gate (re-evaluate
+ * in the same wave) and trigger PAUSE/RESUME upstream. Per the locked
+ * semantic rule for the reactive-options-widening batch (Tier 6.5 3.2.5,
+ * 2026-04-29): "constraints array re-evaluated immediately against
+ * current source; adding/removing constraints triggers gate
+ * re-evaluation in the same wave" — the per-value half is shipped via
+ * the existing constraint-Node subscription model.
+ *
+ * **The constraints ARRAY shape is static.** The factory captures the
+ * `constraints` array reference and each `check` function at
+ * construction; it does NOT diff subsequent arrays. To add or remove
+ * constraints reactively, build the swap at the compositor level (a
+ * `switchMap` rebuild over a constraint-shape Node), or construct a new
+ * gate. Dynamic constraint-array reactivity is intentionally deferred —
+ * the subscription churn (resub on every constraint add/remove) and
+ * `latestValues` shape mutation overshoot the budget-gate's
+ * fire-and-forget ergonomics.
+ *
+ * @param source - Input node.
+ * @param constraints - Reactive constraint checks. MUST be non-empty.
+ * @param opts - Optional node options.
+ * @returns Gated node.
+ *
+ * @throws {RangeError} when `constraints.length === 0`. The gate has no
+ *   meaningful identity without at least one check — degenerate to plain
+ *   pass-through (e.g. via `derived([source], ([v]) => v)`) instead.
+ *
+ * @category resilience
+ */
+declare function budgetGate<T>(source: Node<T>, constraints: ReadonlyArray<BudgetConstraint>, opts?: BudgetGateOptions): BudgetGateBundle<T>;
+
+/**
+ * Fallback — replace upstream ERROR with a static or computed source.
+ *
+ * Accepts scalar / `Node` / `PromiseLike` / `AsyncIterable` fallbacks; non-Node
+ * inputs are routed through `fromAny` so the fallback participates in the
+ * reactive protocol uniformly.
+ */
+
+/** Inputs accepted by {@link fallback}. */
+type FallbackInput<T> = T | Node<T> | PromiseLike<T> | AsyncIterable<T>;
+/**
+ * On upstream terminal `ERROR`, switch to a fallback source instead of propagating the error.
+ *
+ * Accepts any of:
+ * - **scalar value** — emits `[[DATA, fb], [COMPLETE]]`
+ * - **`Node<T>`** — subscribes and forwards all messages (push-on-subscribe delivers current cache)
+ * - **`Promise<T>` / thenable** — resolves into a one-shot `DATA` then `COMPLETE` (via {@link fromAny})
+ * - **`AsyncIterable<T>`** — streams each yielded value as `DATA`, then `COMPLETE` (via {@link fromAny})
+ *
+ * Non-`Node` inputs are routed through {@link fromAny} so the fallback participates in the
+ * reactive protocol uniformly. Bare strings, arrays, and other synchronous scalars are treated
+ * as single values (NOT split into characters / elements) to avoid the `fromAny`-on-string
+ * iteration gotcha.
+ *
+ * Composes naturally with {@link retry}:
+ * `pipe(source, retry({count:3}), fallback("default"))`.
+ *
+ * @param source - Upstream node.
+ * @param fb - Fallback value, node, promise, or async iterable.
+ * @returns Node that replaces errors with the fallback.
+ *
+ * @example
+ * ```ts
+ * import { fallback, throwError } from "@graphrefly/graphrefly-ts";
+ *
+ * const safe = fallback(throwError(new Error("boom")), "default");
+ * safe.cache; // "default" after subscribe
+ * ```
+ *
+ * @category extra
+ */
+declare function fallback<T>(source: Node<T>, fb: FallbackInput<T>, options?: {
+    meta?: Record<string, unknown>;
+}): Node<T>;
+
+/**
+ * Rate limiters — `tokenBucket` (raw meter), `rateLimiter` (operator with
+ * bounded queue + reactive backpressure companions), and the re-export of
+ * `adaptiveRateLimiter` from its standalone module.
+ */
+
+interface TokenBucket {
+    /**
+     * Number of tokens currently available (after refill).
+     *
+     * **Float-valued.** When `refillPerSecond` is fractional (or `capacity` × elapsed-fraction
+     * yields a non-integer), the bucket accumulates fractional refill credit between
+     * `tryConsume`s. Consumers should not assume integer tokens — e.g. with
+     * `tokenBucket(10, 2.5)` after 100ms of elapsed time `available()` may report `0.25`.
+     */
+    available(): number;
+    /** Try to consume `cost` tokens. Returns `true` if successful. */
+    tryConsume(cost?: number): boolean;
+    /**
+     * Return `cost` tokens to the bucket (capped at capacity). Used when a
+     * multi-bucket admission fails partway — e.g., `adaptiveRateLimiter`
+     * consumes from an rpm bucket, then a tpm bucket; if tpm fails, call
+     * `rpmBucket.putBack(requestCost)` so the rpm slot isn't wasted.
+     * No-op for non-positive `cost`.
+     */
+    putBack(cost?: number): void;
+}
+/** Optional configuration for {@link tokenBucket}. */
+interface TokenBucketOptions {
+    /**
+     * Clock function returning **nanoseconds** with `monotonicNs()` semantics
+     * (monotonically non-decreasing). Default: `monotonicNs` from `core/clock`.
+     * Override for deterministic tests — eliminates the need for `vi.useFakeTimers`
+     * to drive token-refill scheduling.
+     */
+    clock?: () => number;
+}
+/**
+ * Token-bucket meter (capacity + refill rate per second). Use with {@link rateLimiter} or custom gates.
+ *
+ * @param capacity - Maximum tokens (must be positive).
+ * @param refillPerSecond - Tokens added per elapsed second (non-negative; may be fractional).
+ * @param opts - Optional `clock` override for deterministic testing.
+ * @returns {@link TokenBucket} instance.
+ *
+ * @remarks
+ * **Float behavior:** the internal token counter is float-valued — fractional refill
+ * accumulates between `tryConsume` calls. See {@link TokenBucket.available} for caveats.
+ *
+ * **Clock injection:** pass `opts.clock` to drive refill scheduling deterministically
+ * in tests. The contract matches {@link circuitBreaker}'s `now` option: must return
+ * `monotonicNs()`-style nanoseconds, never `Date.now()` (wall-clock skew breaks
+ * elapsed math).
+ *
+ * @example
+ * ```ts
+ * import { tokenBucket } from "@graphrefly/graphrefly-ts";
+ *
+ * const bucket = tokenBucket(10, 2); // capacity 10, refill 2 tokens/sec
+ * bucket.tryConsume(3); // true — 7 tokens remaining
+ * bucket.available();   // ~7 (plus any elapsed refill — float-valued)
+ *
+ * // Deterministic test:
+ * let t = 0;
+ * const tb = tokenBucket(5, 1, { clock: () => t });
+ * tb.tryConsume(5);    // exhausts
+ * t = 1_000_000_000;   // advance 1s → +1 refill
+ * tb.tryConsume(1);    // true
+ * ```
+ *
+ * @category extra
+ */
+declare function tokenBucket(capacity: number, refillPerSecond: number, opts?: TokenBucketOptions): TokenBucket;
+type RateLimiterOverflowPolicy = "drop-oldest" | "drop-newest" | "error";
+type RateLimiterOptions = {
+    /** Maximum `DATA` emissions per window (must be > 0). */
+    maxEvents: number;
+    /** Window length in nanoseconds (must be > 0). */
+    windowNs: number;
+    /**
+     * Cap on items queued while waiting for token refill.
+     *
+     * **Required.** Pass a finite positive integer (>= 1) for a bounded queue, OR
+     * the literal `Infinity` to opt in to an unbounded queue (caller acknowledges
+     * the unbounded-memory-growth risk on a high-rate source). Omitting this
+     * throws at construction time — the silent-unbounded-buffer footgun is the
+     * most common rateLimiter mis-configuration.
+     */
+    maxBuffer: number;
+    /** Overflow policy when `maxBuffer` is exceeded. Default: `"drop-newest"`. */
+    onOverflow?: RateLimiterOverflowPolicy;
+    /**
+     * Caller-supplied metadata merged into the produced node's `meta` (Tier 5.2
+     * D8 widening). Use {@link domainMeta} to tag the layer for `describe()` /
+     * mermaid grouping (e.g. `domainMeta("resilient", "rate-limit")`). The
+     * primitive's own `factoryTag("rateLimiter", opts)` and the `droppedCount`
+     * / `rateLimitState` companion seeds always win against caller-supplied
+     * keys so the audit trail can't be silently overwritten.
+     */
+    meta?: Record<string, unknown>;
+};
+/**
+ * Thrown by {@link rateLimiter} when `onOverflow: "error"` and the pending buffer is full.
+ *
+ * @category extra
+ */
+declare class RateLimiterOverflowError extends Error {
+    name: string;
+    constructor(maxBuffer: number);
+}
+/**
+ * Combined runtime state surfaced by {@link rateLimiter} alongside `droppedCount`.
+ * Tier 5.2 D7 widening — exposes pending-buffer occupancy and a `paused`
+ * flag so consumers can render backpressure (UI), feed `lens.health`, or
+ * gate downstream effects.
+ */
+/**
+ * Lifecycle-shaped state companion emitted by {@link rateLimiter}.
+ *
+ * **DS-13.5.B widening (2026-05-01).** `status` extends {@link GateState}
+ * with `"throttled"` (= `paused === true`). Pre-1.0 break vs the prior
+ * shape (which omitted `status`).
+ *
+ * - `"open"` — passing through (no buffering, no recent overflow drops).
+ * - `"throttled"` — at least one item queued awaiting a token refill.
+ * - `"closed"` — reserved for future terminal lifecycle reporting.
+ */
+type RateLimiterState = {
+    /** DS-13.5.B status field — `"open" | "closed" | "throttled"`. */
+    status: GateState | "throttled";
+    /** Cumulative `DATA` items dropped due to overflow since this subscription cycle started. */
+    droppedCount: number;
+    /** Items currently buffered awaiting a token refill. `0` when the limiter is passing through. */
+    pendingCount: number;
+    /** `true` when at least one item is queued (the limiter is actively throttling). */
+    paused: boolean;
+};
+/** Bundle returned by {@link rateLimiter}. */
+type RateLimiterBundle<T> = {
+    /** The throttled stream — at most `maxEvents` `DATA` per `windowNs`. */
+    node: Node<T>;
+    /**
+     * Reactive companion: count of `DATA` items dropped since the producer
+     * activated.
+     *
+     * - Increments on every drop under any overflow policy (`drop-newest`,
+     *   `drop-oldest`). The `error` policy terminates the stream after a single
+     *   overflow, so `droppedCount` increments at most once in that path.
+     * - **Lifecycle scoping (qa A1 + EC7):** the counter retains its final
+     *   value through terminal (`COMPLETE` / `ERROR` / `TEARDOWN`) so consumers
+     *   see the final drop count, not zero. The closure-held counter resets to
+     *   `0` only when the producer fn re-runs — which only happens on a new
+     *   subscription cycle, and only if the producer was constructed with
+     *   `resubscribable: true`. The default `rateLimiter` producer is NOT
+     *   resubscribable, so a single producer-fn run is the typical lifetime.
+     * - Producer-pattern note: this companion is invisible to `describe()`
+     *   traversal from `node` (effect-mirror limitation; same shape as
+     *   `withBreaker.breakerState` and `withStatus.status`). Surface it via
+     *   `node.meta.droppedCount` if you need it in topology snapshots.
+     */
+    droppedCount: Node<number>;
+    /**
+     * Reactive companion: combined `{droppedCount, pendingCount, paused}` view.
+     *
+     * - `pendingCount` reflects the live buffer occupancy and updates on every
+     *   push / shift / overflow drop; `paused` is shorthand for
+     *   `pendingCount > 0`.
+     * - Equality-deduped — re-emits only when one of the three fields actually
+     *   changes (so a busy steady-state where every DATA passes immediately
+     *   produces one `paused: false` emission, not one per DATA).
+     * - **Lifecycle scoping (qa EC7):** same contract as `droppedCount` —
+     *   retains its final value through terminal; resets to the initial
+     *   `{droppedCount: 0, pendingCount: 0, paused: false}` only on a new
+     *   producer-fn run (resubscribable upstream required).
+     * - Same producer-pattern caveat as `droppedCount` re: `describe()` visibility.
+     */
+    rateLimitState: Node<RateLimiterState>;
+};
+/**
+ * Token-bucket rate limiter: at most `maxEvents` `DATA` values per `windowNs`.
+ *
+ * Uses {@link tokenBucket} internally (capacity = `maxEvents`, refill = `maxEvents / windowSeconds`).
+ * Excess items are queued FIFO (in a fixed-capacity {@link RingBuffer} for O(1) push/shift)
+ * until a token is available. The queue is bounded by the **required** `maxBuffer` option
+ * with a configurable overflow policy.
+ *
+ * @param source - Upstream node.
+ * @param opts - Rate + bounded-buffer configuration. `maxBuffer` is required (use `Infinity` to opt in to unbounded).
+ * @returns `{ node, droppedCount }` bundle. Subscribe to `node` for the throttled stream and to `droppedCount` for backpressure pressure.
+ *
+ * @throws {RangeError} when `maxEvents` / `windowNs` is non-positive, when `maxBuffer` is omitted, or when `maxBuffer` is a finite value < 1.
+ *
+ * @remarks
+ * **Terminal:** `COMPLETE` / `ERROR` cancel the refill timer, drop the pending queue,
+ * reset `droppedCount` to `0`, and propagate.
+ *
+ * @example
+ * ```ts
+ * import { rateLimiter, state, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
+ *
+ * const src = state(0);
+ * // Allow at most 5 DATA values per second; queue up to 100 excess items, drop newest beyond.
+ * const { node: limited, droppedCount } = rateLimiter(src, {
+ *   maxEvents: 5,
+ *   windowNs: NS_PER_SEC,
+ *   maxBuffer: 100,
+ * });
+ * droppedCount.subscribe(([m]) => console.log("dropped so far:", m[1]));
+ * ```
+ *
+ * @category extra
+ */
+declare function rateLimiter<T>(source: Node<T>, opts: NodeOrValue<RateLimiterOptions>): RateLimiterBundle<T>;
+
+export { type BudgetConstraint as B, type FallbackInput as F, type RateLimiterBundle as R, type TimeoutBundle as T, type BudgetConstraintSnapshot as a, type BudgetGateBundle as b, type BudgetGateOptions as c, type BudgetGateState as d, type RateLimiterOptions as e, RateLimiterOverflowError as f, type RateLimiterOverflowPolicy as g, type RateLimiterState as h, TimeoutError as i, type TimeoutOptions as j, type TimeoutState as k, type TokenBucket as l, type TokenBucketOptions as m, budgetGate as n, fallback as o, rateLimiter as r, tokenBucket as t, withTimeout as w };