es-toolkit 1.50.0 → 1.51.0-dev.2069

package/dist/index.mjs

@@ -14,7 +14,7 @@ import { dropRightWhile } from "./array/dropRightWhile.mjs";
 import { dropWhile } from "./array/dropWhile.mjs";
 import { fill } from "./array/fill.mjs";
 import { Semaphore } from "./promise/semaphore.mjs";
-import { limitAsync } from "./array/limitAsync.mjs";
+import { limitAsync } from "./promise/limitAsync.mjs";
 import { filterAsync } from "./array/filterAsync.mjs";
 import { flatten } from "./array/flatten.mjs";
 import { flatMap } from "./array/flatMap.mjs";
@@ -116,12 +116,15 @@ import { clone } from "./object/clone.mjs";
 import { isBuffer } from "./predicate/isBuffer.mjs";
 import { cloneDeepWith } from "./object/cloneDeepWith.mjs";
 import { cloneDeep } from "./object/cloneDeep.mjs";
+import { deepFreeze } from "./object/deepFreeze.mjs";
 import { findKey } from "./object/findKey.mjs";
 import { isPlainObject } from "./predicate/isPlainObject.mjs";
 import { flattenObject } from "./object/flattenObject.mjs";
 import { invert } from "./object/invert.mjs";
 import { mapKeys } from "./object/mapKeys.mjs";
+import { mapKeysAsync } from "./object/mapKeysAsync.mjs";
 import { mapValues } from "./object/mapValues.mjs";
+import { mapValuesAsync } from "./object/mapValuesAsync.mjs";
 import { merge } from "./object/merge.mjs";
 import { mergeWith } from "./object/mergeWith.mjs";
 import { omit } from "./object/omit.mjs";
@@ -133,7 +136,13 @@ import { capitalize } from "./string/capitalize.mjs";
 import { words } from "./string/words.mjs";
 import { camelCase } from "./string/camelCase.mjs";
 import { toCamelCaseKeys } from "./object/toCamelCaseKeys.mjs";
+import { constantCase } from "./string/constantCase.mjs";
+import { toConstantCaseKeys } from "./object/toConstantCaseKeys.mjs";
+import { kebabCase } from "./string/kebabCase.mjs";
+import { toKebabCaseKeys } from "./object/toKebabCaseKeys.mjs";
 import { toMerged } from "./object/toMerged.mjs";
+import { pascalCase } from "./string/pascalCase.mjs";
+import { toPascalCaseKeys } from "./object/toPascalCaseKeys.mjs";
 import { snakeCase } from "./string/snakeCase.mjs";
 import { toSnakeCaseKeys } from "./object/toSnakeCaseKeys.mjs";
 import "./object/index.mjs";
@@ -172,15 +181,13 @@ import { Mutex } from "./promise/mutex.mjs";
 import { timeout } from "./promise/timeout.mjs";
 import { withTimeout } from "./promise/withTimeout.mjs";
 import "./promise/index.mjs";
-import { constantCase } from "./string/constantCase.mjs";
 import { deburr } from "./string/deburr.mjs";
+import { dedent } from "./string/dedent.mjs";
 import { escape } from "./string/escape.mjs";
 import { escapeRegExp } from "./string/escapeRegExp.mjs";
-import { kebabCase } from "./string/kebabCase.mjs";
 import { lowerCase } from "./string/lowerCase.mjs";
 import { lowerFirst } from "./string/lowerFirst.mjs";
 import { pad } from "./string/pad.mjs";
-import { pascalCase } from "./string/pascalCase.mjs";
 import { reverseString } from "./string/reverseString.mjs";
 import { startCase } from "./string/startCase.mjs";
 import { trimEnd } from "./string/trimEnd.mjs";
@@ -194,4 +201,4 @@ import { attempt } from "./util/attempt.mjs";
 import { attemptAsync } from "./util/attemptAsync.mjs";
 import { invariant } from "./util/invariant.mjs";
 import "./util/index.mjs";
-export { AbortError, Mutex, Semaphore, TimeoutError, after, allKeyed, ary, invariant as assert, asyncNoop, at, attempt, attemptAsync, before, camelCase, capitalize, cartesianProduct, chunk, chunkBy, clamp, clone, cloneDeep, cloneDeepWith, combinations, compact, constantCase, countBy, curry, curryRight, debounce, deburr, delay, difference, differenceBy, differenceWith, drop, dropRight, dropRightWhile, dropWhile, escape, escapeRegExp, fill, filterAsync, findKey, flatMap, flatMapAsync, flatMapDeep, flatten, flattenDeep, flattenObject, flow, flowRight, forEachAsync, forEachRight, groupBy, head, identity, inRange, initial, intersection, intersectionBy, intersectionWith, invariant, invert, isArrayBuffer, isBlob, isBoolean, isBrowser, isBuffer, isDate, isEmptyObject, isEqual, isEqualWith, isError, isFile, isFunction, isIterable, isJSON, isJSONArray, isJSONObject, isJSONValue, isLength, isMap, isNil, isNode, isNotNil, isNull, isNumber, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isString, isSubset, isSubsetWith, isSymbol, isTypedArray, isUndefined, isWeakMap, isWeakSet, kebabCase, keyBy, last, limitAsync, lowerCase, lowerFirst, mapAsync, mapKeys, mapValues, maxBy, mean, meanBy, median, medianBy, memoize, merge, mergeWith, minBy, negate, noop, omit, omitBy, once, orderBy, pad, partial, partialRight, partition, pascalCase, percentile, pick, pickBy, pull, pullAt, random, randomInt, range, rangeRight, reduceAsync, remove, rest, retry, reverseString, round, sample, sampleSize, shuffle, snakeCase, sortBy, sortKeys, spread, startCase, sum, sumBy, tail, take, takeRight, takeRightWhile, takeWhile, throttle, timeout, toCamelCaseKeys, toFilled, toMerged, toSnakeCaseKeys, trim, trimEnd, trimStart, unary, unescape, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unzip, unzipWith, upperCase, upperFirst, windowed, withTimeout, without, words, xor, xorBy, xorWith, zip, zipObject, zipWith };
+export { AbortError, Mutex, Semaphore, TimeoutError, after, allKeyed, ary, invariant as assert, asyncNoop, at, attempt, attemptAsync, before, camelCase, capitalize, cartesianProduct, chunk, chunkBy, clamp, clone, cloneDeep, cloneDeepWith, combinations, compact, constantCase, countBy, curry, curryRight, debounce, deburr, dedent, deepFreeze, delay, difference, differenceBy, differenceWith, drop, dropRight, dropRightWhile, dropWhile, escape, escapeRegExp, fill, filterAsync, findKey, flatMap, flatMapAsync, flatMapDeep, flatten, flattenDeep, flattenObject, flow, flowRight, forEachAsync, forEachRight, groupBy, head, identity, inRange, initial, intersection, intersectionBy, intersectionWith, invariant, invert, isArrayBuffer, isBlob, isBoolean, isBrowser, isBuffer, isDate, isEmptyObject, isEqual, isEqualWith, isError, isFile, isFunction, isIterable, isJSON, isJSONArray, isJSONObject, isJSONValue, isLength, isMap, isNil, isNode, isNotNil, isNull, isNumber, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isString, isSubset, isSubsetWith, isSymbol, isTypedArray, isUndefined, isWeakMap, isWeakSet, kebabCase, keyBy, last, limitAsync, lowerCase, lowerFirst, mapAsync, mapKeys, mapKeysAsync, mapValues, mapValuesAsync, maxBy, mean, meanBy, median, medianBy, memoize, merge, mergeWith, minBy, negate, noop, omit, omitBy, once, orderBy, pad, partial, partialRight, partition, pascalCase, percentile, pick, pickBy, pull, pullAt, random, randomInt, range, rangeRight, reduceAsync, remove, rest, retry, reverseString, round, sample, sampleSize, shuffle, snakeCase, sortBy, sortKeys, spread, startCase, sum, sumBy, tail, take, takeRight, takeRightWhile, takeWhile, throttle, timeout, toCamelCaseKeys, toConstantCaseKeys, toFilled, toKebabCaseKeys, toMerged, toPascalCaseKeys, toSnakeCaseKeys, trim, trimEnd, trimStart, unary, unescape, union, unionBy, unionWith, uniq, uniqBy, uniqWith, unzip, unzipWith, upperCase, upperFirst, windowed, withTimeout, without, words, xor, xorBy, xorWith, zip, zipObject, zipWith };

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;

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;