@johnhenry/iteration 0.0.0

package/src/consumers.ts

@@ -0,0 +1,425 @@
+/**
+ * Terminal consumer operations: resolve an iterable to a single value (or a
+ * Promise of one), rather than returning another iterable. Two families:
+ *
+ * - Iterator-Helper parity (some/every/find/forEach/fold): native ES2025
+ *   Iterator Helpers give sync code `.some()`/`.every()`/`.find()`/
+ *   `.forEach()`/`.reduce()` for free via Iterator.from(iterable); there is
+ *   no shipped async equivalent (AsyncIterator helpers are TC39 Stage 2),
+ *   so the async half here is hand-rolled.
+ * - Summary/aggregate consumers (first/last/nth/quantify/min/max): not part
+ *   of core Python itertools, but a near-universal expectation for any
+ *   itertools-adjacent library (see itertools-ts's "summary" namespace);
+ *   `quantify` specifically is a named recipe from Python's own itertools
+ *   docs, not an invented name.
+ *
+ * House conventions:
+ * - Async variants `await` their callback's return value (predicate/fn/keyFn
+ *   may be async); sync variants do not, matching native Iterator Helpers'
+ *   own non-awaiting behavior and every other sync callback in this library
+ *   (groupBySync's keyFn, uniqueSync's keyFn, etc.).
+ * - Required-callback functions put the callback first (matching
+ *   itertools.ts: takeWhileSync(predicate, iterable)). Optional-callback
+ *   functions put `iterable` first (matching Python's own builtin order:
+ *   min(iterable, key=..., default=...)).
+ * - find/first/last/nth/min/max return `undefined` (or a caller-supplied
+ *   `defaultValue`) on an empty iterable/no match, rather than throwing --
+ *   consistent with Array.prototype.find, deliberately diverging from
+ *   Python's own min()/max() (which throw without a default).
+ *
+ * `fold` is named deliberately -- NOT `reduce` -- to avoid colliding with
+ * reduceSync/reduceAsync in iterator-tools.ts, which are an internal
+ * streaming primitive (yield each emitted item) rather than a terminal
+ * reduce-to-one-value.
+ */
+
+import { abortable, type SignalOptions } from "./abort.ts";
+import { isliceAsync, isliceSync } from "./itertools.ts";
+
+type MaybePromise<T> = T | Promise<T>;
+export type AnyAsyncIterable<T> = AsyncIterable<T> | Iterable<T>;
+
+const maybeAbortable = <T>(iterable: AnyAsyncIterable<T>, signal?: AbortSignal): AnyAsyncIterable<T> =>
+  signal ? abortable(iterable, signal) : iterable;
+
+/**
+ * True for a numeric NaN key. `NaN < x` and `NaN > x` are always false, so
+ * without an explicit check a NaN key silently falls out of every
+ * comparison instead of poisoning the result -- see minSync/maxSync.
+ * @ignore
+ */
+const isNaNKey = (key: unknown): boolean => typeof key === "number" && Number.isNaN(key);
+
+/**
+ * True if any item satisfies predicate. Short-circuits on the first match.
+ * @kind function
+ * @name someSync
+ */
+export const someSync = <T>(predicate: (item: T) => boolean, iterable: Iterable<T>): boolean =>
+  Iterator.from(iterable).some(predicate);
+
+/**
+ * Asynchronous dual of someSync. Short-circuits (a `return` inside
+ * `for await...of` closes the underlying async iterator).
+ * @kind function
+ * @name someAsync
+ */
+export const someAsync = async <T>(
+  predicate: (item: T) => MaybePromise<boolean>,
+  iterable: AnyAsyncIterable<T>,
+  { signal }: SignalOptions = {},
+): Promise<boolean> => {
+  for await (const item of maybeAbortable(iterable, signal)) {
+    if (await predicate(item)) return true;
+  }
+  return false;
+};
+
+/**
+ * True only if every item satisfies predicate. Short-circuits on the first
+ * failure.
+ * @kind function
+ * @name everySync
+ */
+export const everySync = <T>(predicate: (item: T) => boolean, iterable: Iterable<T>): boolean =>
+  Iterator.from(iterable).every(predicate);
+
+/**
+ * Asynchronous dual of everySync.
+ * @kind function
+ * @name everyAsync
+ */
+export const everyAsync = async <T>(
+  predicate: (item: T) => MaybePromise<boolean>,
+  iterable: AnyAsyncIterable<T>,
+  { signal }: SignalOptions = {},
+): Promise<boolean> => {
+  for await (const item of maybeAbortable(iterable, signal)) {
+    if (!(await predicate(item))) return false;
+  }
+  return true;
+};
+
+/**
+ * The first item satisfying predicate, or undefined. Short-circuits.
+ * @kind function
+ * @name findSync
+ */
+export const findSync = <T>(predicate: (item: T) => boolean, iterable: Iterable<T>): T | undefined =>
+  Iterator.from(iterable).find(predicate);
+
+/**
+ * Asynchronous dual of findSync.
+ * @kind function
+ * @name findAsync
+ */
+export const findAsync = async <T>(
+  predicate: (item: T) => MaybePromise<boolean>,
+  iterable: AnyAsyncIterable<T>,
+  { signal }: SignalOptions = {},
+): Promise<T | undefined> => {
+  for await (const item of maybeAbortable(iterable, signal)) {
+    if (await predicate(item)) return item;
+  }
+  return undefined;
+};
+
+/**
+ * Call fn once per item, for side effects. Returns undefined.
+ * @kind function
+ * @name forEachSync
+ */
+export const forEachSync = <T>(fn: (item: T) => unknown, iterable: Iterable<T>): void =>
+  Iterator.from(iterable).forEach(fn);
+
+/**
+ * Asynchronous dual of forEachSync. Distinct from `run` (iterator-tools.ts)
+ * -- `run` is framed around "rendering a program" (reversed argument order,
+ * `render` defaults to console.log); this is the itertools-parity-family
+ * addition with the family's usual (fn, iterable) argument order.
+ * @kind function
+ * @name forEachAsync
+ * @see run
+ */
+export const forEachAsync = async <T>(
+  fn: (item: T) => unknown,
+  iterable: AnyAsyncIterable<T>,
+  { signal }: SignalOptions = {},
+): Promise<void> => {
+  for await (const item of maybeAbortable(iterable, signal)) {
+    await fn(item);
+  }
+};
+
+/**
+ * Reduce iterable to a single value, given an explicit initial value
+ * (unlike Array.prototype.reduce, `init` is required -- avoids replicating
+ * reduce's "throws on empty array with no initial value" edge case).
+ * Named `fold`, not `reduce`, to avoid colliding with reduceSync/reduceAsync
+ * (iterator-tools.ts), which are an internal streaming primitive, not a
+ * terminal reduce-to-one-value.
+ * @kind function
+ * @name foldSync
+ */
+export const foldSync = <T, Acc>(fn: (acc: Acc, item: T) => Acc, init: Acc, iterable: Iterable<T>): Acc =>
+  Iterator.from(iterable).reduce(fn, init);
+
+/**
+ * Asynchronous dual of foldSync.
+ * @kind function
+ * @name foldAsync
+ */
+export const foldAsync = async <T, Acc>(
+  fn: (acc: Acc, item: T) => MaybePromise<Acc>,
+  init: Acc,
+  iterable: AnyAsyncIterable<T>,
+  { signal }: SignalOptions = {},
+): Promise<Acc> => {
+  let acc = init;
+  for await (const item of maybeAbortable(iterable, signal)) {
+    acc = await fn(acc, item);
+  }
+  return acc;
+};
+
+/**
+ * The first item, or defaultValue if the iterable is empty.
+ * @kind function
+ * @name firstSync
+ */
+export const firstSync = <T, D = undefined>(iterable: Iterable<T>, defaultValue?: D): T | D => {
+  const { value, done } = iterable[Symbol.iterator]().next();
+  return done ? (defaultValue as D) : value;
+};
+
+/**
+ * Asynchronous dual of firstSync.
+ * @kind function
+ * @name firstAsync
+ */
+export const firstAsync = async <T, D = undefined>(
+  iterable: AsyncIterable<T>,
+  defaultValue?: D,
+  { signal }: SignalOptions = {},
+): Promise<T | D> => {
+  if (signal) {
+    for await (const item of abortable(iterable, signal)) {
+      return item;
+    }
+    return defaultValue as D;
+  }
+  const { value, done } = await iterable[Symbol.asyncIterator]().next();
+  return done ? (defaultValue as D) : value;
+};
+
+/**
+ * The last item, or defaultValue if the iterable is empty. Necessarily
+ * consumes the entire iterable -- no way around it for a generic source.
+ * @kind function
+ * @name lastSync
+ */
+export const lastSync = <T, D = undefined>(iterable: Iterable<T>, defaultValue?: D): T | D => {
+  let result: T | D = defaultValue as D;
+  for (const item of iterable) {
+    result = item;
+  }
+  return result;
+};
+
+/**
+ * Asynchronous dual of lastSync.
+ * @kind function
+ * @name lastAsync
+ */
+export const lastAsync = async <T, D = undefined>(
+  iterable: AnyAsyncIterable<T>,
+  defaultValue?: D,
+  { signal }: SignalOptions = {},
+): Promise<T | D> => {
+  let result: T | D = defaultValue as D;
+  for await (const item of maybeAbortable(iterable, signal)) {
+    result = item;
+  }
+  return result;
+};
+
+/**
+ * The item at position n (0-indexed), or defaultValue if out of range.
+ * Reuses isliceSync rather than duplicating positional-skip logic.
+ * @kind function
+ * @name nthSync
+ */
+export const nthSync = <T, D = undefined>(iterable: Iterable<T>, n: number, defaultValue?: D): T | D => {
+  for (const item of isliceSync(iterable, n, n + 1)) {
+    return item;
+  }
+  return defaultValue as D;
+};
+
+/**
+ * Asynchronous dual of nthSync.
+ * @kind function
+ * @name nthAsync
+ */
+export const nthAsync = async <T, D = undefined>(
+  iterable: AsyncIterable<T>,
+  n: number,
+  defaultValue?: D,
+  { signal }: SignalOptions = {},
+): Promise<T | D> => {
+  for await (const item of isliceAsync(maybeAbortable(iterable, signal) as AsyncIterable<T>, n, n + 1)) {
+    return item;
+  }
+  return defaultValue as D;
+};
+
+/**
+ * Count items satisfying predicate (default: count all items). Named after
+ * the `quantify(iterable, pred=bool)` recipe documented in Python's own
+ * itertools docs -- not part of core itertools, but not an invented name
+ * either. Deliberately not named `count`/`countSync`, which already mirror
+ * Python's itertools.count (an integer *sequence generator*, unrelated).
+ * @kind function
+ * @name quantifySync
+ */
+export const quantifySync = <T>(iterable: Iterable<T>, predicate: (item: T) => boolean = () => true): number => {
+  let count = 0;
+  for (const item of iterable) {
+    if (predicate(item)) count++;
+  }
+  return count;
+};
+
+/**
+ * Asynchronous dual of quantifySync.
+ * @kind function
+ * @name quantifyAsync
+ */
+export const quantifyAsync = async <T>(
+  iterable: AnyAsyncIterable<T>,
+  predicate: (item: T) => MaybePromise<boolean> = () => true,
+  { signal }: SignalOptions = {},
+): Promise<number> => {
+  let count = 0;
+  for await (const item of maybeAbortable(iterable, signal)) {
+    if (await predicate(item)) count++;
+  }
+  return count;
+};
+
+/**
+ * The item with the minimum key (default: the item itself), or defaultValue
+ * if the iterable is empty. Necessarily consumes the entire iterable.
+ * Mirrors Python's builtin min(iterable, key=..., default=...), but
+ * returns undefined rather than throwing when empty and no default is given.
+ * A NaN key anywhere in the iterable poisons the result to NaN, matching
+ * `Math.min`'s own NaN-poisoning convention (rather than silently dropping
+ * out of every comparison and returning an unrelated wrong item).
+ * @kind function
+ * @name minSync
+ */
+export const minSync = <T, D = undefined>(
+  iterable: Iterable<T>,
+  keyFn: (item: T) => unknown = (x) => x,
+  defaultValue?: D,
+): T | D => {
+  let best: T | undefined, bestKey: unknown;
+  let found = false;
+  let sawNaN = false;
+  for (const item of iterable) {
+    const key = keyFn(item);
+    if (isNaNKey(key)) sawNaN = true;
+    if (!found || (key as number) < (bestKey as number)) {
+      best = item;
+      bestKey = key;
+      found = true;
+    }
+  }
+  if (sawNaN) return NaN as unknown as T | D;
+  return found ? (best as T) : (defaultValue as D);
+};
+
+/**
+ * Asynchronous dual of minSync; keyFn may be async. Same NaN-poisoning
+ * convention as minSync.
+ * @kind function
+ * @name minAsync
+ */
+export const minAsync = async <T, D = undefined>(
+  iterable: AnyAsyncIterable<T>,
+  keyFn: (item: T) => unknown = (x) => x,
+  defaultValue?: D,
+  { signal }: SignalOptions = {},
+): Promise<T | D> => {
+  let best: T | undefined, bestKey: unknown;
+  let found = false;
+  let sawNaN = false;
+  for await (const item of maybeAbortable(iterable, signal)) {
+    const key = await keyFn(item);
+    if (isNaNKey(key)) sawNaN = true;
+    if (!found || (key as number) < (bestKey as number)) {
+      best = item;
+      bestKey = key;
+      found = true;
+    }
+  }
+  if (sawNaN) return NaN as unknown as T | D;
+  return found ? (best as T) : (defaultValue as D);
+};
+
+/**
+ * The item with the maximum key (default: the item itself), or defaultValue
+ * if the iterable is empty. Mirrors Python's builtin
+ * max(iterable, key=..., default=...); see minSync for the
+ * undefined-vs-throw divergence and the NaN-poisoning convention.
+ * @kind function
+ * @name maxSync
+ */
+export const maxSync = <T, D = undefined>(
+  iterable: Iterable<T>,
+  keyFn: (item: T) => unknown = (x) => x,
+  defaultValue?: D,
+): T | D => {
+  let best: T | undefined, bestKey: unknown;
+  let found = false;
+  let sawNaN = false;
+  for (const item of iterable) {
+    const key = keyFn(item);
+    if (isNaNKey(key)) sawNaN = true;
+    if (!found || (key as number) > (bestKey as number)) {
+      best = item;
+      bestKey = key;
+      found = true;
+    }
+  }
+  if (sawNaN) return NaN as unknown as T | D;
+  return found ? (best as T) : (defaultValue as D);
+};
+
+/**
+ * Asynchronous dual of maxSync; keyFn may be async. Same NaN-poisoning
+ * convention as minSync.
+ * @kind function
+ * @name maxAsync
+ */
+export const maxAsync = async <T, D = undefined>(
+  iterable: AnyAsyncIterable<T>,
+  keyFn: (item: T) => unknown = (x) => x,
+  defaultValue?: D,
+  { signal }: SignalOptions = {},
+): Promise<T | D> => {
+  let best: T | undefined, bestKey: unknown;
+  let found = false;
+  let sawNaN = false;
+  for await (const item of maybeAbortable(iterable, signal)) {
+    const key = await keyFn(item);
+    if (isNaNKey(key)) sawNaN = true;
+    if (!found || (key as number) > (bestKey as number)) {
+      best = item;
+      bestKey = key;
+      found = true;
+    }
+  }
+  if (sawNaN) return NaN as unknown as T | D;
+  return found ? (best as T) : (defaultValue as D);
+};

package/src/count.ts

@@ -0,0 +1,72 @@
+type Numeric = number | bigint;
+
+const count = <N extends Numeric>(zero: N, one: N) =>
+  function* (min: N = zero, max?: N, inc: N = one): Generator<N> {
+    if (max === undefined) {
+      if (min < zero) {
+        max = zero;
+      } else {
+        max = min;
+        min = zero;
+      }
+    }
+
+    if (min < max) {
+      for (let i = min; i <= max; i = ((i as number) + (inc as number)) as N) {
+        yield i;
+      }
+    } else if (min > max) {
+      for (let i = min; i >= max; i = ((i as number) - (inc as number)) as N) {
+        yield i;
+      }
+    } else {
+      yield min;
+    }
+
+    return;
+  };
+
+/**
+ * Create a sequence of numbers
+ * @kind function
+ * @name countSync
+ * @param min number at which to start iteration
+ * @param max number before which to stop iteration
+ * @param inc increment
+ * @see countAsync
+ * @example <caption>Log an infinite sequence of numbers starting with 5 </caption>
+ * ```javascript
+ * import { countSync } from '@johnhenry/iteration';
+ * for(const num of countSync(5, Infinity)){
+ *   console.log(num);
+ * }
+ * ```
+ */
+export const countSync = count<number>(0, 1);
+export const countBigSync = count<bigint>(0n, 1n);
+/**
+ * Create an asynchronous sequence of numbers
+ * @kind function
+ * @name countAsync
+ * @param min number at which to start iteration
+ * @param max number before which to stop iteration
+ * @param inc increment
+ * @see countSync
+ * @example <caption>Log an infinite sequence of numbers starting with 5 </caption>
+ * ```javascript
+ * import { countAsync } from '@johnhenry/iteration';
+ * for await(const num of countAsync(5, Infinity)){
+ *   console.log(num);
+ * }
+ * ```
+ */
+export const countAsync = async function* (min = 0, max?: number, inc = 1): AsyncGenerator<number> {
+  yield* countSync(min, max, inc);
+};
+// min/inc default to undefined here (not 0/1) so countBigSync's own
+// BigInt defaults (bound via count(0n, 1n)) actually apply -- a Number
+// default of 0/1 would flow straight through and crash the first time
+// `min += inc` mixed a BigInt with a Number.
+export const countBigAsync = async function* (min?: bigint, max?: bigint, inc?: bigint): AsyncGenerator<bigint> {
+  yield* countBigSync(min, max, inc);
+};

package/src/empty-iterator.ts

@@ -0,0 +1,17 @@
+import { conjoinAsync, conjoinSync } from "./iterator-tools.ts";
+/**
+ * "The" Empty Iterator
+ *  Immediately finishes and yields nothing.
+ * @kind function
+ * @name emptySync
+ */
+
+export const emptySync: Generator<never> = conjoinSync<never>();
+
+/**
+ * "The" Empty Asynchronous Iterator
+ *  Immediately finishes and yields nothing.
+ * @kind function
+ * @name emptyAsync
+ */
+export const emptyAsync: AsyncGenerator<never> = conjoinAsync<never>();

package/src/eventualequal.ts

@@ -0,0 +1,54 @@
+import { exhaust } from "./exhaust.ts";
+import { isAsyncIterator, isIterator } from "./is-iterator.ts";
+
+export const eventualequal = async (a: unknown, b: unknown): Promise<boolean> => {
+  if (a === b) return true;
+  if (a && b && typeof a === "object" && typeof b === "object") {
+    let length: number, i: number, keys: string[];
+    if (Array.isArray(a) && Array.isArray(b)) {
+      length = a.length;
+      if (length !== b.length) return false;
+      for (i = length; i-- !== 0; ) {
+        if (!(await eventualequal(a[i], b[i]))) return false;
+      }
+      return true;
+    }
+    if (isIterator(a) || isAsyncIterator(a) || isIterator(b) || isAsyncIterator(b)) {
+      try {
+        return eventualequal(await exhaust(a), await exhaust(b));
+      } catch (_e) {
+        return false;
+      }
+    }
+
+    if (a.constructor === RegExp) {
+      return (a as RegExp).source === (b as RegExp).source && (a as RegExp).flags === (b as RegExp).flags;
+    }
+    if (a.valueOf !== Object.prototype.valueOf) {
+      return a.valueOf() === b.valueOf();
+    }
+    if (a.toString !== Object.prototype.toString) {
+      return a.toString() === b.toString();
+    }
+
+    keys = Object.keys(a);
+    length = keys.length;
+    if (length !== Object.keys(b).length) return false;
+
+    for (i = length; i-- !== 0; ) {
+      if (!Object.hasOwn(b, keys[i] as string)) return false;
+    }
+
+    for (i = length; i-- !== 0; ) {
+      const key = keys[i] as string;
+      if (!(await eventualequal((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])))
+        return false;
+    }
+
+    return true;
+  }
+
+  // true if both NaN, false otherwise
+  // biome-ignore lint/suspicious/noSelfCompare: deliberate NaN check (x !== x is true only for NaN)
+  return a !== a && b !== b;
+};

package/src/exhaust.ts

@@ -0,0 +1,26 @@
+import { isAsyncIterator, isIterator } from "./is-iterator.ts";
+
+export const exhaustSync = <T>(iterator: Iterable<T>): T[] => {
+  return [...iterator];
+};
+export const exhaustAsync = async <T>(asyncIterator: AsyncIterable<T>): Promise<T[]> => {
+  const r: T[] = [];
+  for await (const o of asyncIterator) {
+    r.push(o);
+  }
+  return r;
+};
+
+export function exhaust<T>(obj: Iterable<T>): T[];
+export function exhaust<T>(obj: AsyncIterable<T>): Promise<T[]>;
+export function exhaust(obj: unknown): unknown[] | Promise<unknown[]>;
+export function exhaust(obj: unknown): unknown[] | Promise<unknown[]> {
+  if (isIterator(obj)) {
+    return exhaustSync(obj);
+  } else if (isAsyncIterator(obj)) {
+    return exhaustAsync(obj);
+  }
+  throw new TypeError(`${obj} is not iterable`);
+}
+
+export default exhaust;

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./abort.ts";
+export * from "./async-channel.ts";
+export * from "./concurrency.ts";
+export * from "./consumers.ts";
+export * from "./count.ts";
+export * from "./empty-iterator.ts";
+export * from "./exhaust.ts";
+export * from "./is-iterator.ts";
+export * from "./iterator-tools.ts";
+export * from "./itertools.ts";
+export * from "./tee.ts";
+export * from "./transduce.ts";
+
+import * as channelDecorators from "./channel-decorators.ts";
+import * as transducers from "./transducers.ts";
+
+export { channelDecorators, transducers };

package/src/is-iterator.ts

@@ -0,0 +1,9 @@
+export const isIterator = (obj: unknown): obj is Iterable<unknown> =>
+  typeof (obj as Iterable<unknown>)?.[Symbol.iterator] === "function";
+
+export const isAsyncIterator = (obj: unknown): obj is AsyncIterable<unknown> =>
+  typeof (obj as AsyncIterable<unknown>)?.[Symbol.asyncIterator] === "function";
+
+export const exhaustable = (obj: unknown): boolean => isIterator(obj) || isAsyncIterator(obj);
+
+export default exhaustable;