Table of Contents

The Hook

constresults=data.filter(item=>item.age>=18&&item.status==='active'&&(item.role==='admin'||item.role==='moderator')&&item.email.endsWith('@company.com')&&item.createdAt>=thirtyDaysAgo);

constresults=filter(data,{age:{$gte:18},status:'active',role:['admin','moderator'],email:{$endsWith:'@company.com'},createdAt:{$gte:thirtyDaysAgo}});

Quick Start

Install

npm install @mcabreradev/filter# orpnpm add @mcabreradev/filter# oryarn add @mcabreradev/filter

Your First Filter

import{filter}from'@mcabreradev/filter';constusers=[{name:'Alice',age:30,city:'Berlin',active:true},{name:'Bob',age:25,city:'London',active:false},{name:'Charlie',age:35,city:'Berlin',active:true}];// Simple string searchconstberlinUsers=filter(users,'Berlin');// → [{ name: 'Alice', ... }, { name: 'Charlie', ... }]// Object-based filteringconstactiveBerlinUsers=filter(users,{city:'Berlin',active:true});// → [{ name: 'Alice', ... }]// MongoDB-style operatorsconstadults=filter(users,{age:{$gte:18}});// → All users (all are 18+)// That's it! You're filtering like a pro.

Why You'll Love It

🚀Blazing Fast

🎯Developer Friendly

🔧Incredibly Flexible

📦Production Ready

🪶Ultra Lightweight

🔒Type-Safe by Default

🎨Framework Agnostic

📊Handles Big Data

Examples

Basic Filtering

// String matching - searches all propertiesfilter(products,'Laptop');// Object matching - AND logicfilter(products,{category:'Electronics',price:{$lt:1000}});// Wildcard patterns (SQL-like)filter(users,'%alice%');// Contains 'alice'filter(users,'Al%');// Starts with 'Al'filter(users,'%son');// Ends with 'son'

MongoDB-Style Operators

// Comparison operatorsfilter(products,{price:{$gte:100,$lte:500}});// Array operatorsfilter(products,{category:{$in:['Electronics','Books']},tags:{$contains:'sale'}});// String operatorsfilter(users,{email:{$endsWith:'@company.com'},name:{$startsWith:'John'}});// Logical operatorsfilter(products,{$and:[{inStock:true},{$or:[{rating:{$gte:4.5}},{price:{$lt:50}}]}]});

Array OR Syntax (Intuitive!)

// Clean array syntax - no $in needed!filter(products,{category:['Electronics','Books']});// Equivalent to: { category: { $in: ['Electronics', 'Books'] }}// Multiple propertiesfilter(users,{city:['Berlin','Paris'],role:['admin','moderator']});

Geospatial Queries

import{filter,typeGeoPoint}from'@mcabreradev/filter';constuserLocation:GeoPoint={lat:52.52,lng:13.405};// Find restaurants within 5kmfilter(restaurants,{location:{$near:{center:userLocation,maxDistanceMeters:5000}},rating:{$gte:4.5}});

Datetime Filtering

// Events in next 7 daysfilter(events,{date:{$upcoming:{days:7}}});// Recent events (last 24 hours)filter(events,{date:{$recent:{hours:24}}});// Weekday events during business hoursfilter(events,{date:{$dayOfWeek:[1,2,3,4,5]},startTime:{$timeOfDay:{start:9,end:17}}});// Users who logged in recently (last 7 days)filter(users,{lastLogin:{$recent:{days:7}}});// Upcoming meetings in next 2 hoursfilter(meetings,{startTime:{$upcoming:{hours:2}}});// Weekend events onlyfilter(events,{date:{$isWeekend:true}});// Calculate age (users over 18)filter(users,{birthDate:{$age:{$gte:18}}});// Events before a specific datefilter(events,{date:{$isBefore:newDate('2025-12-31')}});

Performance Optimization

// Enable caching for repeated queriesconstresults=filter(largeDataset,expression,{enableCache:true,orderBy:{field:'price',direction:'desc'},limit:100});// Lazy evaluation for large datasetsimport{filterFirst}from'@mcabreradev/filter';constfirst10=filterFirst(users,{premium:true},10);

Real-World: E-commerce Search

interfaceProduct{id:number;name:string;price:number;category:string;brand:string;rating:number;inStock:boolean;tags:string[];}constproducts:Product[]=[...];// Find affordable, highly-rated electronics in stockconstaffordableElectronics=filter(products,{category:'Electronics',price:{$lte:1000},rating:{$gte:4.5},inStock:true});// Search with multiple filtersconstsearchResults=filter(products,{name:{$contains:'laptop'},brand:{$in:['Apple','Dell','HP']},price:{$gte:500,$lte:2000}});// Sort resultsconstsortedProducts=filter(products,{category:'Electronics',inStock:true},{orderBy:[{field:'price',direction:'asc'},{field:'rating',direction:'desc'}],limit:20});

Framework Integrations

React

import{useFilter}from'@mcabreradev/filter/react';functionUserList(){const{ filtered, isFiltering}=useFilter(users,{active:true});return<div>{filtered.map(u=><Userkey={u.id}{...u}/>)}</div>;}

Vue

<script setup>import {useFilter }from'@mcabreradev/filter/vue';const {filtered }=useFilter(users, { active:true });</script>

Svelte

<script>import {useFilter }from'@mcabreradev/filter/svelte';const {filtered }=useFilter(users,writable({ active:true }));</script>

Angular

import{FilterService}from'@mcabreradev/filter/angular';@Component({providers:[FilterService],template:`    @for (user of filterService.filtered(); track user.id) {      <div>{{ user.name }}</div>    }  `})exportclassUserListComponent{filterService=inject(FilterService<User>);}

SolidJS

import{useFilter}from'@mcabreradev/filter/solidjs';functionUserList(){const{ filtered}=useFilter(()=>users,()=>({active:true}));return<Foreach={filtered()}>{(u)=><div>{u.name}</div>}</For>;}

Preact

import{useFilter}from'@mcabreradev/filter/preact';functionUserList(){const{ filtered}=useFilter(users,{active:true});return<div>{filtered.map(u=><divkey={u.id}>{u.name}</div>)}</div>;}

Core Features

Supported Operators

TypeScript Support

interfaceProduct{name:string;price:number;tags:string[];}filter<Product>(products,{price:{},// Autocomplete: $gt, $gte, $lt, $lte, $eq, $nename:{},// Autocomplete: $startsWith, $endsWith, $contains, $regextags:{}// Autocomplete: $in, $nin, $contains, $size});

Configuration Options

filter(data,expression,{caseSensitive:false,// Case-sensitive string matchingmaxDepth:3,// Max depth for nested objectsenableCache:true,// Enable result caching (530x faster)orderBy:'price',// Sort resultslimit:10,// Limit number of resultsdebug:true// Visual debugging mode});

Advanced Features

Lazy Evaluation

import{filterLazy,filterFirst,filterExists,filterCount}from'@mcabreradev/filter';// Process items on-demandconstfiltered=filterLazy(millionRecords,{active:true});for(constitemoffiltered){process(item);if(shouldStop)break;// Early exit}// Find first N matchesconstfirst10=filterFirst(users,{premium:true},10);// Check existence without processing all itemsconsthasAdmin=filterExists(users,{role:'admin'});// Count matchesconstactiveCount=filterCount(users,{active:true});

Memoization & Caching

// First call - processes dataconstresults=filter(largeDataset,{age:{$gte:18}},{enableCache:true});// Second call - returns cached result instantlyconstsameResults=filter(largeDataset,{age:{$gte:18}},{enableCache:true});

Visual Debugging

filter(users,{city:'Berlin'},{debug:true});// Console output:// ┌─ Filter Debug Tree// │  Expression: {"city":"Berlin"}// │  Matched: 3/10 (30.0%)// │  Execution time: 0.42ms// └─ ✓ city = "Berlin"

Documentation

📖 Complete Guides

🎯 Quick Links

Performance

// ✅ Fast: Operators with early exitfilter(data,{age:{$gte:18}});// ✅ Fast with caching for repeated queriesfilter(largeData,expression,{enableCache:true});// ✅ Fast with lazy evaluation for large datasetsconstresult=filterFirst(millionRecords,{active:true},100);

Bundle Size

Browser Support

Migration from v3.x

// ✅ All v3.x syntax still worksfilter(data,'string');filter(data,{prop:'value'});filter(data,(item)=>true);filter(data,'%pattern%');// ✅ New in v5.xfilter(data,{age:{$gte:18}});filter(data,expression,{enableCache:true});

Changelog

v5.8.3 (Current)

v5.8.0

v5.7.0

v5.6.0

v5.5.0

Contributing

License

Support