# bloomrun > JS object pattern matching Latest version **4.1.1** (published 2018-12-03) · MIT license · 0 weekly downloads ## Install ```sh npm install bloomrun pnpm add bloomrun yarn add bloomrun bun add bloomrun ``` ## 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.1.1 | | Published | 2018-12-03 | | First published | 2015-08-19 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Dependencies | 1 | | Unpacked size | 40.1 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 120 | | Author | Matteo Collina | | Maintainers | matteo.collina, mcdonnelldean | ## Links - npm: https://www.npmjs.com/package/bloomrun - Repository: https://github.com/mcollina/bloomrun - Homepage: https://github.com/mcollina/bloomrun#readme - Issues: https://github.com/mcollina/bloomrun/issues - npm.io page: https://npm.io/package/bloomrun ## Dependencies (1) - [sorted-array-functions](https://npm.io/package/sorted-array-functions.md) ^1.1.0 ## Recent versions - 4.1.1 (latest) — 2018-12-03 - 4.1.0 — 2018-01-29 - 4.0.0 — 2017-09-23 - 3.0.6 — 2017-08-07 - 3.0.5 — 2017-08-04 - 3.0.4 — 2017-03-04 - 3.0.3 — 2017-01-18 - 3.0.2 — 2017-01-14 - 3.0.1 — 2016-11-22 - 3.0.0 — 2016-11-13 - 2.3.0 — 2016-10-11 - 2.2.2 — 2016-09-22 - 2.2.1 — 2016-09-20 - 2.2.0 — 2016-09-20 - 2.1.3 — 2016-08-18 - … 18 more at https://npm.io/package/bloomrun/versions ## README [![logo][logo-url]][npm-url] # bloomrun [![npm][npm-badge]][npm-url] [![travis][travis-badge]][travis-url] [![coveralls][coveralls-badge]][coveralls-url] [![david][david-badge]][david-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](#install) * [Example](#example) * [API](#api) * [Acknowledgements](#acknowledgements) * [License](#license) ## Install To install bloomrun, simply use npm: ``` npm install bloomrun --save ``` ## Example 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'})) ``` ## API * bloomrun() * instance.add() * instance.remove() * instance.lookup() * instance.iterator() * instance.list() * instance.default() ------------------------------------------------------- ### bloomrun([opts]) Creates a new instance of __bloomrun__. Options are: * `indexing`: it can be either `insertion` (default) or `depth`; if set to `insertion`, it will try to match entries in insertion order; if set to `depth`, 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. ------------------------------------------------------- ### instance.add(pattern [,payload]) 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. ------------------------------------------------------- ### instance.remove(pattern [,payload]) 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. ------------------------------------------------------- ### instance.lookup(obj [, opts]) 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 ------------------------------------------------------- ### instance.iterator(obj [, opts]) Returns an iterator, which is an object with a `next` method. `next` will return the next pattern that matches the object or `null` if there are no more. If `obj` is null, all patterns/payload will be returned. Options: * `patterns: true`, if you want to retrieve patterns, defaults to `false` * `payloads: true`, if you want to retrieve payloads, defaults to `true` 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. ------------------------------------------------------- ### instance.list(obj [, opts]) 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 to `false` * `payloads: true`, if you want to retrieve payloads, defaults to `true` 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 case the `opts.patterns` is `true`, the element in the list will have the form: ```js { default: true, payload } ``` ------------------------------------------------------- ### instance.default(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. ------------------------------------------------------- ## Acknowledgements This project was kindly sponsored by [nearForm](http://nearform.com). This library is heavily inspired by Richard Rodger's [patrun](http://npm.im/patrun) and [Seneca](http://npm.im/seneca). The bloomrun logo was created, with thanks, by [Dean McDonnell](https:/github.com/mcdonnelldean) ## License 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 --- _Source: https://npm.io/package/bloomrun · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._