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

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

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

package/dist/fp/iterator/dropWhile.js

@@ -0,0 +1,23 @@
+const require_dropWhile = require("../../iterator/dropWhile.js");
+//#region src/fp/iterator/dropWhile.ts
+/**
+* Creates a function that lazily skips elements of an iterator while `shouldDrop`
+* returns truthy, then yields the rest, for use with {@link pipe}.
+*
+* @template T - The type of elements produced by the source iterator.
+* @param shouldDrop - Called with `(value, index)`; elements are skipped while it returns truthy.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { dropWhile, toArray } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3, 1].values(), dropWhile(x => x < 3), toArray()); // => [3, 1]
+*/
+function dropWhile(shouldDrop) {
+	return function dropWhileInIterator(source) {
+		return require_dropWhile.dropWhile(source, shouldDrop);
+	};
+}
+//#endregion
+exports.dropWhile = dropWhile;

package/dist/fp/iterator/dropWhile.mjs

@@ -0,0 +1,23 @@
+import { dropWhile as dropWhile$1 } from "../../iterator/dropWhile.mjs";
+//#region src/fp/iterator/dropWhile.ts
+/**
+* Creates a function that lazily skips elements of an iterator while `shouldDrop`
+* returns truthy, then yields the rest, for use with {@link pipe}.
+*
+* @template T - The type of elements produced by the source iterator.
+* @param shouldDrop - Called with `(value, index)`; elements are skipped while it returns truthy.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { dropWhile, toArray } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3, 1].values(), dropWhile(x => x < 3), toArray()); // => [3, 1]
+*/
+function dropWhile(shouldDrop) {
+	return function dropWhileInIterator(source) {
+		return dropWhile$1(source, shouldDrop);
+	};
+}
+//#endregion
+export { dropWhile };

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

@@ -0,0 +1,20 @@
+//#region src/fp/iterator/every.d.ts
+/**
+ * Creates a function that consumes an iterator until `predicate` returns falsy
+ * and reports whether every element matched, for use as the terminal step of a
+ * {@link pipe}. It delegates to the native `Iterator.prototype.every` and stops
+ * pulling at the first non-match.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @param predicate - Called with `(value, index)`; falsy short-circuits to `false`.
+ * @returns A function mapping an `Iterator<T>` to a boolean.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { every } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([2, 4, 6].values(), every(x => x % 2 === 0)); // => true
+ */
+declare function every<T>(predicate: (value: T, index: number) => unknown): (source: Iterator<T>) => boolean;
+//#endregion
+export { every };

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

@@ -0,0 +1,20 @@
+//#region src/fp/iterator/every.d.ts
+/**
+ * Creates a function that consumes an iterator until `predicate` returns falsy
+ * and reports whether every element matched, for use as the terminal step of a
+ * {@link pipe}. It delegates to the native `Iterator.prototype.every` and stops
+ * pulling at the first non-match.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @param predicate - Called with `(value, index)`; falsy short-circuits to `false`.
+ * @returns A function mapping an `Iterator<T>` to a boolean.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { every } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([2, 4, 6].values(), every(x => x % 2 === 0)); // => true
+ */
+declare function every<T>(predicate: (value: T, index: number) => unknown): (source: Iterator<T>) => boolean;
+//#endregion
+export { every };

package/dist/fp/iterator/every.js

@@ -0,0 +1,24 @@
+//#region src/fp/iterator/every.ts
+/**
+* Creates a function that consumes an iterator until `predicate` returns falsy
+* and reports whether every element matched, for use as the terminal step of a
+* {@link pipe}. It delegates to the native `Iterator.prototype.every` and stops
+* pulling at the first non-match.
+*
+* @template T - The type of elements produced by the source iterator.
+* @param predicate - Called with `(value, index)`; falsy short-circuits to `false`.
+* @returns A function mapping an `Iterator<T>` to a boolean.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { every } from 'es-toolkit/fp/iterator';
+*
+* pipe([2, 4, 6].values(), every(x => x % 2 === 0)); // => true
+*/
+function every(predicate) {
+	return function everyInIterator(source) {
+		return Iterator.from(source).every(predicate);
+	};
+}
+//#endregion
+exports.every = every;

package/dist/fp/iterator/every.mjs

@@ -0,0 +1,24 @@
+//#region src/fp/iterator/every.ts
+/**
+* Creates a function that consumes an iterator until `predicate` returns falsy
+* and reports whether every element matched, for use as the terminal step of a
+* {@link pipe}. It delegates to the native `Iterator.prototype.every` and stops
+* pulling at the first non-match.
+*
+* @template T - The type of elements produced by the source iterator.
+* @param predicate - Called with `(value, index)`; falsy short-circuits to `false`.
+* @returns A function mapping an `Iterator<T>` to a boolean.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { every } from 'es-toolkit/fp/iterator';
+*
+* pipe([2, 4, 6].values(), every(x => x % 2 === 0)); // => true
+*/
+function every(predicate) {
+	return function everyInIterator(source) {
+		return Iterator.from(source).every(predicate);
+	};
+}
+//#endregion
+export { every };

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

@@ -0,0 +1,37 @@
+//#region src/fp/iterator/filter.d.ts
+/**
+ * Creates a function that lazily keeps the elements of an iterator for which
+ * `predicate` returns truthy, narrowing the element type when `predicate` is a
+ * type guard. For use with {@link pipe}. It delegates to the native
+ * `Iterator.prototype.filter`.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @template S - The narrowed element type when `predicate` is a type guard.
+ * @param predicate - Called with `(value, index)`; truthy keeps the element.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<S>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { filter } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3, 4].values(), filter(x => x % 2 === 0)).toArray(); // => [2, 4]
+ */
+declare function filter<T, S extends T>(predicate: (value: T, index: number) => value is S): (source: Iterator<T>) => IteratorObject<S, undefined>;
+/**
+ * Creates a function that lazily keeps the elements of an iterator for which
+ * `predicate` returns truthy, for use with {@link pipe}. It delegates to the
+ * native `Iterator.prototype.filter`.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @param predicate - Called with `(value, index)`; truthy keeps the element.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { filter } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3, 4].values(), filter(x => x % 2 === 0)).toArray(); // => [2, 4]
+ */
+declare function filter<T>(predicate: (value: T, index: number) => unknown): (source: Iterator<T>) => IteratorObject<T, undefined>;
+//#endregion
+export { filter };

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

@@ -0,0 +1,37 @@
+//#region src/fp/iterator/filter.d.ts
+/**
+ * Creates a function that lazily keeps the elements of an iterator for which
+ * `predicate` returns truthy, narrowing the element type when `predicate` is a
+ * type guard. For use with {@link pipe}. It delegates to the native
+ * `Iterator.prototype.filter`.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @template S - The narrowed element type when `predicate` is a type guard.
+ * @param predicate - Called with `(value, index)`; truthy keeps the element.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<S>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { filter } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3, 4].values(), filter(x => x % 2 === 0)).toArray(); // => [2, 4]
+ */
+declare function filter<T, S extends T>(predicate: (value: T, index: number) => value is S): (source: Iterator<T>) => IteratorObject<S, undefined>;
+/**
+ * Creates a function that lazily keeps the elements of an iterator for which
+ * `predicate` returns truthy, for use with {@link pipe}. It delegates to the
+ * native `Iterator.prototype.filter`.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @param predicate - Called with `(value, index)`; truthy keeps the element.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<T>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { filter } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3, 4].values(), filter(x => x % 2 === 0)).toArray(); // => [2, 4]
+ */
+declare function filter<T>(predicate: (value: T, index: number) => unknown): (source: Iterator<T>) => IteratorObject<T, undefined>;
+//#endregion
+export { filter };

package/dist/fp/iterator/filter.js

@@ -0,0 +1,8 @@
+//#region src/fp/iterator/filter.ts
+function filter(predicate) {
+	return function filterInIterator(source) {
+		return Iterator.from(source).filter(predicate);
+	};
+}
+//#endregion
+exports.filter = filter;

package/dist/fp/iterator/filter.mjs

@@ -0,0 +1,8 @@
+//#region src/fp/iterator/filter.ts
+function filter(predicate) {
+	return function filterInIterator(source) {
+		return Iterator.from(source).filter(predicate);
+	};
+}
+//#endregion
+export { filter };

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

@@ -0,0 +1,20 @@
+//#region src/fp/iterator/find.d.ts
+/**
+ * Creates a function that consumes an iterator until `predicate` returns truthy
+ * and returns that element (or `undefined` if none match), for use as the
+ * terminal step of a {@link pipe}. It delegates to the native
+ * `Iterator.prototype.find` and stops pulling at the first match.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @param predicate - Called with `(value, index)`; truthy selects the element.
+ * @returns A function mapping an `Iterator<T>` to the matching element or `undefined`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { find } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3, 4].values(), find(x => x > 2)); // => 3
+ */
+declare function find<T>(predicate: (value: T, index: number) => unknown): (source: Iterator<T>) => T | undefined;
+//#endregion
+export { find };

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

@@ -0,0 +1,20 @@
+//#region src/fp/iterator/find.d.ts
+/**
+ * Creates a function that consumes an iterator until `predicate` returns truthy
+ * and returns that element (or `undefined` if none match), for use as the
+ * terminal step of a {@link pipe}. It delegates to the native
+ * `Iterator.prototype.find` and stops pulling at the first match.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @param predicate - Called with `(value, index)`; truthy selects the element.
+ * @returns A function mapping an `Iterator<T>` to the matching element or `undefined`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { find } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3, 4].values(), find(x => x > 2)); // => 3
+ */
+declare function find<T>(predicate: (value: T, index: number) => unknown): (source: Iterator<T>) => T | undefined;
+//#endregion
+export { find };

package/dist/fp/iterator/find.js

@@ -0,0 +1,24 @@
+//#region src/fp/iterator/find.ts
+/**
+* Creates a function that consumes an iterator until `predicate` returns truthy
+* and returns that element (or `undefined` if none match), for use as the
+* terminal step of a {@link pipe}. It delegates to the native
+* `Iterator.prototype.find` and stops pulling at the first match.
+*
+* @template T - The type of elements produced by the source iterator.
+* @param predicate - Called with `(value, index)`; truthy selects the element.
+* @returns A function mapping an `Iterator<T>` to the matching element or `undefined`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { find } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3, 4].values(), find(x => x > 2)); // => 3
+*/
+function find(predicate) {
+	return function findInIterator(source) {
+		return Iterator.from(source).find(predicate);
+	};
+}
+//#endregion
+exports.find = find;

package/dist/fp/iterator/find.mjs

@@ -0,0 +1,24 @@
+//#region src/fp/iterator/find.ts
+/**
+* Creates a function that consumes an iterator until `predicate` returns truthy
+* and returns that element (or `undefined` if none match), for use as the
+* terminal step of a {@link pipe}. It delegates to the native
+* `Iterator.prototype.find` and stops pulling at the first match.
+*
+* @template T - The type of elements produced by the source iterator.
+* @param predicate - Called with `(value, index)`; truthy selects the element.
+* @returns A function mapping an `Iterator<T>` to the matching element or `undefined`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { find } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3, 4].values(), find(x => x > 2)); // => 3
+*/
+function find(predicate) {
+	return function findInIterator(source) {
+		return Iterator.from(source).find(predicate);
+	};
+}
+//#endregion
+export { find };

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

@@ -0,0 +1,20 @@
+//#region src/fp/iterator/flatMap.d.ts
+/**
+ * Creates a function that lazily maps each element of an iterator to an iterable
+ * (or iterator) and flattens the results one level, for use with {@link pipe}.
+ * It delegates to the native `Iterator.prototype.flatMap`.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @template U - The type of elements produced by the result.
+ * @param callback - Called with `(value, index)`; returns the iterable to flatten in.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<U>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { flatMap } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2].values(), flatMap(x => [x, x * 10])).toArray(); // => [1, 10, 2, 20]
+ */
+declare function flatMap<T, U>(callback: (value: T, index: number) => Iterator<U, unknown, undefined> | Iterable<U, unknown, undefined>): (source: Iterator<T>) => IteratorObject<U, undefined>;
+//#endregion
+export { flatMap };

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

@@ -0,0 +1,20 @@
+//#region src/fp/iterator/flatMap.d.ts
+/**
+ * Creates a function that lazily maps each element of an iterator to an iterable
+ * (or iterator) and flattens the results one level, for use with {@link pipe}.
+ * It delegates to the native `Iterator.prototype.flatMap`.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @template U - The type of elements produced by the result.
+ * @param callback - Called with `(value, index)`; returns the iterable to flatten in.
+ * @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<U>`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { flatMap } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2].values(), flatMap(x => [x, x * 10])).toArray(); // => [1, 10, 2, 20]
+ */
+declare function flatMap<T, U>(callback: (value: T, index: number) => Iterator<U, unknown, undefined> | Iterable<U, unknown, undefined>): (source: Iterator<T>) => IteratorObject<U, undefined>;
+//#endregion
+export { flatMap };

package/dist/fp/iterator/flatMap.js

@@ -0,0 +1,24 @@
+//#region src/fp/iterator/flatMap.ts
+/**
+* Creates a function that lazily maps each element of an iterator to an iterable
+* (or iterator) and flattens the results one level, for use with {@link pipe}.
+* It delegates to the native `Iterator.prototype.flatMap`.
+*
+* @template T - The type of elements produced by the source iterator.
+* @template U - The type of elements produced by the result.
+* @param callback - Called with `(value, index)`; returns the iterable to flatten in.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<U>`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { flatMap } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2].values(), flatMap(x => [x, x * 10])).toArray(); // => [1, 10, 2, 20]
+*/
+function flatMap(callback) {
+	return function flatMapInIterator(source) {
+		return Iterator.from(source).flatMap(callback);
+	};
+}
+//#endregion
+exports.flatMap = flatMap;

package/dist/fp/iterator/flatMap.mjs

@@ -0,0 +1,24 @@
+//#region src/fp/iterator/flatMap.ts
+/**
+* Creates a function that lazily maps each element of an iterator to an iterable
+* (or iterator) and flattens the results one level, for use with {@link pipe}.
+* It delegates to the native `Iterator.prototype.flatMap`.
+*
+* @template T - The type of elements produced by the source iterator.
+* @template U - The type of elements produced by the result.
+* @param callback - Called with `(value, index)`; returns the iterable to flatten in.
+* @returns A function mapping an `Iterator<T>` to a lazy `IteratorObject<U>`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { flatMap } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2].values(), flatMap(x => [x, x * 10])).toArray(); // => [1, 10, 2, 20]
+*/
+function flatMap(callback) {
+	return function flatMapInIterator(source) {
+		return Iterator.from(source).flatMap(callback);
+	};
+}
+//#endregion
+export { flatMap };

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

@@ -0,0 +1,22 @@
+//#region src/fp/iterator/forEach.d.ts
+/**
+ * Creates a function that consumes an iterator and runs `callback` for each
+ * element, for use as the terminal step of a {@link pipe}. It delegates to the
+ * native `Iterator.prototype.forEach`.
+ *
+ * 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.
+ * @param callback - Called with `(value, index)` for each element.
+ * @returns A function mapping an `Iterator<T>` to `void`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { forEach } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3].values(), forEach(x => console.log(x))); // logs 1, 2, 3
+ */
+declare function forEach<T>(callback: (value: T, index: number) => void): (source: Iterator<T>) => void;
+//#endregion
+export { forEach };

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

@@ -0,0 +1,22 @@
+//#region src/fp/iterator/forEach.d.ts
+/**
+ * Creates a function that consumes an iterator and runs `callback` for each
+ * element, for use as the terminal step of a {@link pipe}. It delegates to the
+ * native `Iterator.prototype.forEach`.
+ *
+ * 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.
+ * @param callback - Called with `(value, index)` for each element.
+ * @returns A function mapping an `Iterator<T>` to `void`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { forEach } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3].values(), forEach(x => console.log(x))); // logs 1, 2, 3
+ */
+declare function forEach<T>(callback: (value: T, index: number) => void): (source: Iterator<T>) => void;
+//#endregion
+export { forEach };

package/dist/fp/iterator/forEach.js

@@ -0,0 +1,26 @@
+//#region src/fp/iterator/forEach.ts
+/**
+* Creates a function that consumes an iterator and runs `callback` for each
+* element, for use as the terminal step of a {@link pipe}. It delegates to the
+* native `Iterator.prototype.forEach`.
+*
+* 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.
+* @param callback - Called with `(value, index)` for each element.
+* @returns A function mapping an `Iterator<T>` to `void`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { forEach } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3].values(), forEach(x => console.log(x))); // logs 1, 2, 3
+*/
+function forEach(callback) {
+	return function forEachInIterator(source) {
+		Iterator.from(source).forEach(callback);
+	};
+}
+//#endregion
+exports.forEach = forEach;

package/dist/fp/iterator/forEach.mjs

@@ -0,0 +1,26 @@
+//#region src/fp/iterator/forEach.ts
+/**
+* Creates a function that consumes an iterator and runs `callback` for each
+* element, for use as the terminal step of a {@link pipe}. It delegates to the
+* native `Iterator.prototype.forEach`.
+*
+* 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.
+* @param callback - Called with `(value, index)` for each element.
+* @returns A function mapping an `Iterator<T>` to `void`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { forEach } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3].values(), forEach(x => console.log(x))); // logs 1, 2, 3
+*/
+function forEach(callback) {
+	return function forEachInIterator(source) {
+		Iterator.from(source).forEach(callback);
+	};
+}
+//#endregion
+export { forEach };

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

@@ -0,0 +1,19 @@
+//#region src/fp/iterator/head.d.ts
+/**
+ * Creates a function that returns the first element of an iterator (or
+ * `undefined` if it is empty), for use as the terminal step of a {@link pipe}.
+ * It pulls a single element and then closes the source via its `return` method,
+ * so it is safe on an infinite iterator.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @returns A function mapping an `Iterator<T>` to its first element or `undefined`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { filter, head } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3, 4].values(), filter(x => x % 2 === 0), head()); // => 2
+ */
+declare function head<T>(): (source: Iterator<T>) => T | undefined;
+//#endregion
+export { head };

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

@@ -0,0 +1,19 @@
+//#region src/fp/iterator/head.d.ts
+/**
+ * Creates a function that returns the first element of an iterator (or
+ * `undefined` if it is empty), for use as the terminal step of a {@link pipe}.
+ * It pulls a single element and then closes the source via its `return` method,
+ * so it is safe on an infinite iterator.
+ *
+ * @template T - The type of elements produced by the source iterator.
+ * @returns A function mapping an `Iterator<T>` to its first element or `undefined`.
+ *
+ * @example
+ * import { pipe } from 'es-toolkit/fp';
+ * import { filter, head } from 'es-toolkit/fp/iterator';
+ *
+ * pipe([1, 2, 3, 4].values(), filter(x => x % 2 === 0), head()); // => 2
+ */
+declare function head<T>(): (source: Iterator<T>) => T | undefined;
+//#endregion
+export { head };

package/dist/fp/iterator/head.js

@@ -0,0 +1,24 @@
+const require_head = require("../../iterator/head.js");
+//#region src/fp/iterator/head.ts
+/**
+* Creates a function that returns the first element of an iterator (or
+* `undefined` if it is empty), for use as the terminal step of a {@link pipe}.
+* It pulls a single element and then closes the source via its `return` method,
+* so it is safe on an infinite iterator.
+*
+* @template T - The type of elements produced by the source iterator.
+* @returns A function mapping an `Iterator<T>` to its first element or `undefined`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { filter, head } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3, 4].values(), filter(x => x % 2 === 0), head()); // => 2
+*/
+function head() {
+	return function headInIterator(source) {
+		return require_head.head(source);
+	};
+}
+//#endregion
+exports.head = head;

package/dist/fp/iterator/head.mjs

@@ -0,0 +1,24 @@
+import { head as head$1 } from "../../iterator/head.mjs";
+//#region src/fp/iterator/head.ts
+/**
+* Creates a function that returns the first element of an iterator (or
+* `undefined` if it is empty), for use as the terminal step of a {@link pipe}.
+* It pulls a single element and then closes the source via its `return` method,
+* so it is safe on an infinite iterator.
+*
+* @template T - The type of elements produced by the source iterator.
+* @returns A function mapping an `Iterator<T>` to its first element or `undefined`.
+*
+* @example
+* import { pipe } from 'es-toolkit/fp';
+* import { filter, head } from 'es-toolkit/fp/iterator';
+*
+* pipe([1, 2, 3, 4].values(), filter(x => x % 2 === 0), head()); // => 2
+*/
+function head() {
+	return function headInIterator(source) {
+		return head$1(source);
+	};
+}
+//#endregion
+export { head };