GitHub - thadeu/recollect-array-js: A simple and lightweight way to filter array using JavaScript

🔃 recollect-array-js

Simple wrapper to filter array using JavaScript and simple predicate conditions

Motivation

Because in sometimes, we need filter array passing conditions. This library simplify this work.

Documentation

Version	Documentation
unreleased	https://github.com/thadeu/recollect-array-js/blob/main/README.md

Compatibility

kind	branch	javascript
unreleased	main	>= 14.x, <= 18.x

Installation

Please prefer install directly from Github using tags or branch main

yarn add github:thadeu/recollect-array-js#main

# or 

yarn add github:thadeu/recollect-array-js#v1.0.8

Use Yarn

yarn add recollect-array-js

or use NPM

npm i --save recollect-array-js

and then, enjoy!

import RecollectArray from 'recollect-array-js'

Configuration

Without configuration, because we use only JavaScript. ❤️

Availables Predicates for all values

Type	Suffix	Value
Equal	eq	Anywhere
NotEqual	not_eq	Anywhere
Contains	cont	Anywhere
NotContains	not_cont	Anywhere
Included	in	Anywhere
NotIncluded	not_in	Anywhere
LessThan	lt	Anywhere
LessThanEqual	lte	Anywhere
GreaterThan	gt	Anywhere
GreaterThanEqual	gte	Anywhere
GreaterThanEqual	gte	Anywhere
Empty	empty	Anywhere
Regex	reg or regex	Anywhere
NotRegex	not_reg or not_regex	Anywhere

Availables Predicates only when value is Object

💡 Below predicates works only when value is Object

Type	Suffix	Value
Exists	exists	Anywhere
NotEqual	not_eq	Object
NotContains	not_cont	Object
NotIncluded	not_in	Object
NotMatches	not_matches	Object

Usage

Think that your data seems like this.

data = [
  {
    id: 1,
    name: 'Test #1',
    email: 'test1@email1.com',
    schedule: { all_day: true },
    numbers: [1, 2],
    active: true,
    count: 9
  },
  {
    id: 2,
    name: 'Test #2',
    email: 'test2@email2.com',
    schedule: { all_day: false },
    numbers: [3, 4],
    active: true,
    count: 10
  },
  {
    id: 3,
    name: 'Test #3',
    email: 'test3@email3.com',
    schedule: { all_day: false },
    numbers: [5, 6],
    active: false,
    count: 99,
    members: null
  }
]

You can use one or multiples predicates in your filter. We see some use cases.

Flexible Use Case (Hash)

Regex

We going to test value with the Regex was passed to predicate, for example.

filters = {
  email: { regex: '.*@email3.com$' }
}

collection = RecollectArray.filter(data, filters)

Empty

We going to check if value is has some items [null, undefined, NaN, '', ' ']

filters = {
  members: { empty: true }
}

collection = RecollectArray.filter(data, filters)

Equal

filters = {
  active: { eq: true }
}

collection = RecollectArray.filter(data, filters)

NotEqual

filters = {
  active: {
    not_eq: true
  }
}

collection = RecollectArray.filter(data, filters)

Exists

Filter only if value be different of null or undefined

filters = {
  members: {
    exists: true
  }
}

collection = RecollectArray.filter(data, filters)

NotExists

filters = {
  members: {
    exists: false
  }
}

collection = RecollectArray.filter(data, filters)

Nested Hash Paths

filters = {
  'schedule.all_day': {
    eq: true
  }
}

collection = RecollectArray.filter(data, filters)

Nested Array Paths

Note the .0 🎉

filters = {
  'numbers.0': {
    eq: '3'
  }
}

collection = RecollectArray.filter(data, filters)

filters = {
  numbers: {
    in: '3' // or in: ['3']
  }
}

collection = RecollectArray.filter(data, filters)

Using default Equal predicate.

RecollectArray.filter(data, { numbers: 3 })

RecollectArray.filter(data, { active: true })

RecollectArray.filter(data, { id: 3 })

If array, you can navigate into self, using property.NUMBER.property

data = [
  {
    schedules: [
      {
        opened: true,
        all_day: true
      },
      {
        opened: false,
        all_day: true
      }
    ]
  },
  {
    schedules: [
      {
        opened: false,
        all_day: true
      },
      {
        opened: false,
        all_day: true
      }
    ]
  }
]

filters = {
  'schedules.0.opened': {
    eq: true
  }
}

collection = RecollectArray.filter(data, filters)

# [{ schedules: [{ opened: true, all_day: true }, { opened: false, all_day: true }] }]

Amazing, you can pass a Function value as value, like this.

filters = {
  'schedules.0.opened': { eq: () => true }
}

collection = Recollect::Array.filter(data, filters)

Combine conditions

Yes, you can combine one or multiple predicates to filter you array.

filters = {
  active: { eq: true },
  numbers: {
    in: [5],
    not_in: '10'
  },
  email: {
    cont: 'email1',
    not_cont: '@gmail'
  },
  'schedule.all_day': {
    in: [true, false]
  }
}

collection = RecollectArray.filter(data, filters)

⬆️ Back to Top

Development

After checking out the repo, install dependencies. Then, run yarn test to run the tests.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/thadeu/recollect-array-js. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.