furgoneta
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.
Usage
From a browserify enabled client side module
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.
From a server side node.js module
Same as above. Declare the dependency on the package.json
of your module/app
and require it normally.
From a browser side application that does NOT use browserify
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.
Contents
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 =
Documentation terms and reference
...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.
Arguments
Utilities and functions to work with arguments.
toArray(...args)
Converts an arguments variable into a JS array.
{ console // > [ 1, 'Hello', 2 ]}1 'Hello' 2
Arrays
Utilities and functions to work with javascript arrays.
first(xs)
Returns the first element of the array.
f // > 1
last(xs)
Returns the last element of the array.
f // > 4
rest(xs)
Returns the rest of elements of the array, that is all but the first one.
f // > [ 2, 3, 4 ]
initial(xs)
Returns the initial elements of the array, that is all but the last one.
f // > [ 1, 2, 3 ]
Objects
Utilities and functions to work with javascript objects.
keys(obj)
Returns the keys of the object in an array.
f // > [ 'a', 'b' ]
extend(...args)
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// > { a: 1, b: 2, c: 3 }
Collections
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.
each(fn(x, idx, xs), xs)
Iterate through a collection from left to right calling fn.
var { console} // With arrays: f// > 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// > 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 }
eachRight(fn(x, idx, xs), xs)
Iterate through a collection from right to left calling fn.
var { console} // With arrays: f// > 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// > 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 }
map(function(x, idx, xs), xs)
Apply fn through the items of a collection and return an array of the results.
var { return x * x } f// > [ 1, 4, 9 ] f// > [ 1, 4, 9 ]
reduce(fn(memo, x, idx, xs), seed, coll) Alias: fold
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 { console return acc + x} f// > 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// > Total: 0 Item: 5 , Idx: john , Coll: { john: 5, mary: 8 }// > Total: 5 Item: 8 , Idx: mary , Coll: { john: 5, mary: 8 }// > 13
reduce1(fn(memo, x, idx, xs), coll) Alias: fold1
Works like reduce but it uses as seed value the first element of the collection.
var { console return acc + x} f// > Total: 1 Item: 2 , Idx: 1 , Coll: [ 1, 2, 3 ]// > Total: 3 Item: 3 , Idx: 2 , Coll: [ 1, 2, 3 ]// > 6 f// > Total: 5 Item: 8 , Idx: mary , Coll: { john: 5, mary: 8 }// > 13
reduceRight(fn(memo, x, idx, xs), seed, coll) Alias: foldR
Same as reduce but from right to left instead of left to right.
var { console return acc + x} f// > 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// > Total: 0 Item: 8 , Idx: mary , Coll: { john: 5, mary: 8 }// > Total: 8 Item: 5 , Idx: john , Coll: { john: 5, mary: 8 }// > 13
reduceRight1(fn(memo, x, idx, xs), coll) Alias: foldR1
Same as reduce1 but from right to left instead of left to right.
var { console return acc + x} f// > Total: 3 Item: 2 , Idx: 1 , Coll: [ 1, 2, 3 ]// > Total: 5 Item: 1 , Idx: 0 , Coll: [ 1, 2, 3 ]// > 6 f// > Total: 8 Item: 5 , Idx: john , Coll: { john: 5, mary: 8 }// > 13
find(fn(x, idx, coll), xs) Alias: detect
Return the first element that passes the truth test fn
.
var { return !x % 2 }var odd = f f// > 2 f// > 5
filter(fn(x, idx, coll), xs) Alias: select
Return all the elements that pass the truth test fn
.
var { return !x % 2 }var odd = f f// > [ 1, 3 ] f// > [ 4, 6 ]
Functions
compose(...args)
Creates a new function that is the composition of the argument functions. So:
compose(f, g)(x) <-> f(g(x))
var { return !x % 2 }var { return !x } var odd = f // So now odd(3) <-> not(even(3))console// > true true
partial(fn, ...args)
Creates a function that is fn with bound arguments. You could say that it has pre-filled arguments.
// A simple examplevar { return x + y }var add5 = f// So add5 = f.add(5, ???) // > 8 // Another example var { return !x % 2 } var evenNumbers = f// So evenNumbers = f.filter(even, ???) // > [ 2, 4, 6 ]
id(x)
Identity function. Returns x
as it comes in.
fid5// > 5
functor(x)
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 valuevar gimme5 = f // > 5 // For functions, it returns the function as it is (so this sample is useless)var now = f // > 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 { var getKey = f return { return obj }} var getName = var getAge = // > 'John'// > 21
Operators
furgoneta
includes some operators as functions to ease its usage through your
functional code.
Math
add(x, y)
Equivalent to the infix operator +
f// > 8
sub(x, y)
Equivalent to the infix operator -
f// > 4
mul(x, y)
Equivalent to the infix operator *
f// > 12
div(x, y)
Equivalent to the infix operator /
f// > 3
mod(x, y)
Equivalent to the infix operator %
f// > 0
Comparison
eq(x, y)
Equivalent to the infix operator ===
f// > false
eqc(x, y)
Equivalent to the infix operator ==
f// > true
neq(x, y)
Equivalent to the infix operator !==
f// > true
neqc(x, y)
Equivalent to the infix operator !=
f// > false
gt(x, y)
Equivalent to the infix operator >
f// > true
ge(x, y)
Equivalent to the infix operator >=
f// > true
lt(x, y)
Equivalent to the infix operator <
f// > false
le(x, y)
Equivalent to the infix operator <=
f// > false
Logic
not(x)
Equivalent to the operator !
f// > falsef// > false
and(x, y)
Equivalent to the infix operator &&
f// > false
or(x, y)
Equivalent to the infix operator ||
f// > true
Types
There are several functions to help with typing conversion and detection.
Conversion
objToFunc(x)
Converts an object into a function of its keys. Works both with arrays and objects.
var participant = f // > 'John' var participantStuff = fconsole// > [ 'John', 25 ]
prop(x)
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 = fconsole// > [ 'Johnny', 'Anthony', 'Mary' ]
typeOf(x)
Function that returns a string with the type from the {}.toString method. That is:
f// > 'String' f// > 'Number' f// > 'Boolean' f// > 'Function' f// > 'Array' f// > 'Object'
isA(type, x)
Truth tests a type string with the type of x.
f// > truef// > truef// > false
isNumber(x)
// > true
isArray(x)
// > true
isObject(x)
// > true
isString(x)
// > true
isFunction(x)
// > true
isBoolean(x)
// > true
Development
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.
Inspiration
This library is inspired and influenced by various libraries and languages: