es-toolkit 1.31.0-dev.987 → 1.31.0-dev.991

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

@@ -4,6 +4,7 @@
  * @template T
  * @param {ArrayLike<T> | null | undefined} arr - The array to search through.
  * @param {(item: T, index: number, arr: T[]) => unknown} doesMatch - A function that takes an item, its index, and the array, and returns a truthy value if the item matches the criteria.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first item that matches the predicate, or `undefined` if no match is found.
  *
  * @example
@@ -12,13 +13,14 @@
  * const result = find(items, (item) => item > 3);
  * console.log(result); // 4
  */
-declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: (item: T, index: number, arr: readonly T[]) => unknown): T | undefined;
+declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: (item: T, index: number, arr: readonly T[]) => unknown, fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an array that matches the given partial object.
  *
  * @template T
  * @param {ArrayLike<T> | null | undefined} arr - The array to search through.
  * @param {Partial<T>} doesMatch - A partial object that specifies the properties to match.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first item that matches the partial object, or `undefined` if no match is found.
  *
  * @example
@@ -27,13 +29,14 @@ declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: (item:
  * const result = find(items, { name: 'Bob' });
  * console.log(result); // { id: 2, name: 'Bob' }
  */
-declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: Partial<T>): T | undefined;
+declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: Partial<T>, fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an array that matches a property with a specific value.
  *
  * @template T
  * @param {ArrayLike<T> | null | undefined} arr - The array to search through.
  * @param {[keyof T, unknown]} doesMatchProperty - An array where the first element is the property key and the second element is the value to match.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first item that has the specified property value, or `undefined` if no match is found.
  *
  * @example
@@ -42,13 +45,14 @@ declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: Partia
  * const result = find(items, ['name', 'Alice']);
  * console.log(result); // { id: 1, name: 'Alice' }
  */
-declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatchProperty: [keyof T, unknown]): T | undefined;
+declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatchProperty: [keyof T, unknown], fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an array that has a specific property, where the property name is provided as a PropertyKey.
  *
  * @template T
  * @param {ArrayLike<T> | null | undefined} arr - The array to search through.
  * @param {PropertyKey} propertyToCheck - The property name to check.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first item that has the specified property, or `undefined` if no match is found.
  *
  * @example
@@ -57,13 +61,14 @@ declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatchProperty
  * const result = find(items, 'name');
  * console.log(result); // { id: 1, name: 'Alice' }
  */
-declare function find<T>(arr: ArrayLike<T> | null | undefined, propertyToCheck: PropertyKey): T | undefined;
+declare function find<T>(arr: ArrayLike<T> | null | undefined, propertyToCheck: PropertyKey, fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an object that matches the given predicate function.
  *
  * @template T
  * @param {T | null | undefined} object - The object to search through.
  * @param {(item: T[keyof T], index: number, arr: T) => unknown} doesMatch - A function that takes an item, its key, and the object, and returns a truthy value if the item matches the criteria.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first property value that matches the predicate, or `undefined` if no match is found.
  *
  * @example
@@ -72,13 +77,14 @@ declare function find<T>(arr: ArrayLike<T> | null | undefined, propertyToCheck:
  * const result = find(obj, (item) => item > 2);
  * console.log(result); // 3
  */
-declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatch: (item: T[keyof T], index: keyof T, object: T) => unknown): T | undefined;
+declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatch: (item: T[keyof T], index: keyof T, object: T) => unknown, fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an object that matches the given partial value.
  *
  * @template T
  * @param {T | null | undefined} object - The object to search through.
  * @param {Partial<T[keyof T]>} doesMatch - A partial value to match against the values of the object.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first property value that matches the partial value, or `undefined` if no match is found.
  *
  * @example
@@ -87,13 +93,14 @@ declare function find<T extends Record<string, unknown>>(object: T | null | unde
  * const result = find(obj, { name: 'Bob' });
  * console.log(result); // { id: 2, name: 'Bob' }
  */
-declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatch: Partial<T[keyof T]>): T | undefined;
+declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatch: Partial<T[keyof T]>, fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an object that matches a property with a specific value.
  *
  * @template T
  * @param {T | null | undefined} object - The object to search through.
  * @param {[keyof T[keyof T], unknown]} doesMatchProperty - An array where the first element is the property key and the second element is the value to match.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first item that has the specified property value, or `undefined` if no match is found.
  *
  * @example
@@ -102,13 +109,14 @@ declare function find<T extends Record<string, unknown>>(object: T | null | unde
  * const result = find(items, ['name', 'Alice']);
  * console.log(result); // { id: 1, name: 'Alice' }
  */
-declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatchProperty: [keyof T[keyof T], unknown]): T | undefined;
+declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatchProperty: [keyof T[keyof T], unknown], fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an object that has a specific property, where the property name is provided as a PropertyKey.
  *
  * @template T
  * @param {T | null | undefined} object - The object to search through.
  * @param {PropertyKey} propertyToCheck - The property name to check.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first property value that has the specified property, or `undefined` if no match is found.
  *
  * @example
@@ -117,6 +125,6 @@ declare function find<T extends Record<string, unknown>>(object: T | null | unde
  * const result = find(obj, 'name');
  * console.log(result); // { id: 1, name: 'Alice' }
  */
-declare function find<T extends Record<string, unknown>>(object: T | null | undefined, propertyToCheck: PropertyKey): T | undefined;
+declare function find<T extends Record<string, unknown>>(object: T | null | undefined, propertyToCheck: PropertyKey, fromIndex?: number): T | undefined;
 
 export { find };

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

@@ -4,6 +4,7 @@
  * @template T
  * @param {ArrayLike<T> | null | undefined} arr - The array to search through.
  * @param {(item: T, index: number, arr: T[]) => unknown} doesMatch - A function that takes an item, its index, and the array, and returns a truthy value if the item matches the criteria.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first item that matches the predicate, or `undefined` if no match is found.
  *
  * @example
@@ -12,13 +13,14 @@
  * const result = find(items, (item) => item > 3);
  * console.log(result); // 4
  */
-declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: (item: T, index: number, arr: readonly T[]) => unknown): T | undefined;
+declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: (item: T, index: number, arr: readonly T[]) => unknown, fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an array that matches the given partial object.
  *
  * @template T
  * @param {ArrayLike<T> | null | undefined} arr - The array to search through.
  * @param {Partial<T>} doesMatch - A partial object that specifies the properties to match.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first item that matches the partial object, or `undefined` if no match is found.
  *
  * @example
@@ -27,13 +29,14 @@ declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: (item:
  * const result = find(items, { name: 'Bob' });
  * console.log(result); // { id: 2, name: 'Bob' }
  */
-declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: Partial<T>): T | undefined;
+declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: Partial<T>, fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an array that matches a property with a specific value.
  *
  * @template T
  * @param {ArrayLike<T> | null | undefined} arr - The array to search through.
  * @param {[keyof T, unknown]} doesMatchProperty - An array where the first element is the property key and the second element is the value to match.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first item that has the specified property value, or `undefined` if no match is found.
  *
  * @example
@@ -42,13 +45,14 @@ declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatch: Partia
  * const result = find(items, ['name', 'Alice']);
  * console.log(result); // { id: 1, name: 'Alice' }
  */
-declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatchProperty: [keyof T, unknown]): T | undefined;
+declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatchProperty: [keyof T, unknown], fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an array that has a specific property, where the property name is provided as a PropertyKey.
  *
  * @template T
  * @param {ArrayLike<T> | null | undefined} arr - The array to search through.
  * @param {PropertyKey} propertyToCheck - The property name to check.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first item that has the specified property, or `undefined` if no match is found.
  *
  * @example
@@ -57,13 +61,14 @@ declare function find<T>(arr: ArrayLike<T> | null | undefined, doesMatchProperty
  * const result = find(items, 'name');
  * console.log(result); // { id: 1, name: 'Alice' }
  */
-declare function find<T>(arr: ArrayLike<T> | null | undefined, propertyToCheck: PropertyKey): T | undefined;
+declare function find<T>(arr: ArrayLike<T> | null | undefined, propertyToCheck: PropertyKey, fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an object that matches the given predicate function.
  *
  * @template T
  * @param {T | null | undefined} object - The object to search through.
  * @param {(item: T[keyof T], index: number, arr: T) => unknown} doesMatch - A function that takes an item, its key, and the object, and returns a truthy value if the item matches the criteria.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first property value that matches the predicate, or `undefined` if no match is found.
  *
  * @example
@@ -72,13 +77,14 @@ declare function find<T>(arr: ArrayLike<T> | null | undefined, propertyToCheck:
  * const result = find(obj, (item) => item > 2);
  * console.log(result); // 3
  */
-declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatch: (item: T[keyof T], index: keyof T, object: T) => unknown): T | undefined;
+declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatch: (item: T[keyof T], index: keyof T, object: T) => unknown, fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an object that matches the given partial value.
  *
  * @template T
  * @param {T | null | undefined} object - The object to search through.
  * @param {Partial<T[keyof T]>} doesMatch - A partial value to match against the values of the object.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first property value that matches the partial value, or `undefined` if no match is found.
  *
  * @example
@@ -87,13 +93,14 @@ declare function find<T extends Record<string, unknown>>(object: T | null | unde
  * const result = find(obj, { name: 'Bob' });
  * console.log(result); // { id: 2, name: 'Bob' }
  */
-declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatch: Partial<T[keyof T]>): T | undefined;
+declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatch: Partial<T[keyof T]>, fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an object that matches a property with a specific value.
  *
  * @template T
  * @param {T | null | undefined} object - The object to search through.
  * @param {[keyof T[keyof T], unknown]} doesMatchProperty - An array where the first element is the property key and the second element is the value to match.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first item that has the specified property value, or `undefined` if no match is found.
  *
  * @example
@@ -102,13 +109,14 @@ declare function find<T extends Record<string, unknown>>(object: T | null | unde
  * const result = find(items, ['name', 'Alice']);
  * console.log(result); // { id: 1, name: 'Alice' }
  */
-declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatchProperty: [keyof T[keyof T], unknown]): T | undefined;
+declare function find<T extends Record<string, unknown>>(object: T | null | undefined, doesMatchProperty: [keyof T[keyof T], unknown], fromIndex?: number): T | undefined;
 /**
  * Finds the first item in an object that has a specific property, where the property name is provided as a PropertyKey.
  *
  * @template T
  * @param {T | null | undefined} object - The object to search through.
  * @param {PropertyKey} propertyToCheck - The property name to check.
+ * @param {number} [fromIndex=0] - The index to start the search from, defaults to 0.
  * @returns {T | undefined} - The first property value that has the specified property, or `undefined` if no match is found.
  *
  * @example
@@ -117,6 +125,6 @@ declare function find<T extends Record<string, unknown>>(object: T | null | unde
  * const result = find(obj, 'name');
  * console.log(result); // { id: 1, name: 'Alice' }
  */
-declare function find<T extends Record<string, unknown>>(object: T | null | undefined, propertyToCheck: PropertyKey): T | undefined;
+declare function find<T extends Record<string, unknown>>(object: T | null | undefined, propertyToCheck: PropertyKey, fromIndex?: number): T | undefined;
 
 export { find };

package/dist/compat/array/find.mjs

@@ -2,11 +2,14 @@ import { property } from '../object/property.mjs';
 import { matches } from '../predicate/matches.mjs';
 import { matchesProperty } from '../predicate/matchesProperty.mjs';
 
-function find(source, doesMatch) {
+function find(source, doesMatch, fromIndex = 0) {
     if (!source) {
         return undefined;
     }
-    const values = Array.isArray(source) ? source : Object.values(source);
+    if (fromIndex < 0) {
+        fromIndex = Math.max(source.length + fromIndex, 0);
+    }
+    const values = Array.isArray(source) ? source.slice(fromIndex) : Object.values(source).slice(fromIndex);
     switch (typeof doesMatch) {
         case 'function': {
             if (!Array.isArray(source)) {

package/dist/compat/index.js

@@ -726,11 +726,14 @@ function filter(source, predicate) {
     }
 }
 
-function find(source, doesMatch) {
+function find(source, doesMatch, fromIndex = 0) {
     if (!source) {
         return undefined;
     }
-    const values = Array.isArray(source) ? source : Object.values(source);
+    if (fromIndex < 0) {
+        fromIndex = Math.max(source.length + fromIndex, 0);
+    }
+    const values = Array.isArray(source) ? source.slice(fromIndex) : Object.values(source).slice(fromIndex);
     switch (typeof doesMatch) {
         case 'function': {
             if (!Array.isArray(source)) {

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.31.0-dev.987+63d52d83",
+  "version": "1.31.0-dev.991+74858bcd",
   "homepage": "https://es-toolkit.slash.page",
   "bugs": "https://github.com/toss/es-toolkit/issues",
   "repository": {