@mcabreradev/filter

Filter arrays like a pro. A powerful, SQL-like array filtering library for TypeScript with advanced pattern matching, MongoDB-style operators, deep object comparison, geospatial queries, and zero dependencies.

Quick Start • Why You'll Love It • Examples • Playground • Documentation

The Hook

Tired of writing complex filter logic? Stop wrestling with nested Array.filter() chains and verbose conditionals. Write clean, declarative filters that read like queries.

Before:

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

After:

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

Same result. 70% less code. 100% more readable.

Quick Start

Install

npm install @mcabreradev/filter
# or
pnpm add @mcabreradev/filter
# or
yarn add @mcabreradev/filter

Requirements: Node.js >= 20, TypeScript 5.0+ (optional)

Your First Filter

import { filter } from '@mcabreradev/filter';

const users = [
  { 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 search
const berlinUsers = filter(users, 'Berlin');
// → [{ name: 'Alice', ... }, { name: 'Charlie', ... }]

// Object-based filtering
const activeBerlinUsers = filter(users, {
  city: 'Berlin',
  active: true
});
// → [{ name: 'Alice', ... }]

// MongoDB-style operators
const adults = filter(users, {
  age: { $gte: 18 }
});
// → All users (all are 18+)

// That's it! You're filtering like a pro.

🎮 Try it in the Playground →

Why You'll Love It

🚀 Blazing Fast

530x faster with optional caching
500x faster with lazy evaluation for large datasets
Optimized for production workloads

🎯 Developer Friendly

Intuitive API that feels natural
SQL-like syntax you already know
Full TypeScript support with intelligent autocomplete

🔧 Incredibly Flexible

Multiple filtering strategies (strings, objects, operators, predicates)
Works with any data structure
Combine approaches seamlessly

📦 Production Ready

993+ tests ensuring reliability
Zero dependencies (12KB gzipped)
Used in production by companies worldwide
MIT licensed

🪶 Ultra Lightweight

Truly zero dependencies!
Tiny 12KB bundle
Optional Zod for validation
No bloat, just pure filtering power

🔒 Type-Safe by Default

Built with strict TypeScript
Catch errors at compile time
Full IntelliSense and autocomplete support

🎨 Framework Agnostic

Works everywhere: React, Vue, Svelte, Angular, SolidJS, Preact
First-class hooks and composables included
SSR compatible (Next.js, Nuxt, SvelteKit)

📊 Handles Big Data

Process millions of records efficiently
Lazy evaluation for memory optimization
Built for scale

Examples

Basic Filtering

// String matching - searches all properties
filter(products, 'Laptop');

// Object matching - AND logic
filter(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 operators
filter(products, {
  price: { $gte: 100, $lte: 500 }
});

// Array operators
filter(products, {
  category: { $in: ['Electronics', 'Books'] },
  tags: { $contains: 'sale' }
});

// String operators
filter(users, {
  email: { $endsWith: '@company.com' },
  name: { $startsWith: 'John' }
});

// Logical operators
filter(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 properties
filter(users, {
  city: ['Berlin', 'Paris'],
  role: ['admin', 'moderator']
});

Geospatial Queries

import { filter, type GeoPoint } from '@mcabreradev/filter';

const userLocation: GeoPoint = { lat: 52.52, lng: 13.405 };

// Find restaurants within 5km
filter(restaurants, {
  location: {
    $near: {
      center: userLocation,
      maxDistanceMeters: 5000
    }
  },
  rating: { $gte: 4.5 }
});

Datetime Filtering

// Events in next 7 days
filter(events, {
  date: { $upcoming: { days: 7 } }
});

// Recent events (last 24 hours)
filter(events, {
  date: { $recent: { hours: 24 } }
});

// Weekday events during business hours
filter(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 hours
filter(meetings, {
  startTime: { $upcoming: { hours: 2 } }
});

// Weekend events only
filter(events, {
  date: { $isWeekend: true }
});

// Calculate age (users over 18)
filter(users, {
  birthDate: { $age: { $gte: 18 } }
});

// Events before a specific date
filter(events, {
  date: { $isBefore: new Date('2025-12-31') }
});

Performance Optimization

// Enable caching for repeated queries
const results = filter(largeDataset, expression, {
  enableCache: true,
  orderBy: { field: 'price', direction: 'desc' },
  limit: 100
});

// Lazy evaluation for large datasets
import { filterFirst } from '@mcabreradev/filter';
const first10 = filterFirst(users, { premium: true }, 10);

Real-World: E-commerce Search

interface Product {
  id: number;
  name: string;
  price: number;
  category: string;
  brand: string;
  rating: number;
  inStock: boolean;
  tags: string[];
}

const products: Product[] = [...];

// Find affordable, highly-rated electronics in stock
const affordableElectronics = filter(products, {
  category: 'Electronics',
  price: { $lte: 1000 },
  rating: { $gte: 4.5 },
  inStock: true
});

// Search with multiple filters
const searchResults = filter(products, {
  name: { $contains: 'laptop' },
  brand: { $in: ['Apple', 'Dell', 'HP'] },
  price: { $gte: 500, $lte: 2000 }
});

// Sort results
const sortedProducts = filter(products, {
  category: 'Electronics',
  inStock: true
}, {
  orderBy: [
    { field: 'price', direction: 'asc' },
    { field: 'rating', direction: 'desc' }
  ],
  limit: 20
});

Framework Integrations

Works seamlessly with your favorite framework:

React

import { useFilter } from '@mcabreradev/filter/react';

function UserList() {
  const { filtered, isFiltering } = useFilter(users, { active: true });
  return <div>{filtered.map(u => <User key={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>
    }
  `
})
export class UserListComponent {
  filterService = inject(FilterService<User>);
}

SolidJS

import { useFilter } from '@mcabreradev/filter/solidjs';

function UserList() {
  const { filtered } = useFilter(
    () => users,
    () => ({ active: true })
  );
  return <For each={filtered()}>{(u) => <div>{u.name}</div>}</For>;
}

Preact

import { useFilter } from '@mcabreradev/filter/preact';

function UserList() {
  const { filtered } = useFilter(users, { active: true });
  return <div>{filtered.map(u => <div key={u.id}>{u.name}</div>)}</div>;
}

Features:

✅ Full TypeScript support with generics
✅ Debounced search hooks/services
✅ Pagination support
✅ SSR compatible
✅ 100% test coverage

📖 Complete Framework Guide →

Core Features

Supported Operators

Comparison: $gt, $gte, $lt, $lte, $eq, $ne Array: $in, $nin, $contains, $size String: $startsWith, $endsWith, $contains, $regex, $match Logical: $and, $or, $not Geospatial: $near, $geoBox, $geoPolygon Datetime: $recent, $upcoming, $dayOfWeek, $timeOfDay, $age, $isWeekday, $isWeekend, $isBefore, $isAfter

TypeScript Support

Full type safety with intelligent autocomplete:

interface Product {
  name: string;
  price: number;
  tags: string[];
}

filter<Product>(products, {
  price: {  }, // Autocomplete: $gt, $gte, $lt, $lte, $eq, $ne
  name: {  },  // Autocomplete: $startsWith, $endsWith, $contains, $regex
  tags: {  }   // Autocomplete: $in, $nin, $contains, $size
});

Configuration Options

filter(data, expression, {
  caseSensitive: false,      // Case-sensitive string matching
  maxDepth: 3,                // Max depth for nested objects
  enableCache: true,          // Enable result caching (530x faster)
  orderBy: 'price',           // Sort results
  limit: 10,                  // Limit number of results
  debug: true                 // Visual debugging mode
});

Advanced Features

Lazy Evaluation

Efficiently process large datasets with lazy evaluation:

import { filterLazy, filterFirst, filterExists, filterCount } from '@mcabreradev/filter';

// Process items on-demand
const filtered = filterLazy(millionRecords, { active: true });
for (const item of filtered) {
  process(item);
  if (shouldStop) break; // Early exit
}

// Find first N matches
const first10 = filterFirst(users, { premium: true }, 10);

// Check existence without processing all items
const hasAdmin = filterExists(users, { role: 'admin' });

// Count matches
const activeCount = filterCount(users, { active: true });

Benefits:

🚀 500x faster for operations that don't need all results
💾 100,000x less memory for large datasets
⚡ Early exit optimization

📖 Lazy Evaluation Guide →

Memoization & Caching

530x faster with optional caching:

// First call - processes data
const results = filter(largeDataset, { age: { $gte: 18 } }, { enableCache: true });

// Second call - returns cached result instantly
const sameResults = filter(largeDataset, { age: { $gte: 18 } }, { enableCache: true });

Performance Gains:

Scenario	Without Cache	With Cache	Speedup
Simple query (10K items)	5.3ms	0.01ms	530x
Regex pattern	12.1ms	0.02ms	605x
Complex nested	15.2ms	0.01ms	1520x

📖 Memoization Guide →

Visual Debugging

Built-in debug mode with expression tree visualization:

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"

📖 Debug Guide →

Documentation

📖 Complete Guides

Getting Started - Installation and first steps
All Operators - Complete operator reference
Geospatial Queries - Location-based filtering
Datetime Operators - Temporal filtering
Framework Integrations - React, Vue, Svelte, Angular, SolidJS, Preact
Lazy Evaluation - Efficient large dataset processing
Memoization & Caching - Performance optimization
Visual Debugging - Debug mode and tree visualization

🎯 Quick Links

Performance

Filter is optimized for performance:

Operators use early exit strategies for fast evaluation
Regex patterns are compiled and cached
Optional caching for repeated queries (530x-1520x faster)
Lazy evaluation for efficient large dataset processing (500x faster)
Type guards for fast type checking

// ✅ Fast: Operators with early exit
filter(data, { age: { $gte: 18 } });

// ✅ Fast with caching for repeated queries
filter(largeData, expression, { enableCache: true });

// ✅ Fast with lazy evaluation for large datasets
const result = filterFirst(millionRecords, { active: true }, 100);

Bundle Size

Import	Size (gzipped)	Tree-Shakeable
Full	12 KB	✅
Core only	8.4 KB	✅
React hooks	9.2 KB	✅
Lazy evaluation	5.4 KB	✅

Browser Support

Works in all modern browsers and Node.js:

Node.js: >= 20
Browsers: Chrome, Firefox, Safari, Edge (latest versions)
TypeScript: >= 5.0
Module Systems: ESM, CommonJS

Migration from v3.x

Good news: v5.x is 100% backward compatible! All v3.x code continues to work.

// ✅ All v3.x syntax still works
filter(data, 'string');
filter(data, { prop: 'value' });
filter(data, (item) => true);
filter(data, '%pattern%');

// ✅ New in v5.x
filter(data, { age: { $gte: 18 } });
filter(data, expression, { enableCache: true });

📖 Migration Guide →

Changelog

v5.8.3 (Current)

🐛 Bug Fix: Fixed critical issue where limit option was ignored in cache key
⚡ Performance: Replaced unbounded caches with LRU strategy to prevent memory leaks
🔒 Stability: Improved memory management for long-running applications

v5.8.0

🎨 New Framework Integrations: Angular, SolidJS, and Preact support
🔢 Limit Option: New limit configuration option to restrict result count
📊 OrderBy Option: New OrderBy configuration option to sort filtered results by field(s) in ascending or descending order
✅ 993+ tests with comprehensive coverage

v5.7.0

🅰️ Angular: Services and Pipes with Signals support
🔷 SolidJS: Signal-based reactive hooks
⚡ Preact: Lightweight hooks API

v5.6.0

🌍 Geospatial Operators: Location-based filtering with $near, $geoBox, $geoPolygon
📅 Datetime Operators: Temporal filtering with $recent, $upcoming, $dayOfWeek, $age

v5.5.0

🎨 Array OR Syntax: Intuitive array-based OR filtering
🐛 Visual Debugging: Built-in debug mode with expression tree visualization
🎮 Interactive Playground: Online playground for testing filters

📖 Full Changelog →

Contributing

We welcome contributions! Please read our Contributing Guide for details.

Ways to Contribute:

Report bugs or request features via GitHub Issues
Submit pull requests with bug fixes or new features
Improve documentation
Share your use cases and examples

License

MIT License - see LICENSE.md for details.

Support

Made with ❤️ for the JavaScript/TypeScript community

Name		Name	Last commit message	Last commit date
Latest commit History 218 Commits
.claude		.claude
.github		.github
.husky		.husky
__test__		__test__
docs		docs
examples		examples
scripts		scripts
src		src
.editorconfig		.editorconfig
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc		.prettierrc
.size-limit.json		.size-limit.json
CLAUDE.md		CLAUDE.md
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
techstack.md		techstack.md
techstack.yml		techstack.yml
tsconfig.json		tsconfig.json
tsconfig.tsd.json		tsconfig.tsd.json
tsd.json		tsd.json
typedoc.json		typedoc.json
vitest.config.ts		vitest.config.ts
vitest.docs.config.ts		vitest.docs.config.ts

License

mcabreradev/filter

Folders and files

Latest commit

History

Repository files navigation

@mcabreradev/filter

Table of Contents

The Hook

Quick Start

Install

Your First Filter

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

MongoDB-Style Operators

Array OR Syntax (Intuitive!)

Geospatial Queries

Datetime Filtering

Performance Optimization

Real-World: E-commerce Search

Framework Integrations

React

Vue

Svelte

Angular

SolidJS

Preact

Core Features

Supported Operators

TypeScript Support

Configuration Options

Advanced Features

Lazy Evaluation

Memoization & Caching

Visual Debugging

Documentation

📖 Complete Guides

🎯 Quick Links

Performance

Bundle Size

Browser Support

Migration from v3.x

Changelog

v5.8.3 (Current)

v5.8.0

v5.7.0

v5.6.0

v5.5.0

Contributing

License

Support

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Uh oh!

Contributors 5

Uh oh!

Languages