jbus-common-filter v0.0.13

jbus-common-filter

Repo: Encapsule/jbus-common-filter

See also:

• JBUS Filter Introduction
• JBUS Filter Spec Guide
• Examples
• Interactive Demo

Summary

jbus-common-fiter was designed to make it possible for single developers, or small teams, to pound out production-worthy subsystems in JavaScript to, for example, stuff into Dockerized Node.js containers. Or, into your favorite HTML5 SPA.

The library specifically targets JavaScript functions providing a mechanism to automate function I/O validation/shaping logic via declarative JSON contracts.

Filters "wrap" a function you write with automated data validation/shaping and error handling logic that bolster its defensive (input stage) and offensive (output stage) capabilities.

This "wrapping" reduces per-function development and maintenance costs by eliminating ancillary function subroutines that ensure the fidelity of data I/O to/from a function's core algorithm. And, this in turn reduces the per-function cost of test development and maintenance.

The system works by requiring developers to declare their function I/O contracts using terse JSON documents called "Filter Specs". Not only is this far more efficient than writing the equivalent logic, but it can be done before any code is written. Or, while the project is in-flight.

Runtime I/O validation/shaping is handled transparently by the Filter library for all functions processed through the library's main function factory method, create. Filter accomplishes this by using developer-specific Filter Spec JSON documents to adapt its runtime validation/shaping behavior to match each function's unique requirements.

Audience

The current release of jbus-common-filter is intended for system architects and advanced JavaScript practictioners responsible for the design and delivery of large-scale Node.js/HTML5 deployments.

Licensing

jbus-common and all of its jbus-* dependencies are licensed under the terms of the GNU Affero General Public Licence (AGPL). Please consult the included LICENSE file for details.

Encapsule.io supports the development of open source projects that seek to advance the state of the programming art and make it simpler and less stressful for developers to get their jobs done well.

Authors of MIT licensed tools and utility projects in the Node.js ecosystem in particular who might benefit from Filter and other JBUS technologies are encouraged to get in touch. For select projects free non-transferable "Community Licenses" will be granted to eliminate downstream virality.

Commerical customers can obtain "Internal Evaluation" and "Production" licensed packages for use in closed-source and proprietary products by contacting Encapsule.io.

Get it

jbus-common-filter package may be used by itself but you have to install several peer dependency packages manually if you go this route.

More simply, grab the jbus-common package that rolls up jbus-common-filter and all its dependencies (plus ~20K of graph library).

npm install jbus-common --save # all you need and a little more

Note that if you're using the 'jbus-common' package, get the jbus-common-filter export object from jbus-common as follows:

var jbus = {};
jbus.common = require('jbus-common');
var filterlib = jbus.common.filter;

console.log(filterlib.__meta);
console.log(filterlib.create({operationID:'demo'}); // NOOP filter w/random op ID

Minimum Dependencies

If you want just Filter and none of the other bits rolled into jbus-common then you'll need to install peer dependencies manually.

Currently, jbus-common is ~50KB and jbus-common-filter + its dependencies are ~27K (packed and uglified).

    npm install jbus-common-filter --save
    npm install jbus-common-types --save
    npm install jbus-common-identifier --save
    npm install node-uuid --save
    npm install murmurhash-js --save

Learn How to Use Filter

JBUS Filter Introduction : Technical introduction to JBUS Filter library for developers.

JBUS Filter Spec Guide : Technical reference for JBUS Filter authors.

Try It!

jbus-common-filter requires an initial investment on the part of the developer to learn how to read and write filter specs fluently and get used to the idea that the "contract" part of their functions lives in a sharable JSON document, not burried inside their functions and tests.

Examples

The simplest way to get going with JBUS Filter is to clone the Encapsule/jbus-common-filter repository, npm install it, and then play around with the example scripts in the ./examples directory.

git clone git@github.com:Encapsule/jbus-common-filter
cd jbus-common-filter
npm install
cd ./examples
node ./00-passthrough.js

Try making some small changes and re-executing the example scripts to observe the results. It should be very hard to break JBUS Filter's factory function create or its generated Filter.request function. This doesn't mean it will work for you the first time you try it. It does mean it will tell you exactly why its not working in sufficient detail for you to make progress without having refer back to the documentation.

Note the useful tool-make-irut.js script among the examples that is used for generating Internet Routable Unique Token (IRUT) identifiers (used everywhere in JBUS).

Interactive Demo

Thanks to the folks at Tonic we have an interactive demo:

JBUS Filter Interactive Demo

Designing Filters

Key to understanding the Filter library is understanding its core Filter Spec Processor (FSP) algorithm and how to program it with Filter Spec JSON documents.

As you venture off into your own code to try Filter, please refer to the JBUS Filter Spec Guide.

[ Next: Technical Introduction ]