function

Function*(al)* utilities.

awaitDelay(fn, delay):Function

Returns a function that ensures that fn is only called after delay milliseconds have elapsed. When the returned function is called before the delay has elapsed, it will wait until the delay has elapsed and then call fn. When the returned function is called after the delay has elapsed, it will call fn after the next "tick" (it will always be called asynchronously). The context and arguments that the returned function is called in are applied to fn.

In the below example onLoaded will not be executed before a 1000 millisecond delay. Even if loadImages loads and calls callback earlier. However, say the images take 1500 milliseconds to load, it will trigger onLoaded immediately.

var callback = awaitDelay(onLoaded, 1000);
loadImages(callback);
function onLoaded(){
    console.log('loaded');
}

You can also cancel de delayed call by simply using the native clearTimeout method (like a regular setTimeout call).

var timeoutId = callback();
// onLoaded won't be called since it was canceled before the 1000ms delay
clearTimeout(timeoutId);

Arguments:

1. fn (Function) : Target Function
2. delay (Number) : Delay of execution in milliseconds

See: debounce()

bind(fn, context, [...args]):Function

Return a function that will execute in the given context, optionally adding any additional supplied parameters to the beginning of the arguments collection.

Arguments

1. fn (Function) : Target Function
2. context (Object) : Execution context (object used as this)
3. [...args] (*) : Arguments (0...n arguments)

See: partial(), object/bindAll

compose(...fn):Function

Returns the composition of a list of functions, where each function consumes the return value of the function that follows. In math terms, composing the functions f(), g(), and h() produces f(g(h())).

function add2(x) { return x + 2 }
function multi2(x) { return x * 2 }
map([1, 2, 3], compose(add2, multi2)); // [4, 6, 8]

//same as
map([1, 2, 3], function(x){
    return add2( multi2(x) );
});

constant(value):Function

Returns a new function that will always return value when called.

var f = constant('foo');
f(); // 'foo'

// Provided arguments are ignored; value is always returned
f(1); // 'foo'

f = constant({ foo: 'bar' });
f(); // { foo: 'bar' }

debounce(fn, delay[, isAsap]):Function

Creates a function that will delay the execution of fn until after delay milliseconds have elapsed since the last time it was invoked.

Subsequent calls to the debounced function will return the result of the last fn call.

// sometimes less is more
var lazyRedraw = debounce(redraw, 300);
foo.on.resize.add(lazyRedraw);

In this visualization, | is a debounced-function call and X is the actual callback execution:

Default
||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
                         X                                 X

Debounced with `isAsap == true`:
||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
X                                 X

You also have the option to cancel the debounced call if it didn't happen yet:

lazyRedraw();
// lazyRedraw won't be called since `cancel` was called before the `delay`
lazyRedraw.cancel();

See: throttle()

func(name):Function

Returns a function that calls a method with given name on supplied object. Useful for iteration methods like array/map and array/forEach.

See: prop()

// will call the method `getName()` for each `user`
var names = map(users, func('getName'));

identity(val):*

Returns the first argument provided to it.

identity(3);     // 3
identity(1,2,3); // 1
identity('foo'); // "foo"

partial(fn, [...args]):Function

Return a partially applied function supplying default arguments.

This method is similar to bind, except it does not alter the this binding.

Arguments

1. fn (Function) : Target Function
2. [...args] (*) : Arguments (0...n arguments)

See: bind()

function add(a, b){ return a + b }
var add10 = partial(add, 10);
console.log( add10(2) ); // 12

prop(name):Function

Returns a function that gets a property with given name from supplied object. Useful for using in conjunction with array/map and/or for creating getters.

See: array/pluck()

var users = [{name:"John", age:21}, {name:"Jane", age:25}];
// ["John", "Jane"]
var names = map(users, prop('name'));

series(...fn):Function

Returns a function that will execute all the supplied functions in order and passing the same parameters to all of them. Useful for combining multiple array/forEach into a single one and/or for debugging.

// call `console.log()` and `doStuff()` for each item item in the array
forEach(arr, series(console.log, doStuff));

throttle(fn, interval):Function

Creates a function that, when executed, will only call the fn function at most once per every interval milliseconds.

If the throttled function is invoked more than once during the wait timeout, fn will also be called on the trailing edge of the timeout.

Subsequent calls to the throttled function will return the result of the last fn call.

// sometimes less is more
var lazyRedraw = throttle(redraw, 300);
foo.on.resize.add(lazyRedraw);

In this visualization, | is a throttled-function call and X is the actual fn execution:

||||||||||||||||||||||||| (pause) |||||||||||||||||||||||||
X    X    X    X    X    X        X    X    X    X    X    X

You also have the option to cancel the throttled call if it didn't happen yet:

lazyRedraw();
setTimeout(function(){
    lazyRedraw();
    // lazyRedraw will be called only once since `cancel` was called before
    // the `interval` for 2nd call completed
    lazyRedraw.cancel();
}, 250);

See: debounce()

timeout(fn, millis, context, [...args]):Number

Functions as a wrapper for setTimeout. Calls a the function fn after a given delay millis in milliseconds. The function is called within the specified context. The return value can be used to clear the timeout using clearTimeout.

var id = timeout(doStuff, 300, this);

clearTimeout(id);

times(n, callback, [context]):void

Iterates over a callback n times.

Arguments

1. n (Number) : Number of iterations
2. callback (Function) : Closure executed for every iteration
3. context (Object) : Execution context (object used as this)

var output = '';
times(5, function(i) {
    output += i.toString();
});
// output: 01234

wrap(fn, wrapper):Function

Wraps the first fn inside of the wrapper function, passing it as the first argument. This allows the wrapper to execute code before and after the fn runs, adjust the arguments, and execute it conditionally.

var hello = function(name) { return "hello: " + name; };
hello = wrap(hello, function(func) {
  return "before, " + func("moe") + ", after";
});
hello();
// output: 'before, hello: moe, after'

See: partial()

For more usage examples check specs inside /tests folder. Unit tests are the best documentation you can get...