@okikio/observables 1.0.2

package/esm/helpers/operations/timing.js

@@ -0,0 +1,457 @@
+/**
+ * Time-based operators for spacing, delaying, and expiring stream values.
+ *
+ * This entrypoint groups the operators that make time part of your pipeline's
+ * behavior. Use it for UI patterns such as debouncing search input, throttling
+ * bursty events, delaying retries, or timing out work that takes too long.
+ *
+ * Timing operators do not just change values; they change when work is allowed
+ * to move downstream. That makes them especially important for coordinating
+ * async side effects without piling up stale requests or overwhelming slower
+ * consumers.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+import { createOperator, createStatefulOperator } from "../operators.js";
+import { isObservableError, ObservableError } from "../../error.js";
+/**
+ * Delays each item in the stream by a specified number of milliseconds.
+ *
+ * This operator shifts the entire stream of events forward in time, preserving
+ * the relative time between them.
+ *
+ * > Note: This does not delay error emissions. If an error occurs, it will
+ * > be emitted immediately, regardless of the delay.
+ *
+ * @example
+ * ```ts
+ * import { pipe, delay, from } from "./helpers/mod.ts";
+ *
+ * // No direct Array equivalent, as it's about timing.
+ *
+ * // Stream behavior
+ * const sourceStream = from([1, 2, 3]);
+ * const delayedStream = pipe(sourceStream, delay(1000));
+ * // Emits 1 (after 1s), then 2 (immediately after), then 3 (immediately after).
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `delay` to simulate network latency in tests, or to introduce a small
+ * pause in a UI animation sequence to make it feel more natural.
+ *
+ * ## Key Insight
+ *
+ * `delay` is about shifting the timeline of events, not about pausing between
+ * them. It's a simple way to control when a stream begins to emit its values.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param ms - The delay duration in milliseconds
+ * @returns A stream operator that delays each value
+ */
+export function delay(ms) {
+    return createStatefulOperator({
+        name: "delay",
+        errorMode: "pass-through", // Should be explicit
+        createState: () => ({
+            timeoutId: null,
+            buffer: [],
+            hasStarted: false,
+            delayOver: false,
+            pendingFlush: null,
+        }),
+        transform(chunk, state, controller) {
+            // If delay period is over, emit immediately
+            if (state.delayOver)
+                controller.enqueue(chunk);
+            // Buffer the item and start delay timer if not already started
+            else
+                state.buffer.push(chunk);
+            // Start the delay timer on the first item
+            if (!state.hasStarted) {
+                state.pendingFlush = Promise.withResolvers();
+                state.timeoutId = setTimeout(() => {
+                    // Mark delay as complete
+                    state.delayOver = true;
+                    // Release all buffered items
+                    for (const value of state.buffer) {
+                        controller.enqueue(value);
+                    }
+                    state.buffer.length = 0; // Fast array clear
+                    // Clean up timeout reference
+                    clearTimeout(state.timeoutId);
+                    state.timeoutId = null;
+                    // If flush was waiting, complete it now
+                    if (state.pendingFlush) {
+                        state.pendingFlush.resolve();
+                        state.pendingFlush = null;
+                    }
+                }, ms);
+                state.hasStarted = true;
+            }
+        },
+        async flush(state, controller) {
+            // If delay hasn't completed yet, we need to wait
+            if (state.pendingFlush)
+                await state.pendingFlush.promise;
+            // Cancel timeout if stream ends during delay
+            if (state.timeoutId !== null) {
+                clearTimeout(state.timeoutId);
+                state.timeoutId = null;
+            }
+            // Emit any remaining buffered items
+            for (const item of state.buffer) {
+                controller.enqueue(item);
+            }
+            state.buffer.length = 0;
+        },
+        cancel(state) {
+            // Critical: clean up timeout to prevent memory leaks
+            if (state.timeoutId !== null) {
+                clearTimeout(state.timeoutId);
+                state.timeoutId = null;
+            }
+            state.buffer.length = 0;
+        },
+    });
+}
+/**
+ * Delays each individual item by a specified number of milliseconds.
+ *
+ * This operator delays every item independently, preserving the relative
+ * spacing between them while shifting each one forward by the same amount.
+ * Think of it as "adding X milliseconds to each item's timestamp."
+ *
+ * > Note: This does not delay error emissions. If an error occurs, it will
+ * > be emitted immediately, regardless of the delay.
+ *
+ * @example
+ * ```ts
+ * import { pipe, delayEach, from } from "./helpers/mod.ts";
+ *
+ * // Stream behavior
+ * const sourceStream = from([1, 2, 3]); // Items at T+0, T+100, T+200
+ * const delayedStream = pipe(sourceStream, delayEach(1000));
+ * // Emits 1 (at T+1000), 2 (at T+1100), 3 (at T+1200)
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `delayEach` to simulate processing time for each item, or to add
+ * consistent lag to every operation (useful for testing race conditions
+ * or simulating network latency per request).
+ *
+ * ## Key Insight
+ *
+ * `delayEach` maintains the original spacing between items while shifting
+ * each one. For delaying the entire stream timeline, use `delay` instead.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param ms - The delay duration in milliseconds for each item
+ * @returns A stream operator that delays each value individually
+ */
+export function delayEach(ms) {
+    return createStatefulOperator({
+        name: "delayEach",
+        errorMode: "pass-through",
+        createState: () => ({
+            pendingTimeouts: new Set(),
+            isComplete: false,
+        }),
+        transform(chunk, state, controller) {
+            // Schedule delayed emission for this specific item
+            const timeout = setTimeout((_chunk) => {
+                controller.enqueue(_chunk);
+                state.pendingTimeouts.delete(timeout);
+                clearTimeout(timeout);
+                // If stream ended and this was the last pending timeout, close stream
+                if (state.isComplete && state.pendingTimeouts.size === 0) {
+                    controller.terminate();
+                }
+            }, ms, chunk);
+            state.pendingTimeouts.add(timeout);
+        },
+        flush(state, controller) {
+            state.isComplete = true;
+            // If no pending timeouts, stream can complete immediately
+            if (state.pendingTimeouts.size === 0) {
+                controller.terminate();
+            }
+            // Otherwise, wait for pending timeouts to finish (handled in transform)
+        },
+        cancel(state) {
+            // Critical: clean up all pending timeouts to prevent memory leaks
+            for (const timeout of state.pendingTimeouts) {
+                clearTimeout(timeout);
+            }
+            state.pendingTimeouts.clear();
+        },
+    });
+}
+/**
+ * Emits only the latest item after a specified period of inactivity.
+ *
+ * This is the "search bar" operator. It waits for the user to stop typing
+ * before firing off a search query.
+ *
+ * > Note: This operator does not delay error emissions. If an error occurs,
+ * > it will be emitted immediately, regardless of the debounce period.
+ *
+ * @example
+ * ```ts
+ * import { pipe, debounce, from } from "./helpers/mod.ts";
+ *
+ * // No direct Array equivalent.
+ *
+ * // Stream behavior
+ * const inputStream = from(["a", "ab", "abc"]); // User typing quickly
+ * const debouncedStream = pipe(inputStream, debounce(300));
+ * // After 300ms of no new input, it will emit "abc".
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `debounce` for any event that fires rapidly, but you only care about the
+ * final value, such as search inputs, window resize events, or auto-saving
+ * form fields.
+ *
+ * ## Key Insight
+ *
+ * `debounce` filters out noise from rapid-fire events, ensuring that expensive
+ * operations (like API calls) are only triggered when necessary.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param ms - The debounce duration in milliseconds
+ * @returns A stream operator that debounces values
+ */
+export function debounce(ms) {
+    return createStatefulOperator({
+        name: "debounce",
+        errorMode: "pass-through",
+        createState: () => ({
+            timeout: null,
+            lastValue: null,
+            hasValue: false,
+        }),
+        transform(chunk, state, controller) {
+            // Cancel any pending timeout
+            if (state.timeout !== null) {
+                clearTimeout(state.timeout);
+                state.timeout = null;
+            }
+            // Store the latest value
+            state.lastValue = chunk;
+            state.hasValue = true;
+            // Set up a new timeout to emit the latest value
+            state.timeout = setTimeout(() => {
+                if (state.hasValue) {
+                    controller.enqueue(state.lastValue);
+                }
+                state.timeout = null;
+                state.lastValue = null;
+                state.hasValue = false;
+            }, ms);
+        },
+        flush(state, controller) {
+            // Clear any pending timeout
+            if (state.timeout !== null) {
+                clearTimeout(state.timeout);
+                state.timeout = null;
+            }
+            // Emit the last value if we have one
+            if (state.hasValue) {
+                controller.enqueue(state.lastValue);
+                state.lastValue = null;
+                state.hasValue = false;
+            }
+        },
+        cancel(state) {
+            // Clean up on cancellation
+            if (state.timeout !== null) {
+                clearTimeout(state.timeout);
+                state.timeout = null;
+            }
+            state.lastValue = null;
+            state.hasValue = false;
+        },
+    });
+}
+/**
+ * Limits the stream to emit at most one item per specified time interval.
+ *
+ * This is the "scroll event" operator. It ensures that even if an event fires
+ * hundreds of times per second, you only handle it at a manageable rate.
+ *
+ * @example
+ * ```ts
+ * import { pipe, throttle, from } from "./helpers/mod.ts";
+ *
+ * // No direct Array equivalent.
+ *
+ * // Stream behavior
+ * const scrollStream = from([10, 20, 50, 100, 150]); // Scroll events
+ * const throttledStream = pipe(scrollStream, throttle(100));
+ * // Emits 10 immediately, then waits 100ms before being able to emit again.
+ * // If 150 is the last value, it will be emitted after the throttle window.
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `throttle` for high-frequency events where you need to guarantee a
+ * regular sampling of the data, such as scroll position tracking, mouse
+ * movement, or real-time data visualization.
+ *
+ * ## Key Insight
+ *
+ * `throttle` guarantees a steady flow of data, unlike `debounce` which waits
+ * for silence. It's about rate-limiting, not just handling the final value.
+ *
+ * @typeParam T - Type of values from the source stream
+ * @param ms - The throttle duration in milliseconds
+ * @returns A stream operator that throttles values
+ */
+export function throttle(ms) {
+    return createStatefulOperator({
+        name: "throttle",
+        errorMode: "pass-through",
+        createState: () => ({
+            lastEmitTime: 0,
+            nextValue: null,
+            hasNextValue: false,
+            timeoutId: null,
+        }),
+        transform(chunk, state, controller) {
+            if (isObservableError(chunk)) {
+                // If the chunk is an error, we can immediately emit it
+                controller.enqueue(chunk);
+                return;
+            }
+            const now = Date.now();
+            const timeSinceLastEmit = now - state.lastEmitTime;
+            // If we haven't emitted for the throttle duration, emit immediately
+            if (timeSinceLastEmit >= ms) {
+                state.lastEmitTime = now;
+                controller.enqueue(chunk);
+                return;
+            }
+            // Otherwise, store this value to emit later
+            state.nextValue = chunk;
+            state.hasNextValue = true;
+            // If we don't have a timeout scheduled, schedule one
+            if (state.timeoutId === null) {
+                const remainingTime = ms - timeSinceLastEmit;
+                state.timeoutId = setTimeout(() => {
+                    if (state.hasNextValue) {
+                        state.lastEmitTime = Date.now();
+                        controller.enqueue(state.nextValue);
+                        state.nextValue = null;
+                        state.hasNextValue = false;
+                    }
+                    state.timeoutId = null;
+                }, remainingTime);
+            }
+        },
+        flush(state, controller) {
+            // Clean up any scheduled timeout
+            if (state.timeoutId !== null) {
+                clearTimeout(state.timeoutId);
+                state.timeoutId = null;
+            }
+            // Emit the last value if we have one
+            if (state.hasNextValue) {
+                controller.enqueue(state.nextValue);
+                state.nextValue = null;
+                state.hasNextValue = false;
+            }
+        },
+        cancel(state) {
+            // Clean up on cancellation
+            if (state.timeoutId !== null) {
+                clearTimeout(state.timeoutId);
+                state.timeoutId = null;
+            }
+            state.nextValue = null;
+            state.hasNextValue = false;
+        },
+    });
+}
+/**
+ * Errors if an item takes too long to be processed.
+ *
+ * This operator passes normal synchronous values through immediately, but when
+ * an upstream operator emits a promise-like chunk it waits for that chunk to
+ * settle and races it against a timer. If the promise-like chunk does not
+ * resolve before the timer finishes, it emits an `ObservableError` instead.
+ *
+ * The implementation uses an async transform so Web Streams backpressure keeps
+ * later chunks from overtaking the timed chunk. In practice that means operator
+ * chains still stay ordered: each promise-like chunk either resolves to a value
+ * or times out before the next chunk is processed.
+ *
+ * @example
+ * ```ts
+ * import { pipe, timeout, from } from "./helpers/mod.ts";
+ *
+ * // Stream behavior
+ * const sourceStream = from([
+ *   new Promise(res => setTimeout(() => res(1), 100)),
+ *   new Promise(res => setTimeout(() => res(2), 2000))
+ * ]);
+ *
+ * const timedStream = pipe(sourceStream, timeout(1000));
+ * // Emits 1, then emits an error because the second promise took too long.
+ * ```
+ *
+ * ## Practical Use Case
+ *
+ * Use `timeout` to enforce Service Level Agreements (SLAs) on asynchronous
+ * operations, such as API calls. If a request takes too long, you can gracefully
+ * handle the timeout instead of letting your application hang.
+ *
+ * ## Key Insight
+ *
+ * `timeout` is a crucial tool for building resilient systems that can handle
+ * slow or unresponsive dependencies. It turns an indefinite wait into a
+ * predictable failure.
+ *
+ * @typeParam T The type of data in the stream.
+ * @param ms The timeout duration in milliseconds.
+ * @returns An operator that enforces a timeout on each item.
+ */
+export function timeout(ms) {
+    return createOperator({
+        name: "timeout",
+        errorMode: "pass-through",
+        async transform(chunk, controller) {
+            // If the chunk is an error, we can immediately emit it
+            if (isObservableError(chunk)) {
+                controller.enqueue(chunk);
+                return;
+            }
+            if (chunk !== null &&
+                (typeof chunk === "object" || typeof chunk === "function") &&
+                "then" in chunk &&
+                typeof chunk.then === "function") {
+                const timeoutResult = Symbol("timeout");
+                let timeoutId;
+                const result = await Promise.race([
+                    chunk,
+                    new Promise((resolve) => {
+                        timeoutId = setTimeout(() => resolve(timeoutResult), ms);
+                    }),
+                ]);
+                if (timeoutId !== undefined) {
+                    clearTimeout(timeoutId);
+                }
+                if (result === timeoutResult) {
+                    controller.enqueue(ObservableError.from(new Error(`Operation timed out after ${ms}ms`), "operator:timeout", { timeoutMs: ms, chunk }));
+                    return;
+                }
+                controller.enqueue(result);
+                return;
+            }
+            controller.enqueue(chunk);
+        },
+    });
+}