es-toolkit 1.21.0-dev.683 → 1.21.0-dev.684

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

@@ -0,0 +1,118 @@
+/**
+ * Filters items from a array and returns an array of elements.
+ *
+ * @template T
+ * @param {T[]} arr - The array to iterate over.
+ * @param {(item: T, index: number, arr: T[]) => unknown} doesMatch - The function invoked per iteration.
+ * @returns {T[]} - Returns a new array of elements that satisfy the given doesMatch function.
+
+ *
+ * @example
+ * filter([1, 2, 3], n => n % 2 === 0)
+ * // => [2]
+ */
+declare function filter<T>(arr: readonly T[], doesMatch?: (item: T, index: number, arr: readonly T[]) => unknown): T[];
+/**
+ * Filters elements in a arr that match the properties of the given partial object.
+ *
+ * @template T
+ * @param {T[]} arr - The array to iterate over.
+ * @param {Partial<T>} doesMatch - A partial object that specifies the properties to match.
+ * @returns {T[]} - Returns a new array of elements that match the given properties.
+ *
+ * @example
+ * const arr = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ * filter(arr, { name: 'Bob' });
+ * // => [{ id: 2, name: 'Bob' }]
+ */
+declare function filter<T>(arr: readonly T[], doesMatch: Partial<T>): T[];
+/**
+ * Filters elements in a arr that match the given key-value pair.
+ *
+ * @template T
+ * @param {readonly T[]} arr - The array to iterate over.
+ * @param {[keyof T, unknown]} doesMatchProperty - The key-value pair to match.
+ * @returns {T[]} - Returns a new array of elements that match the given key-value pair.
+ *
+ * @example
+ * const arr = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ * filter(arr, ['name', 'Alice']);
+ * // => [{ id: 1, name: 'Alice' }]
+ */
+declare function filter<T>(arr: readonly T[], doesMatchProperty: [keyof T, unknown]): T[];
+/**
+ * Filters the arr, returning elements that contain the given property name.
+ *
+ * @template T
+ * @param {readonly T[]} arr - The array to iterate over.
+ * @param {string} propertyToCheck - The property name to check.
+ * @returns {T[]} - Returns a new array of elements that match the given property name.
+ *
+ * @example
+ * const arr = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, age: 28 }];
+ * filter(arr, 'name');
+ * // => [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ */
+declare function filter<T>(arr: readonly T[], propertyToCheck: string): T[];
+/**
+ * Filters items from a object and returns an array of elements that match the given predicate function.
+ *
+ * @template T
+ * @param {T extends Record<string, unknown> ? T : never} object - The object to iterate over.
+ * @param {(item: T[keyof T], index: number, arr: T) => unknown} doesMatch - The function invoked per iteration.
+ * @returns {T[]} - Returns a new array of elements that satisfy the given predicate function.
+ *
+ * @example
+ * const obj = { item1: { a: 0 }, item2: { a: 1 }, item3: { a: 0 } }
+ * filter(obj, items => items.a)
+ * // => [{ a: 1 }]
+ *
+ * const obj = { a: 1, b: 2, c: 3 };
+ * filter(obj, item => item > 2)
+ * // => [3]
+ */
+declare function filter<T extends Record<string, unknown>>(object: T, doesMatch: (item: T[keyof T], index: number, object: T) => unknown): T[];
+/**
+ * Filters elements in a object that match the properties of the given partial object.
+ *
+ * @template T
+ * @param {T extends Record<string, unknown> ? T : never} object - The object to iterate over.
+ * @param {Partial<T[keyof T]>} doesMatch - The partial object to match
+ * @returns {T[]} - Returns a new array of elements that match the given properties.pair.
+ *
+ * @example
+ * const obj = { a: { id: 1, name: 'Alice' }, b: { id: 2, name: 'Bob' } };
+ * filter(obj, { name: 'Bob' });
+ * // => [{ id: 2, name: 'Bob' }]
+ */
+declare function filter<T extends Record<string, unknown>>(object: T, doesMatch: Partial<T[keyof T]>): T[];
+/**
+ * Filters elements in a arr that match the given key-value pair.
+ *
+ * @template T
+ * @param {T extends Record<string, unknown> ? T : never} object - The object to iterate over.
+ * @param {[keyof T, unknown]} doesMatchProperty - The key-value pair to match.
+ * @returns {T[]} - Returns a new array of elements that match the given key-value pair.
+ *
+ * @example
+ * const obj = { alice: { id: 1, name: 'Alice' }, bob: { id: 2, name: 'Bob' } };
+ * filter(obj, ['name', 'Alice']);
+ * // => [{ id: 1, name: 'Alice' }]
+ */
+declare function filter<T extends Record<string, unknown>>(object: T, doesMatchProperty: [keyof T, unknown]): T[];
+/**
+ * Filters the object, returning elements that contain the given property name.
+ *
+ * @template T
+ * @param {T extends Record<string, unknown> ? T : never} object - The object to iterate over.
+ * @param {string} propertyToCheck - The property name to check.
+ * @returns {T[]} - Returns a new array of elements that match the given property name.
+ *
+ * @example
+ * const obj = { a: { id: 1, name: 'Alice' }, b: { id: 2, name: 'Bob' }, c: { id: 3, age: 28 } };
+ * filter(obj, 'name');
+ * // => [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ */
+declare function filter<T extends Record<string, unknown>>(object: T, propertyToCheck: string): T[];
+
+export { filter };

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

@@ -0,0 +1,118 @@
+/**
+ * Filters items from a array and returns an array of elements.
+ *
+ * @template T
+ * @param {T[]} arr - The array to iterate over.
+ * @param {(item: T, index: number, arr: T[]) => unknown} doesMatch - The function invoked per iteration.
+ * @returns {T[]} - Returns a new array of elements that satisfy the given doesMatch function.
+
+ *
+ * @example
+ * filter([1, 2, 3], n => n % 2 === 0)
+ * // => [2]
+ */
+declare function filter<T>(arr: readonly T[], doesMatch?: (item: T, index: number, arr: readonly T[]) => unknown): T[];
+/**
+ * Filters elements in a arr that match the properties of the given partial object.
+ *
+ * @template T
+ * @param {T[]} arr - The array to iterate over.
+ * @param {Partial<T>} doesMatch - A partial object that specifies the properties to match.
+ * @returns {T[]} - Returns a new array of elements that match the given properties.
+ *
+ * @example
+ * const arr = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ * filter(arr, { name: 'Bob' });
+ * // => [{ id: 2, name: 'Bob' }]
+ */
+declare function filter<T>(arr: readonly T[], doesMatch: Partial<T>): T[];
+/**
+ * Filters elements in a arr that match the given key-value pair.
+ *
+ * @template T
+ * @param {readonly T[]} arr - The array to iterate over.
+ * @param {[keyof T, unknown]} doesMatchProperty - The key-value pair to match.
+ * @returns {T[]} - Returns a new array of elements that match the given key-value pair.
+ *
+ * @example
+ * const arr = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ * filter(arr, ['name', 'Alice']);
+ * // => [{ id: 1, name: 'Alice' }]
+ */
+declare function filter<T>(arr: readonly T[], doesMatchProperty: [keyof T, unknown]): T[];
+/**
+ * Filters the arr, returning elements that contain the given property name.
+ *
+ * @template T
+ * @param {readonly T[]} arr - The array to iterate over.
+ * @param {string} propertyToCheck - The property name to check.
+ * @returns {T[]} - Returns a new array of elements that match the given property name.
+ *
+ * @example
+ * const arr = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, age: 28 }];
+ * filter(arr, 'name');
+ * // => [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ */
+declare function filter<T>(arr: readonly T[], propertyToCheck: string): T[];
+/**
+ * Filters items from a object and returns an array of elements that match the given predicate function.
+ *
+ * @template T
+ * @param {T extends Record<string, unknown> ? T : never} object - The object to iterate over.
+ * @param {(item: T[keyof T], index: number, arr: T) => unknown} doesMatch - The function invoked per iteration.
+ * @returns {T[]} - Returns a new array of elements that satisfy the given predicate function.
+ *
+ * @example
+ * const obj = { item1: { a: 0 }, item2: { a: 1 }, item3: { a: 0 } }
+ * filter(obj, items => items.a)
+ * // => [{ a: 1 }]
+ *
+ * const obj = { a: 1, b: 2, c: 3 };
+ * filter(obj, item => item > 2)
+ * // => [3]
+ */
+declare function filter<T extends Record<string, unknown>>(object: T, doesMatch: (item: T[keyof T], index: number, object: T) => unknown): T[];
+/**
+ * Filters elements in a object that match the properties of the given partial object.
+ *
+ * @template T
+ * @param {T extends Record<string, unknown> ? T : never} object - The object to iterate over.
+ * @param {Partial<T[keyof T]>} doesMatch - The partial object to match
+ * @returns {T[]} - Returns a new array of elements that match the given properties.pair.
+ *
+ * @example
+ * const obj = { a: { id: 1, name: 'Alice' }, b: { id: 2, name: 'Bob' } };
+ * filter(obj, { name: 'Bob' });
+ * // => [{ id: 2, name: 'Bob' }]
+ */
+declare function filter<T extends Record<string, unknown>>(object: T, doesMatch: Partial<T[keyof T]>): T[];
+/**
+ * Filters elements in a arr that match the given key-value pair.
+ *
+ * @template T
+ * @param {T extends Record<string, unknown> ? T : never} object - The object to iterate over.
+ * @param {[keyof T, unknown]} doesMatchProperty - The key-value pair to match.
+ * @returns {T[]} - Returns a new array of elements that match the given key-value pair.
+ *
+ * @example
+ * const obj = { alice: { id: 1, name: 'Alice' }, bob: { id: 2, name: 'Bob' } };
+ * filter(obj, ['name', 'Alice']);
+ * // => [{ id: 1, name: 'Alice' }]
+ */
+declare function filter<T extends Record<string, unknown>>(object: T, doesMatchProperty: [keyof T, unknown]): T[];
+/**
+ * Filters the object, returning elements that contain the given property name.
+ *
+ * @template T
+ * @param {T extends Record<string, unknown> ? T : never} object - The object to iterate over.
+ * @param {string} propertyToCheck - The property name to check.
+ * @returns {T[]} - Returns a new array of elements that match the given property name.
+ *
+ * @example
+ * const obj = { a: { id: 1, name: 'Alice' }, b: { id: 2, name: 'Bob' }, c: { id: 3, age: 28 } };
+ * filter(obj, 'name');
+ * // => [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]
+ */
+declare function filter<T extends Record<string, unknown>>(object: T, propertyToCheck: string): T[];
+
+export { filter };

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/index.d.mts

@@ -113,6 +113,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';

package/dist/compat/index.d.ts

@@ -113,6 +113,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';

package/dist/compat/index.js

@@ -787,6 +787,30 @@ function zipObjectDeep(keys, values) {
     return result;
 }
 
+function isArray(value) {
+    return Array.isArray(value);
+}
+
+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));
+        }
+    }
+}
+
 function ary(func, n = func.length, guard) {
     if (guard) {
         n = func.length;
@@ -1299,10 +1323,6 @@ function fromPairs(pairs) {
     return result;
 }
 
-function isArray(value) {
-    return Array.isArray(value);
-}
-
 function isObject(value) {
     return value !== null && (typeof value === 'object' || typeof value === 'function');
 }
@@ -1836,6 +1856,7 @@ exports.dropWhile = dropWhile;
 exports.endsWith = endsWith;
 exports.every = every;
 exports.fill = fill;
+exports.filter = filter;
 exports.find = find;
 exports.findIndex = findIndex;
 exports.findLastIndex = findLastIndex;

package/dist/compat/index.mjs

@@ -114,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';

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.21.0-dev.683+55539081",
+  "version": "1.21.0-dev.684+6e3226e2",
   "homepage": "https://es-toolkit.slash.page",
   "bugs": "https://github.com/toss/es-toolkit/issues",
   "repository": {