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

package/dist/iterator/dropWhile.mjs

@@ -0,0 +1,52 @@
+import { iterator } from "./_internal/iterator.mjs";
+//#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 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
+export { dropWhile };

package/dist/iterator/head.d.mts

@@ -0,0 +1,21 @@
+//#region src/iterator/head.d.ts
+/**
+ * Returns the first element produced by `source`, or `undefined` if it is empty.
+ * This pulls a single element and then stops, so it is safe to use on an
+ * infinite iterator.
+ *
+ * This consumes the iterator rather than peeking at it: after reading the first
+ * element, `source` is closed via its `return` method (matching the native
+ * `Iterator.prototype.find`), so it cannot be iterated further.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to read the first element from.
+ * @returns The first element, or `undefined` when the iterator yields nothing.
+ *
+ * @example
+ * head([1, 2, 3].values()); // => 1
+ * head([].values()); // => undefined
+ */
+declare function head<T>(source: Iterator<T>): T | undefined;
+//#endregion
+export { head };

package/dist/iterator/head.d.ts

@@ -0,0 +1,21 @@
+//#region src/iterator/head.d.ts
+/**
+ * Returns the first element produced by `source`, or `undefined` if it is empty.
+ * This pulls a single element and then stops, so it is safe to use on an
+ * infinite iterator.
+ *
+ * This consumes the iterator rather than peeking at it: after reading the first
+ * element, `source` is closed via its `return` method (matching the native
+ * `Iterator.prototype.find`), so it cannot be iterated further.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to read the first element from.
+ * @returns The first element, or `undefined` when the iterator yields nothing.
+ *
+ * @example
+ * head([1, 2, 3].values()); // => 1
+ * head([].values()); // => undefined
+ */
+declare function head<T>(source: Iterator<T>): T | undefined;
+//#endregion
+export { head };

package/dist/iterator/head.js

@@ -0,0 +1,26 @@
+//#region src/iterator/head.ts
+/**
+* Returns the first element produced by `source`, or `undefined` if it is empty.
+* This pulls a single element and then stops, so it is safe to use on an
+* infinite iterator.
+*
+* This consumes the iterator rather than peeking at it: after reading the first
+* element, `source` is closed via its `return` method (matching the native
+* `Iterator.prototype.find`), so it cannot be iterated further.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to read the first element from.
+* @returns The first element, or `undefined` when the iterator yields nothing.
+*
+* @example
+* head([1, 2, 3].values()); // => 1
+* head([].values()); // => undefined
+*/
+function head(source) {
+	const result = source.next();
+	if (result.done) return;
+	source.return?.();
+	return result.value;
+}
+//#endregion
+exports.head = head;

package/dist/iterator/head.mjs

@@ -0,0 +1,26 @@
+//#region src/iterator/head.ts
+/**
+* Returns the first element produced by `source`, or `undefined` if it is empty.
+* This pulls a single element and then stops, so it is safe to use on an
+* infinite iterator.
+*
+* This consumes the iterator rather than peeking at it: after reading the first
+* element, `source` is closed via its `return` method (matching the native
+* `Iterator.prototype.find`), so it cannot be iterated further.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to read the first element from.
+* @returns The first element, or `undefined` when the iterator yields nothing.
+*
+* @example
+* head([1, 2, 3].values()); // => 1
+* head([].values()); // => undefined
+*/
+function head(source) {
+	const result = source.next();
+	if (result.done) return;
+	source.return?.();
+	return result.value;
+}
+//#endregion
+export { head };

package/dist/iterator/index.d.mts

@@ -0,0 +1,13 @@
+import { cartesianProduct } from "./cartesianProduct.mjs";
+import { chunk } from "./chunk.mjs";
+import { count } from "./count.mjs";
+import { dropWhile } from "./dropWhile.mjs";
+import { head } from "./head.mjs";
+import { iterate } from "./iterate.mjs";
+import { partition } from "./partition.mjs";
+import { range } from "./range.mjs";
+import { scan } from "./scan.mjs";
+import { takeWhile } from "./takeWhile.mjs";
+import { uniqBy } from "./uniqBy.mjs";
+import { zip } from "./zip.mjs";
+export { cartesianProduct, chunk, count, dropWhile, head, iterate, partition, range, scan, takeWhile, uniqBy, zip };

package/dist/iterator/index.d.ts

@@ -0,0 +1,13 @@
+import { cartesianProduct } from "./cartesianProduct.js";
+import { chunk } from "./chunk.js";
+import { count } from "./count.js";
+import { dropWhile } from "./dropWhile.js";
+import { head } from "./head.js";
+import { iterate } from "./iterate.js";
+import { partition } from "./partition.js";
+import { range } from "./range.js";
+import { scan } from "./scan.js";
+import { takeWhile } from "./takeWhile.js";
+import { uniqBy } from "./uniqBy.js";
+import { zip } from "./zip.js";
+export { cartesianProduct, chunk, count, dropWhile, head, iterate, partition, range, scan, takeWhile, uniqBy, zip };

package/dist/iterator/index.js

@@ -0,0 +1,25 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_cartesianProduct = require("./cartesianProduct.js");
+const require_chunk = require("./chunk.js");
+const require_count = require("./count.js");
+const require_dropWhile = require("./dropWhile.js");
+const require_head = require("./head.js");
+const require_partition = require("./partition.js");
+const require_scan = require("./scan.js");
+const require_takeWhile = require("./takeWhile.js");
+const require_uniqBy = require("./uniqBy.js");
+const require_zip = require("./zip.js");
+const require_iterate = require("./iterate.js");
+const require_range = require("./range.js");
+exports.cartesianProduct = require_cartesianProduct.cartesianProduct;
+exports.chunk = require_chunk.chunk;
+exports.count = require_count.count;
+exports.dropWhile = require_dropWhile.dropWhile;
+exports.head = require_head.head;
+exports.iterate = require_iterate.iterate;
+exports.partition = require_partition.partition;
+exports.range = require_range.range;
+exports.scan = require_scan.scan;
+exports.takeWhile = require_takeWhile.takeWhile;
+exports.uniqBy = require_uniqBy.uniqBy;
+exports.zip = require_zip.zip;

package/dist/iterator/index.mjs

@@ -0,0 +1,13 @@
+import { cartesianProduct } from "./cartesianProduct.mjs";
+import { chunk } from "./chunk.mjs";
+import { count } from "./count.mjs";
+import { dropWhile } from "./dropWhile.mjs";
+import { head } from "./head.mjs";
+import { partition } from "./partition.mjs";
+import { scan } from "./scan.mjs";
+import { takeWhile } from "./takeWhile.mjs";
+import { uniqBy } from "./uniqBy.mjs";
+import { zip } from "./zip.mjs";
+import { iterate } from "./iterate.mjs";
+import { range } from "./range.mjs";
+export { cartesianProduct, chunk, count, dropWhile, head, iterate, partition, range, scan, takeWhile, uniqBy, zip };

package/dist/iterator/iterate.d.mts

@@ -0,0 +1,20 @@
+//#region src/iterator/iterate.d.ts
+/**
+ * Creates an infinite lazy iterator that starts with `seed` and repeatedly
+ * applies `getNext` to produce the following value: `seed`, `getNext(seed)`,
+ * `getNext(getNext(seed))`, and so on.
+ *
+ * Because the iterator is infinite, it must be bounded by a short-circuiting
+ * helper such as the native `take` or {@link takeWhile} before being consumed.
+ *
+ * @template T - The type of values produced by the iterator.
+ * @param seed - The first value of the sequence.
+ * @param getNext - Computes the next value from the current one.
+ * @returns An infinite lazy iterator over the generated sequence.
+ *
+ * @example
+ * iterate(1, x => x * 2).take(5).toArray(); // => [1, 2, 4, 8, 16]
+ */
+declare function iterate<T>(seed: T, getNext: (value: T) => T): IteratorObject<T, undefined>;
+//#endregion
+export { iterate };

package/dist/iterator/iterate.d.ts

@@ -0,0 +1,20 @@
+//#region src/iterator/iterate.d.ts
+/**
+ * Creates an infinite lazy iterator that starts with `seed` and repeatedly
+ * applies `getNext` to produce the following value: `seed`, `getNext(seed)`,
+ * `getNext(getNext(seed))`, and so on.
+ *
+ * Because the iterator is infinite, it must be bounded by a short-circuiting
+ * helper such as the native `take` or {@link takeWhile} before being consumed.
+ *
+ * @template T - The type of values produced by the iterator.
+ * @param seed - The first value of the sequence.
+ * @param getNext - Computes the next value from the current one.
+ * @returns An infinite lazy iterator over the generated sequence.
+ *
+ * @example
+ * iterate(1, x => x * 2).take(5).toArray(); // => [1, 2, 4, 8, 16]
+ */
+declare function iterate<T>(seed: T, getNext: (value: T) => T): IteratorObject<T, undefined>;
+//#endregion
+export { iterate };

package/dist/iterator/iterate.js

@@ -0,0 +1,32 @@
+const require_iterator = require("./_internal/iterator.js");
+//#region src/iterator/iterate.ts
+/**
+* Creates an infinite lazy iterator that starts with `seed` and repeatedly
+* applies `getNext` to produce the following value: `seed`, `getNext(seed)`,
+* `getNext(getNext(seed))`, and so on.
+*
+* Because the iterator is infinite, it must be bounded by a short-circuiting
+* helper such as the native `take` or {@link takeWhile} before being consumed.
+*
+* @template T - The type of values produced by the iterator.
+* @param seed - The first value of the sequence.
+* @param getNext - Computes the next value from the current one.
+* @returns An infinite lazy iterator over the generated sequence.
+*
+* @example
+* iterate(1, x => x * 2).take(5).toArray(); // => [1, 2, 4, 8, 16]
+*/
+function iterate(seed, getNext) {
+	let current = seed;
+	let started = false;
+	return require_iterator.iterator(function() {
+		if (started) current = getNext(current);
+		else started = true;
+		return {
+			value: current,
+			done: false
+		};
+	});
+}
+//#endregion
+exports.iterate = iterate;

package/dist/iterator/iterate.mjs

@@ -0,0 +1,32 @@
+import { iterator } from "./_internal/iterator.mjs";
+//#region src/iterator/iterate.ts
+/**
+* Creates an infinite lazy iterator that starts with `seed` and repeatedly
+* applies `getNext` to produce the following value: `seed`, `getNext(seed)`,
+* `getNext(getNext(seed))`, and so on.
+*
+* Because the iterator is infinite, it must be bounded by a short-circuiting
+* helper such as the native `take` or {@link takeWhile} before being consumed.
+*
+* @template T - The type of values produced by the iterator.
+* @param seed - The first value of the sequence.
+* @param getNext - Computes the next value from the current one.
+* @returns An infinite lazy iterator over the generated sequence.
+*
+* @example
+* iterate(1, x => x * 2).take(5).toArray(); // => [1, 2, 4, 8, 16]
+*/
+function iterate(seed, getNext) {
+	let current = seed;
+	let started = false;
+	return iterator(function() {
+		if (started) current = getNext(current);
+		else started = true;
+		return {
+			value: current,
+			done: false
+		};
+	});
+}
+//#endregion
+export { iterate };

package/dist/iterator/partition.d.mts

@@ -0,0 +1,18 @@
+//#region src/iterator/partition.d.ts
+/**
+ * Consumes `source` and splits its elements into two arrays: the first holds the
+ * elements for which `predicate` returns truthy, the second holds the rest.
+ * Relative order is preserved within each group. This is a terminal operation:
+ * it pulls every element, so it must not be used on an infinite iterator.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to partition.
+ * @param predicate - Called with `(value, index)`; truthy sends the element to the first array.
+ * @returns A two-element tuple of `[matched, unmatched]` arrays.
+ *
+ * @example
+ * partition([1, 2, 3, 4].values(), x => x % 2 === 0); // => [[2, 4], [1, 3]]
+ */
+declare function partition<T>(source: Iterator<T>, predicate: (value: T, index: number) => boolean): [T[], T[]];
+//#endregion
+export { partition };

package/dist/iterator/partition.d.ts

@@ -0,0 +1,18 @@
+//#region src/iterator/partition.d.ts
+/**
+ * Consumes `source` and splits its elements into two arrays: the first holds the
+ * elements for which `predicate` returns truthy, the second holds the rest.
+ * Relative order is preserved within each group. This is a terminal operation:
+ * it pulls every element, so it must not be used on an infinite iterator.
+ *
+ * @template T - The type of elements produced by the iterator.
+ * @param source - The iterator to partition.
+ * @param predicate - Called with `(value, index)`; truthy sends the element to the first array.
+ * @returns A two-element tuple of `[matched, unmatched]` arrays.
+ *
+ * @example
+ * partition([1, 2, 3, 4].values(), x => x % 2 === 0); // => [[2, 4], [1, 3]]
+ */
+declare function partition<T>(source: Iterator<T>, predicate: (value: T, index: number) => boolean): [T[], T[]];
+//#endregion
+export { partition };

package/dist/iterator/partition.js

@@ -0,0 +1,36 @@
+//#region src/iterator/partition.ts
+/**
+* Consumes `source` and splits its elements into two arrays: the first holds the
+* elements for which `predicate` returns truthy, the second holds the rest.
+* Relative order is preserved within each group. This is a terminal operation:
+* it pulls every element, so it must not be used on an infinite iterator.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to partition.
+* @param predicate - Called with `(value, index)`; truthy sends the element to the first array.
+* @returns A two-element tuple of `[matched, unmatched]` arrays.
+*
+* @example
+* partition([1, 2, 3, 4].values(), x => x % 2 === 0); // => [[2, 4], [1, 3]]
+*/
+function partition(source, predicate) {
+	const matched = [];
+	const unmatched = [];
+	let index = 0;
+	let next = source.next();
+	while (!next.done) {
+		let isMatch;
+		try {
+			isMatch = predicate(next.value, index++);
+		} catch (error) {
+			source.return?.();
+			throw error;
+		}
+		if (isMatch) matched.push(next.value);
+		else unmatched.push(next.value);
+		next = source.next();
+	}
+	return [matched, unmatched];
+}
+//#endregion
+exports.partition = partition;

package/dist/iterator/partition.mjs

@@ -0,0 +1,36 @@
+//#region src/iterator/partition.ts
+/**
+* Consumes `source` and splits its elements into two arrays: the first holds the
+* elements for which `predicate` returns truthy, the second holds the rest.
+* Relative order is preserved within each group. This is a terminal operation:
+* it pulls every element, so it must not be used on an infinite iterator.
+*
+* @template T - The type of elements produced by the iterator.
+* @param source - The iterator to partition.
+* @param predicate - Called with `(value, index)`; truthy sends the element to the first array.
+* @returns A two-element tuple of `[matched, unmatched]` arrays.
+*
+* @example
+* partition([1, 2, 3, 4].values(), x => x % 2 === 0); // => [[2, 4], [1, 3]]
+*/
+function partition(source, predicate) {
+	const matched = [];
+	const unmatched = [];
+	let index = 0;
+	let next = source.next();
+	while (!next.done) {
+		let isMatch;
+		try {
+			isMatch = predicate(next.value, index++);
+		} catch (error) {
+			source.return?.();
+			throw error;
+		}
+		if (isMatch) matched.push(next.value);
+		else unmatched.push(next.value);
+		next = source.next();
+	}
+	return [matched, unmatched];
+}
+//#endregion
+export { partition };

package/dist/iterator/range.d.mts

@@ -0,0 +1,42 @@
+//#region src/iterator/range.d.ts
+/**
+ * Lazily yields numbers from `0` (inclusive) up to `end` (exclusive), incrementing by `1`.
+ *
+ * Unlike `es-toolkit`'s array `range`, this produces a lazy {@link IteratorObject}:
+ * no numbers are computed until the iterator is consumed, so it composes with
+ * other iterator helpers and supports early termination.
+ *
+ * @param end - The end number of the range (exclusive).
+ * @returns A lazy iterator over the numbers in the range.
+ *
+ * @example
+ * range(4).toArray(); // => [0, 1, 2, 3]
+ */
+declare function range(end: number): IteratorObject<number, undefined>;
+/**
+ * Lazily yields numbers from `start` (inclusive) up to `end` (exclusive), incrementing by `1`.
+ *
+ * @param start - The starting number of the range (inclusive).
+ * @param end - The end number of the range (exclusive).
+ * @returns A lazy iterator over the numbers in the range.
+ *
+ * @example
+ * range(1, 4).toArray(); // => [1, 2, 3]
+ */
+declare function range(start: number, end: number): IteratorObject<number, undefined>;
+/**
+ * Lazily yields numbers from `start` (inclusive) up to `end` (exclusive), incrementing by `step`.
+ *
+ * @param start - The starting number of the range (inclusive).
+ * @param end - The end number of the range (exclusive).
+ * @param step - The step value for the range.
+ * @returns A lazy iterator over the numbers in the range.
+ * @throws {Error} Throws an error if the step value is not a non-zero integer.
+ *
+ * @example
+ * range(0, 20, 5).toArray(); // => [0, 5, 10, 15]
+ * range(0, -4, -1).toArray(); // => [0, -1, -2, -3]
+ */
+declare function range(start: number, end: number, step: number): IteratorObject<number, undefined>;
+//#endregion
+export { range };

package/dist/iterator/range.d.ts

@@ -0,0 +1,42 @@
+//#region src/iterator/range.d.ts
+/**
+ * Lazily yields numbers from `0` (inclusive) up to `end` (exclusive), incrementing by `1`.
+ *
+ * Unlike `es-toolkit`'s array `range`, this produces a lazy {@link IteratorObject}:
+ * no numbers are computed until the iterator is consumed, so it composes with
+ * other iterator helpers and supports early termination.
+ *
+ * @param end - The end number of the range (exclusive).
+ * @returns A lazy iterator over the numbers in the range.
+ *
+ * @example
+ * range(4).toArray(); // => [0, 1, 2, 3]
+ */
+declare function range(end: number): IteratorObject<number, undefined>;
+/**
+ * Lazily yields numbers from `start` (inclusive) up to `end` (exclusive), incrementing by `1`.
+ *
+ * @param start - The starting number of the range (inclusive).
+ * @param end - The end number of the range (exclusive).
+ * @returns A lazy iterator over the numbers in the range.
+ *
+ * @example
+ * range(1, 4).toArray(); // => [1, 2, 3]
+ */
+declare function range(start: number, end: number): IteratorObject<number, undefined>;
+/**
+ * Lazily yields numbers from `start` (inclusive) up to `end` (exclusive), incrementing by `step`.
+ *
+ * @param start - The starting number of the range (inclusive).
+ * @param end - The end number of the range (exclusive).
+ * @param step - The step value for the range.
+ * @returns A lazy iterator over the numbers in the range.
+ * @throws {Error} Throws an error if the step value is not a non-zero integer.
+ *
+ * @example
+ * range(0, 20, 5).toArray(); // => [0, 5, 10, 15]
+ * range(0, -4, -1).toArray(); // => [0, -1, -2, -3]
+ */
+declare function range(start: number, end: number, step: number): IteratorObject<number, undefined>;
+//#endregion
+export { range };

package/dist/iterator/range.js

@@ -0,0 +1,25 @@
+const require_iterator = require("./_internal/iterator.js");
+//#region src/iterator/range.ts
+function range(start, end, step = 1) {
+	if (end == null) {
+		end = start;
+		start = 0;
+	}
+	if (!Number.isInteger(step) || step === 0) throw new Error(`The step value must be a non-zero integer, but got ${step}.`);
+	const finalEnd = end;
+	let current = start;
+	return require_iterator.iterator(function() {
+		if (step > 0 ? current >= finalEnd : current <= finalEnd) return {
+			value: void 0,
+			done: true
+		};
+		const value = current;
+		current += step;
+		return {
+			value,
+			done: false
+		};
+	});
+}
+//#endregion
+exports.range = range;

package/dist/iterator/range.mjs

@@ -0,0 +1,25 @@
+import { iterator } from "./_internal/iterator.mjs";
+//#region src/iterator/range.ts
+function range(start, end, step = 1) {
+	if (end == null) {
+		end = start;
+		start = 0;
+	}
+	if (!Number.isInteger(step) || step === 0) throw new Error(`The step value must be a non-zero integer, but got ${step}.`);
+	const finalEnd = end;
+	let current = start;
+	return iterator(function() {
+		if (step > 0 ? current >= finalEnd : current <= finalEnd) return {
+			value: void 0,
+			done: true
+		};
+		const value = current;
+		current += step;
+		return {
+			value,
+			done: false
+		};
+	});
+}
+//#endregion
+export { range };

package/dist/iterator/scan.d.mts

@@ -0,0 +1,23 @@
+//#region src/iterator/scan.d.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]
+ */
+declare function scan<T, U>(source: Iterator<T>, callback: (accumulator: U, value: T, index: number) => U, initial: U): IteratorObject<U, undefined>;
+//#endregion
+export { scan };

package/dist/iterator/scan.d.ts

@@ -0,0 +1,23 @@
+//#region src/iterator/scan.d.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]
+ */
+declare function scan<T, U>(source: Iterator<T>, callback: (accumulator: U, value: T, index: number) => U, initial: U): IteratorObject<U, undefined>;
+//#endregion
+export { scan };