@effectionx/stream-helpers 0.7.1 → 0.7.3

package/last.test.ts

@@ -0,0 +1,65 @@
+import { describe, it } from "@effectionx/bdd";
+import { expect } from "expect";
+
+import { last } from "./last.ts";
+import { streamOf } from "./stream-of.ts";
+
+describe("last", () => {
+  it("should return the last value from the stream", function* () {
+    const stream = streamOf([1, 2, 3]);
+    const value = yield* last(stream);
+    expect(value).toBe(3);
+  });
+
+  it("should return the only value when stream has one item", function* () {
+    const stream = streamOf([42]);
+    const value = yield* last(stream);
+    expect(value).toBe(42);
+  });
+
+  it("should return undefined if stream closes without yielding any values", function* () {
+    const stream = streamOf([]);
+    const value = yield* last(stream);
+    expect(value).toBe(undefined);
+  });
+
+  it("should work with undefined as a valid value", function* () {
+    const stream = streamOf([1, 2, undefined]);
+    const value = yield* last(stream);
+    expect(value).toBe(undefined);
+  });
+
+  describe("expect", () => {
+    it("should return the last value from the stream", function* () {
+      const stream = streamOf([1, 2, 3]);
+      const value = yield* last.expect(stream);
+      expect(value).toBe(3);
+    });
+
+    it("should return the only value when stream has one item", function* () {
+      const stream = streamOf([42]);
+      const value = yield* last.expect(stream);
+      expect(value).toBe(42);
+    });
+
+    it("should throw if stream closes without yielding any values", function* () {
+      const stream = streamOf([]);
+
+      let error: Error | undefined;
+      try {
+        yield* last.expect(stream);
+      } catch (e) {
+        error = e as Error;
+      }
+
+      expect(error).toBeDefined();
+      expect(error?.message).toBe("Stream closed without yielding any values");
+    });
+
+    it("should work with undefined as a valid value", function* () {
+      const stream = streamOf([1, 2, undefined]);
+      const value = yield* last.expect(stream);
+      expect(value).toBe(undefined);
+    });
+  });
+});

package/last.ts

@@ -0,0 +1,96 @@
+import type { Operation, Stream } from "effection";
+
+/**
+ * Returns the last value yielded by a stream, or `undefined` if the stream
+ * closes without yielding any values.
+ *
+ * Exhausts the entire stream to find the last value.
+ * Use `last.expect()` if you want to throw an error when the stream is empty.
+ *
+ * @template T - The type of items in the stream
+ * @template TClose - The type of the close value (unused)
+ * @param stream - The stream to get the last value from
+ * @returns The last value yielded by the stream, or `undefined` if empty
+ *
+ * @example
+ * ```typescript
+ * import { last } from "./last.ts";
+ *
+ * const stream = streamOf([1, 2, 3]);
+ * const value = yield* last(stream); // returns 3
+ *
+ * const empty = streamOf([]);
+ * const value = yield* last(empty); // returns undefined
+ * ```
+ */
+export function last<T, TClose>(
+  stream: Stream<T, TClose>,
+): Operation<T | undefined> {
+  return {
+    *[Symbol.iterator]() {
+      const subscription = yield* stream;
+      const first = yield* subscription.next();
+
+      if (first.done) {
+        return undefined;
+      }
+
+      let lastValue: T = first.value;
+      let result = yield* subscription.next();
+
+      while (!result.done) {
+        lastValue = result.value;
+        result = yield* subscription.next();
+      }
+
+      return lastValue;
+    },
+  };
+}
+
+/**
+ * Returns the last value yielded by a stream.
+ * Exhausts the entire stream to find the last value.
+ * Throws an error if the stream closes without yielding any values.
+ *
+ * @template T - The type of items in the stream
+ * @template TClose - The type of the close value (unused)
+ * @param stream - The stream to get the last value from
+ * @returns The last value yielded by the stream
+ * @throws Error if the stream closes without yielding any values
+ *
+ * @example
+ * ```typescript
+ * import { last } from "./last.ts";
+ *
+ * const stream = streamOf([1, 2, 3]);
+ * const value = yield* last.expect(stream); // returns 3
+ *
+ * const empty = streamOf([]);
+ * const value = yield* last.expect(empty); // throws Error
+ * ```
+ */
+last.expect = function expectLast<T, TClose>(
+  stream: Stream<T, TClose>,
+): Operation<T> {
+  return {
+    *[Symbol.iterator]() {
+      const subscription = yield* stream;
+      const first = yield* subscription.next();
+
+      if (first.done) {
+        throw new Error("Stream closed without yielding any values");
+      }
+
+      let lastValue: T = first.value;
+      let result = yield* subscription.next();
+
+      while (!result.done) {
+        lastValue = result.value;
+        result = yield* subscription.next();
+      }
+
+      return lastValue;
+    },
+  };
+};

package/mod.ts

@@ -8,3 +8,9 @@ export * from "./subject.ts";
 export * from "./lines.ts";
 export * from "./stream-of.ts";
 export * from "./reduce.ts";
+export * from "./drain.ts";
+export * from "./first.ts";
+export * from "./last.ts";
+export * from "./take.ts";
+export * from "./take-while.ts";
+export * from "./take-until.ts";

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@effectionx/stream-helpers",
-  "version": "0.7.1",
+  "description": "Type-safe stream operators like filter, map, reduce, and forEach",
+  "version": "0.7.3",
   "type": "module",
   "main": "./dist/mod.js",
   "types": "./dist/mod.d.ts",
@@ -20,8 +21,8 @@
   "dependencies": {
     "immutable": "^5",
     "remeda": "^2",
-    "@effectionx/signals": "0.5.0",
-    "@effectionx/timebox": "0.4.0"
+    "@effectionx/signals": "0.5.1",
+    "@effectionx/timebox": "0.4.1"
   },
   "license": "MIT",
   "author": "engineering@frontside.com",
@@ -37,6 +38,6 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@effectionx/bdd": "0.4.1"
+    "@effectionx/bdd": "0.4.2"
   }
 }

package/subject.ts

@@ -48,7 +48,6 @@ export function createSubject<T>(): <TClose>(
         ? {
             *next() {
               iterator = upstream;
-              // biome-ignore lint/style/noNonNullAssertion: current checked in ternary condition
               return current!;
             },
           }

package/take-until.test.ts

@@ -0,0 +1,113 @@
+import { describe, it } from "@effectionx/bdd";
+import { expect } from "expect";
+import { pipe } from "remeda";
+
+import { forEach } from "./for-each.ts";
+import { streamOf } from "./stream-of.ts";
+import { takeUntil } from "./take-until.ts";
+
+describe("takeUntil", () => {
+  it("should yield values until predicate is true, then close with matching value", function* () {
+    const values: { status: string }[] = [];
+
+    const closeValue = yield* forEach(
+      function* (value) {
+        values.push(value);
+      },
+      takeUntil((x: { status: string }) => x.status === "valid")(
+        streamOf([
+          { status: "pending" },
+          { status: "checking" },
+          { status: "valid" },
+          { status: "extra" },
+        ]),
+      ),
+    );
+
+    expect(values).toEqual([{ status: "pending" }, { status: "checking" }]);
+    expect(closeValue).toEqual({ status: "valid" });
+  });
+
+  it("should return source close value if stream ends before predicate matches", function* () {
+    const values: { status: string }[] = [];
+
+    const stream = streamOf(
+      (function* () {
+        yield { status: "pending" };
+        yield { status: "checking" };
+        return "no-match";
+      })(),
+    );
+
+    const closeValue = yield* forEach(
+      function* (value) {
+        values.push(value);
+      },
+      takeUntil((x: { status: string }) => x.status === "valid")(stream),
+    );
+
+    expect(values).toEqual([{ status: "pending" }, { status: "checking" }]);
+    expect(closeValue).toBe("no-match");
+  });
+
+  it("should close immediately with first value if it matches predicate", function* () {
+    const values: { status: string }[] = [];
+
+    const closeValue = yield* forEach(
+      function* (value) {
+        values.push(value);
+      },
+      takeUntil((x: { status: string }) => x.status === "valid")(
+        streamOf([{ status: "valid" }, { status: "extra" }]),
+      ),
+    );
+
+    expect(values).toEqual([]);
+    expect(closeValue).toEqual({ status: "valid" });
+  });
+
+  it("should work with validation progress pattern", function* () {
+    type ValidationProgress =
+      | { status: "validating" }
+      | { status: "checking-inventory" }
+      | { status: "valid"; data: string }
+      | { status: "invalid"; errors: string[] };
+
+    const progressStatuses: string[] = [];
+
+    const result = yield* forEach(
+      function* (progress) {
+        progressStatuses.push(progress.status);
+      },
+      takeUntil(
+        (p: ValidationProgress) =>
+          p.status === "valid" || p.status === "invalid",
+      )(
+        streamOf<ValidationProgress, void>([
+          { status: "validating" },
+          { status: "checking-inventory" },
+          { status: "valid", data: "ok" },
+        ]),
+      ),
+    );
+
+    expect(progressStatuses).toEqual(["validating", "checking-inventory"]);
+    expect(result).toEqual({ status: "valid", data: "ok" });
+  });
+
+  it("should work with pipe", function* () {
+    const values: number[] = [];
+
+    const stream = pipe(
+      streamOf([1, 2, 3, 4, 5]),
+      takeUntil((x) => x === 4),
+    );
+
+    const closeValue = yield* forEach(function* (value) {
+      values.push(value);
+    }, stream);
+
+    expect(values).toEqual([1, 2, 3]);
+    expect(closeValue).toBe(4);
+  });
+});

package/take-until.ts

@@ -0,0 +1,76 @@
+import type { Stream } from "effection";
+
+/**
+ * Creates a stream transformer that yields values from the source stream
+ * until the predicate returns true. Closes with the matching value when
+ * the predicate returns true.
+ *
+ * This is useful for "iterate until a condition is met" patterns, where
+ * the matching value is meaningful (e.g., a terminal status).
+ *
+ * If the source stream closes before the predicate returns true, the
+ * resulting stream closes with the source's close value.
+ *
+ * @template T - The type of items in the stream
+ * @template TClose - The type of the close value
+ * @param predicate - A function that returns true to stop taking values
+ * @returns A stream transformer that yields values until predicate is true,
+ *          closing with the matching value
+ *
+ * @example
+ * ```typescript
+ * import { takeUntil, forEach } from "@effectionx/stream-helpers";
+ *
+ * // Iterate validation progress until we get a terminal status
+ * const result = yield* forEach(function*(progress) {
+ *   showSpinner(progress.status);
+ * }, takeUntil((p) => p.status === "valid" || p.status === "invalid")(channel));
+ *
+ * // result is the validation object with terminal status
+ * if (result.status === "valid") {
+ *   // proceed
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { takeUntil, map } from "@effectionx/stream-helpers";
+ * import { pipe } from "remeda";
+ *
+ * const limited = pipe(
+ *   source,
+ *   takeUntil((x) => x.done),
+ * );
+ * ```
+ */
+export function takeUntil<T>(
+  predicate: (item: T) => boolean,
+): <TClose>(stream: Stream<T, TClose>) => Stream<T, T | TClose> {
+  return <TClose>(stream: Stream<T, TClose>): Stream<T, T | TClose> => ({
+    *[Symbol.iterator]() {
+      const subscription = yield* stream;
+      let done = false;
+
+      return {
+        *next() {
+          if (done) {
+            return { done: true, value: undefined as unknown as T | TClose };
+          }
+
+          const result = yield* subscription.next();
+          if (result.done) {
+            return result;
+          }
+
+          if (predicate(result.value)) {
+            done = true;
+            // Close with the matching value
+            return { done: true, value: result.value };
+          }
+
+          return result;
+        },
+      };
+    },
+  });
+}

package/take-while.test.ts

@@ -0,0 +1,89 @@
+import { describe, it } from "@effectionx/bdd";
+import { expect } from "expect";
+import { pipe } from "remeda";
+
+import { forEach } from "./for-each.ts";
+import { streamOf } from "./stream-of.ts";
+import { takeWhile } from "./take-while.ts";
+
+describe("takeWhile", () => {
+  it("should yield values while predicate is true", function* () {
+    const values: number[] = [];
+
+    const closeValue = yield* forEach(
+      function* (value) {
+        values.push(value);
+      },
+      takeWhile((x: number) => x < 3)(streamOf([1, 2, 3, 4, 5])),
+    );
+
+    expect(values).toEqual([1, 2]);
+    expect(closeValue).toBe(undefined);
+  });
+
+  it("should return source close value if stream ends before predicate fails", function* () {
+    const values: number[] = [];
+
+    const stream = streamOf(
+      (function* () {
+        yield 1;
+        yield 2;
+        return "early-close";
+      })(),
+    );
+
+    const closeValue = yield* forEach(
+      function* (value) {
+        values.push(value);
+      },
+      takeWhile((x: number) => x < 10)(stream),
+    );
+
+    expect(values).toEqual([1, 2]);
+    expect(closeValue).toBe("early-close");
+  });
+
+  it("should not include the failing value", function* () {
+    const values: number[] = [];
+
+    const closeValue = yield* forEach(
+      function* (value) {
+        values.push(value);
+      },
+      takeWhile((x: number) => x < 50)(streamOf([1, 2, 100, 3])),
+    );
+
+    expect(values).toEqual([1, 2]);
+    expect(closeValue).toBe(undefined);
+  });
+
+  it("should stop immediately if first value fails predicate", function* () {
+    const values: number[] = [];
+
+    const closeValue = yield* forEach(
+      function* (value) {
+        values.push(value);
+      },
+      takeWhile((x: number) => x < 50)(streamOf([100, 1, 2])),
+    );
+
+    expect(values).toEqual([]);
+    expect(closeValue).toBe(undefined);
+  });
+
+  it("should work with pipe", function* () {
+    const values: number[] = [];
+
+    const stream = pipe(
+      streamOf([1, 2, 3, 4, 5]),
+      takeWhile((x) => x < 4),
+    );
+
+    const closeValue = yield* forEach(function* (value) {
+      values.push(value);
+    }, stream);
+
+    expect(values).toEqual([1, 2, 3]);
+    expect(closeValue).toBe(undefined);
+  });
+});

package/take-while.ts

@@ -0,0 +1,74 @@
+import type { Stream } from "effection";
+
+/**
+ * Creates a stream transformer that yields values from the source stream
+ * while the predicate returns true. Closes when the predicate returns false,
+ * without including the failing value.
+ *
+ * When the predicate fails, the stream closes immediately without the failing
+ * value. The close value will be `undefined` since we don't have access to
+ * the source's close value without draining the entire stream.
+ *
+ * If the source stream closes before the predicate returns false, the
+ * resulting stream closes with the source's close value.
+ *
+ * @template T - The type of items in the stream
+ * @template TClose - The type of the close value
+ * @param predicate - A function that returns true to continue taking values
+ * @returns A stream transformer that yields values while predicate is true
+ *
+ * @example
+ * ```typescript
+ * import { takeWhile, streamOf } from "@effectionx/stream-helpers";
+ *
+ * const stream = streamOf([1, 2, 3, 4, 5]);
+ * // yields 1, 2 (stops when value >= 3)
+ * const limited = takeWhile((x: number) => x < 3)(stream);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { takeWhile, map } from "@effectionx/stream-helpers";
+ * import { pipe } from "remeda";
+ *
+ * const limited = pipe(
+ *   source,
+ *   map(function* (x) { return x * 2; }),
+ *   takeWhile((x) => x < 100),
+ * );
+ * ```
+ */
+export function takeWhile<T>(
+  predicate: (item: T) => boolean,
+): <TClose>(stream: Stream<T, TClose>) => Stream<T, TClose | undefined> {
+  return <TClose>(
+    stream: Stream<T, TClose>,
+  ): Stream<T, TClose | undefined> => ({
+    *[Symbol.iterator]() {
+      const subscription = yield* stream;
+      let done = false;
+
+      return {
+        *next() {
+          if (done) {
+            return { done: true, value: undefined as TClose | undefined };
+          }
+
+          const result = yield* subscription.next();
+          if (result.done) {
+            return result;
+          }
+
+          if (!predicate(result.value)) {
+            done = true;
+            // Close immediately without the failing value
+            // We return undefined as we don't drain the stream
+            return { done: true, value: undefined as TClose | undefined };
+          }
+
+          return result;
+        },
+      };
+    },
+  });
+}

package/take.test.ts

@@ -0,0 +1,83 @@
+import { describe, it } from "@effectionx/bdd";
+import { expect } from "expect";
+import { pipe } from "remeda";
+
+import { forEach } from "./for-each.ts";
+import { streamOf } from "./stream-of.ts";
+import { take } from "./take.ts";
+
+describe("take", () => {
+  it("should take first n values and close with the nth value", function* () {
+    const values: number[] = [];
+
+    const closeValue = yield* forEach(
+      function* (value) {
+        values.push(value);
+      },
+      take<number>(3)(streamOf([1, 2, 3, 4, 5])),
+    );
+
+    expect(values).toEqual([1, 2]);
+    expect(closeValue).toBe(3);
+  });
+
+  it("should return source close value if stream ends before n values", function* () {
+    const values: number[] = [];
+
+    const stream = streamOf(
+      (function* () {
+        yield 1;
+        yield 2;
+        return "early-close";
+      })(),
+    );
+
+    const closeValue = yield* forEach(function* (value) {
+      values.push(value);
+    }, take<number>(5)(stream));
+
+    expect(values).toEqual([1, 2]);
+    expect(closeValue).toBe("early-close");
+  });
+
+  it("should work with n=1", function* () {
+    const values: number[] = [];
+
+    const closeValue = yield* forEach(
+      function* (value) {
+        values.push(value);
+      },
+      take<number>(1)(streamOf([42, 100])),
+    );
+
+    expect(values).toEqual([]);
+    expect(closeValue).toBe(42);
+  });
+
+  it("should work with n=0", function* () {
+    const values: number[] = [];
+
+    const closeValue = yield* forEach(
+      function* (value) {
+        values.push(value);
+      },
+      take<number>(0)(streamOf([1, 2, 3])),
+    );
+
+    expect(values).toEqual([]);
+    expect(closeValue).toBe(undefined);
+  });
+
+  it("should work with pipe", function* () {
+    const values: number[] = [];
+
+    const stream = pipe(streamOf([1, 2, 3, 4, 5]), take(2));
+
+    const closeValue = yield* forEach(function* (value) {
+      values.push(value);
+    }, stream);
+
+    expect(values).toEqual([1]);
+    expect(closeValue).toBe(2);
+  });
+});