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

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

package/dist/iterator/scan.js

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

package/dist/iterator/scan.mjs

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

package/dist/iterator/takeWhile.d.mts

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

package/dist/iterator/takeWhile.d.ts

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

package/dist/iterator/takeWhile.js

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

package/dist/iterator/takeWhile.mjs

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

package/dist/iterator/uniqBy.d.mts

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

package/dist/iterator/uniqBy.d.ts

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

package/dist/iterator/uniqBy.js

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

package/dist/iterator/uniqBy.mjs

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

package/dist/iterator/zip.d.mts

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

package/dist/iterator/zip.d.ts

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

package/dist/iterator/zip.js

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

package/dist/iterator/zip.mjs

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

package/fp/iterator.d.ts

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