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

| Name | Usage Example | Function | |---------------------|----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| | Sort Reverse | Funnel.L.sort.reverse() | Reverses the order of the items | | Sort Ascending | Funnel.L.sort.ascending(<prop>) | Sorts the items in an ascending manner | | Sort Shuffle | Funnel.L.sort.shuffle() | Sorts the items randomly | | Modify Append | Funnel.L.modify.append(item) | Appends the specified item to the end of the array | | Modify Prepend | Funnel.L.modify.prepend(item) | Prepends the specified item at the beginning of the array | | Modify Remove First | Funnel.L.modify.removeFirst() | Removes the first item of the array | | Modify Remove Last | Funnel.L.modify.removeLast() | Removes the last item of the array | | Filter Equals | Funnel.L.filter.equals(value, <prop>) | Keeps only items that exactly match the first argument | | Filter Not | Funnel.L.filter.not(value, <prop>) | Keeps only items that do not match the first argument | | Filter Greater | Funnel.L.filter.greater(value, <prop>) | Keeps only items that are greater than the first argument | | Filter Smaller | Funnel.L.filter.smaller(value, <prop>) | Keeps only items that are smaller than the first argument | | Filter Maximum | Funnel.L.filter.maximum(value, <prop>) | Keeps only items that don't exceed the maximum specified in the first argument | | Filter Minimum | Funnel.L.filter.minimum(value, <prop>) | Keeps only items that are not below the minimum specified in the first argument | | Filter Custom | Funnel.L.filter.minimum(closure(val), <prop>)| Keeps only values on which the provided closure returns true | | Search Matches | Funnel.L.search.matches(query, <prop>) | Keeps only values of which the query is a substring of their prop. Specify multiple props as an array to enable multi-property search. |

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