0.0.1 • Published 11 years ago

furgoneta v0.0.1

Weekly downloads
4
License
-
Repository
github
Last release
11 years ago

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 = require('furgoneta')

Documentation terms and reference

  • ...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.

Arguments

Utilities and functions to work with arguments.

toArray(...args)

Converts an arguments variable into a JS array.

(function() {
  console.log(f.toArray(arguments))  // > [ 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.first([ 1, 2, 3, 4 ]) // > 1

last(xs)

Returns the last element of the array.

f.last([ 1, 2, 3, 4 ])  // > 4

rest(xs)

Returns the rest of elements of the array, that is all but the first one.

f.rest([ 1, 2, 3, 4 ])  // > [ 2, 3, 4 ]

initial(xs)

Returns the initial elements of the array, that is all but the last one.

f.initial([ 1, 2, 3, 4 ])  // > [ 1, 2, 3 ]

Objects

Utilities and functions to work with javascript objects.

keys(obj)

Returns the keys of the object in an array.

f.keys({ a: 1, b: 2 }) // > [ '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.extend(
  { a: 1, b: 1 },
  { b: 2 },
  { c: 3 }
)
// > { 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 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 }

eachRight(fn(x, idx, xs), xs)

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 }

map(function(x, idx, xs), xs)

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 ]

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 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

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 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

reduceRight(fn(memo, x, idx, xs), seed, coll) Alias: foldR

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

reduceRight1(fn(memo, x, idx, xs), coll) Alias: foldR1

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

find(fn(x, idx, coll), xs) Alias: detect

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

filter(fn(x, idx, coll), xs) Alias: select

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 ]

Functions

compose(...args)

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

partial(fn, ...args)

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 ]

id(x)

Identity function. Returns x as it comes in.

f.id(5)
// > 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 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

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.add(6, 2)
// > 8

sub(x, y)

Equivalent to the infix operator -

f.sub(6, 2)
// > 4

mul(x, y)

Equivalent to the infix operator *

f.mul(6, 2)
// > 12

div(x, y)

Equivalent to the infix operator /

f.div(6, 2)
// > 3

mod(x, y)

Equivalent to the infix operator %

f.mod(6, 2)
// > 0

Comparison

eq(x, y)

Equivalent to the infix operator ===

f.eq(6, '6')
// > false

eqc(x, y)

Equivalent to the infix operator ==

f.eqc(6, '6')
// > true

neq(x, y)

Equivalent to the infix operator !==

f.neq(6, 2)
// > true

neqc(x, y)

Equivalent to the infix operator !=

f.neqc(6, '6')
// > false

gt(x, y)

Equivalent to the infix operator >

f.gt(6, 2)
// > true

ge(x, y)

Equivalent to the infix operator >=

f.ge(6, 2)
// > true

lt(x, y)

Equivalent to the infix operator <

f.lt(6, 2)
// > false

le(x, y)

Equivalent to the infix operator <=

f.le(6, 2)
// > false

Logic

not(x)

Equivalent to the operator !

f.not(6)
// > false
f.not(true)
// > false

and(x, y)

Equivalent to the infix operator &&

f.and(true, null)
// > false

or(x, y)

Equivalent to the infix operator ||

f.or(true, null)
// > 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.objToFunc({ name: 'John', age: 25, country: 'ES' })

participant('name')
// > 'John'

var participantStuff = f.map(participant, [ 'name', 'age' ])
console.log(participantStuff)
// > [ '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 = f.map(f.prop('name'), people)
console.log(names)
// > [ 'Johnny', 'Anthony', 'Mary' ]

typeOf(x)

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'

isA(type, x)

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(x)

isNumber(4)
// > true

isArray(x)

isArray([1])
// > true

isObject(x)

isObject({})
// > true

isString(x)

isString('asdf')
// > true

isFunction(x)

isFunction(function() {})
// > true

isBoolean(x)

isBoolean(false)
// > 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:

@infinitebrahmanuniverse/nolb-fur@everything-registry/sub-chunk-1712
0.0.1

11 years ago