es-toolkit 1.51.0-dev.2065 → 1.51.0-dev.2070

package/dist/iterator/scan.js

@@ -0,0 +1,47 @@
+const require_iterator = require("./_internal/iterator.js");
+//#region src/iterator/scan.ts
+/**
+* Lazily yields the running accumulation of `source` under `callback`, like a
+* `reduce` that emits every intermediate result. The `initial` value is emitted
+* first, followed by the accumulator after each element.
+*
+* For an input of length `n`, the output has length `n + 1`. This is the
+* "scan-left" / prefix-scan behavior and has no native iterator-helper
+* equivalent.
+*
+* @template T - The type of elements produced by `source`.
+* @template U - The type of the accumulated value.
+* @param source - The iterator to accumulate over.
+* @param callback - Called with `(accumulator, value, index)`; returns the next accumulator.
+* @param initial - The initial accumulator, emitted as the first value.
+* @returns A lazy iterator over the initial value and each successive accumulator.
+*
+* @example
+* scan([1, 2, 3].values(), (acc, x) => acc + x, 0).toArray(); // => [0, 1, 3, 6]
+*/
+function scan(source, callback, initial) {
+	let accumulator = initial;
+	let index = 0;
+	let emittedInitial = false;
+	return require_iterator.iterator(function() {
+		if (!emittedInitial) {
+			emittedInitial = true;
+			return {
+				value: accumulator,
+				done: false
+			};
+		}
+		const result = source.next();
+		if (result.done) return {
+			value: void 0,
+			done: true
+		};
+		accumulator = callback(accumulator, result.value, index++);
+		return {
+			value: accumulator,
+			done: false
+		};
+	}, () => void source.return?.());
+}
+//#endregion
+exports.scan = scan;

package/dist/iterator/scan.mjs

@@ -0,0 +1,47 @@
+import { iterator } from "./_internal/iterator.mjs";
+//#region src/iterator/scan.ts
+/**
+* Lazily yields the running accumulation of `source` under `callback`, like a
+* `reduce` that emits every intermediate result. The `initial` value is emitted
+* first, followed by the accumulator after each element.
+*
+* For an input of length `n`, the output has length `n + 1`. This is the
+* "scan-left" / prefix-scan behavior and has no native iterator-helper
+* equivalent.
+*
+* @template T - The type of elements produced by `source`.
+* @template U - The type of the accumulated value.
+* @param source - The iterator to accumulate over.
+* @param callback - Called with `(accumulator, value, index)`; returns the next accumulator.
+* @param initial - The initial accumulator, emitted as the first value.
+* @returns A lazy iterator over the initial value and each successive accumulator.
+*
+* @example
+* scan([1, 2, 3].values(), (acc, x) => acc + x, 0).toArray(); // => [0, 1, 3, 6]
+*/
+function scan(source, callback, initial) {
+	let accumulator = initial;
+	let index = 0;
+	let emittedInitial = false;
+	return iterator(function() {
+		if (!emittedInitial) {
+			emittedInitial = true;
+			return {
+				value: accumulator,
+				done: false
+			};
+		}
+		const result = source.next();
+		if (result.done) return {
+			value: void 0,
+			done: true
+		};
+		accumulator = callback(accumulator, result.value, index++);
+		return {
+			value: accumulator,
+			done: false
+		};
+	}, () => void source.return?.());
+}
+//#endregion
+export { scan };

package/dist/iterator/takeWhile.d.mts

@@ -0,0 +1,20 @@
+//#region src/iterator/takeWhile.d.ts
+/**
+ * Lazily yields elements from `source` as long as `shouldContinue` returns a
+ * truthy value, stopping at (and excluding) the first element for which it
+ * returns a falsy value. The remaining elements are never pulled from `source`.
+ *
+ * The native iterator helpers offer `take` (by count) but not a predicate-based
+ * `takeWhile`, which is why this is provided.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to take elements from.
+ * @param shouldContinue - Called with `(value, index)`; iteration stops once it returns falsy.
+ * @returns A lazy iterator over the leading run of matching elements.
+ *
+ * @example
+ * takeWhile([1, 2, 3, 4, 1].values(), x => x < 3).toArray(); // => [1, 2]
+ */
+declare function takeWhile<T>(source: Iterator<T>, shouldContinue: (value: T, index: number) => boolean): IteratorObject<T, undefined>;
+//#endregion
+export { takeWhile };

package/dist/iterator/takeWhile.d.ts

@@ -0,0 +1,20 @@
+//#region src/iterator/takeWhile.d.ts
+/**
+ * Lazily yields elements from `source` as long as `shouldContinue` returns a
+ * truthy value, stopping at (and excluding) the first element for which it
+ * returns a falsy value. The remaining elements are never pulled from `source`.
+ *
+ * The native iterator helpers offer `take` (by count) but not a predicate-based
+ * `takeWhile`, which is why this is provided.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to take elements from.
+ * @param shouldContinue - Called with `(value, index)`; iteration stops once it returns falsy.
+ * @returns A lazy iterator over the leading run of matching elements.
+ *
+ * @example
+ * takeWhile([1, 2, 3, 4, 1].values(), x => x < 3).toArray(); // => [1, 2]
+ */
+declare function takeWhile<T>(source: Iterator<T>, shouldContinue: (value: T, index: number) => boolean): IteratorObject<T, undefined>;
+//#endregion
+export { takeWhile };

package/dist/iterator/takeWhile.js

@@ -0,0 +1,34 @@
+const require_iterator = require("./_internal/iterator.js");
+//#region src/iterator/takeWhile.ts
+/**
+* Lazily yields elements from `source` as long as `shouldContinue` returns a
+* truthy value, stopping at (and excluding) the first element for which it
+* returns a falsy value. The remaining elements are never pulled from `source`.
+*
+* The native iterator helpers offer `take` (by count) but not a predicate-based
+* `takeWhile`, which is why this is provided.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to take elements from.
+* @param shouldContinue - Called with `(value, index)`; iteration stops once it returns falsy.
+* @returns A lazy iterator over the leading run of matching elements.
+*
+* @example
+* takeWhile([1, 2, 3, 4, 1].values(), x => x < 3).toArray(); // => [1, 2]
+*/
+function takeWhile(source, shouldContinue) {
+	let index = 0;
+	return require_iterator.iterator(function() {
+		const result = source.next();
+		if (result.done || !shouldContinue(result.value, index++)) return {
+			value: void 0,
+			done: true
+		};
+		return {
+			value: result.value,
+			done: false
+		};
+	}, () => void source.return?.());
+}
+//#endregion
+exports.takeWhile = takeWhile;

package/dist/iterator/takeWhile.mjs

@@ -0,0 +1,34 @@
+import { iterator } from "./_internal/iterator.mjs";
+//#region src/iterator/takeWhile.ts
+/**
+* Lazily yields elements from `source` as long as `shouldContinue` returns a
+* truthy value, stopping at (and excluding) the first element for which it
+* returns a falsy value. The remaining elements are never pulled from `source`.
+*
+* The native iterator helpers offer `take` (by count) but not a predicate-based
+* `takeWhile`, which is why this is provided.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to take elements from.
+* @param shouldContinue - Called with `(value, index)`; iteration stops once it returns falsy.
+* @returns A lazy iterator over the leading run of matching elements.
+*
+* @example
+* takeWhile([1, 2, 3, 4, 1].values(), x => x < 3).toArray(); // => [1, 2]
+*/
+function takeWhile(source, shouldContinue) {
+	let index = 0;
+	return iterator(function() {
+		const result = source.next();
+		if (result.done || !shouldContinue(result.value, index++)) return {
+			value: void 0,
+			done: true
+		};
+		return {
+			value: result.value,
+			done: false
+		};
+	}, () => void source.return?.());
+}
+//#endregion
+export { takeWhile };

package/dist/iterator/uniqBy.d.mts

@@ -0,0 +1,22 @@
+//#region src/iterator/uniqBy.d.ts
+/**
+ * Lazily yields the elements of `source` whose mapped key has not been seen
+ * before, preserving the order of first occurrence. Keys are compared with
+ * SameValueZero semantics (matching `Set`).
+ *
+ * Deduplication is streaming: each element is emitted as soon as it is found to
+ * be unique, so this works with infinite iterators when bounded by a
+ * short-circuiting helper.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @template K - The type of the key used for comparison.
+ * @param source - The iterator to deduplicate.
+ * @param getKey - Maps an element to the key used to detect duplicates.
+ * @returns A lazy iterator over the elements with duplicate keys removed.
+ *
+ * @example
+ * uniqBy([1.1, 1.2, 2.3, 2.4].values(), Math.floor).toArray(); // => [1.1, 2.3]
+ */
+declare function uniqBy<T, K>(source: Iterator<T>, getKey: (value: T) => K): IteratorObject<T, undefined>;
+//#endregion
+export { uniqBy };

package/dist/iterator/uniqBy.d.ts

@@ -0,0 +1,22 @@
+//#region src/iterator/uniqBy.d.ts
+/**
+ * Lazily yields the elements of `source` whose mapped key has not been seen
+ * before, preserving the order of first occurrence. Keys are compared with
+ * SameValueZero semantics (matching `Set`).
+ *
+ * Deduplication is streaming: each element is emitted as soon as it is found to
+ * be unique, so this works with infinite iterators when bounded by a
+ * short-circuiting helper.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @template K - The type of the key used for comparison.
+ * @param source - The iterator to deduplicate.
+ * @param getKey - Maps an element to the key used to detect duplicates.
+ * @returns A lazy iterator over the elements with duplicate keys removed.
+ *
+ * @example
+ * uniqBy([1.1, 1.2, 2.3, 2.4].values(), Math.floor).toArray(); // => [1.1, 2.3]
+ */
+declare function uniqBy<T, K>(source: Iterator<T>, getKey: (value: T) => K): IteratorObject<T, undefined>;
+//#endregion
+export { uniqBy };

package/dist/iterator/uniqBy.js

@@ -0,0 +1,43 @@
+const require_iterator = require("./_internal/iterator.js");
+//#region src/iterator/uniqBy.ts
+/**
+* Lazily yields the elements of `source` whose mapped key has not been seen
+* before, preserving the order of first occurrence. Keys are compared with
+* SameValueZero semantics (matching `Set`).
+*
+* Deduplication is streaming: each element is emitted as soon as it is found to
+* be unique, so this works with infinite iterators when bounded by a
+* short-circuiting helper.
+*
+* @template T - The type of elements produced by the iterator.
+* @template K - The type of the key used for comparison.
+* @param source - The iterator to deduplicate.
+* @param getKey - Maps an element to the key used to detect duplicates.
+* @returns A lazy iterator over the elements with duplicate keys removed.
+*
+* @example
+* uniqBy([1.1, 1.2, 2.3, 2.4].values(), Math.floor).toArray(); // => [1.1, 2.3]
+*/
+function uniqBy(source, getKey) {
+	const seen = /* @__PURE__ */ new Set();
+	return require_iterator.iterator(function() {
+		let result = source.next();
+		while (!result.done) {
+			const key = getKey(result.value);
+			if (!seen.has(key)) {
+				seen.add(key);
+				return {
+					value: result.value,
+					done: false
+				};
+			}
+			result = source.next();
+		}
+		return {
+			value: void 0,
+			done: true
+		};
+	}, () => void source.return?.());
+}
+//#endregion
+exports.uniqBy = uniqBy;

package/dist/iterator/uniqBy.mjs

@@ -0,0 +1,43 @@
+import { iterator } from "./_internal/iterator.mjs";
+//#region src/iterator/uniqBy.ts
+/**
+* Lazily yields the elements of `source` whose mapped key has not been seen
+* before, preserving the order of first occurrence. Keys are compared with
+* SameValueZero semantics (matching `Set`).
+*
+* Deduplication is streaming: each element is emitted as soon as it is found to
+* be unique, so this works with infinite iterators when bounded by a
+* short-circuiting helper.
+*
+* @template T - The type of elements produced by the iterator.
+* @template K - The type of the key used for comparison.
+* @param source - The iterator to deduplicate.
+* @param getKey - Maps an element to the key used to detect duplicates.
+* @returns A lazy iterator over the elements with duplicate keys removed.
+*
+* @example
+* uniqBy([1.1, 1.2, 2.3, 2.4].values(), Math.floor).toArray(); // => [1.1, 2.3]
+*/
+function uniqBy(source, getKey) {
+	const seen = /* @__PURE__ */ new Set();
+	return iterator(function() {
+		let result = source.next();
+		while (!result.done) {
+			const key = getKey(result.value);
+			if (!seen.has(key)) {
+				seen.add(key);
+				return {
+					value: result.value,
+					done: false
+				};
+			}
+			result = source.next();
+		}
+		return {
+			value: void 0,
+			done: true
+		};
+	}, () => void source.return?.());
+}
+//#endregion
+export { uniqBy };

package/dist/iterator/zip.d.mts

@@ -0,0 +1,23 @@
+//#region src/iterator/zip.d.ts
+type IteratorValue<T> = T extends Iterator<infer V> ? V : never;
+/**
+ * Lazily combines several iterators into a single iterator of tuples, pairing
+ * the elements at matching positions. Iteration stops as soon as the **shortest**
+ * source is exhausted.
+ *
+ * Stopping at the shortest source (rather than padding to the longest, as the
+ * array `zip` does) is what makes this safe to use with infinite iterators:
+ * `zip(range(0, Infinity), names.values())` ends with `names`. When iteration
+ * ends — because a source ran out or the consumer terminated early — every
+ * source is closed via its `return` method.
+ *
+ * @template T - A tuple of the source iterator types.
+ * @param sources - The iterators to zip together.
+ * @returns A lazy iterator over tuples of the paired elements.
+ *
+ * @example
+ * zip([1, 2, 3].values(), ['a', 'b'].values()).toArray(); // => [[1, 'a'], [2, 'b']]
+ */
+declare function zip<T extends Array<Iterator<unknown>>>(...sources: T): IteratorObject<{ [K in keyof T]: IteratorValue<T[K]> }, undefined>;
+//#endregion
+export { zip };

package/dist/iterator/zip.d.ts

@@ -0,0 +1,23 @@
+//#region src/iterator/zip.d.ts
+type IteratorValue<T> = T extends Iterator<infer V> ? V : never;
+/**
+ * Lazily combines several iterators into a single iterator of tuples, pairing
+ * the elements at matching positions. Iteration stops as soon as the **shortest**
+ * source is exhausted.
+ *
+ * Stopping at the shortest source (rather than padding to the longest, as the
+ * array `zip` does) is what makes this safe to use with infinite iterators:
+ * `zip(range(0, Infinity), names.values())` ends with `names`. When iteration
+ * ends — because a source ran out or the consumer terminated early — every
+ * source is closed via its `return` method.
+ *
+ * @template T - A tuple of the source iterator types.
+ * @param sources - The iterators to zip together.
+ * @returns A lazy iterator over tuples of the paired elements.
+ *
+ * @example
+ * zip([1, 2, 3].values(), ['a', 'b'].values()).toArray(); // => [[1, 'a'], [2, 'b']]
+ */
+declare function zip<T extends Array<Iterator<unknown>>>(...sources: T): IteratorObject<{ [K in keyof T]: IteratorValue<T[K]> }, undefined>;
+//#endregion
+export { zip };

package/dist/iterator/zip.js

@@ -0,0 +1,45 @@
+const require_iterator = require("./_internal/iterator.js");
+//#region src/iterator/zip.ts
+/**
+* Lazily combines several iterators into a single iterator of tuples, pairing
+* the elements at matching positions. Iteration stops as soon as the **shortest**
+* source is exhausted.
+*
+* Stopping at the shortest source (rather than padding to the longest, as the
+* array `zip` does) is what makes this safe to use with infinite iterators:
+* `zip(range(0, Infinity), names.values())` ends with `names`. When iteration
+* ends — because a source ran out or the consumer terminated early — every
+* source is closed via its `return` method.
+*
+* @template T - A tuple of the source iterator types.
+* @param sources - The iterators to zip together.
+* @returns A lazy iterator over tuples of the paired elements.
+*
+* @example
+* zip([1, 2, 3].values(), ['a', 'b'].values()).toArray(); // => [[1, 'a'], [2, 'b']]
+*/
+function zip(...sources) {
+	return require_iterator.iterator(function() {
+		if (sources.length === 0) return {
+			value: void 0,
+			done: true
+		};
+		const tuple = new Array(sources.length);
+		for (let index = 0; index < sources.length; index++) {
+			const result = sources[index].next();
+			if (result.done) return {
+				value: void 0,
+				done: true
+			};
+			tuple[index] = result.value;
+		}
+		return {
+			value: tuple,
+			done: false
+		};
+	}, () => {
+		for (const source of sources) source.return?.();
+	});
+}
+//#endregion
+exports.zip = zip;

package/dist/iterator/zip.mjs

@@ -0,0 +1,45 @@
+import { iterator } from "./_internal/iterator.mjs";
+//#region src/iterator/zip.ts
+/**
+* Lazily combines several iterators into a single iterator of tuples, pairing
+* the elements at matching positions. Iteration stops as soon as the **shortest**
+* source is exhausted.
+*
+* Stopping at the shortest source (rather than padding to the longest, as the
+* array `zip` does) is what makes this safe to use with infinite iterators:
+* `zip(range(0, Infinity), names.values())` ends with `names`. When iteration
+* ends — because a source ran out or the consumer terminated early — every
+* source is closed via its `return` method.
+*
+* @template T - A tuple of the source iterator types.
+* @param sources - The iterators to zip together.
+* @returns A lazy iterator over tuples of the paired elements.
+*
+* @example
+* zip([1, 2, 3].values(), ['a', 'b'].values()).toArray(); // => [[1, 'a'], [2, 'b']]
+*/
+function zip(...sources) {
+	return iterator(function() {
+		if (sources.length === 0) return {
+			value: void 0,
+			done: true
+		};
+		const tuple = new Array(sources.length);
+		for (let index = 0; index < sources.length; index++) {
+			const result = sources[index].next();
+			if (result.done) return {
+				value: void 0,
+				done: true
+			};
+			tuple[index] = result.value;
+		}
+		return {
+			value: tuple,
+			done: false
+		};
+	}, () => {
+		for (const source of sources) source.return?.();
+	});
+}
+//#endregion
+export { zip };

package/fp/iterator.d.ts

@@ -0,0 +1 @@
+export * from '../dist/fp/iterator';

package/fp/iterator.js

@@ -0,0 +1 @@
+module.exports = require('../dist/fp/iterator');

package/iterator.d.ts

@@ -0,0 +1 @@
+export * from './dist/iterator';

package/iterator.js

@@ -0,0 +1 @@
+module.exports = require('./dist/iterator');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-toolkit",
-  "version": "1.51.0-dev.2065+5dc4477f",
+  "version": "1.51.0-dev.2070+912e8324",
   "description": "A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.",
   "homepage": "https://es-toolkit.dev",
   "bugs": "https://github.com/toss/es-toolkit/issues",
@@ -94,6 +94,16 @@
         "default": "./dist/fp/index.js"
       }
     },
+    "./fp/iterator": {
+      "import": {
+        "types": "./dist/fp/iterator/index.d.mts",
+        "default": "./dist/fp/iterator/index.mjs"
+      },
+      "require": {
+        "types": "./dist/fp/iterator/index.d.ts",
+        "default": "./dist/fp/iterator/index.js"
+      }
+    },
     "./function": {
       "import": {
         "types": "./dist/function/index.d.mts",
@@ -104,6 +114,16 @@
         "default": "./dist/function/index.js"
       }
     },
+    "./iterator": {
+      "import": {
+        "types": "./dist/iterator/index.d.mts",
+        "default": "./dist/iterator/index.mjs"
+      },
+      "require": {
+        "types": "./dist/iterator/index.d.ts",
+        "default": "./dist/iterator/index.js"
+      }
+    },
     "./map": {
       "import": {
         "types": "./dist/map/index.d.mts",
@@ -204,7 +224,10 @@
     "compat.js",
     "error.js",
     "fp.js",
+    "fp/iterator.js",
+    "fp/iterator.d.ts",
     "function.js",
+    "iterator.js",
     "map.js",
     "math.js",
     "object.js",
@@ -358,6 +381,16 @@
           "default": "./dist/fp/index.js"
         }
       },
+      "./fp/iterator": {
+        "import": {
+          "types": "./dist/fp/iterator/index.d.mts",
+          "default": "./dist/fp/iterator/index.mjs"
+        },
+        "require": {
+          "types": "./dist/fp/iterator/index.d.ts",
+          "default": "./dist/fp/iterator/index.js"
+        }
+      },
       "./function": {
         "import": {
           "types": "./dist/function/index.d.mts",
@@ -368,6 +401,16 @@
           "default": "./dist/function/index.js"
         }
       },
+      "./iterator": {
+        "import": {
+          "types": "./dist/iterator/index.d.mts",
+          "default": "./dist/iterator/index.mjs"
+        },
+        "require": {
+          "types": "./dist/iterator/index.d.ts",
+          "default": "./dist/iterator/index.js"
+        }
+      },
       "./map": {
         "import": {
           "types": "./dist/map/index.d.mts",