Skip to content

index.md

Latest commit

 

History

History
360 lines (291 loc) · 10.1 KB

index.md

File metadata and controls

360 lines (291 loc) · 10.1 KB
layout home
hero
name text tagline image actions
@mcabreradev/filter
SQL-like Array Filtering
A powerful TypeScript/JavaScript library with MongoDB-style operators, lazy evaluation, and truly zero dependencies
src alt
/logo.svg
Filter Library
theme text link
brand
Get Started
/guide/getting-started
theme text link
alt
Try Playground
/playground/
theme text link
alt
View on GitHub
features
icon title details
🎯
SQL-like Wildcards
Use % and _ for flexible pattern matching. Search like a pro with familiar SQL syntax.
icon title details
🔍
Deep Object Filtering
Search through nested objects up to configurable depths. No data structure is too complex.
icon title details
⚡
Zero Dependencies
Truly zero dependencies! Lightweight and production-ready. Optional Zod for validation features.
icon title details
🔒
Type-Safe
Built with strict TypeScript for maximum reliability. Full IntelliSense support.
icon title details
🎨
Multiple Strategies
String patterns, objects, predicates, operators, or custom comparators. Your choice.
icon title details
🚀
Performance Optimized
Optional caching and regex compilation. 530x faster with memoization.
icon title details
📦
MongoDB-Style Operators
30+ operators for advanced filtering including $and, $or, $not, $regex, geospatial, and datetime operators.
icon title details
💨
Lazy Evaluation
Process large datasets efficiently with generators. 500x faster for early exits.
icon title details
🎁
Modular Imports
Tree-shakeable exports for optimal bundle size. 50-70% smaller with granular imports.
icon title details
🐛
Debug Mode
Visual debugging with tree visualization, match statistics, and performance metrics. Understand your filters.
icon title details
🎨
Framework Integration
React Hooks, Vue Composables, Angular Services, SolidJS, and Preact. First-class framework support.
icon title details
🧪
Battle-Tested
300+ tests ensuring reliability. 100% test coverage across all features.
icon title details
📚
Comprehensive Docs
Extensive documentation with 150+ examples. Learn by doing.
icon title details
🌐
Universal
Works in Node.js, browsers, and edge runtimes. Deploy anywhere.

Quick Start

Install the package:

# Using npm
npm install @mcabreradev/filter

# Using yarn
yarn add @mcabreradev/filter

# Using pnpm
pnpm add @mcabreradev/filter

::: tip Import Styles Choose between classic imports (all features) or modular imports (50-70% smaller bundle). Learn more :::

Start filtering:

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

// Or modular import (recommended for production)
import { filter } from '@mcabreradev/filter/core';

const users = [
  { name: 'Alice', email: 'alice@example.com', age: 30, city: 'Berlin' },
  { name: 'Bob', email: 'bob@example.com', age: 25, city: 'London' },
  { name: 'Charlie', email: 'charlie@example.com', age: 35, city: 'Berlin' }
];

// Simple string matching
filter(users, 'Berlin');
// → Returns Alice and Charlie

// Wildcard patterns
filter(users, '%alice%');
// → Returns Alice

// Object-based filtering
filter(users, { city: 'Berlin', age: 30 });
// → Returns Alice

// MongoDB-style operators
filter(users, { age: { $gte: 25, $lt: 35 } });
// → Returns Bob and Alice

// Logical operators
filter(users, {
  $and: [
    { city: 'Berlin' },
    { age: { $gte: 30 } }
  ]
});
// → Returns Alice and Charlie

// Debug mode for visual inspection
import { filterDebug } from '@mcabreradev/filter';

const result = filterDebug(users, {
  $and: [
    { city: 'Berlin' },
    { $or: [{ age: { $lt: 30 } }, { premium: true }] }
  ]
});

result.print();
// Outputs visual tree with match statistics

Framework Integration

React

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

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

Vue

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

const searchTerm = ref('');
const { filtered, isFiltering } = useFilter(users, searchTerm);
</script>

Why Choose This Library?

⚡
Blazing Fast
530x faster with caching, 500x faster with lazy evaluation. Optimized for production workloads.
🎯
Developer Friendly
Intuitive API that feels natural. SQL-like syntax you already know. Full TypeScript support.
🔧
Flexible
Multiple filtering strategies. Use what fits your use case. Combine approaches seamlessly.
📦
Production Ready
Battle-tested with 300+ tests. Used in production by companies worldwide. MIT licensed.
🪶
Ultra Lightweight
Truly zero dependencies! Tiny 12 KB 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, Angular, Node.js, Deno, Bun. First-class hooks and composables included.
📊
Handles Big Data
Process millions of records efficiently. Lazy evaluation for memory optimization. Built for scale.
🛡️
Runtime Validation
Optional Zod-powered schema validation. Catch invalid queries before they run. Safe and predictable behavior.
🎓
Easy Learning Curve
Familiar MongoDB and SQL patterns. Comprehensive docs with 150+ examples. Get productive in minutes.
🔄
Active Maintenance
Regular updates and improvements. Responsive to issues and feature requests. Community-driven development.
🌍
Edge-Ready
Works in Cloudflare Workers, Vercel Edge, Deno Deploy. Perfect for serverless and edge computing.
🧪
Test Coverage
100% code coverage. 300+ unit and integration tests. Type-level tests for TypeScript guarantees.
🎭
No Vendor Lock-in
Pure JavaScript/TypeScript. No proprietary formats. Easy to migrate to or from. You own your data.
⚙️
Highly Configurable
Customize behavior to your needs. Configure depth, caching, case sensitivity. Fine-tune performance.

Real-World Example

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

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

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

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

// Complex queries with logical operators
const premiumDeals = filter(products, {
  $and: [
    { inStock: true },
    {
      $or: [
        { rating: { $gte: 4.5 } },
        { price: { $lt: 50 } }
      ]
    },
    { $not: { category: 'Clearance' } }
  ]
});

Community & Support

License

MIT License - see LICENSE for details.

Copyright © 2025 Miguelangel Cabrera