Filter chains, event emitter style, with globs and callbacks
npm install glob-filter[![Build Status]](https://travis-ci.org/mantoni/glob-filter.js)
[![SemVer]](http://semver.org)
[![License]](https://github.com/mantoni/glob-filter.js/blob/master/LICENSE)
Filter chains, event emitter style, with globs and callbacks.
Register filters using [glob events][] and process matching [filter chains][].
Callbacks may be used in each filter to pass back errors or values
asynchronously.
- Bi-directional control flow with next / callback pairs
- Add or remove filters while the chain is processed
- Easy to learn, event emitter style API
- Test suite runs on Node.js 0.10, PhantomJS, Chrome, Firefox and IE 9 / 10
- 100% code coverage
npm install glob-filter
Use Browserify to create a standalone file.
This implementation supports flow in both directions which allows each filter
to apply logic before and / or after processing happens on the rest of the
chain:
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Filter A │ │ Filter B │ │ Filter C │
│ │ │ │ │ │
emit ──┼───> next ──┼──┼───> next ──┼──┼───> next ──┼───> then
│ │ │ │ │ │ │
callback <─── callback <┼──┼─ callback <┼──┼─ callback <┼── callback
│ │ │ │ │ │
└────────────┘ └────────────┘ └────────────┘
``js
var GlobFilter = require('glob-filter').GlobFilter;
var gf = new GlobFilter();
gf.addFilter('foo.*', function (next) {
console.log('Foo');
next();
});
gf.emit('foo.bar', function (err, value) {
assert.equal(value, 7);
});
`
A filter which does not block the chain, the next filter will be invoked
immediately:
`js`
gf.addFilter(function () {
// ...
});
A filter that controls when to invoke the next filter:
`js`
gf.addFilter(function (next) {
// ...
next();
});
A filter that controls when to invoke the callback:
`js`
gf.addFilter(function (next, callback) {
next(function (err, value) {
// ...
callback(err, value);
});
});
You can pass a then function to invoke at the end of the filter chain toemit:
`js`
gf.emit('foo.bar', function (callback) {
callback(null, 42);
}, function (err, value) {
assert.equal(value, 42);
});
- emit(event[, then][, callback]): Invokes all filters registered for thethen
given event. Matching rules are applied on the event name as descibed in the
[glob-tree match expressions][]. If a callback is passed, it will be invoked
after all filters returned. If a function is passed, it will benext
invoked after all filters called . It receives a callback as the only(err, value)
argument expecting to be called with . Invoking the callbackaddFilter(event, fn)
causes the filter callback chain to be invoked.
- : Registers a filter for an eventfilterOnce(event, fn)
- : Registers a filter for an event that isremoveFilter(event, fn)
automatically removed on the first invocation
- : Unregisters a filter for an eventremoveAllFilters([event])
- : Unregisters all filters, or all filtersremoveMatchingFilters(event)
for the given event. Matching rules are not applied.
- : Unregister all filters matching the givenfilters([event][, options])
event name as described in the [glob-tree match expressions][].
- : Returns all filters, or all filters
for the given event. Matching rules are applied on the event name as
described in the [glob-tree match expressions][].
The options argument can have these properties:
- matchers: Emit to matchers, defaults to truelisteners
- : Emit to listeners, defaults to true
The first argument passed to emit can be an object with an event property
and any of the above options.
Filters are invoked with a special scope object. If an object is passed to
emit as the event (see Options), that object is used as the scope object.
It is also possible to bind individual filters to specific scope objects:
`js`
gf.addFilter({
event : 'some.event',
scope : this
}, function () { ... });
- newFilter: Emitted by addFilter and filterOnce with the event nameremoveFilter
and the new filter function. Matchers will not receive this event.
- : Emitted by removeFilter and removeAllFilters` with
the event name and the removed filter function. Matchers will not receive
this event.
MIT
[Build Status]: http://img.shields.io/travis/mantoni/glob-filter.js.svg
[SemVer]: http://img.shields.io/:semver-%E2%9C%93-brightgreen.svg
[License]: http://img.shields.io/npm/l/glob-filter.svg
[glob events]: https://github.com/mantoni/glob-events.js
[filter chains]: https://github.com/mantoni/min-filter.js
[glob-tree match expressions]: https://github.com/mantoni/glob-tree.js#match-expressions