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

package/dist/iterator/_internal/iterator.mjs

@@ -0,0 +1,74 @@
+//#region src/iterator/_internal/iterator.ts
+/**
+* Wraps a `next` function into a lazy {@link IteratorObject} whose prototype is
+* the native `Iterator.prototype`. The result therefore behaves exactly like a
+* value returned by a built-in iterator helper (e.g. `array.values().map(...)`):
+* it is single-shot, it is iterable via `Symbol.iterator` (returning itself),
+* and it carries every native helper method (`map`, `filter`, `take`, `drop`,
+* `flatMap`, `reduce`, `toArray`, ...) so results can be chained with them.
+*
+* The result also follows the IteratorClose protocol of the native helpers, so
+* upstream resources (e.g. `try/finally` blocks in generator sources) are
+* released. `onClose` runs exactly once, at whichever of these happens first:
+* the consumer terminates early (`return()`, e.g. from `take` or a `for...of`
+* `break`), `next` throws, or `next` reports done. After the iterator is
+* closed, `next` is never called again and every subsequent step is done.
+*
+* Using a hand-rolled `next` rather than a generator function is a deliberate
+* performance choice — driving the iterator protocol directly measured roughly
+* twice as fast as `yield`-based generators for the same transforms, while
+* `Object.create(Iterator.prototype)` adds no measurable overhead over a plain
+* object literal.
+*
+* @template T - The type of values produced by the iterator.
+* @param next - Called to produce each step; return `{ done: true, value: undefined }` to finish.
+* @param onClose - Called once when the iterator closes; use it to close upstream iterators.
+* @returns A lazy {@link IteratorObject} that yields the values produced by `next`.
+*
+* @example
+* function repeat<T>(value: T, times: number): IteratorObject<T, undefined> {
+*   let remaining = times;
+*   return iterator(function () {
+*     if (remaining <= 0) {
+*       return { value: undefined, done: true };
+*     }
+*     remaining--;
+*     return { value, done: false };
+*   });
+* }
+*/
+function iterator(next, onClose) {
+	let closed = false;
+	const close = () => {
+		if (!closed) {
+			closed = true;
+			onClose?.();
+		}
+	};
+	const result = Object.create(Iterator.prototype);
+	result.next = function() {
+		if (closed) return {
+			value: void 0,
+			done: true
+		};
+		let step;
+		try {
+			step = next();
+		} catch (error) {
+			close();
+			throw error;
+		}
+		if (step.done) close();
+		return step;
+	};
+	result.return = function() {
+		close();
+		return {
+			value: void 0,
+			done: true
+		};
+	};
+	return result;
+}
+//#endregion
+export { iterator };

package/dist/iterator/cartesianProduct.d.mts

@@ -0,0 +1,33 @@
+//#region src/iterator/cartesianProduct.d.ts
+type IteratorValue<T> = T extends Iterator<infer V> ? V : never;
+/**
+ * Lazily computes the [Cartesian product](https://en.wikipedia.org/wiki/Cartesian_product)
+ * of the source iterators, yielding every possible tuple formed by picking one
+ * element from each source, in lexicographic order — the rightmost source
+ * advances fastest, like the digits of an odometer.
+ *
+ * Because every source except the first is traversed many times, those sources
+ * are buffered into arrays when iteration starts. The first source is consumed
+ * lazily, one element at a time, so it may be infinite. When iteration ends —
+ * because the first source ran out, a buffered source was empty, or the
+ * consumer terminated early — every source is closed via its `return` method.
+ *
+ * If no sources are passed, a single empty tuple is yielded, matching the
+ * array `cartesianProduct`. If any source is empty, nothing is yielded.
+ *
+ * @template T - A tuple of the source iterator types.
+ * @param sources - The iterators to take the product of.
+ * @returns A lazy iterator over tuples representing the Cartesian product.
+ *
+ * @example
+ * cartesianProduct([1, 2].values(), ['a', 'b'].values()).toArray();
+ * // => [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+ *
+ * @example
+ * // The first source may be infinite; elements are produced on demand.
+ * cartesianProduct(range(0, Infinity), ['a', 'b'].values()).take(3).toArray();
+ * // => [[0, 'a'], [0, 'b'], [1, 'a']]
+ */
+declare function cartesianProduct<T extends Array<Iterator<unknown>>>(...sources: T): IteratorObject<{ [K in keyof T]: IteratorValue<T[K]> }, undefined>;
+//#endregion
+export { cartesianProduct };

package/dist/iterator/cartesianProduct.d.ts

@@ -0,0 +1,33 @@
+//#region src/iterator/cartesianProduct.d.ts
+type IteratorValue<T> = T extends Iterator<infer V> ? V : never;
+/**
+ * Lazily computes the [Cartesian product](https://en.wikipedia.org/wiki/Cartesian_product)
+ * of the source iterators, yielding every possible tuple formed by picking one
+ * element from each source, in lexicographic order — the rightmost source
+ * advances fastest, like the digits of an odometer.
+ *
+ * Because every source except the first is traversed many times, those sources
+ * are buffered into arrays when iteration starts. The first source is consumed
+ * lazily, one element at a time, so it may be infinite. When iteration ends —
+ * because the first source ran out, a buffered source was empty, or the
+ * consumer terminated early — every source is closed via its `return` method.
+ *
+ * If no sources are passed, a single empty tuple is yielded, matching the
+ * array `cartesianProduct`. If any source is empty, nothing is yielded.
+ *
+ * @template T - A tuple of the source iterator types.
+ * @param sources - The iterators to take the product of.
+ * @returns A lazy iterator over tuples representing the Cartesian product.
+ *
+ * @example
+ * cartesianProduct([1, 2].values(), ['a', 'b'].values()).toArray();
+ * // => [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+ *
+ * @example
+ * // The first source may be infinite; elements are produced on demand.
+ * cartesianProduct(range(0, Infinity), ['a', 'b'].values()).take(3).toArray();
+ * // => [[0, 'a'], [0, 'b'], [1, 'a']]
+ */
+declare function cartesianProduct<T extends Array<Iterator<unknown>>>(...sources: T): IteratorObject<{ [K in keyof T]: IteratorValue<T[K]> }, undefined>;
+//#endregion
+export { cartesianProduct };

package/dist/iterator/cartesianProduct.js

@@ -0,0 +1,95 @@
+const require_iterator = require("./_internal/iterator.js");
+//#region src/iterator/cartesianProduct.ts
+/**
+* Lazily computes the [Cartesian product](https://en.wikipedia.org/wiki/Cartesian_product)
+* of the source iterators, yielding every possible tuple formed by picking one
+* element from each source, in lexicographic order — the rightmost source
+* advances fastest, like the digits of an odometer.
+*
+* Because every source except the first is traversed many times, those sources
+* are buffered into arrays when iteration starts. The first source is consumed
+* lazily, one element at a time, so it may be infinite. When iteration ends —
+* because the first source ran out, a buffered source was empty, or the
+* consumer terminated early — every source is closed via its `return` method.
+*
+* If no sources are passed, a single empty tuple is yielded, matching the
+* array `cartesianProduct`. If any source is empty, nothing is yielded.
+*
+* @template T - A tuple of the source iterator types.
+* @param sources - The iterators to take the product of.
+* @returns A lazy iterator over tuples representing the Cartesian product.
+*
+* @example
+* cartesianProduct([1, 2].values(), ['a', 'b'].values()).toArray();
+* // => [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+*
+* @example
+* // The first source may be infinite; elements are produced on demand.
+* cartesianProduct(range(0, Infinity), ['a', 'b'].values()).take(3).toArray();
+* // => [[0, 'a'], [0, 'b'], [1, 'a']]
+*/
+function cartesianProduct(...sources) {
+	const pools = [];
+	const indices = [];
+	let firstValue;
+	let state = "initial";
+	return require_iterator.iterator(function() {
+		if (state === "done") return {
+			value: void 0,
+			done: true
+		};
+		if (state === "initial") {
+			state = "active";
+			if (sources.length === 0) {
+				state = "done";
+				return {
+					value: [],
+					done: false
+				};
+			}
+			for (let index = 1; index < sources.length; index++) {
+				const pool = [];
+				let step = sources[index].next();
+				while (!step.done) {
+					pool.push(step.value);
+					step = sources[index].next();
+				}
+				pools.push(pool);
+			}
+			if (pools.some((pool) => pool.length === 0)) return {
+				value: void 0,
+				done: true
+			};
+			const step = sources[0].next();
+			if (step.done) return {
+				value: void 0,
+				done: true
+			};
+			firstValue = step.value;
+			for (let index = 0; index < pools.length; index++) indices.push(0);
+		}
+		const tuple = new Array(sources.length);
+		tuple[0] = firstValue;
+		for (let index = 0; index < indices.length; index++) tuple[index + 1] = pools[index][indices[index]];
+		let position = indices.length - 1;
+		while (position >= 0) {
+			indices[position]++;
+			if (indices[position] < pools[position].length) break;
+			indices[position] = 0;
+			position--;
+		}
+		if (position < 0) {
+			const step = sources[0].next();
+			if (step.done) state = "done";
+			else firstValue = step.value;
+		}
+		return {
+			value: tuple,
+			done: false
+		};
+	}, () => {
+		for (const source of sources) source.return?.();
+	});
+}
+//#endregion
+exports.cartesianProduct = cartesianProduct;

package/dist/iterator/cartesianProduct.mjs

@@ -0,0 +1,95 @@
+import { iterator } from "./_internal/iterator.mjs";
+//#region src/iterator/cartesianProduct.ts
+/**
+* Lazily computes the [Cartesian product](https://en.wikipedia.org/wiki/Cartesian_product)
+* of the source iterators, yielding every possible tuple formed by picking one
+* element from each source, in lexicographic order — the rightmost source
+* advances fastest, like the digits of an odometer.
+*
+* Because every source except the first is traversed many times, those sources
+* are buffered into arrays when iteration starts. The first source is consumed
+* lazily, one element at a time, so it may be infinite. When iteration ends —
+* because the first source ran out, a buffered source was empty, or the
+* consumer terminated early — every source is closed via its `return` method.
+*
+* If no sources are passed, a single empty tuple is yielded, matching the
+* array `cartesianProduct`. If any source is empty, nothing is yielded.
+*
+* @template T - A tuple of the source iterator types.
+* @param sources - The iterators to take the product of.
+* @returns A lazy iterator over tuples representing the Cartesian product.
+*
+* @example
+* cartesianProduct([1, 2].values(), ['a', 'b'].values()).toArray();
+* // => [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+*
+* @example
+* // The first source may be infinite; elements are produced on demand.
+* cartesianProduct(range(0, Infinity), ['a', 'b'].values()).take(3).toArray();
+* // => [[0, 'a'], [0, 'b'], [1, 'a']]
+*/
+function cartesianProduct(...sources) {
+	const pools = [];
+	const indices = [];
+	let firstValue;
+	let state = "initial";
+	return iterator(function() {
+		if (state === "done") return {
+			value: void 0,
+			done: true
+		};
+		if (state === "initial") {
+			state = "active";
+			if (sources.length === 0) {
+				state = "done";
+				return {
+					value: [],
+					done: false
+				};
+			}
+			for (let index = 1; index < sources.length; index++) {
+				const pool = [];
+				let step = sources[index].next();
+				while (!step.done) {
+					pool.push(step.value);
+					step = sources[index].next();
+				}
+				pools.push(pool);
+			}
+			if (pools.some((pool) => pool.length === 0)) return {
+				value: void 0,
+				done: true
+			};
+			const step = sources[0].next();
+			if (step.done) return {
+				value: void 0,
+				done: true
+			};
+			firstValue = step.value;
+			for (let index = 0; index < pools.length; index++) indices.push(0);
+		}
+		const tuple = new Array(sources.length);
+		tuple[0] = firstValue;
+		for (let index = 0; index < indices.length; index++) tuple[index + 1] = pools[index][indices[index]];
+		let position = indices.length - 1;
+		while (position >= 0) {
+			indices[position]++;
+			if (indices[position] < pools[position].length) break;
+			indices[position] = 0;
+			position--;
+		}
+		if (position < 0) {
+			const step = sources[0].next();
+			if (step.done) state = "done";
+			else firstValue = step.value;
+		}
+		return {
+			value: tuple,
+			done: false
+		};
+	}, () => {
+		for (const source of sources) source.return?.();
+	});
+}
+//#endregion
+export { cartesianProduct };

package/dist/iterator/chunk.d.mts

@@ -0,0 +1,21 @@
+//#region src/iterator/chunk.d.ts
+/**
+ * Lazily groups the elements of `source` into arrays of length `size`. The final
+ * chunk holds the remaining elements when the source length is not an exact
+ * multiple of `size`, so it may be shorter.
+ *
+ * Each chunk is produced only when requested, so this works with infinite
+ * iterators when bounded by a short-circuiting helper.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to split into chunks.
+ * @param size - The length of each chunk; must be an integer greater than zero.
+ * @returns A lazy iterator over arrays of up to `size` elements.
+ * @throws {Error} Throws an error if `size` is not an integer greater than zero.
+ *
+ * @example
+ * chunk([1, 2, 3, 4, 5].values(), 2).toArray(); // => [[1, 2], [3, 4], [5]]
+ */
+declare function chunk<T>(source: Iterator<T>, size: number): IteratorObject<T[], undefined>;
+//#endregion
+export { chunk };

package/dist/iterator/chunk.d.ts

@@ -0,0 +1,21 @@
+//#region src/iterator/chunk.d.ts
+/**
+ * Lazily groups the elements of `source` into arrays of length `size`. The final
+ * chunk holds the remaining elements when the source length is not an exact
+ * multiple of `size`, so it may be shorter.
+ *
+ * Each chunk is produced only when requested, so this works with infinite
+ * iterators when bounded by a short-circuiting helper.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to split into chunks.
+ * @param size - The length of each chunk; must be an integer greater than zero.
+ * @returns A lazy iterator over arrays of up to `size` elements.
+ * @throws {Error} Throws an error if `size` is not an integer greater than zero.
+ *
+ * @example
+ * chunk([1, 2, 3, 4, 5].values(), 2).toArray(); // => [[1, 2], [3, 4], [5]]
+ */
+declare function chunk<T>(source: Iterator<T>, size: number): IteratorObject<T[], undefined>;
+//#endregion
+export { chunk };

package/dist/iterator/chunk.js

@@ -0,0 +1,40 @@
+const require_iterator = require("./_internal/iterator.js");
+//#region src/iterator/chunk.ts
+/**
+* Lazily groups the elements of `source` into arrays of length `size`. The final
+* chunk holds the remaining elements when the source length is not an exact
+* multiple of `size`, so it may be shorter.
+*
+* Each chunk is produced only when requested, so this works with infinite
+* iterators when bounded by a short-circuiting helper.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to split into chunks.
+* @param size - The length of each chunk; must be an integer greater than zero.
+* @returns A lazy iterator over arrays of up to `size` elements.
+* @throws {Error} Throws an error if `size` is not an integer greater than zero.
+*
+* @example
+* chunk([1, 2, 3, 4, 5].values(), 2).toArray(); // => [[1, 2], [3, 4], [5]]
+*/
+function chunk(source, size) {
+	if (!Number.isInteger(size) || size <= 0) throw new Error("Size must be an integer greater than zero.");
+	return require_iterator.iterator(function() {
+		const buffer = [];
+		while (buffer.length < size) {
+			const result = source.next();
+			if (result.done) break;
+			buffer.push(result.value);
+		}
+		if (buffer.length === 0) return {
+			value: void 0,
+			done: true
+		};
+		return {
+			value: buffer,
+			done: false
+		};
+	}, () => void source.return?.());
+}
+//#endregion
+exports.chunk = chunk;

package/dist/iterator/chunk.mjs

@@ -0,0 +1,40 @@
+import { iterator } from "./_internal/iterator.mjs";
+//#region src/iterator/chunk.ts
+/**
+* Lazily groups the elements of `source` into arrays of length `size`. The final
+* chunk holds the remaining elements when the source length is not an exact
+* multiple of `size`, so it may be shorter.
+*
+* Each chunk is produced only when requested, so this works with infinite
+* iterators when bounded by a short-circuiting helper.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to split into chunks.
+* @param size - The length of each chunk; must be an integer greater than zero.
+* @returns A lazy iterator over arrays of up to `size` elements.
+* @throws {Error} Throws an error if `size` is not an integer greater than zero.
+*
+* @example
+* chunk([1, 2, 3, 4, 5].values(), 2).toArray(); // => [[1, 2], [3, 4], [5]]
+*/
+function chunk(source, size) {
+	if (!Number.isInteger(size) || size <= 0) throw new Error("Size must be an integer greater than zero.");
+	return iterator(function() {
+		const buffer = [];
+		while (buffer.length < size) {
+			const result = source.next();
+			if (result.done) break;
+			buffer.push(result.value);
+		}
+		if (buffer.length === 0) return {
+			value: void 0,
+			done: true
+		};
+		return {
+			value: buffer,
+			done: false
+		};
+	}, () => void source.return?.());
+}
+//#endregion
+export { chunk };

package/dist/iterator/count.d.mts

@@ -0,0 +1,18 @@
+//#region src/iterator/count.d.ts
+/**
+ * Consumes `source` and returns the number of elements it produces. This is a
+ * terminal operation: it pulls every element, so it must not be used on an
+ * infinite iterator.
+ *
+ * Unlike `source.toArray().length`, this counts without allocating an array.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to count.
+ * @returns The number of elements produced by `source`.
+ *
+ * @example
+ * count([1, 2, 3].values()); // => 3
+ */
+declare function count<T>(source: Iterator<T>): number;
+//#endregion
+export { count };

package/dist/iterator/count.d.ts

@@ -0,0 +1,18 @@
+//#region src/iterator/count.d.ts
+/**
+ * Consumes `source` and returns the number of elements it produces. This is a
+ * terminal operation: it pulls every element, so it must not be used on an
+ * infinite iterator.
+ *
+ * Unlike `source.toArray().length`, this counts without allocating an array.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to count.
+ * @returns The number of elements produced by `source`.
+ *
+ * @example
+ * count([1, 2, 3].values()); // => 3
+ */
+declare function count<T>(source: Iterator<T>): number;
+//#endregion
+export { count };

package/dist/iterator/count.js

@@ -0,0 +1,26 @@
+//#region src/iterator/count.ts
+/**
+* Consumes `source` and returns the number of elements it produces. This is a
+* terminal operation: it pulls every element, so it must not be used on an
+* infinite iterator.
+*
+* Unlike `source.toArray().length`, this counts without allocating an array.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to count.
+* @returns The number of elements produced by `source`.
+*
+* @example
+* count([1, 2, 3].values()); // => 3
+*/
+function count(source) {
+	let total = 0;
+	let next = source.next();
+	while (!next.done) {
+		total++;
+		next = source.next();
+	}
+	return total;
+}
+//#endregion
+exports.count = count;

package/dist/iterator/count.mjs

@@ -0,0 +1,26 @@
+//#region src/iterator/count.ts
+/**
+* Consumes `source` and returns the number of elements it produces. This is a
+* terminal operation: it pulls every element, so it must not be used on an
+* infinite iterator.
+*
+* Unlike `source.toArray().length`, this counts without allocating an array.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to count.
+* @returns The number of elements produced by `source`.
+*
+* @example
+* count([1, 2, 3].values()); // => 3
+*/
+function count(source) {
+	let total = 0;
+	let next = source.next();
+	while (!next.done) {
+		total++;
+		next = source.next();
+	}
+	return total;
+}
+//#endregion
+export { count };

package/dist/iterator/dropWhile.d.mts

@@ -0,0 +1,20 @@
+//#region src/iterator/dropWhile.d.ts
+/**
+ * Lazily skips elements from `source` as long as `shouldDrop` returns a truthy
+ * value, then yields every remaining element (including the one that first
+ * failed the predicate).
+ *
+ * The native iterator helpers offer `drop` (by count) but not a predicate-based
+ * `dropWhile`, which is why this is provided.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to drop elements from.
+ * @param shouldDrop - Called with `(value, index)`; elements are skipped while it returns truthy.
+ * @returns A lazy iterator over the elements after the dropped leading run.
+ *
+ * @example
+ * dropWhile([1, 2, 3, 1].values(), x => x < 3).toArray(); // => [3, 1]
+ */
+declare function dropWhile<T>(source: Iterator<T>, shouldDrop: (value: T, index: number) => boolean): IteratorObject<T, undefined>;
+//#endregion
+export { dropWhile };

package/dist/iterator/dropWhile.d.ts

@@ -0,0 +1,20 @@
+//#region src/iterator/dropWhile.d.ts
+/**
+ * Lazily skips elements from `source` as long as `shouldDrop` returns a truthy
+ * value, then yields every remaining element (including the one that first
+ * failed the predicate).
+ *
+ * The native iterator helpers offer `drop` (by count) but not a predicate-based
+ * `dropWhile`, which is why this is provided.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to drop elements from.
+ * @param shouldDrop - Called with `(value, index)`; elements are skipped while it returns truthy.
+ * @returns A lazy iterator over the elements after the dropped leading run.
+ *
+ * @example
+ * dropWhile([1, 2, 3, 1].values(), x => x < 3).toArray(); // => [3, 1]
+ */
+declare function dropWhile<T>(source: Iterator<T>, shouldDrop: (value: T, index: number) => boolean): IteratorObject<T, undefined>;
+//#endregion
+export { dropWhile };

package/dist/iterator/dropWhile.js

@@ -0,0 +1,52 @@
+const require_iterator = require("./_internal/iterator.js");
+//#region src/iterator/dropWhile.ts
+/**
+* Lazily skips elements from `source` as long as `shouldDrop` returns a truthy
+* value, then yields every remaining element (including the one that first
+* failed the predicate).
+*
+* The native iterator helpers offer `drop` (by count) but not a predicate-based
+* `dropWhile`, which is why this is provided.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to drop elements from.
+* @param shouldDrop - Called with `(value, index)`; elements are skipped while it returns truthy.
+* @returns A lazy iterator over the elements after the dropped leading run.
+*
+* @example
+* dropWhile([1, 2, 3, 1].values(), x => x < 3).toArray(); // => [3, 1]
+*/
+function dropWhile(source, shouldDrop) {
+	let index = 0;
+	let dropping = true;
+	return require_iterator.iterator(function() {
+		while (dropping) {
+			const result = source.next();
+			if (result.done) {
+				dropping = false;
+				return {
+					value: void 0,
+					done: true
+				};
+			}
+			if (!shouldDrop(result.value, index++)) {
+				dropping = false;
+				return {
+					value: result.value,
+					done: false
+				};
+			}
+		}
+		const result = source.next();
+		if (result.done) return {
+			value: void 0,
+			done: true
+		};
+		return {
+			value: result.value,
+			done: false
+		};
+	}, () => void source.return?.());
+}
+//#endregion
+exports.dropWhile = dropWhile;