feat: add find as an alias for filter

README.md

@@ -81,7 +81,8 @@
   - [Browser Support](#browser-support)
   - [Migration from v3.x](#migration-from-v3x)
   - [Changelog](#changelog)
-    - [v5.8.2 (Current)](#v582-current)
+    - [v5.9.0 (Current)](#v590-current)
+    - [v5.8.2](#v582)
     - [v5.8.0](#v580)
     - [v5.7.0](#v570)
     - [v5.6.0](#v560)
@@ -166,6 +167,12 @@ const startsWithAl = filter(users, 'Al%');
 // → [{ name: 'Alice', ... }]
 ```
 
+> **`find` is an alias for `filter`** — use whichever name feels more natural:
+> ```typescript
+> import { find } from '@mcabreradev/filter';
+> const result = find(users, { active: true }); // identical to filter()
+> ```
+
 **🎮 [Try it in the Playground →](https://mcabreradev-filter.vercel.app/playground/)**
 
 ---
@@ -728,7 +735,11 @@ filter(data, expression, { enableCache: true, limit: 50 });
 
 ## Changelog
 
-### v5.8.2 (Current)
+### v5.9.0 (Current)
+
+- ✨ **New**: `find` — an alias for `filter` with identical signature and behavior. Use whichever name reads better in your codebase: `import { find } from '@mcabreradev/filter'`
+
+### v5.8.2
 
 - 🐛 **Bug Fix**: Wildcard regex now correctly escapes all special characters (`.`, `+`, `*`, `?`, `(`, `[`, `^`, etc.) — patterns like `%.txt` or `a.b%` no longer silently break
 - 🐛 **Bug Fix**: `$timeOfDay` with `start > end` (e.g. `{ start: 22, end: 5 }`) now correctly fails validation instead of silently never matching

__test__/filter.test.ts

@@ -1,4 +1,4 @@
-import filter from '../src/index';
+import filter, { find } from '../src/index';
 
 import data from './data.json';
 
@@ -300,3 +300,25 @@ describe('Array values with OR logic (syntactic sugar for $in)', () => {
     expect(result.map((u) => u.city).sort()).toEqual(['Berlin', 'Berlin', 'London']);
   });
 });
+
+describe('find alias', () => {
+  it('returns same results as filter', () => {
+    expect(find(data, 'Berlin')).toEqual(filter(data, 'Berlin'));
+  });
+
+  it('works with object expression', () => {
+    const city = 'Berlin';
+    expect(find(data, { city })).toEqual(filter(data, { city }));
+  });
+
+  it('works with predicate function', () => {
+    const pred = (item: (typeof data)[0]) => item.city === 'Berlin';
+    expect(find(data, pred)).toEqual(filter(data, pred));
+  });
+
+  it('works with options', () => {
+    expect(find(data, 'berlin', { caseSensitive: false })).toEqual(
+      filter(data, 'berlin', { caseSensitive: false }),
+    );
+  });
+});

__test__/test-d/filter.test-d.ts

@@ -1,5 +1,5 @@
 import { expectType, expectError } from 'tsd';
-import { filter } from '../../src/core/filter';
+import { filter, find } from '../../src/core/filter';
 import type { FilterOptions } from '../../src/types';
 
 interface User {
@@ -114,3 +114,9 @@ const mixedArray: (string | number)[] = ['a', 1, 'b', 2];
 expectType<(string | number)[]>(filter(mixedArray, 'a'));
 
 expectType<(string | number)[]>(filter(mixedArray, (item) => typeof item === 'string'));
+
+expectType<User[]>(find(users, 'John'));
+expectType<User[]>(find(users, { name: 'John' }));
+expectType<User[]>(find(users, (user) => user.age > 18));
+expectType<User[]>(find(users, { name: 'John' }, options));
+expectError(find('not-an-array', 'test'));

docs/api/reference.md

@@ -34,6 +34,32 @@ const users = [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }];
 const result = filter(users, { age: { $gte: 25 } });
 ```
 
+### find
+
+Alias for `filter` — identical signature and behavior. Use whichever name fits your style.
+
+```typescript
+function find<T>(
+  array: T[],
+  expression: Expression<T>,
+  options?: FilterOptions
+): T[]
+```
+
+**Example:**
+```typescript
+import { find } from '@mcabreradev/filter';
+
+const users = [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }];
+
+// Exactly the same as calling filter()
+const result = find(users, { age: { $gte: 25 } });
+```
+
+::: tip
+`find` and `filter` are the same function. Pick the one that reads most naturally in your codebase.
+:::
+
 ### filterLazy
 
 Returns a lazy iterator for on-demand filtering.

docs/guide/quick-start.md

@@ -23,13 +23,20 @@ Choose between two import styles:
 
 ```typescript
 // Classic import (all features)
-import { filter, useFilter } from '@mcabreradev/filter';
+import { filter, find, useFilter } from '@mcabreradev/filter';
 
 // Modular import (smaller bundle, recommended for production)
-import { filter } from '@mcabreradev/filter/core';
+import { filter, find } from '@mcabreradev/filter/core';
 import { useFilter } from '@mcabreradev/filter/react';
 ```
 
+::: tip `find` is an alias for `filter`
+Both functions are identical — same signature, same results. Use whichever reads more naturally in your codebase.
+```typescript
+find(users, { active: true });   // same as filter(users, { active: true })
+```
+:::
+
 ::: tip Bundle Size
 Modular imports reduce bundle size by **50-70%**! See [Modular Imports](/guide/modular-imports) for details.
 :::

docs/project/changelog.md

@@ -5,6 +5,15 @@ All notable changes to @mcabreradev/filter are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.9.0] - 2026-03-18
+
+### Added
+- **`find` alias**: `find` is now exported as an alias for `filter` with the identical signature and behavior. Import from `@mcabreradev/filter` or `@mcabreradev/filter/core`. Use whichever name reads more naturally in your codebase.
+  ```typescript
+  import { find } from '@mcabreradev/filter';
+  const result = find(users, { active: true }); // same as filter()
+  ```
+
 ## [5.8.2] - 2025-11-17
 
 ### Documentation

src/core/filter/filter.ts

@@ -102,6 +102,8 @@ export function filter<T>(array: T[], expression: Expression<T>, options?: Filte
   }
 }
 
+export const find = filter;
+
 export function clearFilterCache(): void {
   globalFilterCache.clear();
   memoization.clearAll();

src/core/filter/index.ts

@@ -1 +1 @@
-export { filter, clearFilterCache, getFilterCacheStats } from './filter.js';
+export { filter, find, clearFilterCache, getFilterCacheStats } from './filter.js';

src/core/index.ts

@@ -1,4 +1,4 @@
-export { filter, clearFilterCache, getFilterCacheStats } from './filter/filter.js';
+export { filter, find, clearFilterCache, getFilterCacheStats } from './filter/filter.js';
 export {
   filterLazy,
   filterLazyAsync,

src/index.ts

@@ -1,6 +1,7 @@
 import { filter } from './core/index.js';
 
 export { filter };
+export { find } from './core/index.js';
 
 export { clearFilterCache, getFilterCacheStats } from './core/index.js';
 
@@ -26,7 +27,7 @@ export {
   forEach,
   every,
   some,
-  find,
+  find as lazyFind,
   chunk,
   flatten,
   asyncMap,