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

package/dist/fp/iterator/take.js

@@ -0,0 +1,25 @@
+//#region src/fp/iterator/take.ts
+/**
+* Creates a function that lazily yields the first `limit` elements of an
+* iterator, for use with {@link pipe}. It delegates to the native
+* `Iterator.prototype.take`, which stops pulling from the source once `limit`
+* elements have been produced.
+*
+* @template T - The type of elements produced by the source iterator.
+* @param limit - The number of elements to take; must be a non-negative integer.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+* @throws {RangeError} Throws if `limit` is negative or `NaN` (native behavior).
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { take } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3, 4, 5].values(), take(3)).toArray(); // => [1, 2, 3]
+*/
+function take(limit) {
+	return function takeInIterator(source) {
+		return Iterator.from(source).take(limit);
+	};
+}
+//#endregion
+exports.take = take;

package/dist/fp/iterator/take.mjs

@@ -0,0 +1,25 @@
+//#region src/fp/iterator/take.ts
+/**
+* Creates a function that lazily yields the first `limit` elements of an
+* iterator, for use with {@link pipe}. It delegates to the native
+* `Iterator.prototype.take`, which stops pulling from the source once `limit`
+* elements have been produced.
+*
+* @template T - The type of elements produced by the source iterator.
+* @param limit - The number of elements to take; must be a non-negative integer.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+* @throws {RangeError} Throws if `limit` is negative or `NaN` (native behavior).
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { take } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3, 4, 5].values(), take(3)).toArray(); // => [1, 2, 3]
+*/
+function take(limit) {
+	return function takeInIterator(source) {
+		return Iterator.from(source).take(limit);
+	};
+}
+//#endregion
+export { take };

package/dist/fp/iterator/takeWhile.d.mts

@@ -0,0 +1,19 @@
+//#region src/fp/iterator/takeWhile.d.ts
+/**
+ * Creates a function that lazily yields elements of an iterator while
+ * `shouldContinue` returns truthy, stopping at the first failure, for use with
+ * {@link pipe}.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @param shouldContinue - Called with `(value, index)`; iteration stops once it returns falsy.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { takeWhile, toArray } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3, 1].values(), takeWhile(x => x < 3), toArray()); // => [1, 2]
+ */
+declare function takeWhile<T>(shouldContinue: (value: T, index: number) => boolean): (source: Iterator<T>) => IteratorObject<T, undefined>;
+//#endregion
+export { takeWhile };

package/dist/fp/iterator/takeWhile.d.ts

@@ -0,0 +1,19 @@
+//#region src/fp/iterator/takeWhile.d.ts
+/**
+ * Creates a function that lazily yields elements of an iterator while
+ * `shouldContinue` returns truthy, stopping at the first failure, for use with
+ * {@link pipe}.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @param shouldContinue - Called with `(value, index)`; iteration stops once it returns falsy.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { takeWhile, toArray } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3, 1].values(), takeWhile(x => x < 3), toArray()); // => [1, 2]
+ */
+declare function takeWhile<T>(shouldContinue: (value: T, index: number) => boolean): (source: Iterator<T>) => IteratorObject<T, undefined>;
+//#endregion
+export { takeWhile };

package/dist/fp/iterator/takeWhile.js

@@ -0,0 +1,24 @@
+const require_takeWhile = require("../../iterator/takeWhile.js");
+//#region src/fp/iterator/takeWhile.ts
+/**
+* Creates a function that lazily yields elements of an iterator while
+* `shouldContinue` returns truthy, stopping at the first failure, for use with
+* {@link pipe}.
+*
+* @template T - The type of elements produced by the source iterator.
+* @param shouldContinue - Called with `(value, index)`; iteration stops once it returns falsy.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { takeWhile, toArray } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3, 1].values(), takeWhile(x => x < 3), toArray()); // => [1, 2]
+*/
+function takeWhile(shouldContinue) {
+	return function takeWhileInIterator(source) {
+		return require_takeWhile.takeWhile(source, shouldContinue);
+	};
+}
+//#endregion
+exports.takeWhile = takeWhile;

package/dist/fp/iterator/takeWhile.mjs

@@ -0,0 +1,24 @@
+import { takeWhile as takeWhile$1 } from "../../iterator/takeWhile.mjs";
+//#region src/fp/iterator/takeWhile.ts
+/**
+* Creates a function that lazily yields elements of an iterator while
+* `shouldContinue` returns truthy, stopping at the first failure, for use with
+* {@link pipe}.
+*
+* @template T - The type of elements produced by the source iterator.
+* @param shouldContinue - Called with `(value, index)`; iteration stops once it returns falsy.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { takeWhile, toArray } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3, 1].values(), takeWhile(x => x < 3), toArray()); // => [1, 2]
+*/
+function takeWhile(shouldContinue) {
+	return function takeWhileInIterator(source) {
+		return takeWhile$1(source, shouldContinue);
+	};
+}
+//#endregion
+export { takeWhile };

package/dist/fp/iterator/toArray.d.mts

@@ -0,0 +1,21 @@
+//#region src/fp/iterator/toArray.d.ts
+/**
+ * Creates a function that consumes an iterator and collects its elements into an
+ * array, for use as the terminal step of a {@link pipe}. It delegates to the
+ * native `Iterator.prototype.toArray`.
+ *
+ * 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 source iterator.
+ * @returns A function mapping an `Iterator<T>` to a `T[]`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { map, toArray } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3].values(), map(x => x * 2), toArray()); // => [2, 4, 6]
+ */
+declare function toArray<T>(): (source: Iterator<T>) => T[];
+//#endregion
+export { toArray };

package/dist/fp/iterator/toArray.d.ts

@@ -0,0 +1,21 @@
+//#region src/fp/iterator/toArray.d.ts
+/**
+ * Creates a function that consumes an iterator and collects its elements into an
+ * array, for use as the terminal step of a {@link pipe}. It delegates to the
+ * native `Iterator.prototype.toArray`.
+ *
+ * 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 source iterator.
+ * @returns A function mapping an `Iterator<T>` to a `T[]`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { map, toArray } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3].values(), map(x => x * 2), toArray()); // => [2, 4, 6]
+ */
+declare function toArray<T>(): (source: Iterator<T>) => T[];
+//#endregion
+export { toArray };

package/dist/fp/iterator/toArray.js

@@ -0,0 +1,25 @@
+//#region src/fp/iterator/toArray.ts
+/**
+* Creates a function that consumes an iterator and collects its elements into an
+* array, for use as the terminal step of a {@link pipe}. It delegates to the
+* native `Iterator.prototype.toArray`.
+*
+* 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 source iterator.
+* @returns A function mapping an `Iterator<T>` to a `T[]`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { map, toArray } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3].values(), map(x => x * 2), toArray()); // => [2, 4, 6]
+*/
+function toArray() {
+	return function toArrayInIterator(source) {
+		return Iterator.from(source).toArray();
+	};
+}
+//#endregion
+exports.toArray = toArray;

package/dist/fp/iterator/toArray.mjs

@@ -0,0 +1,25 @@
+//#region src/fp/iterator/toArray.ts
+/**
+* Creates a function that consumes an iterator and collects its elements into an
+* array, for use as the terminal step of a {@link pipe}. It delegates to the
+* native `Iterator.prototype.toArray`.
+*
+* 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 source iterator.
+* @returns A function mapping an `Iterator<T>` to a `T[]`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { map, toArray } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3].values(), map(x => x * 2), toArray()); // => [2, 4, 6]
+*/
+function toArray() {
+	return function toArrayInIterator(source) {
+		return Iterator.from(source).toArray();
+	};
+}
+//#endregion
+export { toArray };

package/dist/fp/iterator/uniqBy.d.mts

@@ -0,0 +1,20 @@
+//#region src/fp/iterator/uniqBy.d.ts
+/**
+ * Creates a function that lazily yields the elements of an iterator whose mapped
+ * key has not been seen before, preserving first-occurrence order, for use with
+ * {@link pipe}. Keys are compared with SameValueZero semantics.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @template K - The type of the key used for comparison.
+ * @param getKey - Maps an element to the key used to detect duplicates.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { uniqBy, toArray } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1.1, 1.2, 2.3].values(), uniqBy(Math.floor), toArray()); // => [1.1, 2.3]
+ */
+declare function uniqBy<T, K>(getKey: (value: T) => K): (source: Iterator<T>) => IteratorObject<T, undefined>;
+//#endregion
+export { uniqBy };

package/dist/fp/iterator/uniqBy.d.ts

@@ -0,0 +1,20 @@
+//#region src/fp/iterator/uniqBy.d.ts
+/**
+ * Creates a function that lazily yields the elements of an iterator whose mapped
+ * key has not been seen before, preserving first-occurrence order, for use with
+ * {@link pipe}. Keys are compared with SameValueZero semantics.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @template K - The type of the key used for comparison.
+ * @param getKey - Maps an element to the key used to detect duplicates.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { uniqBy, toArray } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1.1, 1.2, 2.3].values(), uniqBy(Math.floor), toArray()); // => [1.1, 2.3]
+ */
+declare function uniqBy<T, K>(getKey: (value: T) => K): (source: Iterator<T>) => IteratorObject<T, undefined>;
+//#endregion
+export { uniqBy };

package/dist/fp/iterator/uniqBy.js

@@ -0,0 +1,25 @@
+const require_uniqBy = require("../../iterator/uniqBy.js");
+//#region src/fp/iterator/uniqBy.ts
+/**
+* Creates a function that lazily yields the elements of an iterator whose mapped
+* key has not been seen before, preserving first-occurrence order, for use with
+* {@link pipe}. Keys are compared with SameValueZero semantics.
+*
+* @template T - The type of elements produced by the source iterator.
+* @template K - The type of the key used for comparison.
+* @param getKey - Maps an element to the key used to detect duplicates.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { uniqBy, toArray } from 'es-toolkit/fp/iterator';
+*
+* pipe([1.1, 1.2, 2.3].values(), uniqBy(Math.floor), toArray()); // => [1.1, 2.3]
+*/
+function uniqBy(getKey) {
+	return function uniqByInIterator(source) {
+		return require_uniqBy.uniqBy(source, getKey);
+	};
+}
+//#endregion
+exports.uniqBy = uniqBy;

package/dist/fp/iterator/uniqBy.mjs

@@ -0,0 +1,25 @@
+import { uniqBy as uniqBy$1 } from "../../iterator/uniqBy.mjs";
+//#region src/fp/iterator/uniqBy.ts
+/**
+* Creates a function that lazily yields the elements of an iterator whose mapped
+* key has not been seen before, preserving first-occurrence order, for use with
+* {@link pipe}. Keys are compared with SameValueZero semantics.
+*
+* @template T - The type of elements produced by the source iterator.
+* @template K - The type of the key used for comparison.
+* @param getKey - Maps an element to the key used to detect duplicates.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { uniqBy, toArray } from 'es-toolkit/fp/iterator';
+*
+* pipe([1.1, 1.2, 2.3].values(), uniqBy(Math.floor), toArray()); // => [1.1, 2.3]
+*/
+function uniqBy(getKey) {
+	return function uniqByInIterator(source) {
+		return uniqBy$1(source, getKey);
+	};
+}
+//#endregion
+export { uniqBy };

package/dist/fp/iterator/zip.d.mts

@@ -0,0 +1,20 @@
+//#region src/fp/iterator/zip.d.ts
+/**
+ * Creates a function that lazily pairs the elements of the piped iterator with
+ * those of `other`, for use with {@link pipe}. Iteration stops as soon as either
+ * iterator is exhausted.
+ *
+ * @template T - The type of elements produced by the piped iterator.
+ * @template U - The type of elements produced by `other`.
+ * @param other - The iterator to pair with the piped one.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<[T, U]>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { zip, toArray } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3].values(), zip(['a', 'b'].values()), toArray()); // => [[1, 'a'], [2, 'b']]
+ */
+declare function zip<T, U>(other: Iterator<U>): (source: Iterator<T>) => IteratorObject<[T, U], undefined>;
+//#endregion
+export { zip };

package/dist/fp/iterator/zip.d.ts

@@ -0,0 +1,20 @@
+//#region src/fp/iterator/zip.d.ts
+/**
+ * Creates a function that lazily pairs the elements of the piped iterator with
+ * those of `other`, for use with {@link pipe}. Iteration stops as soon as either
+ * iterator is exhausted.
+ *
+ * @template T - The type of elements produced by the piped iterator.
+ * @template U - The type of elements produced by `other`.
+ * @param other - The iterator to pair with the piped one.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<[T, U]>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { zip, toArray } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3].values(), zip(['a', 'b'].values()), toArray()); // => [[1, 'a'], [2, 'b']]
+ */
+declare function zip<T, U>(other: Iterator<U>): (source: Iterator<T>) => IteratorObject<[T, U], undefined>;
+//#endregion
+export { zip };

package/dist/fp/iterator/zip.js

@@ -0,0 +1,25 @@
+const require_zip = require("../../iterator/zip.js");
+//#region src/fp/iterator/zip.ts
+/**
+* Creates a function that lazily pairs the elements of the piped iterator with
+* those of `other`, for use with {@link pipe}. Iteration stops as soon as either
+* iterator is exhausted.
+*
+* @template T - The type of elements produced by the piped iterator.
+* @template U - The type of elements produced by `other`.
+* @param other - The iterator to pair with the piped one.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<[T, U]>`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { zip, toArray } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3].values(), zip(['a', 'b'].values()), toArray()); // => [[1, 'a'], [2, 'b']]
+*/
+function zip(other) {
+	return function zipInIterator(source) {
+		return require_zip.zip(source, other);
+	};
+}
+//#endregion
+exports.zip = zip;

package/dist/fp/iterator/zip.mjs

@@ -0,0 +1,25 @@
+import { zip as zip$1 } from "../../iterator/zip.mjs";
+//#region src/fp/iterator/zip.ts
+/**
+* Creates a function that lazily pairs the elements of the piped iterator with
+* those of `other`, for use with {@link pipe}. Iteration stops as soon as either
+* iterator is exhausted.
+*
+* @template T - The type of elements produced by the piped iterator.
+* @template U - The type of elements produced by `other`.
+* @param other - The iterator to pair with the piped one.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<[T, U]>`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { zip, toArray } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3].values(), zip(['a', 'b'].values()), toArray()); // => [[1, 'a'], [2, 'b']]
+*/
+function zip(other) {
+	return function zipInIterator(source) {
+		return zip$1(source, other);
+	};
+}
+//#endregion
+export { zip };

package/dist/iterator/_internal/iterator.js

@@ -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
+exports.iterator = iterator;

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/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;