@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 Problem

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 — the usual mess:

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 — clean and declarative:

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

// Object matching — AND logic across fields
const activeBerlinUsers = filter(users, { city: 'Berlin', active: true });
// → [{ name: 'Alice', ... }]

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

// SQL-like wildcards
const startsWithAl = filter(users, 'Al%');
// → [{ name: 'Alice', ... }]

🎮 Try it in the Playground →

Why You'll Love It

🚀 Blazing Fast

530x faster on repeated queries with optional LRU caching
500x faster with lazy evaluation for large datasets
Compiled predicates and regex patterns cached automatically

🎯 Developer Friendly

Intuitive API — reads like English
SQL-like wildcards (%, _) you already know
Full TypeScript generics with intelligent autocomplete

🔧 Incredibly Flexible

Four filtering strategies: strings, objects, operators, predicates
Combine them seamlessly in a single expression
Works with any data shape — flat, nested, arrays

📦 Production Ready

1,004+ tests ensuring bulletproof reliability
Zero runtime dependencies (only Zod for optional validation)
Battle-tested in production applications
MIT licensed

🪶 Ultra Lightweight

Full package: 12KB gzipped
Core only: 8.4KB gzipped
Zero mandatory dependencies
Tree-shakeable — only pay for what you use

🔒 Type-Safe by Default

Built with strict TypeScript
Catch errors at compile time, not runtime
Full IntelliSense for operators based on field types

🎨 Framework Agnostic

First-class hooks: React, Vue, Svelte, Angular, SolidJS, Preact
Debounced search, pagination, and reactive state out of the box
SSR compatible: Next.js, Nuxt, SvelteKit

📊 Handles Big Data

Generator-based lazy evaluation for millions of records
Early exit — stop processing when you have enough results
LRU caches with TTL prevent memory leaks in long-running apps

Examples

Basic Filtering

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

// Exact field matching — AND logic
filter(products, { category: 'Electronics', price: { $lt: 1000 } });

// SQL wildcard patterns
filter(users, '%alice%');   // contains 'alice'
filter(users, 'Al%');       // starts with 'Al'
filter(users, '%son');      // ends with 'son'
filter(users, 'J_hn');      // single-char wildcard

// Predicate functions — full control
filter(users, (u) => u.score > 90 && u.verified);

MongoDB-Style Operators

// Comparison
filter(products, { price: { $gte: 100, $lte: 500 } });
filter(products, { rating: { $gt: 4 }, stock: { $ne: 0 } });

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

// String matching
filter(users, {
  email: { $endsWith: '@company.com' },
  name: { $startsWith: 'John' },
  bio: { $regex: /developer/i }
});

// Logical combinators
filter(products, {
  $and: [
    { inStock: true },
    { $or: [{ rating: { $gte: 4.5 } }, { price: { $lt: 50 } }] }
  ]
});

// Negate with $not
filter(users, { role: { $not: 'banned' } });

Array OR Syntax (Intuitive!)

// Pass an array → automatic OR logic, no $in needed
filter(products, { category: ['Electronics', 'Books'] });
// Same as: { category: { $in: ['Electronics', 'Books'] } }

// Combine across fields
filter(users, {
  city: ['Berlin', 'Paris', 'London'],
  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 rated 4.5+
filter(restaurants, {
  location: { $near: { center: userLocation, maxDistanceMeters: 5000 } },
  rating: { $gte: 4.5 }
});

// Bounding box search
filter(places, {
  location: {
    $geoBox: {
      topLeft: { lat: 53.0, lng: 13.0 },
      bottomRight: { lat: 52.0, lng: 14.0 }
    }
  }
});

Datetime Filtering

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

// Recent activity (last 24 hours)
filter(logs, { createdAt: { $recent: { hours: 24 } } });

// Weekday events during business hours
filter(events, {
  date: { $dayOfWeek: [1, 2, 3, 4, 5] },       // Mon–Fri
  startTime: { $timeOfDay: { start: 9, end: 17 } }  // 9am–5pm
});

// Users of age 18–65
filter(users, { birthDate: { $age: { min: 18, max: 65 } } });

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

// Events before a deadline
filter(tasks, { dueDate: { $isBefore: new Date('2025-12-31') } });

Performance Optimization

// LRU caching — 530x faster on repeat queries
const results = filter(largeDataset, expression, {
  enableCache: true,
  orderBy: { field: 'price', direction: 'desc' },
  limit: 100
});

// Lazy evaluation — process millions of records without loading all into memory
import { filterFirst, filterExists, filterCount, filterLazy } from '@mcabreradev/filter';

const first10 = filterFirst(millionRecords, { premium: true }, 10);
const hasAdmin = filterExists(users, { role: 'admin' });      // exits on first match
const activeCount = filterCount(users, { active: true });     // no array allocated

Real-World: E-commerce Search

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

// Affordable, highly-rated electronics in stock
const results = filter<Product>(products, {
  category: 'Electronics',
  price: { $lte: 1000 },
  rating: { $gte: 4.5 },
  inStock: true
});

// Full-text search with brand filter
const searchResults = filter<Product>(products, {
  name: { $contains: 'laptop' },
  brand: ['Apple', 'Dell', 'HP'],
  price: { $gte: 500, $lte: 2000 }
});

// Sorted and paginated results
const page1 = filter<Product>(products, { category: 'Electronics', inStock: true }, {
  orderBy: [
    { field: 'price', direction: 'asc' },
    { field: 'rating', direction: 'desc' }
  ],
  limit: 20
});

Framework Integrations

First-class hooks and composables — reactive, debounced, paginated, ready to drop in:

React

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

function UserList() {
  const { filtered, isFiltering } = useFilter(users, { active: true });

  return (
    <ul>
      {filtered.map(u => <li key={u.id}>{u.name}</li>)}
    </ul>
  );
}

// Debounced live search
function SearchBox() {
  const [query, setQuery] = useState('');
  const { filtered, isPending } = useDebouncedFilter(users, query, { delay: 300 });

  return (
    <>
      <input onChange={e => setQuery(e.target.value)} />
      {isPending ? <Spinner /> : filtered.map(u => <User key={u.id} user={u} />)}
    </>
  );
}

Vue

<script setup lang="ts">
import { ref } from 'vue';
import { useFilter } from '@mcabreradev/filter/vue';

const expression = ref({ active: true });
const { filtered, isFiltering } = useFilter(users, expression);
</script>

<template>
  <ul>
    <li v-for="user in filtered" :key="user.id">{{ user.name }}</li>
  </ul>
</template>

Svelte

<script lang="ts">
  import { writable } from 'svelte/store';
  import { useFilter } from '@mcabreradev/filter/svelte';

  const expression = writable({ active: true });
  const { filtered } = useFilter(users, expression);
</script>

{#each $filtered as user}
  <p>{user.name}</p>
{/each}

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>;
}

Every integration includes:

✅ Full TypeScript generics
✅ Debounced search hook with isPending state
✅ Pagination hook with nextPage, prevPage, goToPage
✅ SSR compatible
✅ 100% test coverage

📖 Complete Framework Guide →

Core Features

Supported Operators

Category	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`

18+ operators covering every filtering scenario you'll encounter.

TypeScript Support

Full type safety — autocomplete shows only valid operators for each field type:

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

filter<Product>(products, {
  price: { $gte: 100 },    // ✅ number operators
  name: { $contains: '' }, // ✅ string operators
  tags: { $size: 3 },      // ✅ array operators
  price: { $contains: '' } // ❌ TypeScript error — string op on number field
});

Configuration Options

filter(data, expression, {
  caseSensitive: false,           // default: false
  maxDepth: 3,                    // nested object traversal depth (1–10)
  enableCache: true,              // LRU result caching (530x speedup)
  orderBy: 'price',               // sort field or array of fields
  limit: 10,                      // cap result count
  debug: true,                    // print expression tree to console
  verbose: true,                  // detailed per-item evaluation logs
  showTimings: true,              // execution time per operator
  enablePerformanceMonitoring: true,  // collect performance metrics
});

Advanced Features

Lazy Evaluation

Process large datasets without loading everything into memory:

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

// Generator — pull items one by one, exit any time
const lazy = filterLazy(millionRecords, { active: true });
for (const item of lazy) {
  process(item);
  if (shouldStop) break; // ← zero wasted work
}

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

// Check existence — exits on first match
const hasBanned = filterExists(users, { role: 'banned' });

// Count matches — no array allocated
const total = filterCount(orders, { status: 'pending' });

Scenario	Array.filter	filterLazy / filterFirst
First match in 1M items	~50ms	~0.1ms
Memory for 1M items	~80MB	~0KB
Early exit	❌	✅

📖 Lazy Evaluation Guide →

Memoization & Caching

Three-tier LRU caching strategy with automatic TTL eviction:

// First call — compiles predicates, runs filter, stores result
const results = filter(largeDataset, { age: { $gte: 18 } }, { enableCache: true });

// Subsequent calls — returns cached result instantly
const same = filter(largeDataset, { age: { $gte: 18 } }, { enableCache: true });

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

Caches are bounded (LRU, max 500 entries each) and auto-expire after 5 minutes — safe for long-running servers.

📖 Memoization Guide →

Visual Debugging

Built-in tree visualization for understanding filter behavior:

filter(users, { city: 'Berlin', age: { $gte: 18 } }, { debug: true });

// Console output:
// ┌─ Filter Debug Tree
// │  Expression: {"city":"Berlin","age":{"$gte":18}}
// │  Matched: 3/10 items (30.0%)
// │  Execution time: 0.42ms
// ├─ ✓ city = "Berlin"         [3 matches]
// └─ ✓ age >= 18               [3 matches]

📖 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

Technique	Benefit
Early-exit operators	Skip remaining items on first mismatch
LRU result cache	530x–1520x speedup on repeated queries
LRU predicate cache	Compiled predicates reused across calls
LRU regex cache	Compiled patterns reused, bounded to 500 entries
Lazy generators	500x faster when you don't need all results
Absolute TTL eviction	Stale entries removed after 5 min — no memory leaks

// Enable all optimizations at once
filter(data, expression, { enableCache: true });

// Maximum efficiency for large datasets
const first100 = 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, limit: 50 });

📖 Migration Guide →

Changelog

v5.8.2 (Current)

🐛 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
🐛 Bug Fix: React useDebouncedFilter now reacts to delay prop changes — previously the initial delay was frozen for the hook's lifetime
🔒 Validation: limit option now validated by schema — negative or non-integer values throw a clear configuration error
🔒 Validation: debug, verbose, showTimings, colorize, enablePerformanceMonitoring options now validated by schema
⚡ Performance: Pattern-matching regex cache now delegates to the shared LRU MemoizationManager — the previously unbounded Map is gone
⚡ Performance: LRU cache TTL is now absolute (expire 5 min after creation) instead of sliding — entries can no longer live forever under heavy load
🧹 Code Quality: Svelte pagination replaced subscribe()() anti-pattern with idiomatic get() from svelte/store
✅ Tests: 1,004+ tests — added coverage for every bug fixed in this release

v5.8.0

🎨 New Framework Integrations: Angular, SolidJS, and Preact support
🔢 Limit Option: New limit configuration to restrict result count
📊 OrderBy Option: 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 223 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

Folders and files

Latest commit

History

Repository files navigation

@mcabreradev/filter

Table of Contents

The Problem

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.2 (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

Uh oh!

Languages