Basic Filtering

Learn the fundamentals of filtering with @mcabreradev/filter.

Introduction

@mcabreradev/filter provides a declarative, type-safe way to filter arrays using operator-based expressions.

Simple Equality

Basic Equality Check

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

const users = [
  { name: 'John', age: 25, status: 'active' },
  { name: 'Jane', age: 30, status: 'inactive' },
  { name: 'Bob', age: 35, status: 'active' }
];

const expression = {
  status: { $eq: 'active' }
};

const result = filter(users, expression);

Multiple Properties

const expression = {
  status: { $eq: 'active' },
  age: { $eq: 25 }
};

Comparison Operators

Greater Than / Less Than

const expression = {
  age: { $gt: 25 }
};

const expression = {
  age: { $gte: 25 }
};

const expression = {
  age: { $lt: 30 }
};

const expression = {
  age: { $lte: 30 }
};

Not Equal

const expression = {
  status: { $ne: 'deleted' }
};

Range Queries

const expression = {
  $and: [
    { age: { $gte: 18 } },
    { age: { $lte: 65 } }
  ]
};

String Operators

Contains

const expression = {
  name: { $contains: 'john' }
};

Starts With / Ends With

const expression = {
  email: { $endsWith: '@example.com' }
};

const expression = {
  username: { $startsWith: 'user_' }
};

Regular Expressions

const expression = {
  name: { $regex: /john/i }
};

const expression = {
  email: { $regex: /^[a-z]+@example\.com$/ }
};

Array Operators

In Array

const expression = {
  role: { $in: ['admin', 'moderator', 'user'] }
};

Not In Array

const expression = {
  status: { $nin: ['deleted', 'banned'] }
};

Array Contains

const users = [
  { name: 'John', tags: ['javascript', 'react'] },
  { name: 'Jane', tags: ['python', 'django'] }
];

const expression = {
  tags: { $contains: 'javascript' }
};

Logical Operators

AND Operator

const expression = {
  $and: [
    { age: { $gte: 18 } },
    { status: { $eq: 'active' } },
    { role: { $in: ['admin', 'user'] } }
  ]
};

OR Operator

const expression = {
  $or: [
    { role: { $eq: 'admin' } },
    { permissions: { $contains: 'write' } }
  ]
};

NOT Operator

const expression = {
  $not: {
    status: { $eq: 'deleted' }
  }
};

Complex Combinations

const expression = {
  $and: [
    {
      $or: [
        { role: { $eq: 'admin' } },
        { role: { $eq: 'moderator' } }
      ]
    },
    { status: { $eq: 'active' } },
    {
      $not: {
        email: { $endsWith: '@blocked.com' }
      }
    }
  ]
};

Nested Objects

Dot Notation

const users = [
  {
    name: 'John',
    address: {
      city: 'New York',
      country: 'USA'
    }
  }
];

const expression = {
  'address.city': { $eq: 'New York' }
};

Nested Object Syntax

const expression = {
  address: {
    city: { $eq: 'New York' },
    country: { $eq: 'USA' }
  }
};

Deep Nesting

const expression = {
  'profile.settings.notifications.email': { $eq: true }
};

Working with Null and Undefined

Check for Null

const expression = {
  deletedAt: { $eq: null }
};

Check for Not Null

const expression = {
  deletedAt: { $ne: null }
};

Handle Optional Properties

const users = [
  { name: 'John', age: 25 },
  { name: 'Jane' },
  { name: 'Bob', age: null }
];

const expression = {
  age: { $ne: null }
};

Type Safety with TypeScript

Define Interfaces

interface User {
  id: number;
  name: string;
  age: number;
  status: 'active' | 'inactive';
  email: string;
}

const expression: Expression<User> = {
  status: { $eq: 'active' },
  age: { $gte: 18 }
};

Type-Safe Expressions

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

const createUserFilter = (minAge: number): Expression<User> => ({
  $and: [
    { age: { $gte: minAge } },
    { status: { $eq: 'active' } }
  ]
});

Common Patterns

Active Records

const ACTIVE_EXPRESSION = {
  $and: [
    { status: { $eq: 'active' } },
    { deletedAt: { $eq: null } }
  ]
};

Search Pattern

const createSearchExpression = (term: string) => ({
  $or: [
    { name: { $regex: new RegExp(term, 'i') } },
    { email: { $regex: new RegExp(term, 'i') } },
    { username: { $regex: new RegExp(term, 'i') } }
  ]
});

Date Range Pattern

const createDateRangeExpression = (start: Date, end: Date) => ({
  $and: [
    { createdAt: { $gte: start } },
    { createdAt: { $lte: end } }
  ]
});

Permission Check Pattern

const createPermissionExpression = (requiredPermissions: string[]) => ({
  $or: [
    { role: { $eq: 'admin' } },
    {
      permissions: {
        $in: requiredPermissions
      }
    }
  ]
});

Performance Tips

Use Specific Operators

const expression = {
  status: { $eq: 'active' }
};

const expression = {
  status: { $regex: /active/ }
};

Avoid Nested OR Operations

const expression = {
  $or: [
    { $or: [{ a: 1 }, { b: 2 }] },
    { $or: [{ c: 3 }, { d: 4 }] }
  ]
};

const expression = {
  $or: [
    { a: 1 },
    { b: 2 },
    { c: 3 },
    { d: 4 }
  ]
};

Use $in Instead of Multiple $or

const expression = {
  $or: [
    { status: { $eq: 'active' } },
    { status: { $eq: 'pending' } },
    { status: { $eq: 'approved' } }
  ]
};

const expression = {
  status: { $in: ['active', 'pending', 'approved'] }
};

Next Steps

• Learn about Framework Integration
• Explore Advanced Features
• Check out Examples
• Read Best Practices

Related Resources

• Operator Reference
• Configuration Guide
• TypeScript Types
• Troubleshooting