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

Table of Contents

• Installation
• Configuration
• Availables Predicates
• Usage
• Utilities

Compatibility

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

Availables Predicates only when value is Object

Below predicates works only when value is Object

Usage

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
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 }] }]
Array of Objects (without index)
When a path crosses an array of objects and the next segment is not an index, the predicate is applied to every element and the item is kept if any of them satisfies it.
data = [
  { id: 1, post_attendances: [{ digits: '1' }, { digits: '5' }] },
  { id: 2, post_attendances: [{ digits: '5' }] },
  { id: 3, post_attendances: [{ digits: '9' }] },
  { id: 4, post_attendances: [] }
]

filters = {
  'post_attendances.digits': { eq: '5' }
}

collection = RecollectArray.filter(data, filters)

# [{ id: 1, ... }, { id: 2, ... }]
You can also be explicit with *, which is useful for arrays of scalars.
filters = {
  'post_attendances.*.digits': { eq: '5' },
  'tags.*': { eq: 'urgent' }
}

collection = RecollectArray.filter(data, filters)
It works with every predicate, and negative predicates read as no element satisfies it.
filters = {
  'post_attendances.digits': { not_eq: '5' } // keeps 3 and 4
}
Nesting more than one array level also works.
filters = {
  'calls.post_attendances.digits': { eq: '5' }
}
 Use .0 when you want a specific position and no index when you want any element.

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.
 }
}

collection = RecollectArray.filter(data, filters)

Empty

We going to check if value is has some items __INLINE_CODE_0__

Equal

NotEqual

Exists

Filter only if value be different of null or undefined

NotExists

Nested Hash Paths

Nested Array Paths

Note the __INLINE_CODE_1__

Using default Equal predicate.

If array, you can navigate into self, using __INLINE_CODE_2__

Array of Objects (without index)

When a path crosses an array of objects and the next segment is not an index, the predicate is applied to every element and the item is kept if any of them satisfies it.

You can also be explicit with __INLINE_CODE_3__, which is useful for arrays of scalars.

It works with every predicate, and negative predicates read as no element satisfies it.

Nesting more than one array level also works.

Use __INLINE_CODE_4__ when you want a specific position and no index when you want any element.

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

Combine conditions

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

 Back to Top

Development

After checking out the repo, install dependencies. Then, run __INLINE_CODE_5__ 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.