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

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;

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,12 @@
+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 { chunk, count, dropWhile, head, iterate, partition, range, scan, takeWhile, uniqBy, zip };

package/dist/iterator/index.d.ts

@@ -0,0 +1,12 @@
+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 { chunk, count, dropWhile, head, iterate, partition, range, scan, takeWhile, uniqBy, zip };

package/dist/iterator/index.js

@@ -0,0 +1,23 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+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.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,12 @@
+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 { 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 };