Helper library to make functional programming in JS easier.
Disclaimer: This is a work in progress and a personal project to learn functional concepts, how are they implemented and to become familiar with them. Despite all this, it is usable, tested and it works.
If you are developing a module or application and using browserify as a module
loader, then just include furgoneta on the package.json
as a
dependency, and require it normally.
Same as above. Declare the dependency on the package.json
of your module/app
and require it normally.
You have to grab the file browser/furgoneta.js
or
browser/furgoneta-min.js
and include it on your page after the
required dependencies. It will define a global variable on the window object
called furgoneta
, that you can use then normally.
Next you will find a list of functions exported by furgoneta, classified by groups, as they are in the source code.
On the samples, we will asume that we imported and are using the furgoneta library
with the variable f
as if we had done:
var f = require('furgoneta')
...args
: refers to an indeterminate number of arguments, a variadic functionidx
: var name of an index or keyx
: var name usually used to indicate an item or valuexs
: var name of a sequence or collectionfn
: var name of a function.fn(x)
: var name of a function that will receive a paramx
(an item).
Note that along the docs, the examples' output will be noted in nearby comments.
Utilities and functions to work with arguments.
Converts an arguments variable into a JS array.
(function() {
console.log(f.toArray(arguments)) // > [ 1, 'Hello', 2 ]
})(1, 'Hello', 2)
Utilities and functions to work with javascript arrays.
Returns the first element of the array.
f.first([ 1, 2, 3, 4 ]) // > 1
Returns the last element of the array.
f.last([ 1, 2, 3, 4 ]) // > 4
Returns the rest of elements of the array, that is all but the first one.
f.rest([ 1, 2, 3, 4 ]) // > [ 2, 3, 4 ]
Returns the initial elements of the array, that is all but the last one.
f.initial([ 1, 2, 3, 4 ]) // > [ 1, 2, 3 ]
Utilities and functions to work with javascript objects.
Returns the keys of the object in an array.
f.keys({ a: 1, b: 2 }) // > [ 'a', 'b' ]
Extends all the objects passed as arguments from right to left into a new object. For the moment it is not recursive so properties that are objects will be copied by reference.
var o = f.extend(
{ a: 1, b: 1 },
{ b: 2 },
{ c: 3 }
)
// > { a: 1, b: 2, c: 3 }
We can consider collections to groups of items, and there are multiple functions we can use to manipulate them. Any object or array will work with this functions.
Iterate through a collection from left to right calling fn.
var logger = function(x, idx, xs) {
console.log('Item: ', x, ', Idx: ', idx, ', Coll: ', xs)
}
// With arrays:
f.each(logger, [ 1, 2, 3 ])
// > Item: 1 , Idx: 0 , Coll: [ 1, 2, 3 ]
// > Item: 2 , Idx: 1 , Coll: [ 1, 2, 3 ]
// > Item: 3 , Idx: 2 , Coll: [ 1, 2, 3 ]
// With objects
f.each(logger, { a: 1, b: 2, c: 3 })
// > Item: 1 , Idx: a , Coll: { a: 1, b: 2, c: 3 }
// > Item: 2 , Idx: b , Coll: { a: 1, b: 2, c: 3 }
// > Item: 3 , Idx: c , Coll: { a: 1, b: 2, c: 3 }
Iterate through a collection from right to left calling fn.
var logger = function(x, idx, xs) {
console.log('Item: ', x, ', Idx: ', idx, ', Coll: ', xs)
}
// With arrays:
f.eachRight(logger, [ 1, 2, 3 ])
// > Item: 3 , Idx: 2 , Coll: [ 1, 2, 3 ]
// > Item: 2 , Idx: 1 , Coll: [ 1, 2, 3 ]
// > Item: 1 , Idx: 0 , Coll: [ 1, 2, 3 ]
// With objects
f.eachRight(logger, { a: 1, b: 2, c: 3 })
// > Item: 3 , Idx: c , Coll: { a: 1, b: 2, c: 3 }
// > Item: 2 , Idx: b , Coll: { a: 1, b: 2, c: 3 }
// > Item: 1 , Idx: a , Coll: { a: 1, b: 2, c: 3 }
Apply fn through the items of a collection and return an array of the results.
var double = function(x) { return x * x }
f.map(double, [ 1, 2, 3 ])
// > [ 1, 4, 9 ]
f.map(double, { a: 1, b: 2, c: 3 })
// > [ 1, 4, 9 ]
Apply fn to each element of the collection passing an accumulator.
The return value of fn will be the accumulator for the next iteration, when
the collection is over the last memo will be returned by reduce
.
The first time it is called, memo
gets the value of the parameter seed
.
var scoreReducer = function(acc, x, idx, xs) {
console.log('Total:', acc, 'Item:', x, ', Idx:', idx, ', Coll:', xs)
return acc + x
}
f.reduce(scoreReducer, 10, [ 1, 2, 3 ])
// > Total: 10 Item: 1 , Idx: 0 , Coll: [ 1, 2, 3 ]
// > Total: 11 Item: 2 , Idx: 1 , Coll: [ 1, 2, 3 ]
// > Total: 13 Item: 3 , Idx: 2 , Coll: [ 1, 2, 3 ]
// > 16
f.reduce(scoreReducer, 0, { john: 5, mary: 8 })
// > Total: 0 Item: 5 , Idx: john , Coll: { john: 5, mary: 8 }
// > Total: 5 Item: 8 , Idx: mary , Coll: { john: 5, mary: 8 }
// > 13
Works like reduce but it uses as seed value the first element of the collection.
var scoreReducer = function(acc, x, idx, xs) {
console.log('Total:', acc, 'Item:', x, ', Idx:', idx, ', Coll:', xs)
return acc + x
}
f.reduce1(scoreReducer, [ 1, 2, 3 ])
// > Total: 1 Item: 2 , Idx: 1 , Coll: [ 1, 2, 3 ]
// > Total: 3 Item: 3 , Idx: 2 , Coll: [ 1, 2, 3 ]
// > 6
f.reduce1(scoreReducer, { john: 5, mary: 8 })
// > Total: 5 Item: 8 , Idx: mary , Coll: { john: 5, mary: 8 }
// > 13
Same as reduce but from right to left instead of left to right.
var scoreReducer = function(acc, x, idx, xs) {
console.log('Total:', acc, 'Item:', x, ', Idx:', idx, ', Coll:', xs)
return acc + x
}
f.reduceRight(scoreReducer, 10, [ 1, 2, 3 ])
// > Total: 10 Item: 3 , Idx: 2 , Coll: [ 1, 2, 3 ]
// > Total: 13 Item: 2 , Idx: 1 , Coll: [ 1, 2, 3 ]
// > Total: 15 Item: 1 , Idx: 0 , Coll: [ 1, 2, 3 ]
// > 16
f.reduceRight(scoreReducer, 0, { john: 5, mary: 8 })
// > Total: 0 Item: 8 , Idx: mary , Coll: { john: 5, mary: 8 }
// > Total: 8 Item: 5 , Idx: john , Coll: { john: 5, mary: 8 }
// > 13
Same as reduce1 but from right to left instead of left to right.
var scoreReducer = function(acc, x, idx, xs) {
console.log('Total:', acc, 'Item:', x, ', Idx:', idx, ', Coll:', xs)
return acc + x
}
f.reduceRight1(scoreReducer, [ 1, 2, 3 ])
// > Total: 3 Item: 2 , Idx: 1 , Coll: [ 1, 2, 3 ]
// > Total: 5 Item: 1 , Idx: 0 , Coll: [ 1, 2, 3 ]
// > 6
f.reduceRight1(scoreReducer, { john: 5, mary: 8 })
// > Total: 8 Item: 5 , Idx: john , Coll: { john: 5, mary: 8 }
// > 13
Return the first element that passes the truth test fn
.
var even = function(x) { return !(x % 2) }
var odd = f.compose(f.not, even)
f.find(even, [ 1, 2, 3 ])
// > 2
f.find(odd, { a: 4, b: 5, c: 6 })
// > 5
Return all the elements that pass the truth test fn
.
var even = function(x) { return !(x % 2) }
var odd = f.compose(f.not, even)
f.filter(odd, [ 1, 2, 3 ])
// > [ 1, 3 ]
f.filter(even, { a: 4, b: 5, c: 6 })
// > [ 4, 6 ]
Return all the elements that didn't pass the truth test fn
. Returns the
inverse of filter
.
var even = function(x) { return !(x % 2) }
var odd = f.compose(f.not, even)
f.reject(odd, [ 1, 2, 3 ])
// > [ 2 ]
f.reject(even, { a: 4, b: 5, c: 6 })
// > [ 5 ]
Returns true if all the elements in the collection pass the truth test fn
.
var isEven = function(x) { return !(x % 2) }
f.every(isEven, [1, 2, 3])
// > false
f.all(isEven, [2, 4, 6])
// > true
Returns true if any of the elements in the collection pass the truth test fn
.
var isEven = function(x) { return !(x % 2) }
f.some(isEven, [1, 2, 3])
// > true
f.any(isEven, [2, 4, 6])
// > true
f.any(isEven, [1, 3, 5])
// > false
Creates a new function that is the composition of the argument functions. So:
compose(f, g)(x) <-> f(g(x))
var even = function(x) { return !(x % 2) }
var not = function(x) { return !x }
var odd = f.compose(not, even)
// So now odd(3) <-> not(even(3))
console.log(odd(3), not(even(3)))
// > true true
Creates a function that is fn with bound arguments. You could say that it has pre-filled arguments.
// A simple example
var add = function(x, y) { return x + y }
var add5 = f.partial(add, 5)
// So add5 = f.add(5, ???)
add5(3)
// > 8
// Another example
var even = function(x) { return !(x % 2) }
var evenNumbers = f.partial(f.filter, even)
// So evenNumbers = f.filter(even, ???)
evenNumbers([ 1, 2, 3, 4, 5, 6 ])
// > [ 2, 4, 6 ]
Identity function. Returns x
as it comes in.
f.id(5)
// > 5
Identity functor, returns a function that returns x
. If x
is a function,
then functor(f) === f
// Basic behaviour
// For *not functions* it returns a function that returns the value
var gimme5 = f.functor(5)
gimme5()
// > 5
// For functions, it returns the function as it is (so this sample is useless)
var now = f.functor(function() { return Date.now() })
now()
// > 1369228597829
// A more complex example:
// Using a functor to make a function able to take both vars and functions as
// arguments
// `getter` is a function which receives a prop and returns a function that
// gets that property from its parameter obj. It is a getter creator.
// To make the `getter` function able to accept property as a value or a
// function that returns a value we can use the functor to normalize the
// behaviour and make all values behave as functions that return its values.
var getter = function(prop) {
var getKey = f.functor(prop)
return function(obj) {
return obj[getKey()]
}
}
var getName = getter('name')
var getAge = getter(function() { return 'age' })
getName({ age: 21, name: 'John' })
// > 'John'
getAge({ age: 21, name: 'John' })
// > 21
furgoneta
includes some operators as functions to ease its usage through your
functional code.
Equivalent to the infix operator +
f.add(6, 2)
// > 8
Equivalent to the infix operator -
f.sub(6, 2)
// > 4
Equivalent to the infix operator *
f.mul(6, 2)
// > 12
Equivalent to the infix operator /
f.div(6, 2)
// > 3
Equivalent to the infix operator %
f.mod(6, 2)
// > 0
Equivalent to the infix operator ===
f.eq(6, '6')
// > false
Equivalent to the infix operator ==
f.eqc(6, '6')
// > true
Equivalent to the infix operator !==
f.neq(6, 2)
// > true
Equivalent to the infix operator !=
f.neqc(6, '6')
// > false
Equivalent to the infix operator >
f.gt(6, 2)
// > true
Equivalent to the infix operator >=
f.ge(6, 2)
// > true
Equivalent to the infix operator <
f.lt(6, 2)
// > false
Equivalent to the infix operator <=
f.le(6, 2)
// > false
Equivalent to the operator !
f.not(6)
// > false
f.not(true)
// > false
Equivalent to the infix operator &&
f.and(true, null)
// > false
Equivalent to the infix operator ||
f.or(true, null)
// > true
There are several functions to help with typing conversion and detection.
Converts an object into a function of its keys. Works both with arrays and objects.
var participant = f.objToFunc({ name: 'John', age: 25, country: 'ES' })
participant('name')
// > 'John'
var participantStuff = f.map(participant, [ 'name', 'age' ])
console.log(participantStuff)
// > [ 'John', 25 ]
Converts a property into a function that takes an object and gets that property.
var people = [
{ name: 'Johnny', age: '23' },
{ name: 'Anthony', age: '32' },
{ name: 'Mary', age: '28' }
]
var names = f.map(f.prop('name'), people)
console.log(names)
// > [ 'Johnny', 'Anthony', 'Mary' ]
Function that returns a string with the type from the {}.toString method. That is:
f.typeOf('hello')
// > 'String'
f.typeOf(6)
// > 'Number'
f.typeOf(true)
// > 'Boolean'
f.typeOf(function() {})
// > 'Function'
f.typeOf([1, 2, 3])
// > 'Array'
f.typeOf({ a: 1, b: 2 })
// > 'Object'
Truth tests a type string with the type of x.
f.isA('String', 'hello')
// > true
f.isA('Object', { a: 1 })
// > true
f.isA('Boolean', 2)
// > false
isNumber(4)
// > true
isArray([1])
// > true
isObject({})
// > true
isString('asdf')
// > true
isFunction(function() {})
// > true
isBoolean(false)
// > true
To get the dependencies do a npm install
Source is on the src
folder.
Tests on the test
folder.
Make actions:
- All:
make
- Build browser:
make build-browser
- Test:
make test
- Tests watcher:
make test-w
On the folder docs
there are pdfs of the three sites that I want to use as
inspiration.
This library is inspired and influenced by various libraries and languages: