furgoneta

Functional JS support library

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 function
  • idx : var name of an index or key
  • x : var name usually used to indicate an item or value
  • xs : var name of a sequence or collection
  • fn : var name of a function.
  • fn(x) : var name of a function that will receive a param x (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(xidxxs) {
  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(xidxxs) {
  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(accxidxxs) {
  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(accxidxxs) {
  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(accxidxxs) {
  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(accxidxxs) {
  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 !(% 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 !(% 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 ] 

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 !(% 2) }
var not = function(x) { return !}
 
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(xy) { return x + y }
var add5 = f.partial(add, 5)
// So add5 = f.add(5, ???) 
 
add5(3)
// > 8 
 
// Another example 
 
var even = function(x) { return !(% 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: