funnel-transform v1.0.2

Funnel

Transform your array data using a simple and extensible pipes interface.

Features

• Straightforward to learn and use
• 100% test coverage
• Easily add custom transformation layers

Installation

npm i funnel-transform --save    OR    yarn add funnel-transform

Now either include the dist/funnel.js file directly in a web page or require('funnel-transform') it.

Usage

Example 1: Reversing the order

var output = Funnel.input(data)
    .pipe(Funnel.L.sort.reverse)
    .output();

First, we input our raw data into funnel's pipeline. We then use the fluent pipe(<Layer>) method to transform the data. In this case we are using the built-in Funnel.L.sort.reverse layer, adding custom ones is described further below. Finally we return the resulting array using output().

Example 2: Sorting an array of objects

var data = [
    {
        name: "Charlie",
        numbers: {
            age: 5,
            size: 50
        }
    },
    ...
]

var output = Funnel.input(data)
    .pipe(Funnel.L.sort.ascending('numbers.age'))
    .output();

This time we pipe our data through a different layer: The ascending sorter. It accepts an optional parameter, which you can pass by adding function braces to the end of the layer. In the parameter you can use dot-syntax to specify the object property to sort by. If omitted the whole item is being compared.

Example 3: Composing layers

var output = Funnel.input(data)
    .pipe(Funnel.L.sort.ascending('numbers.age'))
    .pipe(Funnel.L.sort.reverse)
    .output();

This is where funnel truly shines: You can compose your array transformation out of potentially lots of smaller transformations called layers. In this example we are turning the ascending sorter into a descending sorter by simply adding a reverse layer at the bottom. This reverses the order of the items.

Built-in layers

Advanced features

Custom layers

var output = Funnel.input(sampledata)
    .pipe(function(items){
        // Do things with the array and return it
        return items;
    })
    .output();

You may pass a closure to the pipe method to use a custom transformation layer.

Multi-field search matching

var output = Funnel.input(sampledata)
    .pipe(funnel.L.search.matches('Search query', ['name','numbers.age', 'numbers.size']))
    .output();

This feature would be useful in the following example situation:
You need to have a single search box that can search through 3 different properties of your objects in an array. To achieve this, pass an array of dot-syntax object paths into the second argument of the search layer instead of just one string.

Contributing

Installing:

$ git clone https://github.com/hiwye/funnel.git
$ yarn

Developing:

$ gulp //Watch for changes and then build
$ npm run test //Run mocha tests
$ npm run coverage //Run istanbul test coverage

Thanks for using this library, please report issues as they occur :)
Cheers,
Seb