Installation

Learn how to install and configure @mcabreradev/filter for your project.

Package Managers

Install using your preferred package manager:

npm

npm install @mcabreradev/filter

yarn

yarn add @mcabreradev/filter

pnpm

pnpm add @mcabreradev/filter

bun

bun add @mcabreradev/filter

Requirements

• Node.js: >= 20
• TypeScript: >= 5.0 (optional)
• Zero dependencies - Truly dependency-free!

Optional Validation

If you need runtime validation features (like validateExpression or validateOptions), install Zod as a peer dependency:

npm install zod

The core filtering functionality works without any dependencies.

Import Styles

@mcabreradev/filter supports two import styles:

Classic Import (All Features)

Import everything from the main package:

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

const results = filter(users, { active: true });

Bundle size: ~12 KB (gzipped)

Best for:

• Getting started quickly
• Small applications
• Prototyping
• Development

Modular Import (Production Recommended)

Import only what you need for optimal bundle size:

// Core filtering
import { filter } from '@mcabreradev/filter/core';

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

// Vue composables
import { useFilter } from '@mcabreradev/filter/vue';

// Lazy evaluation
import { filterLazy } from '@mcabreradev/filter/lazy';

// Operators
import { applyComparisonOperators } from '@mcabreradev/filter/operators/comparison';

Bundle size: ~3-5 KB (gzipped) - 50-70% smaller!

Best for:

• Production applications
• Bundle size optimization
• Tree-shaking support
• Specific feature usage

Recommendation

Use classic imports for development and prototyping, then switch to modular imports for production to optimize bundle size.

TypeScript Setup

Add to your tsconfig.json for optimal type support:

{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Framework-Specific Setup

React

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

// Modular import (recommended)
import { useFilter } from '@mcabreradev/filter/react';

function UserList() {
  const { filtered, isFiltering } = useFilter(users, { active: true });
  return <div>{/* ... */}</div>;
}

Vue 3

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

// Modular import (recommended)
import { useFilter } from '@mcabreradev/filter/vue';

const searchTerm = ref('');
const { filtered, isFiltering } = useFilter(users, searchTerm);

CDN Usage

For quick prototyping without a build step:

<script type="module">
  import { filter } from 'https://esm.sh/@mcabreradev/filter';
  
  const users = [
    { name: 'Alice', age: 30 },
    { name: 'Bob', age: 25 }
  ];
  
  const adults = filter(users, { age: { $gte: 18 } });
  console.log(adults);
</script>

Deno

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

const users = [
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 }
];

const adults = filter(users, { age: { $gte: 18 } });
console.log(adults);

Browser Support

Works in all modern browsers:

• ✅ Chrome/Edge (latest)
• ✅ Firefox (latest)
• ✅ Safari (latest)
• ✅ Node.js >= 20
• ✅ Deno
• ✅ Bun

Bundle Size

Import Strategy	Size (gzipped)	Use Case
import { ... } from '@mcabreradev/filter'	~12 KB	Quick start, prototypes
import { filter } from '@mcabreradev/filter/core'	~3 KB	Production apps
import { useFilter } from '@mcabreradev/filter/react'	~3 KB	React apps
import { filterLazy } from '@mcabreradev/filter/lazy'	~2 KB	Large datasets

See Modular Imports for detailed bundle optimization strategies.

Verification

Verify your installation works:

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

const users = [
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 }
];

const adults = filter(users, { age: { $gte: 18 } });
console.log(adults); // [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]

Next Steps

• Quick Start - Get started in minutes
• Modular Imports - Optimize bundle size
• Basic Filtering - Learn core concepts
• Framework Integrations - React, Vue guides

Troubleshooting

Module not found

If you see module resolution errors:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

TypeScript errors

Ensure your tsconfig.json has:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "esModuleInterop": true
  }
}

Import path errors

For modular imports, ensure you're using the exact paths:

// ✅ Correct
import { filter } from '@mcabreradev/filter/core';

// ❌ Wrong
import { filter } from '@mcabreradev/filter/core/index';

Support

Need help? Check out:

• FAQ - Common questions
• Troubleshooting - Common issues
• GitHub Issues - Report bugs
• GitHub Discussions - Ask questions