# recollect-array-js

> A simple and lightweight way to filter array using JavaScript

Latest version **1.0.10** (published 2026-08-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install recollect-array-js
pnpm add recollect-array-js
yarn add recollect-array-js
bun add recollect-array-js
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.0.10 |
| Published | 2026-08-17 |
| First published | 2023-03-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 95.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Thadeu Esteves |
| Maintainers | thadeu |
| Keywords | metaprogramming, array conditions, filter collection, filter array, ransack, filtering, search array |

## Links

- npm: https://www.npmjs.com/package/recollect-array-js
- Repository: https://github.com/thadeu/recollect-array-js
- Homepage: https://github.com/thadeu/recollect-array-js#readme
- Issues: https://github.com/thadeu/recollect-array-js/issues
- npm.io page: https://npm.io/package/recollect-array-js

## Dependencies (7)

- [lodash.get](https://npm.io/package/lodash.get.md) ^4.4.2
- [lodash.last](https://npm.io/package/lodash.last.md) ^3.0.0
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) ^4.2.0
- [lodash.filter](https://npm.io/package/lodash.filter.md) ^4.6.0
- [lodash.isempty](https://npm.io/package/lodash.isempty.md) ^4.4.0
- [lodash.isfunction](https://npm.io/package/lodash.isfunction.md) ^3.0.9
- [lodash.isplainobject](https://npm.io/package/lodash.isplainobject.md) ^4.0.6

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 1.0.10 (latest) — 2026-08-17
- 1.0.7 — 2024-10-09
- 1.0.6 — 2024-09-18
- 1.0.5 — 2024-09-18
- 1.0.3 — 2023-10-04
- 1.0.0 — 2023-03-31

## README

<p align="center">
  <h1 align="center">🔃 recollect-array-js</h1>
  <p align="center"><i>Simple wrapper to filter array using JavaScript and simple predicate conditions</i></p>
</p>

<p align="center">
  <a href="https://github.com/thadeu/recollect-array-js/actions/workflows/ci.yml">
    <img alt="Build Status" src="https://github.com/thadeu/recollect-array-js/actions/workflows/ci.yml/badge.svg">
  </a>
</p>


## Motivation

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

## Documentation <!-- omit in toc -->

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

## Table of Contents <!-- omit in toc -->
  - [Installation](#installation)
  - [Configuration](#configuration)
  - [Availables Predicates](#availables-predicates)
  - [Usage](#usage)
  - [Utilities](#utilities)

## Compatibility

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

## Installation

Please prefer install directly from Github using tags or branch main

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

# or 

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

Use Yarn

```bash
yarn add recollect-array-js
```

or use NPM

```bash
npm i --save recollect-array-js
```

and then, enjoy!

```ts
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

<details>
  <summary>Think that your data seems like this.</summary>
  
  ```ts
  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
    }
  ]
  ```
</details>

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.

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

collection = RecollectArray.filter(data, filters)
```

**Empty**

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

```ts
filters = {
  members: { empty: true }
}

collection = RecollectArray.filter(data, filters)
```

**Equal**

```ts
filters = {
  active: { eq: true }
}

collection = RecollectArray.filter(data, filters)
```

**NotEqual**

```ts
filters = {
  active: {
    not_eq: true
  }
}

collection = RecollectArray.filter(data, filters)
```

**Exists**

Filter only if value be different of null or undefined

```ts
filters = {
  members: {
    exists: true
  }
}

collection = RecollectArray.filter(data, filters)
```

**NotExists**

```ts
filters = {
  members: {
    exists: false
  }
}

collection = RecollectArray.filter(data, filters)
```

**Nested Hash Paths**

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

collection = RecollectArray.filter(data, filters)
```

**Nested Array Paths**

> Note the `.0` 🎉

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

collection = RecollectArray.filter(data, filters)
```

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

collection = RecollectArray.filter(data, filters)
```

Using default Equal predicate.

```ts
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`

```ts
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.

```ts
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.

```ts
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*.

```ts
filters = {
  'post_attendances.digits': { not_eq: '5' } // keeps 3 and 4
}
```

Nesting more than one array level also works.

```ts
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.

```javascript
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.


```ts
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)
```

[⬆️ &nbsp;Back to Top](#table-of-contents-)

## 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](https://github.com/thadeu/recollect-array-js/blob/master/CODE_OF_CONDUCT.md).


## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

---
_Source: https://npm.io/package/recollect-array-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._