@johnhenry/iteration 0.0.0 → 0.1.0

package/src/iterator-tools.ts

@@ -1,4 +1,4 @@
-import { isAsyncIterator } from "./is-iterator.ts";
+import { closeAll, closeAllSync, entryOf, pull } from "./internal.ts";
 
 /**
  * Sentinel returned by a reducer step to stop consumption of the source
@@ -28,6 +28,19 @@ export { HALT as HAULT };
 export interface ReducerStep<in In> {
   (buffer: unknown[], item: In, iterator?: Iterable<In> | AsyncIterable<In>): unknown[] | Halt;
   complete?: (buffer: unknown[]) => unknown[];
+  /**
+   * What this step (and the steps after it) keep between calls: a half-full
+   * `group`, `partitionBy`'s open run, `accumulate`'s running value,
+   * `dedupe`'s last key. Steps that keep nothing omit it. Cascades like
+   * `complete`.
+   */
+  held?: () => unknown[];
+  /**
+   * Let go of the held items for which `predicate` is true, and return how
+   * many were let go. It never emits, and never changes what is later
+   * emitted beyond leaving the dropped items out. Cascades like `complete`.
+   */
+  drop?: (predicate: (held: unknown) => boolean) => number;
 }
 
 /**
@@ -221,17 +234,30 @@ export const conjoinAsync = async function* <T>(
  * @returns an iterator who's members are the members of the given iterators zipped sequencially
  */
 export const zipSync = function* <T>(...iteratorList: Array<Iterable<T>>): Generator<T[]> {
-  const generators = iteratorList.map((iterator) => iterator[Symbol.iterator]());
-  outer: while (true) {
-    const result: T[] = [];
-    for (const generator of generators) {
-      const { value, done } = generator.next();
-      if (done) {
-        break outer;
+  const entries = iteratorList.map((iterator) => ({ it: iterator[Symbol.iterator](), done: false }));
+  try {
+    outer: while (true) {
+      const result: T[] = [];
+      for (const entry of entries) {
+        let step: IteratorResult<T>;
+        try {
+          step = entry.it.next();
+        } catch (error) {
+          entry.done = true; // an iterator that threw is not closed again
+          throw error;
+        }
+        if (step.done) {
+          entry.done = true;
+          break outer;
+        }
+        result.push(step.value);
       }
-      result.push(value);
+      yield result;
     }
-    yield result;
+  } finally {
+    // Close every input that has not ended -- when the shortest input ends,
+    // when an input throws, and when the consumer exits early.
+    closeAllSync(entries);
   }
 };
 
@@ -248,17 +274,19 @@ export const zipSync = function* <T>(...iteratorList: Array<Iterable<T>>): Gener
 export const zipAsync = async function* <T>(
   ...iteratorList: Array<AsyncIterable<T> | Iterable<T>>
 ): AsyncGenerator<T[]> {
-  const generators = iteratorList.map((iterator) =>
-    isAsyncIterator(iterator)
-      ? (iterator as AsyncIterable<T>)[Symbol.asyncIterator]()
-      : (iterator as Iterable<T>)[Symbol.iterator](),
-  );
-  while (true) {
-    const results = await Promise.all(generators.map((g) => g.next()));
-    if (results.some(({ done }) => done)) {
-      break;
+  const entries = iteratorList.map((iterator) => entryOf(iterator));
+  try {
+    while (true) {
+      const results = await Promise.all(entries.map((entry) => pull(entry)));
+      if (results.some(({ done }) => done)) {
+        break;
+      }
+      yield results.map(({ value }) => value as T);
     }
-    yield results.map(({ value }) => value as T);
+  } finally {
+    // Close every input that has not ended -- when the shortest input ends,
+    // when an input rejects, and when the consumer exits early.
+    await closeAll(entries);
   }
 };
 

package/src/itertools.ts

@@ -19,7 +19,7 @@
  * Python's itertools module and the documented design divergences.
  */
 
-import { isAsyncIterator } from "./is-iterator.ts";
+import { closeAll, closeAllSync, entryOf, pull } from "./internal.ts";
 import { concatAsync, concatSync, zipAsync, zipSync } from "./iterator-tools.ts";
 
 /**
@@ -428,21 +428,33 @@ export async function* starmapAsync<Args extends unknown[], R>(
  * @param iteratorList iterables to zip
  */
 export function* zipLongestSync<T, F>(fillValue: F, ...iteratorList: Array<Iterable<T>>): Generator<Array<T | F>> {
-  const generators = iteratorList.map((iterator) => iterator[Symbol.iterator]());
-  while (true) {
-    const result: Array<T | F> = [];
-    let anyNotDone = false;
-    for (const generator of generators) {
-      const { value, done } = generator.next();
-      if (done) {
-        result.push(fillValue);
-      } else {
-        anyNotDone = true;
-        result.push(value);
+  const entries = iteratorList.map((iterator) => ({ it: iterator[Symbol.iterator](), done: false }));
+  try {
+    while (true) {
+      const result: Array<T | F> = [];
+      let anyNotDone = false;
+      for (const entry of entries) {
+        let step: IteratorResult<T>;
+        try {
+          step = entry.it.next();
+        } catch (error) {
+          entry.done = true; // an iterator that threw is not closed again
+          throw error;
+        }
+        if (step.done) {
+          entry.done = true;
+          result.push(fillValue);
+        } else {
+          anyNotDone = true;
+          result.push(step.value);
+        }
       }
+      if (!anyNotDone) return;
+      yield result;
     }
-    if (!anyNotDone) return;
-    yield result;
+  } finally {
+    // Close every input that has not ended, on an error or an early exit.
+    closeAllSync(entries);
   }
 }
 
@@ -456,15 +468,16 @@ export async function* zipLongestAsync<T, F>(
   fillValue: F,
   ...iteratorList: Array<AsyncIterable<T> | Iterable<T>>
 ): AsyncGenerator<Array<T | F>> {
-  const generators = iteratorList.map((iterator) =>
-    isAsyncIterator(iterator)
-      ? (iterator as AsyncIterable<T>)[Symbol.asyncIterator]()
-      : (iterator as Iterable<T>)[Symbol.iterator](),
-  );
-  while (true) {
-    const results = await Promise.all(generators.map((g) => g.next()));
-    if (results.every(({ done }) => done)) return;
-    yield results.map(({ value, done }) => (done ? fillValue : (value as T)));
+  const entries = iteratorList.map((iterator) => entryOf(iterator));
+  try {
+    while (true) {
+      const results = await Promise.all(entries.map((entry) => pull(entry)));
+      if (results.every(({ done }) => done)) return;
+      yield results.map(({ value, done }) => (done ? fillValue : (value as T)));
+    }
+  } finally {
+    // Close every input that has not ended, on an error or an early exit.
+    await closeAll(entries);
   }
 }
 

package/src/tee.ts

@@ -16,9 +16,66 @@
 
 const DONE = Symbol("DONE");
 
+/**
+ * Optional bound on how far branches may drift apart. Without it (the
+ * default), a branch that falls behind buffers without limit.
+ */
+export interface TeeOptions {
+  /** Most items a branch may hold unread (an integer >= 1). */
+  limit: number;
+  /**
+   * What happens when a branch pulls a new item while another branch
+   * already holds `limit` unread items:
+   * - `"wait"` (teeAsync only): the pulling branch waits until the slowest
+   *   branch reads (true backpressure);
+   * - `"drop-oldest"`: the item is delivered and that branch's oldest
+   *   unread item is discarded, so each branch keeps its newest `limit`;
+   * - `"error"`: the pull throws a RangeError instead.
+   */
+  overflow?: "wait" | "drop-oldest" | "error";
+}
+
+/** teeSync cannot block, so it supports every overflow mode except "wait". */
+export interface TeeSyncOptions extends TeeOptions {
+  overflow?: "drop-oldest" | "error";
+}
+
+const validate = (name: string, options: TeeOptions, allowWait: boolean): Required<TeeOptions> => {
+  const { limit, overflow = allowWait ? "wait" : "error" } = options;
+  if (!(limit === Infinity || (Number.isInteger(limit) && limit >= 1))) {
+    throw new RangeError(`${name}: limit must be an integer >= 1`);
+  }
+  if (overflow === "wait" && !allowWait) {
+    throw new TypeError(`${name}: overflow "wait" needs to block, which only teeAsync can do`);
+  }
+  if (overflow !== "wait" && overflow !== "drop-oldest" && overflow !== "error") {
+    throw new TypeError(`${name}: unknown overflow mode ${String(overflow)}`);
+  }
+  return { limit, overflow };
+};
+
+const overflowError = (name: string, limit: number): RangeError =>
+  new RangeError(`${name}: a branch already holds ${limit} unread items (overflow: "error")`);
+
+/**
+ * Track branches that have finished or been closed, so they stop
+ * receiving items (and stop counting toward the limit). Overriding
+ * `return` on the instance also catches a branch closed before its first
+ * next(), whose generator body (and finally block) never runs.
+ */
+const trackClose = <G extends Generator<unknown> | AsyncGenerator<unknown>>(gen: G, onClose: () => void): G => {
+  const original = gen.return.bind(gen) as (value?: unknown) => unknown;
+  (gen as { return: (value?: unknown) => unknown }).return = (value?: unknown) => {
+    onClose();
+    return original(value);
+  };
+  return gen;
+};
+
 export const teeSync =
-  (num = 0) =>
+  (num = 0, options?: TeeSyncOptions) =>
   <T>(iterable: Iterable<T>): Array<Generator<T>> => {
+    if (options) return boundedTeeSync(num, validate("teeSync", options, false), iterable);
     const source = iterable[Symbol.iterator]();
     const buffers: T[][] = new Array(num).fill(null).map(() => []);
 
@@ -62,8 +119,9 @@ export const teeSync =
   };
 
 export const teeAsync =
-  (num = 0) =>
+  (num = 0, options?: TeeOptions) =>
   <T>(iterable: AsyncIterable<T>): Array<AsyncGenerator<T>> => {
+    if (options) return boundedTeeAsync(num, validate("teeAsync", options, true), iterable);
     const source = iterable[Symbol.asyncIterator]();
     const buffers: T[][] = new Array(num).fill(null).map(() => []);
 
@@ -134,3 +192,145 @@ export const teeAsync =
       }
     });
   };
+
+/**
+ * teeSync with a per-branch limit. A separate code path so the default,
+ * unbounded teeSync is untouched.
+ * @ignore
+ */
+const boundedTeeSync = <T>(num: number, { limit, overflow }: Required<TeeOptions>, iterable: Iterable<T>) => {
+  const source = iterable[Symbol.iterator]();
+  const buffers: T[][] = new Array(num).fill(null).map(() => []);
+  const open: boolean[] = new Array(num).fill(true);
+
+  const next = (i: number): T | typeof DONE => {
+    const buffer = buffers[i] as T[];
+    if (buffer.length !== 0) {
+      return buffer.shift() as T;
+    }
+    if (overflow === "error" && buffers.some((b, j) => j !== i && open[j] && b.length >= limit)) {
+      throw overflowError("teeSync", limit);
+    }
+    const x = source.next();
+    if (x.done) {
+      return DONE;
+    }
+    for (let j = 0; j < buffers.length; j++) {
+      if (j === i || !open[j]) continue;
+      const other = buffers[j] as T[];
+      other.push(x.value);
+      if (other.length > limit) other.shift(); // drop-oldest
+    }
+    return x.value;
+  };
+
+  return buffers.map((_, i) => {
+    const close = () => {
+      open[i] = false;
+      (buffers[i] as T[]).length = 0;
+    };
+    return trackClose(
+      (function* () {
+        try {
+          for (;;) {
+            const x = next(i);
+            if (x === DONE) break;
+            yield x;
+          }
+        } finally {
+          close();
+          source.return?.();
+        }
+      })(),
+      close,
+    );
+  });
+};
+
+/**
+ * teeAsync with a per-branch limit. A separate code path so the default,
+ * unbounded teeAsync is untouched.
+ * @ignore
+ */
+const boundedTeeAsync = <T>(num: number, { limit, overflow }: Required<TeeOptions>, iterable: AsyncIterable<T>) => {
+  const source = iterable[Symbol.asyncIterator]();
+  const buffers: T[][] = new Array(num).fill(null).map(() => []);
+  const open: boolean[] = new Array(num).fill(true);
+  let inFlight: Promise<unknown> | null = null;
+  let sourceDone = false;
+  // Branches blocked by overflow "wait", woken whenever a buffer shrinks
+  // or a branch closes.
+  let waiters: Array<() => void> = [];
+  const wake = () => {
+    const ready = waiters;
+    waiters = [];
+    for (const resolve of ready) resolve();
+  };
+  const full = (i: number) => buffers.some((b, j) => j !== i && open[j] && b.length >= limit);
+
+  const next = async (i: number): Promise<T | typeof DONE> => {
+    const buffer = buffers[i] as T[];
+    if (buffer.length !== 0) {
+      const value = buffer.shift() as T;
+      wake();
+      return value;
+    }
+    if (sourceDone) {
+      return DONE;
+    }
+    if (inFlight) {
+      await inFlight;
+      return next(i);
+    }
+    if (full(i)) {
+      if (overflow === "error") throw overflowError("teeAsync", limit);
+      if (overflow === "wait") {
+        await new Promise<void>((resolve) => waiters.push(resolve));
+        return next(i);
+      }
+    }
+    const pull = (async (): Promise<T | typeof DONE> => {
+      const x = await source.next();
+      if (x.done) {
+        sourceDone = true;
+        return DONE;
+      }
+      for (let j = 0; j < buffers.length; j++) {
+        if (j === i || !open[j]) continue;
+        const other = buffers[j] as T[];
+        other.push(x.value);
+        if (other.length > limit) other.shift(); // drop-oldest
+      }
+      return x.value;
+    })();
+    inFlight = pull;
+    try {
+      return await pull;
+    } finally {
+      inFlight = null;
+    }
+  };
+
+  return buffers.map((_, i) => {
+    const close = () => {
+      open[i] = false;
+      (buffers[i] as T[]).length = 0;
+      wake();
+    };
+    return trackClose(
+      (async function* () {
+        try {
+          for (;;) {
+            const x = await next(i);
+            if (x === DONE) break;
+            yield x;
+          }
+        } finally {
+          close();
+          await source.return?.();
+        }
+      })(),
+      close,
+    );
+  });
+};

package/src/time.ts

@@ -0,0 +1,262 @@
+/**
+ * Time-based operators: debounceAsync and throttleAsync.
+ *
+ * Both drain their source eagerly (timing depends on when values arrive,
+ * not on when the consumer reads) and queue what they emit until the
+ * consumer reads it. Both take an injectable `clock`, so they can be driven
+ * by a fake clock in tests or by a host's own scheduler, and an optional
+ * `signal`. On abort, on a source error, and on consumer exit they clear
+ * their timer and close (`return()`) the source.
+ */
+
+import { type SignalOptions, throwIfAborted } from "./abort.ts";
+import { type AnyIterable, closeAll, createFailure, entryOf, listenAbort, pull, Wakeup } from "./internal.ts";
+
+/**
+ * The timer functions the time operators use. Defaults to the host's
+ * global `setTimeout`/`clearTimeout` and `performance.now()` (or
+ * `Date.now()` where `performance` is missing). `now()` must use the same
+ * time base as the delays given to `setTimeout`.
+ */
+export interface Clock {
+  setTimeout(callback: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+  now(): number;
+}
+
+export interface TimeOptions extends SignalOptions {
+  clock?: Clock;
+}
+
+export interface ThrottleOptions extends TimeOptions {
+  /** Emit the value that opens a window immediately. Default `true`. */
+  leading?: boolean;
+  /** At the end of a window, emit the newest value that arrived during it. Default `true`. */
+  trailing?: boolean;
+}
+
+/** The host's timers. */
+export const systemClock: Clock = {
+  setTimeout: (callback, ms) => globalThis.setTimeout(callback, ms),
+  clearTimeout: (handle) => globalThis.clearTimeout(handle as Parameters<typeof globalThis.clearTimeout>[0]),
+  now: () => (typeof globalThis.performance?.now === "function" ? globalThis.performance.now() : Date.now()),
+};
+
+const checkMs = (name: string, ms: number): void => {
+  if (!(typeof ms === "number" && ms >= 0 && Number.isFinite(ms))) {
+    throw new RangeError(`${name}: ms must be a finite number >= 0`);
+  }
+};
+
+/**
+ * Run the shared machinery of a time operator: pump the source, hand each
+ * value and the end to `hooks`, and yield whatever they emit, in order.
+ */
+const timed = async function* <T>(
+  iterable: AnyIterable<T>,
+  { signal }: SignalOptions,
+  setup: (emit: (value: T) => void) => { onValue(value: T): void; onEnd(): void; dispose(): void },
+): AsyncGenerator<T> {
+  throwIfAborted(signal);
+  const entry = entryOf(iterable);
+  const aborted = createFailure();
+  const wakeup = new Wakeup();
+  const queue: T[] = [];
+  let ended = false;
+  let stopped = false;
+  let sourceError: { error: unknown } | undefined;
+  const hooks = setup((value) => {
+    queue.push(value);
+    wakeup.wake();
+  });
+  const unlisten = listenAbort(signal, (reason) => {
+    aborted.fail(reason);
+    wakeup.wake();
+  });
+  const pump = async () => {
+    try {
+      while (!stopped) {
+        const result = await pull(entry);
+        if (stopped) return;
+        if (result.done) {
+          hooks.onEnd();
+          ended = true;
+          wakeup.wake();
+          return;
+        }
+        hooks.onValue(result.value);
+      }
+    } catch (error) {
+      hooks.dispose(); // drop a waiting value; stop the timer
+      sourceError = { error };
+      wakeup.wake();
+    }
+  };
+  try {
+    void pump();
+    while (true) {
+      // Abort wins at once; a source error comes after the values that
+      // were already emitted.
+      if (aborted.failed) throw aborted.error;
+      if (queue.length > 0) {
+        yield queue.shift() as T;
+        continue;
+      }
+      if (sourceError) throw sourceError.error;
+      if (ended) return;
+      await Promise.race([wakeup.wait(), aborted.promise]);
+    }
+  } finally {
+    stopped = true;
+    hooks.dispose();
+    unlisten();
+    await closeAll([entry]);
+  }
+};
+
+/**
+ * Emit a value only after `ms` have passed with no newer value: a burst of
+ * values becomes its last value, emitted `ms` after the burst ends. When
+ * the source ends, a value still waiting is emitted at once.
+ *
+ * Emitted values queue until the consumer reads them. A source error is
+ * rethrown after the queued values; a value still waiting for its quiet
+ * period is dropped.
+ * @kind function
+ * @name debounceAsync
+ * @example
+ * ```javascript
+ * for await (const query of debounceAsync(250, keystrokes)) search(query);
+ * ```
+ */
+export const debounceAsync = <T>(
+  ms: number,
+  iterable: AnyIterable<T>,
+  { clock = systemClock, signal }: TimeOptions = {},
+): AsyncGenerator<T> => {
+  checkMs("debounceAsync", ms);
+  return timed<T>(iterable, { signal }, (emit) => {
+    let timer: unknown;
+    let armed = false;
+    let waiting = false;
+    let value: T | undefined;
+    let lastAt = 0;
+    const fire = () => {
+      armed = false;
+      if (!waiting) return;
+      // Re-arm rather than reset the timer on every value: one timer per
+      // quiet period instead of one per value.
+      const elapsed = clock.now() - lastAt;
+      if (elapsed < ms) {
+        armed = true;
+        timer = clock.setTimeout(fire, ms - elapsed);
+        return;
+      }
+      const out = value as T;
+      waiting = false;
+      value = undefined;
+      emit(out);
+    };
+    return {
+      onValue(next) {
+        value = next;
+        waiting = true;
+        lastAt = clock.now();
+        if (!armed) {
+          armed = true;
+          timer = clock.setTimeout(fire, ms);
+        }
+      },
+      onEnd() {
+        if (armed) clock.clearTimeout(timer);
+        armed = false;
+        if (waiting) {
+          waiting = false;
+          emit(value as T);
+        }
+      },
+      dispose() {
+        if (armed) clock.clearTimeout(timer);
+        armed = false;
+      },
+    };
+  });
+};
+
+/**
+ * Emit at most one value per `ms` window. A value arriving while no window
+ * is open opens one, and is emitted at once if `leading` (default `true`).
+ * With `trailing` (default `true`), the newest value that arrived during a
+ * window is emitted when the window closes, which opens the next window.
+ * When the source ends, a trailing value still waiting is emitted at once.
+ *
+ * `leading` and `trailing` cannot both be false. Emitted values queue
+ * until the consumer reads them. A source error is rethrown after the
+ * queued values; a trailing value still waiting is dropped.
+ * @kind function
+ * @name throttleAsync
+ * @example
+ * ```javascript
+ * for await (const position of throttleAsync(16, pointerMoves)) draw(position);
+ * ```
+ */
+export const throttleAsync = <T>(
+  ms: number,
+  iterable: AnyIterable<T>,
+  { leading = true, trailing = true, clock = systemClock, signal }: ThrottleOptions = {},
+): AsyncGenerator<T> => {
+  checkMs("throttleAsync", ms);
+  if (!leading && !trailing) {
+    throw new RangeError("throttleAsync: leading and trailing cannot both be false");
+  }
+  return timed<T>(iterable, { signal }, (emit) => {
+    let timer: unknown;
+    let open = false;
+    let waiting = false;
+    let value: T | undefined;
+    const close = () => {
+      open = false;
+      if (trailing && waiting) {
+        const out = value as T;
+        waiting = false;
+        value = undefined;
+        emit(out);
+        openWindow();
+      }
+    };
+    const openWindow = () => {
+      open = true;
+      timer = clock.setTimeout(close, ms);
+    };
+    return {
+      onValue(next) {
+        if (open) {
+          if (trailing) {
+            value = next;
+            waiting = true;
+          }
+          return;
+        }
+        if (leading) {
+          emit(next);
+        } else {
+          value = next;
+          waiting = true;
+        }
+        openWindow();
+      },
+      onEnd() {
+        if (open) clock.clearTimeout(timer);
+        open = false;
+        if (trailing && waiting) {
+          waiting = false;
+          emit(value as T);
+        }
+      },
+      dispose() {
+        if (open) clock.clearTimeout(timer);
+        open = false;
+      },
+    };
+  });
+};