> For the complete documentation index, see [llms.txt](https://conductor.js.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://conductor.js.org/1.3.0/api-reference/filter.md).

# filter

```erlang
filter :: (Function predicate, Collection collection) => Collection | Promise<Collection>
```

## description

Iterates over a *collection* (`Array, Object, Map, Set`) and returns a new collection of the same type containing only the values for which the `predicate` function evaluates to `true`.

Like many `Collection` methods in Conductor, `filter` works with **both asynchronous & synchronous** mappers. If you use a synchronous predicate function, `filter` will work like `Array.prototype.filter` and return a Collection synchronously.

```javascript
const values = [0, 1, 2, 3]
const isEven = x => x % 2 === 0
filter(isEven, values) // [0, 2]
```

If you use an *asynchronous* mapper, `filter` will return a `Promise`, and you will need to use `await` or `Promise.prototype.then` to retrieve the new collection.

```javascript
const values = [0, 1, 2, 3]
const isEven = async x => x % 2 === 0
filter(double, values) // Promise<Pending>
await filter(double, values) // [0, 2]
```

{% hint style="warning" %}
If you use an *asynchronous* predicate function, all calls to the `predicate` function will be done in **parallel**, but the input collection's **order will be preserved**.
{% endhint %}

## examples

### basic example

```javascript
import { filter } from 'conductor'

const values = [0, 1, 2, 3]
const isEven = x => x % 2 === 0
filter(isEven, values) // [0, 2]
```

Here, we are just using filtering on an array to keep only even values. The predicate function is synchronous.

### other data structures

```javascript
import { filter } from 'conductor'

const object = { drummer: 1, drumsticks: 2 }
const map = new Map([['drummer', 1], ['drumsticks', 2]])
const set = new Set([0, 1, 2, 3])
const isEven = x => x % 2 === 0
filter(isEven, object) // { drumsticks: 2 }
filter(isEven, map) // Map { 'drumsticks' => 2 }
filter(isEven, set) // Set { 0, 2 }
```

### using the index in the predicate function

```javascript
import { filter } from 'conductor'

const words = ['hello', 'hello', 'world', 'world']
const isEven = x => x % 2 === 0
filter((_, index) => isEven(index), words) // ['hello', 'world']
```

### using an asynchronous predicate

```javascript
import { filter } from 'conductor'

const values = [0, 1, 2, 3]
const isEven = async x => x % 2 === 0
await filter(double, values) // [0, 2]
```

If your predicate function is *asynchronous*, you will need to use `await` (or `Promise.prototype.then`) because the result will be a `Promise`.