Handy Filter

Overview

Handy Filter is a JavaScript/TypeScript library for handy arrays filtration. With her you can filter by conditions of any complexity in declarative style.

If you want to work with React see handy-filter-hook

Installation

npm:

npm install handy-filter

yarn:

yarn add handy-filter

Table of Contents

• Usage
  • Base usage
  • Plain syntax
  • With an array of objects
  • Create filter in runtime
• The __any__ value
• Conditions
  • Simple conditions
  • Logical conditions
  • Range conditions
  • RegExp conditions
  • Independent use
• Supported types
• Filter options
  • addTo

Usage

Base usage

import Filter, { gte, lt, not, eq } from 'handy-filter';

// num < 10 or num >= 100 and num !== 500
const filter = new Filter(lt(10)).or(gte(100)).and(not(eq(500)));
const example = [2, 1, 3, 10, 5, 10, 100, 1000, 200, 10, 500];

filter.filter(example); // result is [2, 1, 3, 5, 100, 1000, 200]

See more about Conditions.

NOTE that you can pass to the methods any number of conditions.

With an array of objects

You can use the Filter with an array of objects.

You can filter objects by properties of any deep.

import Filter, { eq, gt, not } from 'handy-filter';

const example = [
  { num: 20, nested: { str: 'bar', prop: true }},
  { num: 100, nested: { str: 'bar', prop: false }},
  { num: 100, nested: { str: 'foo', prop: null }},
  { num: 10, nested: { str: 'bar', prop: true }},
];

// obj.num > 20 and obj.nested.prop !== null or obj.nested.str === 'foo'
const filter = new Filter(gt('num', 20)).and(not(eq('nested.prop', null))).or(eq('nested.str', 'foo'));

filter.filter(example);
// result is [
//   { num: 100, nested: { str: 'bar', prop: false }},
//   { num: 100, nested: { str: 'foo', prop: null }},
// ]

Plain syntax

It is just another way to use conditions.

import Filter from 'handy-filter';

const example = [
  { num: 20, nested: { str: 'bar', prop: true }},
  { num: 100, nested: { str: 'bar', prop: false }},
  { num: 100, nested: { str: 'foo', prop: null }},
  { num: 10, nested: { str: 'bar', prop: true }},
];

// obj.num > 20 and obj.nested.prop !== null or obj.nested.str === 'foo'
const filter = new Filter(['num__gt', 20]).and(['nested.prop__eq', false]).or(['nested.str__eq', 'foo']);

filter.filter(example);
// result is [
//   { num: 100, nested: { str: 'bar', prop: false }},
//   { num: 100, nested: { str: 'foo', prop: null }},
// ]

See more about Conditions.

Create filter in runtime

import Filter, { lt, lte, gt, eq } from 'handy-filter';

let filter1 = new Filter(lte((20)));

if (Math.random() < 0.5) {
  filter = filter.and(gt(10));
} else {
  filter = filter.and(lt(30)).or(eq(100));
}

NOTE that "and" and "or" methods create a new instance of the Filter:

import Filter, { lte, gt } from 'handy-filter';

const filter1 = new Filter(lte(20));
// the filter1 still contain the "lte(20)" condition, but filter2 contain "lte(20) and gt(10)"
const filter2 = filter1.and(gt(10));

The __any__ value

To make a condition always true, you can use the __any__. This can be useful if you don't want to change a structure of the filter, but want to change his values. Or, for example, you want to disable a part of the filter condition.

import Filter, { ANY, not, eq, lt, gt, gte } from 'handy-filter';

// This is equivalent to "value !== 20 and value < 100"
new Filter(not(eq(20))).and(gt('__any__')).and(lt(100)).and(not(eq(ANY)));

// This will always be true
new Filter(not(eq(20))).or(lt(100)).or(gte('__any__'));

The Filter automatically optimising conditions containing __any__ values, so you don't need to worry about performance.

Conditions

Simple conditions

Simple conditions work with all basic types.

Name	Alias	Purpose
Equal	eq	Check if a value is equal to another value
Greater	gt	Check if a value is greater than another value
Greater than or equal	gte	Check if a value is grater than or equal to another value
Less	lt	Check if a value less than another value
Less than or equal	lte	Check if a value less than or equal to another value

Logical conditions

Can check values of any base type, but only conditions can be passed as constructor parameters:

• Simple conditions;
• Logical conditions;
• Range conditions;
• RegExp conditions.

Name	Alias	Purpose
And	and	Combine other conditions through logical "and"
Or	or	Combine other conditions through logical "or"
Not	not	Takes truth to falsity and vice versa

Range conditions

These conditions check if a value is in some range/set. Work with all base types.

Name	Alias	Purpose
In	inl	Check if a value is in a list of values

RegExp conditions

Can check values of any base type, but only values of type string or RegExp can be passed as constructor parameters.

NOTE that RegExp conditions automatically convert all values to string type.

Name	Alias	Purpose
Contain	cnt	Check if a value contains another value
Ignore case contain	icnt	Check if a value contains another value

Independent use

You can use conditions independently of the filter:

import { and, or, eq } from 'handy-filter';

const user = {
  active: true,
  isAdmin: false,
  permissions: {
    canWrite: true,
    canRead: true,
  },
};

const isActive = eq('active', true);
const isAdmin = eq('isAdmin', true);
const canWrite = and(isActive, or(isAdmin, eq('permissions.canWrite', true)));

if (canWrite.check(user)) {
// do somthing
}

Supported types

1. bigint;
2. boolean;
3. Date;
4. null;
5. number;
6. string;
7. undefined.

Filter options

The Filter constructor can receive options object as the second parameter.

addTo

Valid values	Default
all, latest	latest

This option changes how the filter add new conditions using "and" and "or" methods:

import Filter, { and, not, or, eq, gt, lte } from 'handy-filter';

const values = [4, 1, 60, 3, 5, 10, 50, 20, 100, 30, 1000];

// This is equivalent to "value < 0 or value > 50 and value <= 100 or value != 60 and value === 30"
const defaultFilter = new Filter(lt(0)).or(gt(50)).and(lte(100)).or(not(eq(60))).and(eq(30));
// This is equivalent to "(((value < 0 or value > 50) and value <= 100) or value != 60) and value === 30"
const filterWithOption = new Filter(lt(0), { addTo: 'all' }).or(gt(50)).and(lte(100)).or(not(eq(60))).and(eq(30));

defaultFilter.filter(values); // result is [60, 100, 30]
filterWithOption.filter(values); // result is [30]