# eventuate-filter

> Create filtered eventuate, acting as subset of broader eventuate

Latest version **4.3.0** (published 2015-11-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install eventuate-filter
pnpm add eventuate-filter
yarn add eventuate-filter
bun add eventuate-filter
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.3.0 |
| Published | 2015-11-16 |
| First published | 2015-03-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Jason Pincin |
| Maintainers | jasonpincin |
| Keywords | eventuate, event, emitter, handler, callback, EventEmitter |

## Links

- npm: https://www.npmjs.com/package/eventuate-filter
- Repository: https://github.com/jasonpincin/eventuate-filter
- Issues: https://github.com/jasonpincin/eventuate-filter/issues
- npm.io page: https://npm.io/package/eventuate-filter

## Dependencies (2)

- [is-promise](https://npm.io/package/is-promise.md) ~2.1.0
- [eventuate-chainable](https://npm.io/package/eventuate-chainable.md) ~2.0.0

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 4.3.0 (latest) — 2015-11-16
- 4.2.1 — 2015-11-13
- 4.2.0 — 2015-11-13
- 4.1.1 — 2015-11-07
- 4.1.0 — 2015-11-07
- 4.0.3 — 2015-11-06
- 4.0.2 — 2015-11-06
- 4.0.1 — 2015-11-06
- 4.0.0 — 2015-11-05
- 3.0.0 — 2015-08-07
- 2.0.0 — 2015-07-28
- 1.1.0 — 2015-07-11
- 1.0.0 — 2015-03-12

## README

# eventuate-filter

[![NPM version](https://badge.fury.io/js/eventuate-filter.png)](http://badge.fury.io/js/eventuate-filter)
[![Build Status](https://travis-ci.org/jasonpincin/eventuate-filter.svg?branch=master)](https://travis-ci.org/jasonpincin/eventuate-filter)
[![Coverage Status](https://coveralls.io/repos/jasonpincin/eventuate-filter/badge.png?branch=master)](https://coveralls.io/r/jasonpincin/eventuate-filter?branch=master)
[![Sauce Test Status](https://saucelabs.com/browser-matrix/jp-project9.svg)](https://saucelabs.com/u/jp-project9)

Create an eventuate that re-produces a subset of events from another eventuate.

This tiny module is also part of the larger aggregate module: 
[eventuate](https://github.com/jasonpincin/eventuate)

This module may also be used stand-alone, with 
[eventuate-core](https://github.com/jasonpincin/eventuate-core).

## example

```javascript
var eventuate = require('eventuate-core'),
    filter    = require('eventuate-filter')

var logMessage = eventuate()
var errorMessage = filter(logMessage, function (log) {
    return log.level === 'error'
})

errorMessage(function (log) {
    console.error(log.message)
})

logMessage.produce({ level: 'info', message: 'something happened' })
logMessage.produce({ level: 'error', message: 'something bad happened' })
logMessage.produce({ level: 'info', message: 'something else happened' })

// output:
// something bad happened
```

## api

```javascript
var eventuate = require('eventuate-core')
var filter    = require('eventuate-filter')

var upstreamEventuate = eventuate()
```

The API of the `filteredEventuate` is mostly identical to the `eventuate` it 
is filtering. 

### var filteredEventuate = filter(upstreamEventuate, options, filterFunc)

Returns a new eventuate, `filteredEventuate`, which re-produces events from 
a non-basic eventuate, `upstreamEventuate`, for which `filterFunc` returns or 
resolves to `true`. 

Valid options are:
* `requireConsumption` (default: `false`) - throw an error if a produced event is not consumed
* `destroyResidual` (default: `true`) - call the destroy function when the last
  consumer is removed via `removeConsumer` or `removeAllConsumers` (after at
  least one consumer was added)
* `lazy` (default: `true`) - wait until a consumer is added before consuming
  from `upstreamEventuate`. If set to `false`, will begin
  consuming/filtering/producing immediately, even with no consumers added. This
  is useful when used in conjunction with `requireConsumption`, for example.
* `order` (default: `false`) - insure the order of items output match the order
  of input, even with an async filter. Be careful using this option, as it will
  cause buffering. 

The `filterFunc` function should accept at least one argument, `data`, but may
optionally accept a 2nd argument of a `callback`; `eventuate-filter` will
determine whether a callback is accepted based on the argument `length` of the
`filterFunc` function. 

If a callback is NOT accepted, then `filterFunc` should return either a `boolean` 
or a `Promise`. If a `Promise` is returned, it should resolve to a `boolean`. If
a callback is accepted, the return value of `filterFunc` is ignored, and the
error-first style callback (`function (err, bool) {}`) must be called with
either a truthy `error` or a falsey `error` and a `boolean`. 

Upon receiving a `truthy` boolean from either a return value, Promise, or
callback, the `filteredEventuate` will produce the `data` in question.

If either the `callback` is supplied an `error`, or the `Promise` is `rejected`,
then the `filteredEventuate` will produce an `Error` object.

If the callback or Promise are resolved/rejected after the `filteredEventuate`
has been destroyed, the value will not be produced.

### filteredEventuate.destroy()

When destroyed, the `filteredEventuate` will stop consuming from the
`upstreamEventuate`. The `filteredEventuate` is automatically destroyed unless
the `destroyResidual` option was given as `false` during creation of the
`filteredEventuate`.

### filteredEventuate.upstreamConsumer

The function added as a consumer to the `upstreamEventuate`.

## install

With [npm](https://npmjs.org) do:

```
npm install --save eventuate-core
```

## testing

`npm test`

Or to run tests in phantom: `npm run phantom`

### coverage

`npm run view-cover`

This will output a textual coverage report.

`npm run open-cover`

This will open an HTML coverage report in the default browser.

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