@effectionx/stream-helpers 0.7.2 → 0.7.3

package/README.md

@@ -231,6 +231,89 @@ function* example() {
 }
 ```
 
+### Take
+
+The `take` helper creates a stream transformer that yields the first `n` values
+from the source stream, then closes with the last taken value.
+
+```typescript
+import { take, forEach, streamOf } from "@effectionx/stream-helpers";
+import { pipe } from "remeda";
+
+function* example() {
+  const stream = streamOf([1, 2, 3, 4, 5]);
+  // yields 1, 2, then closes with 3
+  const closeValue = yield* forEach(function* (value) {
+    console.log(value); // 1, then 2
+  }, take(3)(stream));
+  console.log(closeValue); // 3
+}
+
+// Works with pipe
+const limited = pipe(source, take(3));
+```
+
+### TakeWhile
+
+The `takeWhile` helper creates a stream transformer that yields values while
+the predicate returns true. When the predicate returns false, the stream closes
+immediately (the failing value is not included).
+
+```typescript
+import { takeWhile, forEach, streamOf } from "@effectionx/stream-helpers";
+import { pipe } from "remeda";
+
+function* example() {
+  const stream = streamOf([1, 2, 3, 4, 5]);
+  // yields 1, 2 (stops when value >= 3)
+  yield* forEach(function* (value) {
+    console.log(value); // 1, then 2
+  }, takeWhile((x) => x < 3)(stream));
+}
+
+// Works with pipe
+const filtered = pipe(source, takeWhile((x) => x.isValid));
+```
+
+### TakeUntil
+
+The `takeUntil` helper creates a stream transformer that yields values until
+the predicate returns true. When the predicate matches, the stream closes with
+the matching value. This is useful for "iterate until a condition is met"
+patterns.
+
+```typescript
+import { takeUntil, forEach } from "@effectionx/stream-helpers";
+import { pipe } from "remeda";
+
+function* example() {
+  // 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")(
+      validationStream,
+    ),
+  );
+
+  // result is the validation object with terminal status
+  if (result.status === "valid") {
+    console.log("Validation passed!");
+  }
+}
+
+// Works with pipe
+const untilDone = pipe(source, takeUntil((x) => x.done));
+```
+
+**Key difference between `takeWhile` and `takeUntil`:**
+
+| Helper      | Yields                  | Closes With    | Use Case                |
+| ----------- | ----------------------- | -------------- | ----------------------- |
+| `takeWhile` | While predicate is true | `undefined`    | "Keep going while good" |
+| `takeUntil` | Until predicate is true | Matching value | "Stop when you find it" |
+
 ### ForEach
 
 The `forEach` helper invokes a function for each item passing through a stream.

package/batch.ts

@@ -41,7 +41,6 @@ export function batch(
             value: undefined as never,
           };
           if (lastPull && options.maxTime) {
-            // biome-ignore lint/style/noNonNullAssertion: lastPull checked above
             const timeout = yield* timebox(options.maxTime, () => lastPull!);
             if (timeout.timeout) {
               yield* lastPull.halt();

package/dist/batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../batch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAoB,MAAM,WAAW,CAAC;AAE1D,KAAK,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,CAC9D,CAAC,EACD,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CACvB,GACC;KACG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,IAAI,CAAC,CAAC;AAEV,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CACnB,OAAO,EAAE,iBAAiB,CAAC,YAAY,CAAC,GACvC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CA8E/D"}
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../batch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAoB,MAAM,WAAW,CAAC;AAE1D,KAAK,iBAAiB,CAAC,CAAC,EAAE,IAAI,SAAS,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,IAAI,CAC9D,CAAC,EACD,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CACvB,GACC;KACG,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;CACzE,CAAC,IAAI,CAAC,CAAC;AAEV,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CACnB,OAAO,EAAE,iBAAiB,CAAC,YAAY,CAAC,GACvC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CA6E/D"}

package/dist/batch.js

@@ -24,7 +24,6 @@ export function batch(options) {
                         value: undefined,
                     };
                     if (lastPull && options.maxTime) {
-                        // biome-ignore lint/style/noNonNullAssertion: lastPull checked above
                         const timeout = yield* timebox(options.maxTime, () => lastPull);
                         if (timeout.timeout) {
                             yield* lastPull.halt();

package/dist/mod.d.ts

@@ -11,4 +11,7 @@ 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";
 //# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../mod.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../mod.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/mod.js

@@ -11,3 +11,6 @@ export * from "./reduce.js";
 export * from "./drain.js";
 export * from "./first.js";
 export * from "./last.js";
+export * from "./take.js";
+export * from "./take-while.js";
+export * from "./take-until.js";

package/dist/subject.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../subject.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,WAAW,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAAC,CAAC,KAAK,CAAC,MAAM,EACzC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,KACtB,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CA2BrB"}
+{"version":3,"file":"subject.d.ts","sourceRoot":"","sources":["../subject.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAgB,MAAM,WAAW,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,aAAa,CAAC,CAAC,KAAK,CAAC,MAAM,EACzC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,KACtB,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CA0BrB"}

package/dist/subject.js

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

package/dist/take-until.d.ts

@@ -0,0 +1,46 @@
+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 declare function takeUntil<T>(predicate: (item: T) => boolean): <TClose>(stream: Stream<T, TClose>) => Stream<T, T | TClose>;
+//# sourceMappingURL=take-until.d.ts.map

package/dist/take-until.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"take-until.d.ts","sourceRoot":"","sources":["../take-until.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAC9B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CA4B9D"}

package/dist/take-until.js

@@ -0,0 +1,68 @@
+/**
+ * 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(predicate) {
+    return (stream) => ({
+        *[Symbol.iterator]() {
+            const subscription = yield* stream;
+            let done = false;
+            return {
+                *next() {
+                    if (done) {
+                        return { done: true, value: undefined };
+                    }
+                    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/dist/take-while.d.ts

@@ -0,0 +1,41 @@
+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 declare function takeWhile<T>(predicate: (item: T) => boolean): <TClose>(stream: Stream<T, TClose>) => Stream<T, TClose | undefined>;
+//# sourceMappingURL=take-while.d.ts.map

package/dist/take-while.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"take-while.d.ts","sourceRoot":"","sources":["../take-while.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAC9B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,CA+BtE"}

package/dist/take-while.js

@@ -0,0 +1,64 @@
+/**
+ * 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(predicate) {
+    return (stream) => ({
+        *[Symbol.iterator]() {
+            const subscription = yield* stream;
+            let done = false;
+            return {
+                *next() {
+                    if (done) {
+                        return { done: true, value: 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 };
+                    }
+                    return result;
+                },
+            };
+        },
+    });
+}

package/dist/take.d.ts

@@ -0,0 +1,36 @@
+import type { Stream } from "effection";
+/**
+ * Creates a stream transformer that yields the first `n` values from the
+ * source stream, then closes with the last taken value.
+ *
+ * If the source stream closes before yielding `n` values, 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 n - The number of values to take
+ * @returns A stream transformer that yields at most `n` values
+ *
+ * @example
+ * ```typescript
+ * import { take, streamOf } from "@effectionx/stream-helpers";
+ *
+ * const stream = streamOf([1, 2, 3, 4, 5]);
+ * // yields 1, 2, then closes with 3
+ * const limited = take(3)(stream);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { take, map } from "@effectionx/stream-helpers";
+ * import { pipe } from "remeda";
+ *
+ * const limited = pipe(
+ *   source,
+ *   map(function* (x) { return x * 2; }),
+ *   take(5),
+ * );
+ * ```
+ */
+export declare function take<T>(n: number): <TClose>(stream: Stream<T, TClose>) => Stream<T, T | TClose>;
+//# sourceMappingURL=take.d.ts.map

package/dist/take.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"take.d.ts","sourceRoot":"","sources":["../take.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,CAAC,EAAE,MAAM,GACR,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CA6B9D"}

package/dist/take.js

@@ -0,0 +1,59 @@
+/**
+ * Creates a stream transformer that yields the first `n` values from the
+ * source stream, then closes with the last taken value.
+ *
+ * If the source stream closes before yielding `n` values, 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 n - The number of values to take
+ * @returns A stream transformer that yields at most `n` values
+ *
+ * @example
+ * ```typescript
+ * import { take, streamOf } from "@effectionx/stream-helpers";
+ *
+ * const stream = streamOf([1, 2, 3, 4, 5]);
+ * // yields 1, 2, then closes with 3
+ * const limited = take(3)(stream);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { take, map } from "@effectionx/stream-helpers";
+ * import { pipe } from "remeda";
+ *
+ * const limited = pipe(
+ *   source,
+ *   map(function* (x) { return x * 2; }),
+ *   take(5),
+ * );
+ * ```
+ */
+export function take(n) {
+    return (stream) => ({
+        *[Symbol.iterator]() {
+            const subscription = yield* stream;
+            let count = 0;
+            return {
+                *next() {
+                    if (count >= n) {
+                        // Should not happen if used correctly, but handle gracefully
+                        return { done: true, value: undefined };
+                    }
+                    const result = yield* subscription.next();
+                    if (result.done) {
+                        return result;
+                    }
+                    count++;
+                    if (count >= n) {
+                        // This is the nth value, return it and mark as done
+                        return { done: true, value: result.value };
+                    }
+                    return result;
+                },
+            };
+        },
+    });
+}