funnel-transform

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