es-toolkit 1.21.0 → 1.22.0-dev.690

package/dist/compat/array/filter.mjs

@@ -0,0 +1,27 @@
+import { identity } from '../_internal/identity.mjs';
+import { property } from '../object/property.mjs';
+import { isArray } from '../predicate/isArray.mjs';
+import { matches } from '../predicate/matches.mjs';
+import { matchesProperty } from '../predicate/matchesProperty.mjs';
+
+function filter(source, predicate) {
+    if (!predicate) {
+        predicate = identity;
+    }
+    const collection = isArray(source) ? source : Object.values(source);
+    switch (typeof predicate) {
+        case 'function': {
+            return collection.filter(predicate);
+        }
+        case 'object': {
+            return isArray(predicate)
+                ? collection.filter(matchesProperty(predicate[0], predicate[1]))
+                : collection.filter(matches(predicate));
+        }
+        case 'string': {
+            return collection.filter(property(predicate));
+        }
+    }
+}
+
+export { filter };

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

@@ -72,7 +72,7 @@ declare function find<T>(arr: readonly T[], propertyToCheck: string): T | undefi
  * const result = find(obj, (item) => item > 2);
  * console.log(result); // 3
  */
-declare function find<T extends Record<string, unknown>>(object: T, doesMatch: (item: T[keyof T], index: number, object: T) => unknown): T | undefined;
+declare function find<T extends Record<string, unknown>>(object: T, doesMatch: (item: T[keyof T], index: keyof T, object: T) => unknown): T | undefined;
 /**
  * Finds the first item in an object that matches the given partial value.
  *

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

@@ -72,7 +72,7 @@ declare function find<T>(arr: readonly T[], propertyToCheck: string): T | undefi
  * const result = find(obj, (item) => item > 2);
  * console.log(result); // 3
  */
-declare function find<T extends Record<string, unknown>>(object: T, doesMatch: (item: T[keyof T], index: number, object: T) => unknown): T | undefined;
+declare function find<T extends Record<string, unknown>>(object: T, doesMatch: (item: T[keyof T], index: keyof T, object: T) => unknown): T | undefined;
 /**
  * Finds the first item in an object that matches the given partial value.
  *

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

@@ -0,0 +1,62 @@
+/**
+ * Checks if an item is included in an array.
+ *
+ * @param {T[]} arr - The array to search in.
+ * @param {T} item - The item to search for.
+ * @param {number} [fromIndex=0] - The index to start searching from. If negative, it is treated as an offset from the end of the array.
+ * @returns {boolean} `true` if the item is found in the array, `false` otherwise.
+ *
+ * @example
+ * includes([1, 2, 3], 2); // true
+ * includes([1, 2, 3], 4); // false
+ * includes([1, 2, 3], 3, -1); // true
+ */
+declare function includes<T>(arr: readonly T[], item: T, fromIndex?: number): boolean;
+/**
+ * Checks if a value is included in an object.
+ *
+ * @param {T} obj - The object to search in.
+ * @param {T[keyof T]} value - The value to search for.
+ * @param {number} [fromIndex=0] - The index to start searching from. If negative, it is treated as an offset from the end of the array.
+ * @returns {boolean} `true` if the value is found in the object, `false` otherwise.
+ *
+ * @example
+ * includes({ a: 1, b: 'a', c: NaN }, 1); // true
+ * includes({ a: 1, b: 'a', c: NaN }, 'a'); // true
+ * includes({ a: 1, b: 'a', c: NaN }, NaN); // true
+ * includes({ [Symbol('sym1')]: 1 }, 1); // false
+ */
+declare function includes<T extends Record<string, any>>(obj: T, value: T[keyof T], fromIndex?: number): boolean;
+/**
+ * Checks if a substring is included in a string.
+ *
+ * @param {string} str - The string to search in.
+ * @param {string} substr - The substring to search for.
+ * @param {number} [fromIndex=0] - The index to start searching from. If negative, it is treated as an offset from the end of the string.
+ * @returns {boolean} `true` if the substring is found in the string, `false` otherwise.
+ *
+ * @example
+ * includes('hello world', 'world'); // true
+ * includes('hello world', 'test'); // false
+ * includes('hello world', 'o', 5); // true
+ */
+declare function includes(str: string, substr: string, fromIndex?: number): boolean;
+/**
+ * Checks if a specified value exists within a given source, which can be an array, an object, or a string.
+ *
+ * The comparison uses SameValueZero to check for inclusion.
+ *
+ * @param {T[] | Record<string, any> | string} source - The source to search in. It can be an array, an object, or a string.
+ * @param {T} [target] - The value to search for in the source.
+ * @param {number} [fromIndex=0] - The index to start searching from. If negative, it is treated as an offset from the end of the source.
+ * @returns {boolean} `true` if the value is found in the source, `false` otherwise.
+ *
+ * @example
+ * includes([1, 2, 3], 2); // true
+ * includes({ a: 1, b: 'a', c: NaN }, 'a'); // true
+ * includes('hello world', 'world'); // true
+ * includes('hello world', 'test'); // false
+ */
+declare function includes<T>(source: readonly T[] | Record<string, any> | string, target?: T, fromIndex?: number): boolean;
+
+export { includes };

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

@@ -0,0 +1,62 @@
+/**
+ * Checks if an item is included in an array.
+ *
+ * @param {T[]} arr - The array to search in.
+ * @param {T} item - The item to search for.
+ * @param {number} [fromIndex=0] - The index to start searching from. If negative, it is treated as an offset from the end of the array.
+ * @returns {boolean} `true` if the item is found in the array, `false` otherwise.
+ *
+ * @example
+ * includes([1, 2, 3], 2); // true
+ * includes([1, 2, 3], 4); // false
+ * includes([1, 2, 3], 3, -1); // true
+ */
+declare function includes<T>(arr: readonly T[], item: T, fromIndex?: number): boolean;
+/**
+ * Checks if a value is included in an object.
+ *
+ * @param {T} obj - The object to search in.
+ * @param {T[keyof T]} value - The value to search for.
+ * @param {number} [fromIndex=0] - The index to start searching from. If negative, it is treated as an offset from the end of the array.
+ * @returns {boolean} `true` if the value is found in the object, `false` otherwise.
+ *
+ * @example
+ * includes({ a: 1, b: 'a', c: NaN }, 1); // true
+ * includes({ a: 1, b: 'a', c: NaN }, 'a'); // true
+ * includes({ a: 1, b: 'a', c: NaN }, NaN); // true
+ * includes({ [Symbol('sym1')]: 1 }, 1); // false
+ */
+declare function includes<T extends Record<string, any>>(obj: T, value: T[keyof T], fromIndex?: number): boolean;
+/**
+ * Checks if a substring is included in a string.
+ *
+ * @param {string} str - The string to search in.
+ * @param {string} substr - The substring to search for.
+ * @param {number} [fromIndex=0] - The index to start searching from. If negative, it is treated as an offset from the end of the string.
+ * @returns {boolean} `true` if the substring is found in the string, `false` otherwise.
+ *
+ * @example
+ * includes('hello world', 'world'); // true
+ * includes('hello world', 'test'); // false
+ * includes('hello world', 'o', 5); // true
+ */
+declare function includes(str: string, substr: string, fromIndex?: number): boolean;
+/**
+ * Checks if a specified value exists within a given source, which can be an array, an object, or a string.
+ *
+ * The comparison uses SameValueZero to check for inclusion.
+ *
+ * @param {T[] | Record<string, any> | string} source - The source to search in. It can be an array, an object, or a string.
+ * @param {T} [target] - The value to search for in the source.
+ * @param {number} [fromIndex=0] - The index to start searching from. If negative, it is treated as an offset from the end of the source.
+ * @returns {boolean} `true` if the value is found in the source, `false` otherwise.
+ *
+ * @example
+ * includes([1, 2, 3], 2); // true
+ * includes({ a: 1, b: 'a', c: NaN }, 'a'); // true
+ * includes('hello world', 'world'); // true
+ * includes('hello world', 'test'); // false
+ */
+declare function includes<T>(source: readonly T[] | Record<string, any> | string, target?: T, fromIndex?: number): boolean;
+
+export { includes };

package/dist/compat/array/includes.mjs

@@ -0,0 +1,42 @@
+import { isString } from '../predicate/isString.mjs';
+import { toInteger } from '../util/toInteger.mjs';
+
+function includes(source, target, fromIndex, guard) {
+    if (source == null) {
+        return false;
+    }
+    if (guard || !fromIndex) {
+        fromIndex = 0;
+    }
+    else {
+        fromIndex = toInteger(fromIndex);
+    }
+    if (isString(source)) {
+        if (fromIndex > source.length || target instanceof RegExp) {
+            return false;
+        }
+        if (fromIndex < 0) {
+            fromIndex = Math.max(0, source.length + fromIndex);
+        }
+        return source.includes(target, fromIndex);
+    }
+    if (Array.isArray(source)) {
+        return source.includes(target, fromIndex);
+    }
+    const keys = [];
+    for (const key in source) {
+        keys.push(key);
+    }
+    if (fromIndex < 0) {
+        fromIndex = Math.max(0, keys.length + fromIndex);
+    }
+    for (let i = fromIndex; i < keys.length; i++) {
+        const value = Reflect.get(source, keys[i]);
+        if (value === target || (Number.isNaN(value) && Number.isNaN(target))) {
+            return true;
+        }
+    }
+    return false;
+}
+
+export { includes };

package/dist/compat/function/flip.d.mts

@@ -0,0 +1,20 @@
+/**
+ * Reverses the order of arguments for a given function.
+ *
+ * @template F - The type of the function being flipped.
+ * @param {F} func - The function whose arguments will be reversed.
+ * @returns {(...args: Reversed<Parameters<F>>) => ReturnType<F>} A new function that takes the
+ * reversed arguments and returns the result of calling `func`.
+ *
+ * @example
+ * function fn(a: string, b: string, c: string, d: string) {
+ *   return [a, b, c, d];
+ * }
+ *
+ * const flipped = flip(fn);
+ * flipped('a', 'b', 'c', 'd'); // => ['d', 'c', 'b', 'a']
+ */
+declare function flip<F extends (...args: any[]) => any>(func: F): (...args: Reversed<Parameters<F>>) => ReturnType<F>;
+type Reversed<T extends any[]> = T extends [infer First, ...infer Rest] ? [...Reversed<Rest>, First] : [];
+
+export { flip };

package/dist/compat/function/flip.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Reverses the order of arguments for a given function.
+ *
+ * @template F - The type of the function being flipped.
+ * @param {F} func - The function whose arguments will be reversed.
+ * @returns {(...args: Reversed<Parameters<F>>) => ReturnType<F>} A new function that takes the
+ * reversed arguments and returns the result of calling `func`.
+ *
+ * @example
+ * function fn(a: string, b: string, c: string, d: string) {
+ *   return [a, b, c, d];
+ * }
+ *
+ * const flipped = flip(fn);
+ * flipped('a', 'b', 'c', 'd'); // => ['d', 'c', 'b', 'a']
+ */
+declare function flip<F extends (...args: any[]) => any>(func: F): (...args: Reversed<Parameters<F>>) => ReturnType<F>;
+type Reversed<T extends any[]> = T extends [infer First, ...infer Rest] ? [...Reversed<Rest>, First] : [];
+
+export { flip };

package/dist/compat/function/flip.mjs

@@ -0,0 +1,7 @@
+function flip(func) {
+    return function (...args) {
+        return func.apply(this, args.reverse());
+    };
+}
+
+export { flip };

package/dist/compat/index.d.mts

@@ -5,7 +5,6 @@ export { differenceBy } from '../array/differenceBy.mjs';
 export { differenceWith } from '../array/differenceWith.mjs';
 export { dropRight } from '../array/dropRight.mjs';
 export { dropRightWhile } from '../array/dropRightWhile.mjs';
-export { dropWhile } from '../array/dropWhile.mjs';
 export { flatMap } from '../array/flatMap.mjs';
 export { flatMapDeep } from '../array/flatMapDeep.mjs';
 export { forEachRight } from '../array/forEachRight.mjs';
@@ -57,6 +56,8 @@ export { MemoizeCache, memoize } from '../function/memoize.mjs';
 export { unary } from '../function/unary.mjs';
 export { partial } from '../function/partial.mjs';
 export { partialRight } from '../function/partialRight.mjs';
+export { flow } from '../function/flow.mjs';
+export { flowRight } from '../function/flowRight.mjs';
 export { mean } from '../math/mean.mjs';
 export { meanBy } from '../math/meanBy.mjs';
 export { randomInt } from '../math/randomInt.mjs';
@@ -71,12 +72,14 @@ export { flattenObject } from '../object/flattenObject.mjs';
 export { toMerged } from '../object/toMerged.mjs';
 export { isDate } from '../predicate/isDate.mjs';
 export { isEqual } from '../predicate/isEqual.mjs';
+export { isMap } from '../predicate/isMap.mjs';
 export { isNotNil } from '../predicate/isNotNil.mjs';
 export { isNull } from '../predicate/isNull.mjs';
 export { isUndefined } from '../predicate/isUndefined.mjs';
 export { isLength } from '../predicate/isLength.mjs';
 export { isFunction } from '../predicate/isFunction.mjs';
 export { isPrimitive } from '../predicate/isPrimitive.mjs';
+export { isSet } from '../predicate/isSet.mjs';
 export { delay } from '../promise/delay.mjs';
 export { withTimeout } from '../promise/withTimeout.mjs';
 export { timeout } from '../promise/timeout.mjs';
@@ -94,6 +97,8 @@ export { chunk } from './array/chunk.mjs';
 export { concat } from './array/concat.mjs';
 export { difference } from './array/difference.mjs';
 export { drop } from './array/drop.mjs';
+export { dropWhile } from './array/dropWhile.mjs';
+export { every } from './array/every.mjs';
 export { fill } from './array/fill.mjs';
 export { find } from './array/find.mjs';
 export { findIndex } from './array/findIndex.mjs';
@@ -101,6 +106,7 @@ export { findLastIndex } from './array/findLastIndex.mjs';
 export { flatten } from './array/flatten.mjs';
 export { flattenDeep } from './array/flattenDeep.mjs';
 export { flattenDepth } from './array/flattenDepth.mjs';
+export { includes } from './array/includes.mjs';
 export { indexOf } from './array/indexOf.mjs';
 export { join } from './array/join.mjs';
 export { orderBy } from './array/orderBy.mjs';
@@ -108,6 +114,7 @@ export { sortBy } from './array/sortBy.mjs';
 export { size } from './array/size.mjs';
 export { some } from './array/some.mjs';
 export { zipObjectDeep } from './array/zipObjectDeep.mjs';
+export { filter } from './array/filter.mjs';
 export { ary } from './function/ary.mjs';
 export { bind } from './function/bind.mjs';
 export { bindKey } from './function/bindKey.mjs';
@@ -119,6 +126,7 @@ export { rearg } from './function/rearg.mjs';
 export { curry } from './function/curry.mjs';
 export { debounce } from './function/debounce.mjs';
 export { throttle } from './function/throttle.mjs';
+export { flip } from './function/flip.mjs';
 export { get } from './object/get.mjs';
 export { set } from './object/set.mjs';
 export { pick } from './object/pick.mjs';

package/dist/compat/index.d.ts

@@ -5,7 +5,6 @@ export { differenceBy } from '../array/differenceBy.js';
 export { differenceWith } from '../array/differenceWith.js';
 export { dropRight } from '../array/dropRight.js';
 export { dropRightWhile } from '../array/dropRightWhile.js';
-export { dropWhile } from '../array/dropWhile.js';
 export { flatMap } from '../array/flatMap.js';
 export { flatMapDeep } from '../array/flatMapDeep.js';
 export { forEachRight } from '../array/forEachRight.js';
@@ -57,6 +56,8 @@ export { MemoizeCache, memoize } from '../function/memoize.js';
 export { unary } from '../function/unary.js';
 export { partial } from '../function/partial.js';
 export { partialRight } from '../function/partialRight.js';
+export { flow } from '../function/flow.js';
+export { flowRight } from '../function/flowRight.js';
 export { mean } from '../math/mean.js';
 export { meanBy } from '../math/meanBy.js';
 export { randomInt } from '../math/randomInt.js';
@@ -71,12 +72,14 @@ export { flattenObject } from '../object/flattenObject.js';
 export { toMerged } from '../object/toMerged.js';
 export { isDate } from '../predicate/isDate.js';
 export { isEqual } from '../predicate/isEqual.js';
+export { isMap } from '../predicate/isMap.js';
 export { isNotNil } from '../predicate/isNotNil.js';
 export { isNull } from '../predicate/isNull.js';
 export { isUndefined } from '../predicate/isUndefined.js';
 export { isLength } from '../predicate/isLength.js';
 export { isFunction } from '../predicate/isFunction.js';
 export { isPrimitive } from '../predicate/isPrimitive.js';
+export { isSet } from '../predicate/isSet.js';
 export { delay } from '../promise/delay.js';
 export { withTimeout } from '../promise/withTimeout.js';
 export { timeout } from '../promise/timeout.js';
@@ -94,6 +97,8 @@ export { chunk } from './array/chunk.js';
 export { concat } from './array/concat.js';
 export { difference } from './array/difference.js';
 export { drop } from './array/drop.js';
+export { dropWhile } from './array/dropWhile.js';
+export { every } from './array/every.js';
 export { fill } from './array/fill.js';
 export { find } from './array/find.js';
 export { findIndex } from './array/findIndex.js';
@@ -101,6 +106,7 @@ export { findLastIndex } from './array/findLastIndex.js';
 export { flatten } from './array/flatten.js';
 export { flattenDeep } from './array/flattenDeep.js';
 export { flattenDepth } from './array/flattenDepth.js';
+export { includes } from './array/includes.js';
 export { indexOf } from './array/indexOf.js';
 export { join } from './array/join.js';
 export { orderBy } from './array/orderBy.js';
@@ -108,6 +114,7 @@ export { sortBy } from './array/sortBy.js';
 export { size } from './array/size.js';
 export { some } from './array/some.js';
 export { zipObjectDeep } from './array/zipObjectDeep.js';
+export { filter } from './array/filter.js';
 export { ary } from './function/ary.js';
 export { bind } from './function/bind.js';
 export { bindKey } from './function/bindKey.js';
@@ -119,6 +126,7 @@ export { rearg } from './function/rearg.js';
 export { curry } from './function/curry.js';
 export { debounce } from './function/debounce.js';
 export { throttle } from './function/throttle.js';
+export { flip } from './function/flip.js';
 export { get } from './object/get.js';
 export { set } from './object/set.js';
 export { pick } from './object/pick.js';