@johnhenry/iteration 0.0.0

package/src/transduce.ts

@@ -0,0 +1,161 @@
+import { abortable, type SignalOptions } from "./abort.ts";
+import { type ReducerStep, reduceAsync, reduceSync, type Transducer } from "./iterator-tools.ts";
+
+/**
+ * The innermost reducer step ("emit"): pushes an emitted item onto the
+ * pending-emission buffer (the accumulator) and returns the buffer.
+ * Replaces the v2.0 innermost step (conjoinSync/conjoinAsync), which
+ * wrapped the previous accumulator in a fresh generator per item --
+ * forming an ever-growing generator chain and leaking ~176 bytes per item
+ * on long streams. See reduceSync (iterator-tools.ts) for the full
+ * protocol description.
+ */
+const emit: ReducerStep<unknown> = (buffer, item) => {
+  buffer.push(item);
+  return buffer;
+};
+
+/**
+ * Transduce -- low-level plumbing kept for protocol experimentation:
+ * `reduce(itemCollection, reducer(lastreducer), init)`.
+ * @kind function
+ * @name transduce
+ * @ignore
+ */
+export const transduce = <Source, Result>(
+  itemCollection: Source,
+  reducer: (last: ReducerStep<never>) => ReducerStep<never>,
+  lastreducer: ReducerStep<never>,
+  init: unknown[],
+  reduce: (itemCollection: Source, step: ReducerStep<never>, init: unknown[]) => Result,
+): Result => reduce(itemCollection, reducer(lastreducer), init);
+
+/**
+ * Compose Functions
+ * @kind function
+ * @name composeFunctions
+ * @ignore
+ */
+const composeFunctions =
+  (...functions: Array<Transducer<unknown, unknown>>) =>
+  (input: ReducerStep<unknown>): ReducerStep<unknown> =>
+    functions.reduceRight((input, func) => func(input), input);
+
+/**
+ * Create a function that transduces an asynchronous iterator from a list
+ * of transducer functions. Transducers compose left to right as written:
+ * the first listed transducer sees source items first.
+ * @kind function
+ * @name transduceAsync
+ * @param transducers list of transducers
+ * @see transducers
+ * @see transduceSync
+ * @example <caption>Asynchronously log transduced numbers </caption>
+ * ```javascript
+ * import { transduceAsync, transducers, countAsync } from '@johnhenry/iteration';
+ * const {
+ *     map,
+ *     filter,
+ *     take,
+ * } = transducers;
+ * const LIMIT = 2 ** 2;
+ * const transduce = transduceAsync(
+ *     filter(x => x % 2),
+ *     map(x => x + 1),
+ *     take(LIMIT),
+ * );
+ * for await (const result of transduce(countAsync(Infinity))) {
+ *   console.log(result);
+ * }
+ * ```
+ */
+export function transduceAsync<A, B>(
+  t1: Transducer<A, B>,
+): (itemCollection: AsyncIterable<A> | Iterable<A>, options?: SignalOptions) => AsyncGenerator<B>;
+export function transduceAsync<A, B, C>(
+  t1: Transducer<A, B>,
+  t2: Transducer<B, C>,
+): (itemCollection: AsyncIterable<A> | Iterable<A>, options?: SignalOptions) => AsyncGenerator<C>;
+export function transduceAsync<A, B, C, D>(
+  t1: Transducer<A, B>,
+  t2: Transducer<B, C>,
+  t3: Transducer<C, D>,
+): (itemCollection: AsyncIterable<A> | Iterable<A>, options?: SignalOptions) => AsyncGenerator<D>;
+export function transduceAsync<A, B, C, D, E>(
+  t1: Transducer<A, B>,
+  t2: Transducer<B, C>,
+  t3: Transducer<C, D>,
+  t4: Transducer<D, E>,
+): (itemCollection: AsyncIterable<A> | Iterable<A>, options?: SignalOptions) => AsyncGenerator<E>;
+export function transduceAsync<A, B, C, D, E, F>(
+  t1: Transducer<A, B>,
+  t2: Transducer<B, C>,
+  t3: Transducer<C, D>,
+  t4: Transducer<D, E>,
+  t5: Transducer<E, F>,
+): (itemCollection: AsyncIterable<A> | Iterable<A>, options?: SignalOptions) => AsyncGenerator<F>;
+export function transduceAsync(
+  ...functions: Array<Transducer<any, any>>
+): (itemCollection: AsyncIterable<unknown> | Iterable<unknown>, options?: SignalOptions) => AsyncGenerator<unknown>;
+export function transduceAsync(...functions: Array<Transducer<any, any>>) {
+  return (itemCollection: AsyncIterable<unknown> | Iterable<unknown>, { signal }: SignalOptions = {}) =>
+    reduceAsync(signal ? abortable(itemCollection, signal) : itemCollection, composeFunctions(...functions)(emit), []);
+}
+
+/**
+ * Create a function that transduces a synchronous iterator from a list
+ * of transducer functions. Transducers compose left to right as written:
+ * the first listed transducer sees source items first.
+ * @kind function
+ * @name transduceSync
+ * @param transducers list of transducers
+ * @see transducers
+ * @see transduceAsync
+ * @example <caption>Synchronously log transduced numbers </caption>
+ * ```javascript
+ * import { transduceSync, transducers, countSync } from '@johnhenry/iteration';
+ * const {
+ *     map,
+ *     filter,
+ *     take,
+ * } = transducers;
+ * const LIMIT = 2 ** 2;
+ * const transduce = transduceSync(
+ *     filter(x => x % 2),
+ *     map(x => x + 1),
+ *     take(LIMIT),
+ * );
+ * for (const result of transduce(countSync(Infinity))) {
+ *   console.log(result);
+ * }
+ * ```
+ */
+export function transduceSync<A, B>(t1: Transducer<A, B>): (itemCollection: Iterable<A>) => Generator<B>;
+export function transduceSync<A, B, C>(
+  t1: Transducer<A, B>,
+  t2: Transducer<B, C>,
+): (itemCollection: Iterable<A>) => Generator<C>;
+export function transduceSync<A, B, C, D>(
+  t1: Transducer<A, B>,
+  t2: Transducer<B, C>,
+  t3: Transducer<C, D>,
+): (itemCollection: Iterable<A>) => Generator<D>;
+export function transduceSync<A, B, C, D, E>(
+  t1: Transducer<A, B>,
+  t2: Transducer<B, C>,
+  t3: Transducer<C, D>,
+  t4: Transducer<D, E>,
+): (itemCollection: Iterable<A>) => Generator<E>;
+export function transduceSync<A, B, C, D, E, F>(
+  t1: Transducer<A, B>,
+  t2: Transducer<B, C>,
+  t3: Transducer<C, D>,
+  t4: Transducer<D, E>,
+  t5: Transducer<E, F>,
+): (itemCollection: Iterable<A>) => Generator<F>;
+export function transduceSync(
+  ...functions: Array<Transducer<any, any>>
+): (itemCollection: Iterable<unknown>) => Generator<unknown>;
+export function transduceSync(...functions: Array<Transducer<any, any>>) {
+  return (itemCollection: Iterable<unknown>) => reduceSync(itemCollection, composeFunctions(...functions)(emit), []);
+}

package/src/transducers.ts

@@ -0,0 +1,256 @@
+/**
+ * Functions that return transducers
+ * @kind namespace
+ * @name transducerReturners
+ * @see transduceSync
+ * @see transduceAsync
+ */
+
+import { HALT, type ReducerStep, type Transducer } from "./iterator-tools.ts";
+
+/**
+ * Create a transducer that maps values
+ * @kind function
+ * @name map
+ * @param transform transformation function applied to each item
+ * @returns transducer
+ */
+export const map =
+  <In, Out>(transform: (item: In) => Out): Transducer<In, Out> =>
+  (conjoin) =>
+  (init, item) =>
+    conjoin(init, transform(item));
+
+/**
+ * Create a transducer that filters values
+ * @kind function
+ * @name filter
+ * @param predicate boolean function to determine if an item is emitted
+ * @returns transducer
+ */
+export const filter =
+  <In>(predicate: (item: In) => boolean): Transducer<In, In> =>
+  (conjoin) =>
+  (init, item) =>
+    predicate(item) ? conjoin(init, item) : init;
+
+/**
+ * Create a transducer that halts after a given number of values
+ * @kind function
+ * @name take
+ * @param limit maximum total items to emit
+ * @returns transducer
+ */
+export const take =
+  <In>(limit: number): Transducer<In, In> =>
+  (conjoin) => {
+    let amount = 0;
+    // biome-ignore lint/complexity/noCommaOperator: deliberate single-expression step function
+    return (init, item) => (amount < limit ? (amount++, conjoin(init, item)) : HALT);
+  };
+
+/**
+ * Create a transducer that drops the first N values
+ * before begining to yield
+ * @kind function
+ * @name drop
+ * @param limit number of leading items to drop
+ * @returns transducer
+ * @see reject
+ */
+export const drop =
+  <In>(limit: number): Transducer<In, In> =>
+  (conjoin) => {
+    let amount = 0;
+    // biome-ignore lint/complexity/noCommaOperator: deliberate single-expression step function
+    return (init, item) => (amount >= limit ? (amount++, conjoin(init, item)) : (amount++, init));
+  };
+
+/**
+ * Create a transducer that rejects values matching a predicate.
+ * The complement of `filter`.
+ * @kind function
+ * @name reject
+ * @param predicate boolean function; matching items are dropped
+ * @returns transducer
+ * @see filter
+ * @see drop
+ */
+export const reject =
+  <In>(predicate: (item: In) => boolean): Transducer<In, In> =>
+  (conjoin) =>
+  (init, item) =>
+    predicate(item) ? init : conjoin(init, item);
+
+/**
+ * Create a transducer that groups items by quantity before emitting.
+ * Note: this currently returns arrays -- would sets make more sense?
+ * Any trailing items that don't fill a complete group are flushed as a
+ * final, shorter group when the source iterator completes (see the
+ * `.complete` transducer protocol in transduce.ts/iterator-tools.ts).
+ * @kind function
+ * @name group
+ * @param limit size of group
+ * @returns transducer
+ */
+export const group =
+  <In>(limit: number): Transducer<In, In[]> =>
+  (conjoin) => {
+    const partition: In[] = [];
+    const step: ReducerStep<In> = (init, item) => {
+      partition.push(item);
+      if (partition.length === limit) {
+        return conjoin(init, partition.splice(0, limit));
+      }
+      return init;
+    };
+    step.complete = (init) => {
+      const out = partition.length > 0 ? conjoin(init, partition.splice(0)) : init;
+      const buffer = out === HALT ? init : out;
+      return conjoin.complete ? conjoin.complete(buffer) : buffer;
+    };
+    return step;
+  };
+
+/**
+ * Create a transducer that accumulates items into a result and emits them
+ * Similar to #Array.reduce
+ * @kind function
+ * @name accumulate
+ * @param func accumulation function
+ * @param initial initial accumulation value
+ * @returns transducer
+ */
+export const accumulate =
+  <In, Acc = In>(
+    func: (accumulated: Acc, item: In) => Acc = (a, b) =>
+      ((a as unknown as number) + (b as unknown as number)) as unknown as Acc,
+    initial: Acc = 0 as unknown as Acc,
+  ): Transducer<In, Acc> =>
+  (conjoin) => {
+    // Fresh per (conjoin) invocation -- i.e. per transduce run, matching
+    // every other stateful transducer in this file (take's `amount`,
+    // group's `partition`, etc). Mutating the outer `initial` parameter
+    // directly here would carry accumulated state over into the *next*
+    // transduce run that reuses this same accumulate(...) instance.
+    let accumulated = initial;
+    return (init, item) => {
+      accumulated = func(accumulated, item);
+      return conjoin(init, accumulated);
+    };
+  };
+
+/**
+ * Create a transducer that skips consecutive duplicate items (by key).
+ * Mirrors the `unique_justseen` recipe documented in Python's itertools
+ * docs -- the transducer-pipeline, adjacent-only counterpart to
+ * itertools.ts's global, unbounded-memory uniqueSync/uniqueAsync.
+ * @kind function
+ * @name dedupe
+ * @param keyFn maps an item to the key duplicates are compared by
+ * @returns transducer
+ * @see uniqueSync
+ */
+export const dedupe =
+  <In>(keyFn: (item: In) => unknown = (x) => x): Transducer<In, In> =>
+  (conjoin) => {
+    let hasLast = false;
+    let lastKey: unknown;
+    return (init, item) => {
+      const key = keyFn(item);
+      if (hasLast && Object.is(key, lastKey)) {
+        return init;
+      }
+      hasLast = true;
+      lastKey = key;
+      return conjoin(init, item);
+    };
+  };
+
+/**
+ * Create a transducer that inserts `separator` between consecutive
+ * emitted items -- not before the first item, and not after the last.
+ * @kind function
+ * @name interpose
+ * @param separator value inserted between items
+ * @returns transducer
+ */
+export const interpose =
+  <In, Sep = In>(separator: Sep): Transducer<In, In | Sep> =>
+  (conjoin) => {
+    let started = false;
+    return (init, item) => {
+      if (started) {
+        const out = conjoin(init, separator);
+        if (out === HALT) {
+          return HALT;
+        }
+        init = out;
+      }
+      started = true;
+      return conjoin(init, item);
+    };
+  };
+
+/**
+ * Create a transducer that groups consecutive items sharing a key into
+ * arrays, emitting each completed group as soon as the key changes.
+ * The transducer-pipeline counterpart to groupBySync/groupByAsync
+ * (itertools.ts); distinct from `group`, above, which chunks by a fixed
+ * size rather than by a shared key. Any trailing group is flushed when the
+ * source iterator completes, following the same `.complete` protocol as
+ * `group`.
+ * @kind function
+ * @name partitionBy
+ * @param keyFn maps an item to the key runs are grouped by
+ * @returns transducer
+ * @see groupBySync
+ * @see group
+ */
+export const partitionBy =
+  <In>(keyFn: (item: In) => unknown = (x) => x): Transducer<In, In[]> =>
+  (conjoin) => {
+    let hasCurrent = false;
+    let currentKey: unknown;
+    let bucket: In[] = [];
+    const step: ReducerStep<In> = (init, item) => {
+      const key = keyFn(item);
+      if (!hasCurrent) {
+        hasCurrent = true;
+        currentKey = key;
+        bucket = [item];
+        return init;
+      }
+      if (Object.is(key, currentKey)) {
+        bucket.push(item);
+        return init;
+      }
+      const out = conjoin(init, bucket);
+      currentKey = key;
+      bucket = [item];
+      return out;
+    };
+    step.complete = (init) => {
+      const out = bucket.length > 0 ? conjoin(init, bucket) : init;
+      const buffer = out === HALT ? init : out;
+      return conjoin.complete ? conjoin.complete(buffer) : buffer;
+    };
+    return step;
+  };
+
+/**
+ * Create a transducer that calls `fn(item)` for its side effect and passes
+ * the item through unchanged. RxJS-style, for debugging/instrumenting a
+ * pipeline without altering its values.
+ * @kind function
+ * @name tap
+ * @param fn called with each item, for side effects
+ * @returns transducer
+ */
+export const tap =
+  <In>(fn: (item: In) => unknown): Transducer<In, In> =>
+  (conjoin) =>
+  (init, item) => {
+    fn(item);
+    return conjoin(init, item);
+  };