@johnhenry/iteration 0.0.0 → 0.1.0

package/src/transduce.ts

@@ -1,5 +1,5 @@
 import { abortable, type SignalOptions } from "./abort.ts";
-import { type ReducerStep, reduceAsync, reduceSync, type Transducer } from "./iterator-tools.ts";
+import { HALT, type ReducerStep, reduceAsync, reduceSync, type Transducer } from "./iterator-tools.ts";
 
 /**
  * The innermost reducer step ("emit"): pushes an emitted item onto the
@@ -159,3 +159,115 @@ export function transduceSync(
 export function transduceSync(...functions: Array<Transducer<any, any>>) {
   return (itemCollection: Iterable<unknown>) => reduceSync(itemCollection, composeFunctions(...functions)(emit), []);
 }
+
+/**
+ * A push-driven transducer pipeline: feed values in one at a time with
+ * `step`, and flush with `complete` when the input ends.
+ */
+export interface PushTransducer<In, Out> {
+  /**
+   * Run one value through the pipeline and return what it emitted (often
+   * zero or one item; `group` and friends may emit several). Returns `[]`
+   * once the pipeline has halted or completed.
+   */
+  step(value: In): Out[];
+  /**
+   * Flush stateful transducers (`.complete`, e.g. a trailing partial
+   * `group`) and return what they emitted. Call it once when the input
+   * ends, or after `halted` becomes true. Later calls return `[]`.
+   */
+  complete(): Out[];
+  /**
+   * What the stateful transducers keep between steps, upstream first: a
+   * half-full `group`'s items, `partitionBy`'s open run, `accumulate`'s
+   * running value, `dedupe`'s last key. A copy: changing it changes nothing.
+   */
+  held(): unknown[];
+  /**
+   * Let go of the held items `predicate` matches, and return how many. For a
+   * caller that must stop an operator keeping something (a value removed
+   * elsewhere). It never emits and never changes what is later emitted
+   * beyond leaving the dropped items out: a `group` still waits for its full
+   * size, a `partitionBy` run left empty is closed without being emitted,
+   * `accumulate` starts again from its initial value, and `dedupe` forgets
+   * its key (so an equal item passes once).
+   */
+  drop(predicate: (held: unknown) => boolean): number;
+  /** True once a transducer returned HALT (e.g. `take(n)` saw item n + 1). */
+  readonly halted: boolean;
+}
+
+/**
+ * Drive transducers by pushing values in, with no iterator: for code that
+ * receives values by callback (an event handler, a wire in a dataflow
+ * graph). Uses the same left-to-right composition order, `.complete` flush
+ * protocol and HALT semantics as transduceSync:
+ * `transduceSync(...t)(xs)` yields exactly what pushing each `x` through
+ * `step` and then calling `complete()` returns.
+ *
+ * Like transduceSync, the items emitted by the step that returns HALT are
+ * discarded.
+ * @kind function
+ * @name transducePush
+ * @example
+ * ```javascript
+ * import { transducePush, transducers } from '@johnhenry/iteration';
+ * const { map, group } = transducers;
+ * const pipe = transducePush(map((x) => x * 10), group(2));
+ * pipe.step(1); // []
+ * pipe.step(2); // [[10, 20]]
+ * pipe.step(3); // []
+ * pipe.complete(); // [[30]]
+ * ```
+ */
+export function transducePush<A, B>(t1: Transducer<A, B>): PushTransducer<A, B>;
+export function transducePush<A, B, C>(t1: Transducer<A, B>, t2: Transducer<B, C>): PushTransducer<A, C>;
+export function transducePush<A, B, C, D>(
+  t1: Transducer<A, B>,
+  t2: Transducer<B, C>,
+  t3: Transducer<C, D>,
+): PushTransducer<A, D>;
+export function transducePush<A, B, C, D, E>(
+  t1: Transducer<A, B>,
+  t2: Transducer<B, C>,
+  t3: Transducer<C, D>,
+  t4: Transducer<D, E>,
+): PushTransducer<A, E>;
+export function transducePush<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>,
+): PushTransducer<A, F>;
+export function transducePush(...functions: Array<Transducer<any, any>>): PushTransducer<unknown, unknown>;
+export function transducePush(...functions: Array<Transducer<any, any>>): PushTransducer<unknown, unknown> {
+  const step = composeFunctions(...functions)(emit);
+  let halted = false;
+  let completed = false;
+  return {
+    step(value) {
+      if (halted || completed) return [];
+      const out = step([], value);
+      if (out === HALT) {
+        halted = true;
+        return [];
+      }
+      return out;
+    },
+    complete() {
+      if (completed) return [];
+      completed = true;
+      return step.complete ? step.complete([]) : [];
+    },
+    held() {
+      return step.held ? step.held() : [];
+    },
+    drop(predicate) {
+      return step.drop ? step.drop(predicate) : 0;
+    },
+    get halted() {
+      return halted;
+    },
+  };
+}

package/src/transducers.ts

@@ -8,6 +8,56 @@
 
 import { HALT, type ReducerStep, type Transducer } from "./iterator-tools.ts";
 
+/**
+ * Give a stateless transducer's step the inner step's `.complete`, so the
+ * end-of-source flush cascades through it to a stateful transducer further
+ * down the pipeline (e.g. the trailing partial group in
+ * `transduceSync(map(f), group(2))`). A stateless step has nothing of its
+ * own to flush, so it forwards the inner `.complete` unchanged. Without
+ * this, `reduceSync`/`reduceAsync`/`transducePush` only ever saw the
+ * outermost step, which had no `.complete`, and the flush was lost.
+ * @ignore
+ */
+const forwardComplete = <In>(
+  next: Pick<ReducerStep<never>, "complete" | "held" | "drop">,
+  step: ReducerStep<In>,
+): ReducerStep<In> => {
+  if (next.complete) step.complete = next.complete;
+  if (next.held) step.held = next.held;
+  if (next.drop) step.drop = next.drop;
+  return step;
+};
+
+/**
+ * Give a stateful step `held`/`drop` over its own state, then the inner
+ * step's, so the hooks cascade the way `.complete` does. `own` lists the
+ * step's held items; `ownDrop` lets go of the ones `predicate` matches and
+ * returns how many.
+ * @ignore
+ */
+const holding = <In>(
+  next: Pick<ReducerStep<never>, "held" | "drop">,
+  step: ReducerStep<In>,
+  own: () => unknown[],
+  ownDrop: (predicate: (held: unknown) => boolean) => number,
+): ReducerStep<In> => {
+  step.held = () => [...own(), ...(next.held ? next.held() : [])];
+  step.drop = (predicate) => ownDrop(predicate) + (next.drop ? next.drop(predicate) : 0);
+  return step;
+};
+
+/** Remove, in place, the items of `list` that `predicate` matches; returns how many. */
+const dropFrom = (list: unknown[], predicate: (held: unknown) => boolean): number => {
+  let kept = 0;
+  let dropped = 0;
+  for (const item of list) {
+    if (predicate(item)) dropped++;
+    else list[kept++] = item;
+  }
+  list.length = kept;
+  return dropped;
+};
+
 /**
  * Create a transducer that maps values
  * @kind function
@@ -18,8 +68,7 @@ import { HALT, type ReducerStep, type Transducer } from "./iterator-tools.ts";
 export const map =
   <In, Out>(transform: (item: In) => Out): Transducer<In, Out> =>
   (conjoin) =>
-  (init, item) =>
-    conjoin(init, transform(item));
+    forwardComplete(conjoin, (init, item) => conjoin(init, transform(item)));
 
 /**
  * Create a transducer that filters values
@@ -31,8 +80,7 @@ export const map =
 export const filter =
   <In>(predicate: (item: In) => boolean): Transducer<In, In> =>
   (conjoin) =>
-  (init, item) =>
-    predicate(item) ? conjoin(init, item) : init;
+    forwardComplete(conjoin, (init, item) => (predicate(item) ? conjoin(init, item) : init));
 
 /**
  * Create a transducer that halts after a given number of values
@@ -46,7 +94,7 @@ export const take =
   (conjoin) => {
     let amount = 0;
     // biome-ignore lint/complexity/noCommaOperator: deliberate single-expression step function
-    return (init, item) => (amount < limit ? (amount++, conjoin(init, item)) : HALT);
+    return forwardComplete(conjoin, (init, item) => (amount < limit ? (amount++, conjoin(init, item)) : HALT));
   };
 
 /**
@@ -62,8 +110,11 @@ 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));
+    return forwardComplete(conjoin, (init, item) => {
+      const pass = amount >= limit;
+      amount++;
+      return pass ? conjoin(init, item) : init;
+    });
   };
 
 /**
@@ -79,8 +130,7 @@ export const drop =
 export const reject =
   <In>(predicate: (item: In) => boolean): Transducer<In, In> =>
   (conjoin) =>
-  (init, item) =>
-    predicate(item) ? init : conjoin(init, item);
+    forwardComplete(conjoin, (init, item) => (predicate(item) ? init : conjoin(init, item)));
 
 /**
  * Create a transducer that groups items by quantity before emitting.
@@ -109,7 +159,12 @@ export const group =
       const buffer = out === HALT ? init : out;
       return conjoin.complete ? conjoin.complete(buffer) : buffer;
     };
-    return step;
+    return holding(
+      conjoin,
+      step,
+      () => [...partition],
+      (predicate) => dropFrom(partition, predicate),
+    );
   };
 
 /**
@@ -134,10 +189,22 @@ export const accumulate =
     // 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);
-    };
+    let has = false;
+    return holding(
+      conjoin,
+      forwardComplete(conjoin, (init, item) => {
+        accumulated = func(accumulated, item);
+        has = true;
+        return conjoin(init, accumulated);
+      }),
+      () => (has ? [accumulated] : []),
+      (predicate) => {
+        if (!has || !predicate(accumulated)) return 0;
+        accumulated = initial;
+        has = false;
+        return 1;
+      },
+    );
   };
 
 /**
@@ -156,15 +223,25 @@ export const dedupe =
   (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);
-    };
+    return holding(
+      conjoin,
+      forwardComplete(conjoin, (init, item) => {
+        const key = keyFn(item);
+        if (hasLast && Object.is(key, lastKey)) {
+          return init;
+        }
+        hasLast = true;
+        lastKey = key;
+        return conjoin(init, item);
+      }),
+      () => (hasLast ? [lastKey] : []),
+      (predicate) => {
+        if (!hasLast || !predicate(lastKey)) return 0;
+        hasLast = false;
+        lastKey = undefined;
+        return 1;
+      },
+    );
   };
 
 /**
@@ -179,7 +256,7 @@ export const interpose =
   <In, Sep = In>(separator: Sep): Transducer<In, In | Sep> =>
   (conjoin) => {
     let started = false;
-    return (init, item) => {
+    return forwardComplete(conjoin, (init, item) => {
       if (started) {
         const out = conjoin(init, separator);
         if (out === HALT) {
@@ -189,7 +266,7 @@ export const interpose =
       }
       started = true;
       return conjoin(init, item);
-    };
+    });
   };
 
 /**
@@ -235,7 +312,21 @@ export const partitionBy =
       const buffer = out === HALT ? init : out;
       return conjoin.complete ? conjoin.complete(buffer) : buffer;
     };
-    return step;
+    return holding(
+      conjoin,
+      step,
+      () => (hasCurrent ? [...bucket] : []),
+      (predicate) => {
+        const dropped = dropFrom(bucket, predicate);
+        if (hasCurrent && bucket.length === 0) {
+          // A run with nothing left isn't open: the next item starts a fresh
+          // one, and complete() has no empty run to flush.
+          hasCurrent = false;
+          currentKey = undefined;
+        }
+        return dropped;
+      },
+    );
   };
 
 /**
@@ -250,7 +341,7 @@ export const partitionBy =
 export const tap =
   <In>(fn: (item: In) => unknown): Transducer<In, In> =>
   (conjoin) =>
-  (init, item) => {
-    fn(item);
-    return conjoin(init, item);
-  };
+    forwardComplete(conjoin, (init, item) => {
+      fn(item);
+      return conjoin(init, item);
+    });