JS object pattern matching
npm install bloomrun[![logo][logo-url]][npm-url]
A js pattern matcher with results that can be returned in __insertion order__ or __depth order__. 2.5KB minified and gzipped, runs in the browser. Inspired by bloom filters.
* Install
* Example
* API
* Acknowledgements
* License
To install bloomrun, simply use npm:
``
npm install bloomrun --save
The example below can be found [here][example] and ran using node example.js. It
demonstrates how to use bloomrun for pattern matching with a payload.
`js
'use strict'
var bloomrun = require('bloomrun')()
bloomrun.add({say: 'hello'}, 'Hello World!')
bloomrun.add({say: 'goodbye'}, function () {
console.log('Goodbye World!')
})
bloomrun.add({say: 'something', to: /.*/}, 'Matched with a regexp and a prop')
bloomrun.add({say: /.*/}, 'Matched with a regexp!')
var hello = bloomrun.lookup({say: 'hello'})
console.log(hello)
var goodbye = bloomrun.lookup({say: 'goodbye'})
goodbye()
var anything = bloomrun.lookup({say: 'anything'})
console.log(anything)
console.log(bloomrun.lookup({say: 'something', to: 'Matteo'}))
`
* bloomrun()
* instance.add()
* instance.remove()
* instance.lookup()
* instance.iterator()
* instance.list()
* instance.default()
-------------------------------------------------------
Creates a new instance of __bloomrun__.
Options are:
* indexing: it can be either insertion (default) or depth;insertion
if set to , it will try to match entries in insertion order;depth
if set to , it will try to match entries with the most
properties first. Depth indexing is guaranteed if the patterns
overlaps. If multiple matching patterns overlaps it checks on the
first overlapping group of patterns that matches. The insertion order of pattern with the same depth is not guaranteed.
for..of construct:
The bloomrun instance implements iterable protocol, all added patterns can be looped
over in a for..of construct.
-------------------------------------------------------
Adds a pattern to the __bloomrun__ instance. You can also provide an alternative
payload to return instead of the pattern itself. This allows pattern based
retrieval of objects. If no payload is provided the pattern itself will be
returned.
-------------------------------------------------------
Removes a pattern from the __bloomrun__ instance. Filters are rebuilt after each
removal which may mean the same pattern is matched by another filter. In cases
where two patterns differ only by payload, the supplied payload can be used to
determine the correct match. If no payload is supplied any matched pattern will
be removed regardless of it's own payload.
-------------------------------------------------------
Looks up the first entry that matches the given obj. A match happens
when all properties of the added pattern matches with the one in the
passed obj. If a payload was provided it will be returned instead of
the pattern.
Options:
* patterns: true, if you want to retrieve only patterns, not
payloads
-------------------------------------------------------
Returns an iterator, which is an object with a next method. next
will return the next pattern that matches the object or if thereobj
are no more.
If is null, all patterns/payload will be returned.
Options:
* patterns: true, if you want to retrieve patterns, defaults tofalse
* , if you want to retrieve payloads, defaults totrue
If both patterns and payloads are true, the data will be in the
form:
`js`
{
pattern,
payload
}
for..of construct:
The iterator also implements iterable protocol, matched patterns can be looped
over in a for..of construct.
-------------------------------------------------------
Returns all patterns that matches the object. If a payload was provided
this will be returned instead of the pattern.
If obj is null, all patterns/payload will be returned.
Options:
* patterns: true, if you want to retrieve patterns, defaults tofalse
* , if you want to retrieve payloads, defaults totrue
If both patterns and payloads are true, the data will be in the
form:
`js`
{
pattern,
payload
}
If a default is set, it will be returned if obj is falsy. In caseopts.patterns
the is true, the element in the list will have the
form:
`js``
{
default: true,
payload
}
-------------------------------------------------------
Sets a default payload to be returned when no pattern is matched. This
allows a single 'catch all' to be defined. By default, null is returned
when a pattern is not matched.
-------------------------------------------------------
This project was kindly sponsored by nearForm.
This library is heavily inspired by Richard Rodger's
patrun and Seneca.
The bloomrun logo was created, with thanks, by Dean McDonnell
Copyright Matteo Collina 2015-2017, Licensed under [MIT][].
[MIT]: ./LICENSE
[example]: ./example.js
[travis-badge]: https://travis-ci.org/mcollina/bloomrun.svg?branch=master
[travis-url]: https://travis-ci.org/mcollina/bloomrun
[npm-badge]: https://badge.fury.io/js/bloomrun.svg
[npm-url]: https://npmjs.org/package/bloomrun
[logo-url]: https://raw.githubusercontent.com/mcollina/bloomrun/master/assets/bloomrun.png
[coveralls-badge]: https://coveralls.io/repos/mcollina/bloomrun/badge.svg?branch=master&service=github
[coveralls-url]: https://coveralls.io/github/mcollina/bloomrun?branch=master
[david-badge]: https://david-dm.org/mcollina/bloomrun.svg
[david-url]: https://david-dm.org/mcollina/bloomrun