es-toolkit 1.29.0-dev.930 → 1.29.0-dev.932

package/dist/compat/array/map.d.mts

@@ -0,0 +1,182 @@
+/**
+ * Maps each element in a readonly array to a new array of values using an iteratee function.
+ *
+ * @param {readonly T[]} collection - The collection to iterate over.
+ * @param {(value: T, index: number, collection: readonly T[]) => U} iteratee - The function invoked per iteration.
+ * @returns {U[]} - Returns the new mapped array.
+ *
+ * @example
+ * const array = [1, 2, 3];
+ * map(array, value => value * 2); // => [2, 4, 6]
+ */
+declare function map<T, U>(collection: readonly T[], iteratee: (value: T, index: number, collection: readonly T[]) => U): U[];
+/**
+ * Maps each element in a readonly array to a boolean array based on a partial object match.
+ *
+ * @param {readonly T[]} collection - The collection to iterate over.
+ * @param {Partial<T>} iteratee - The partial object to match against each element.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const objects = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(objects, { a: 1 }); // => [true, false, false]
+ */
+declare function map<T>(collection: readonly T[], iteratee: Partial<T>): boolean[];
+/**
+ * Maps each element in a readonly array to a boolean array based on a property-value pair match.
+ *
+ * @param {readonly T[]} collection - The collection to iterate over.
+ * @param {[keyof T, unknown]} iteratee - The property-value pair to match against each element.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const objects = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(objects, ['a', 1]); // => [true, false, false]
+ */
+declare function map<T>(collection: readonly T[], iteratee: [keyof T, unknown]): boolean[];
+/**
+ * Maps each element in a readonly array to an array of property values.
+ *
+ * @param {readonly T[]} collection - The collection to iterate over.
+ * @param {K} iteratee - The key of the property to extract from each element.
+ * @returns {Array<T[K]>} - Returns an array of property values.
+ *
+ * @example
+ * const objects = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(objects, 'a'); // => [1, 2, 3]
+ */
+declare function map<T, K extends keyof T>(collection: readonly T[], iteratee: K): Array<T[K]>;
+/**
+ * Maps each element in a readonly array to itself if no iteratee is provided.
+ *
+ * @param {readonly T[]} collection - The collection to iterate over.
+ * @param {null | undefined} [iteratee] - Optional iteratee.
+ * @returns {T[]} - Returns the original array.
+ *
+ * @example
+ * const numbers = [1, 2, 3];
+ * map(numbers); // => [1, 2, 3]
+ */
+declare function map<T>(collection: readonly T[], iteratee?: null | undefined): T[];
+/**
+ * Maps each element in an ArrayLike object to a new array of values using an iteratee function.
+ *
+ * @param {ArrayLike<T>} collection - The collection to iterate over.
+ * @param {(value: T, index: number, collection: ArrayLike<T>) => U} iteratee - The function invoked per iteration.
+ * @returns {U[]} - Returns the new mapped array.
+ *
+ * @example
+ * const arrayLike = {0: 1, 1: 2, 2: 3, length: 3};
+ * map(arrayLike, value => value * 2); // => [2, 4, 6]
+ */
+declare function map<T, U>(collection: ArrayLike<T>, iteratee: (value: T, index: number, collection: ArrayLike<T>) => U): U[];
+/**
+ * Maps each element in an ArrayLike object to a boolean array based on a partial object match.
+ *
+ * @param {ArrayLike<T>} collection - The collection to iterate over.
+ * @param {Partial<T>} iteratee - The partial object to match against each element.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const arrayLike = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(arrayLike, { a: 1 }); // => [true, false, false]
+ */
+declare function map<T>(collection: ArrayLike<T>, iteratee: Partial<T>): boolean[];
+/**
+ * Maps each element in an ArrayLike object to a boolean array based on a property-value pair match.
+ *
+ * @param {ArrayLike<T>} collection - The collection to iterate over.
+ * @param {[keyof T, unknown]} iteratee - The property-value pair to match against each element.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const arrayLike = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(arrayLike, ['a', 1]); // => [true, false, false]
+ */
+declare function map<T>(collection: ArrayLike<T>, iteratee: [keyof T, unknown]): boolean[];
+/**
+ * Maps each element in an ArrayLike object to an array of property values.
+ *
+ * @param {ArrayLike<T>} collection - The collection to iterate over.
+ * @param {K} iteratee - The key of the property to extract from each element.
+ * @returns {Array<T[K]>} - Returns an array of property values.
+ *
+ * @example
+ * const arrayLike = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(arrayLike, 'a'); // => [1, 2, 3]
+ */
+declare function map<T, K extends keyof T>(collection: ArrayLike<T>, iteratee: K): Array<T[K]>;
+/**
+ * Maps each element in an ArrayLike object to itself if no iteratee is provided.
+ *
+ * @param {ArrayLike<T>} collection - The collection to iterate over.
+ * @param {null | undefined} [iteratee] - Optional iteratee.
+ * @returns {ArrayLike<T>} - Returns the original ArrayLike object.
+ *
+ * @example
+ * const arrayLike = {0: 1, 1: 2, 2: 3, length: 3};
+ * map(arrayLike); // => {0: 1, 1: 2, 2: 3, length: 3}
+ */
+declare function map<T, U>(collection: ArrayLike<T>, iteratee?: null | undefined): ArrayLike<T>;
+/**
+ * Maps each value in an object to a new array of values using an iteratee function.
+ *
+ * @param {T} collection - The object to iterate over.
+ * @param {(value: T[keyof T], key: string, collection: T) => U} iteratee - The function invoked per iteration.
+ * @returns {U[]} - Returns the new mapped array.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * map(obj, (value, key) => `${key}: ${value}`); // => ['a: 1', 'b: 2', 'c: 3']
+ */
+declare function map<T extends object, U>(collection: T, iteratee: (value: T[keyof T], key: string, collection: T) => U): U[];
+/**
+ * Maps each value in an object to a boolean array based on a partial object match.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {Partial<T[keyof T]>} iteratee - The partial object to match against each value.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const obj = { a: { x: 1 }, b: { x: 2 }, c: { x: 3 } };
+ * map(obj, { x: 1 }); // => [true, false, false]
+ */
+declare function map<T>(object: T, iteratee: Partial<T[keyof T]>): boolean[];
+/**
+ * Maps each value in an object to a boolean array based on a property-value pair match.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {[keyof T[keyof T], unknown]} iteratee - The property-value pair to match against each value.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const obj = { a: { x: 1 }, b: { x: 2 }, c: { x: 3 } };
+ * map(obj, ['x', 1]); // => [true, false, false]
+ */
+declare function map<T>(object: T, iteratee: [keyof T[keyof T], unknown]): boolean[];
+/**
+ * Maps each value in an object to an array of property values.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {K} iteratee - The key of the property to extract from each value.
+ * @returns {Array<T[keyof T][K]>} - Returns an array of property values.
+ *
+ * @example
+ * const obj = { a: { x: 1 }, b: { x: 2 }, c: { x: 3 } };
+ * map(obj, 'x'); // => [1, 2, 3]
+ */
+declare function map<T, K extends keyof T[keyof T]>(object: T, iteratee: K): Array<T[keyof T][K]>;
+/**
+ * Maps each value in an object to itself if no iteratee is provided.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {null | undefined} [iteratee] - Optional iteratee.
+ * @returns {U[]} - Returns the original object values as an array.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * map(obj); // => [1, 2, 3]
+ */
+declare function map<T extends object, U>(object: T, iteratee?: null | undefined): U[];
+
+export { map };

package/dist/compat/array/map.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Maps each element in a readonly array to a new array of values using an iteratee function.
+ *
+ * @param {readonly T[]} collection - The collection to iterate over.
+ * @param {(value: T, index: number, collection: readonly T[]) => U} iteratee - The function invoked per iteration.
+ * @returns {U[]} - Returns the new mapped array.
+ *
+ * @example
+ * const array = [1, 2, 3];
+ * map(array, value => value * 2); // => [2, 4, 6]
+ */
+declare function map<T, U>(collection: readonly T[], iteratee: (value: T, index: number, collection: readonly T[]) => U): U[];
+/**
+ * Maps each element in a readonly array to a boolean array based on a partial object match.
+ *
+ * @param {readonly T[]} collection - The collection to iterate over.
+ * @param {Partial<T>} iteratee - The partial object to match against each element.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const objects = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(objects, { a: 1 }); // => [true, false, false]
+ */
+declare function map<T>(collection: readonly T[], iteratee: Partial<T>): boolean[];
+/**
+ * Maps each element in a readonly array to a boolean array based on a property-value pair match.
+ *
+ * @param {readonly T[]} collection - The collection to iterate over.
+ * @param {[keyof T, unknown]} iteratee - The property-value pair to match against each element.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const objects = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(objects, ['a', 1]); // => [true, false, false]
+ */
+declare function map<T>(collection: readonly T[], iteratee: [keyof T, unknown]): boolean[];
+/**
+ * Maps each element in a readonly array to an array of property values.
+ *
+ * @param {readonly T[]} collection - The collection to iterate over.
+ * @param {K} iteratee - The key of the property to extract from each element.
+ * @returns {Array<T[K]>} - Returns an array of property values.
+ *
+ * @example
+ * const objects = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(objects, 'a'); // => [1, 2, 3]
+ */
+declare function map<T, K extends keyof T>(collection: readonly T[], iteratee: K): Array<T[K]>;
+/**
+ * Maps each element in a readonly array to itself if no iteratee is provided.
+ *
+ * @param {readonly T[]} collection - The collection to iterate over.
+ * @param {null | undefined} [iteratee] - Optional iteratee.
+ * @returns {T[]} - Returns the original array.
+ *
+ * @example
+ * const numbers = [1, 2, 3];
+ * map(numbers); // => [1, 2, 3]
+ */
+declare function map<T>(collection: readonly T[], iteratee?: null | undefined): T[];
+/**
+ * Maps each element in an ArrayLike object to a new array of values using an iteratee function.
+ *
+ * @param {ArrayLike<T>} collection - The collection to iterate over.
+ * @param {(value: T, index: number, collection: ArrayLike<T>) => U} iteratee - The function invoked per iteration.
+ * @returns {U[]} - Returns the new mapped array.
+ *
+ * @example
+ * const arrayLike = {0: 1, 1: 2, 2: 3, length: 3};
+ * map(arrayLike, value => value * 2); // => [2, 4, 6]
+ */
+declare function map<T, U>(collection: ArrayLike<T>, iteratee: (value: T, index: number, collection: ArrayLike<T>) => U): U[];
+/**
+ * Maps each element in an ArrayLike object to a boolean array based on a partial object match.
+ *
+ * @param {ArrayLike<T>} collection - The collection to iterate over.
+ * @param {Partial<T>} iteratee - The partial object to match against each element.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const arrayLike = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(arrayLike, { a: 1 }); // => [true, false, false]
+ */
+declare function map<T>(collection: ArrayLike<T>, iteratee: Partial<T>): boolean[];
+/**
+ * Maps each element in an ArrayLike object to a boolean array based on a property-value pair match.
+ *
+ * @param {ArrayLike<T>} collection - The collection to iterate over.
+ * @param {[keyof T, unknown]} iteratee - The property-value pair to match against each element.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const arrayLike = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(arrayLike, ['a', 1]); // => [true, false, false]
+ */
+declare function map<T>(collection: ArrayLike<T>, iteratee: [keyof T, unknown]): boolean[];
+/**
+ * Maps each element in an ArrayLike object to an array of property values.
+ *
+ * @param {ArrayLike<T>} collection - The collection to iterate over.
+ * @param {K} iteratee - The key of the property to extract from each element.
+ * @returns {Array<T[K]>} - Returns an array of property values.
+ *
+ * @example
+ * const arrayLike = [{ a: 1 }, { a: 2 }, { a: 3 }];
+ * map(arrayLike, 'a'); // => [1, 2, 3]
+ */
+declare function map<T, K extends keyof T>(collection: ArrayLike<T>, iteratee: K): Array<T[K]>;
+/**
+ * Maps each element in an ArrayLike object to itself if no iteratee is provided.
+ *
+ * @param {ArrayLike<T>} collection - The collection to iterate over.
+ * @param {null | undefined} [iteratee] - Optional iteratee.
+ * @returns {ArrayLike<T>} - Returns the original ArrayLike object.
+ *
+ * @example
+ * const arrayLike = {0: 1, 1: 2, 2: 3, length: 3};
+ * map(arrayLike); // => {0: 1, 1: 2, 2: 3, length: 3}
+ */
+declare function map<T, U>(collection: ArrayLike<T>, iteratee?: null | undefined): ArrayLike<T>;
+/**
+ * Maps each value in an object to a new array of values using an iteratee function.
+ *
+ * @param {T} collection - The object to iterate over.
+ * @param {(value: T[keyof T], key: string, collection: T) => U} iteratee - The function invoked per iteration.
+ * @returns {U[]} - Returns the new mapped array.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * map(obj, (value, key) => `${key}: ${value}`); // => ['a: 1', 'b: 2', 'c: 3']
+ */
+declare function map<T extends object, U>(collection: T, iteratee: (value: T[keyof T], key: string, collection: T) => U): U[];
+/**
+ * Maps each value in an object to a boolean array based on a partial object match.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {Partial<T[keyof T]>} iteratee - The partial object to match against each value.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const obj = { a: { x: 1 }, b: { x: 2 }, c: { x: 3 } };
+ * map(obj, { x: 1 }); // => [true, false, false]
+ */
+declare function map<T>(object: T, iteratee: Partial<T[keyof T]>): boolean[];
+/**
+ * Maps each value in an object to a boolean array based on a property-value pair match.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {[keyof T[keyof T], unknown]} iteratee - The property-value pair to match against each value.
+ * @returns {boolean[]} - Returns an array of booleans indicating matches.
+ *
+ * @example
+ * const obj = { a: { x: 1 }, b: { x: 2 }, c: { x: 3 } };
+ * map(obj, ['x', 1]); // => [true, false, false]
+ */
+declare function map<T>(object: T, iteratee: [keyof T[keyof T], unknown]): boolean[];
+/**
+ * Maps each value in an object to an array of property values.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {K} iteratee - The key of the property to extract from each value.
+ * @returns {Array<T[keyof T][K]>} - Returns an array of property values.
+ *
+ * @example
+ * const obj = { a: { x: 1 }, b: { x: 2 }, c: { x: 3 } };
+ * map(obj, 'x'); // => [1, 2, 3]
+ */
+declare function map<T, K extends keyof T[keyof T]>(object: T, iteratee: K): Array<T[keyof T][K]>;
+/**
+ * Maps each value in an object to itself if no iteratee is provided.
+ *
+ * @param {T} object - The object to iterate over.
+ * @param {null | undefined} [iteratee] - Optional iteratee.
+ * @returns {U[]} - Returns the original object values as an array.
+ *
+ * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * map(obj); // => [1, 2, 3]
+ */
+declare function map<T extends object, U>(object: T, iteratee?: null | undefined): U[];
+
+export { map };

package/dist/compat/array/map.mjs

@@ -0,0 +1,21 @@
+import { identity } from '../../function/identity.mjs';
+import { range } from '../../math/range.mjs';
+import { isArrayLike } from '../predicate/isArrayLike.mjs';
+import { iteratee } from '../util/iteratee.mjs';
+
+function map(collection, _iteratee) {
+    if (!collection) {
+        return [];
+    }
+    const keys = isArrayLike(collection) || Array.isArray(collection) ? range(0, collection.length) : Object.keys(collection);
+    const iteratee$1 = iteratee(_iteratee ?? identity);
+    const result = new Array(keys.length);
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const value = collection[key];
+        result[i] = iteratee$1(value, key, collection);
+    }
+    return result;
+}
+
+export { map };

package/dist/compat/array/nth.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Gets the element at index `n` of `array`. If `n` is negative, the nth element from the end is returned.
+ *
+ * @param {ArrayLike<T> | null | undefined} array - The array to query.
+ * @param {number} [n=0] - The index of the element to return.
+ * @return {T | undefined} Returns the nth element of `array`.
+ *
+ * @example
+ * nth([1, 2, 3], 1); // => 2
+ * nth([1, 2, 3], -1); // => 3
+ */
+declare function nth<T>(array: ArrayLike<T> | null | undefined, n?: number): T | undefined;
+
+export { nth };

package/dist/compat/array/nth.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Gets the element at index `n` of `array`. If `n` is negative, the nth element from the end is returned.
+ *
+ * @param {ArrayLike<T> | null | undefined} array - The array to query.
+ * @param {number} [n=0] - The index of the element to return.
+ * @return {T | undefined} Returns the nth element of `array`.
+ *
+ * @example
+ * nth([1, 2, 3], 1); // => 2
+ * nth([1, 2, 3], -1); // => 3
+ */
+declare function nth<T>(array: ArrayLike<T> | null | undefined, n?: number): T | undefined;
+
+export { nth };

package/dist/compat/array/nth.mjs

@@ -0,0 +1,15 @@
+import { isArrayLikeObject } from '../predicate/isArrayLikeObject.mjs';
+import { toInteger } from '../util/toInteger.mjs';
+
+function nth(array, n = 0) {
+    if (!isArrayLikeObject(array) || array.length === 0) {
+        return undefined;
+    }
+    n = toInteger(n);
+    if (n < 0) {
+        n += array.length;
+    }
+    return array[n];
+}
+
+export { nth };

package/dist/compat/index.d.mts

@@ -104,6 +104,8 @@ export { intersectionBy } from './array/intersectionBy.mjs';
 export { join } from './array/join.mjs';
 export { last } from './array/last.mjs';
 export { lastIndexOf } from './array/lastIndexOf.mjs';
+export { map } from './array/map.mjs';
+export { nth } from './array/nth.mjs';
 export { orderBy } from './array/orderBy.mjs';
 export { pull } from './array/pull.mjs';
 export { sample } from './array/sample.mjs';

package/dist/compat/index.d.ts

@@ -104,6 +104,8 @@ export { intersectionBy } from './array/intersectionBy.js';
 export { join } from './array/join.js';
 export { last } from './array/last.js';
 export { lastIndexOf } from './array/lastIndexOf.js';
+export { map } from './array/map.js';
+export { nth } from './array/nth.js';
 export { orderBy } from './array/orderBy.js';
 export { pull } from './array/pull.js';
 export { sample } from './array/sample.js';

package/dist/compat/index.js

@@ -1008,6 +1008,32 @@ function lastIndexOf(array, searchElement, fromIndex) {
     return Array.from(array).lastIndexOf(searchElement, index);
 }
 
+function map(collection, _iteratee) {
+    if (!collection) {
+        return [];
+    }
+    const keys = isArrayLike(collection) || Array.isArray(collection) ? rangeRight.range(0, collection.length) : Object.keys(collection);
+    const iteratee$1 = iteratee(_iteratee ?? unary.identity);
+    const result = new Array(keys.length);
+    for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const value = collection[key];
+        result[i] = iteratee$1(value, key, collection);
+    }
+    return result;
+}
+
+function nth(array, n = 0) {
+    if (!isArrayLikeObject(array) || array.length === 0) {
+        return undefined;
+    }
+    n = toInteger(n);
+    if (n < 0) {
+        n += array.length;
+    }
+    return array[n];
+}
+
 function getPriority(a) {
     if (typeof a === 'symbol') {
         return 1;
@@ -2959,6 +2985,7 @@ exports.keysIn = keysIn;
 exports.last = last;
 exports.lastIndexOf = lastIndexOf;
 exports.lowerCase = lowerCase;
+exports.map = map;
 exports.mapKeys = mapKeys;
 exports.mapValues = mapValues;
 exports.matches = matches;
@@ -2968,6 +2995,7 @@ exports.merge = merge;
 exports.mergeWith = mergeWith;
 exports.min = min;
 exports.now = now;
+exports.nth = nth;
 exports.omit = omit;
 exports.orderBy = orderBy;
 exports.pad = pad;

package/dist/compat/index.mjs

@@ -105,6 +105,8 @@ export { intersectionBy } from './array/intersectionBy.mjs';
 export { join } from './array/join.mjs';
 export { last } from './array/last.mjs';
 export { lastIndexOf } from './array/lastIndexOf.mjs';
+export { map } from './array/map.mjs';
+export { nth } from './array/nth.mjs';
 export { orderBy } from './array/orderBy.mjs';
 export { pull } from './array/pull.mjs';
 export { sample } from './array/sample.mjs';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "es-toolkit",
   "description": "A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.",
-  "version": "1.29.0-dev.930+c93ff843",
+  "version": "1.29.0-dev.932+e387b4f5",
   "homepage": "https://es-toolkit.slash.page",
   "bugs": "https://github.com/toss/es-toolkit/issues",
   "repository": {