lang/functional

Functional helper methods.

Usage

The lang/functional module provides functional helper methods. Some of these functions implement APIs from Jeremy Ashkenas's underscore.js and all credits go to him and his contributors.

Globals

Functions

method(lambda)

Takes a function and returns a method associated with an object. When the method is invoked on an instance of the object, the original function is called. It is passed the object instance (i.e. this) as the first parameter, followed by any parameters passed into the method.

let { method } = require("sdk/lang/functional");
let myNumber = {
  times: method(times),
  add: method(add),
  number: 0
};

function times (target, x) {
  return target.number *= x;
}
function add (target, x) {
  return target.number += x;
}

console.log(myNumber.number); // 0
myNumber.add(10); // 10
myNumber.times(2); // 20
myNumber.add(3); // 23

Parameters

lambda : function
The function to be wrapped and returned.

Returns

function : The wrapped lambda.

defer(fn)

Takes a function and returns a wrapped version of the function. Calling the wrapped version will call the original function during the next event loop. This is similar to calling setTimeout with no wait (i.e. setTimeout(function () { ... }, 0)), except that the wrapped function may be reused and does not need to be repeated each time. This also enables you to use these functions as event listeners.

let { defer } = require("sdk/lang/functional");
let fn = defer(function myEvent (event, value) {
  console.log(event + " : " + value);
});

fn("click", "#home");
console.log("done");

// This will print 'done' before 'click : #home' since
// we deferred the execution of the wrapped `myEvent`
// function, making it non-blocking and executing on the
// next event loop

Parameters

fn : function
The function to be deferred.

Returns

function : The new, deferred function.

remit()

An alias for defer.

invoke(callee, params, self)

Invokes callee, passing params as an argument and self as this. Returns the value that is returned by callee.

let { invoke } = require("sdk/lang/functional");

invoke(sum, [1,2,3,4,5], null); // 15

function sum () {
  return Array.slice(arguments).reduce(function (a, b) {
    return a + b;
  });
}

Parameters

callee : function
Function to invoke.

params : Array
Parameters to be passed into callee.

self : mixed
Object to be passed as the this context to callee.

Returns

mixed : Returns the return value of callee.

partial(fn, arguments...)

Takes a function and bind values to one or more arguments, returning a new function of smaller arity.

let { partial } = require("sdk/lang/functional");
let add = function add (x, y) { return x + y; }
let addOne = partial(add, 1);

addOne(5); // 6
addOne(10); // 11
partial(add, addOne(20))(2); // 23

Parameters

fn : function
Function on which partial application is to be performed.

arguments... : mixed
Additional arguments

Returns

function : The partial function.

compose(fn...)

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

let { compose } = require("sdk/lang/functional");

let welcome = compose(exclaim, greet);

welcome('moe'); // "hi: moe!";

function greet (name) { return "hi: " + name; }
function exclaim (statement) { return statement + "!"; }

Parameters

fn... : function
Takes a variable number of functions as arguments and composes them from right to left.

Returns

function : The composed function.

wrap(fn, wrapper)

Returns the first function passed as an argument to the second, allowing you to adjust arguments, run code before and after, and conditionally execute the original function.

let { wrap } = require("sdk/lang/functional");

let wrappedHello = wrap(hello, function (fn, name) {
  return "before, " + fn(name) + "after";
});

wrappedHello("moe"); // "before, hello: moe, after"

function hello (name) { return "hello: " + name; }

Parameters

fn : function
The function to be passed into the wrapper function.

wrapper : function
The function that is called when the return function is executed, taking the wrapped fn as the first parameter.

Returns

function : A function which, when called, executes wrapper with fn as the first parameter, and passes in any additional parameters to the wrapper function.

identity(value)

Returns the same value that is used as the argument. In math: f(x) = x.

let { identity } = require("sdk/lang/functional");
let x = 5;
identity(x); // 5

Parameters

value : mixed
The value to be returned.

Returns

mixed : The value that was originally passed in.

memoize(fn, hasher)

Memoizes a given function by caching the computed result. Useful for speeding up slow-running computations. If passed an optional hashFunction, it will be used to compute the hash key for storing the result, based on the arguments to the original function. The default hashFunction just uses the first argument to the memoized function as the key.

let { memoize } = require("sdk/lang/functional");

let memoizedFn = memoize(primeFactorization);

memoizedFn(50); // Returns [2, 5, 5], had to compute
memoizedFn(100); // Returns [2, 2, 5, 5], had to compute
memoizedFn(50); // Returns [2, 5, 5] again, but pulled from cache

function primeFactorization (x) {
  // Some tricky stuff
}

// We can also use a hash function to compute a different
// hash value. In this example, we'll fabricate a function
// that takes a string of first and last names that
// somehow computes the lineage of that name. Our hash
// function will just parse the last name, as our naive
// implementation assumes that they will share the same lineage

let getLineage = memoize(function (name) {
  // computes lineage
  return data;
}, hasher);

// Hashing function takes a string of first and last name
// and returns the last name.
function hasher (input) {
  return input.split(" ")[1];
}

getLineage("homer simpson"); // Computes and returns information for "simpson"
getLineage("lisa simpson"); // Returns cached for "simpson"

Parameters

fn : function
The function that becomes memoized.

hasher : function
An optional function that takes the memoized function's parameter and returns a hash key for storing the result.

Returns

function : The memoized version of fn.

delay(fn, ms, arguments)

Much like setTimeout, delay invokes a function after waiting a set number of milliseconds. If you pass additional, optional, arguments, they will be forwarded on to the function when it is invoked.

let { delay } = require("sdk/lang/functional");

delay(printAdd, 2000, 5, 10);

// Prints "5+10=15" in two seconds (2000ms)
function printAdd (a, b) { console.log(a + "+" + b + "=" + (a+b)); }

Parameters

fn : function
A function to be delayed.

ms : number
Number of milliseconds to delay the execution of fn.

arguments : mixed
Additional arguments to pass to fn upon execution

once(fn)

Creates a version of the input function that can only be called one time. Repeated calls to the modified function will have no effect, returning the value from the original call. Useful for initialization functions, instead of having to set a boolean flag and checking it later.

let { once } = require("sdk/lang/functional");
let setup = once(function (env) {
  // initializing important things
  console.log("successfully initialized " + env);
  return 1; // Assume success and return 1
});

setup('dev'); // returns 1
// prints "successfully initialized dev"

// Future attempts to call this function just return the cached
// value that was returned previously
setup('production'); // Returns 1
// No print message is displayed since the function isn't executed

Parameters

fn : function
The function that will be executed only once inside the once wrapper.

Returns

function : The wrapped fn that can only be executed once.

chain(fn)

Creates a version of the input function that will return this.

let { chain } = require("sdk/lang/functional");

function Person (age) { this.age = age; }
Person.prototype.happyBirthday = chain(function () this.age++);

let person = new Person(30);

person
  .happyBirthday()
  .happyBirthday()
  .happyBirthday()

console.log(person.age); // 33

Parameters

fn : function
The function that will be wrapped by the chain function.

Returns

function : The wrapped function that executes fn and returns this.

cache()

An alias for once.

debounce(fn, wait)

From Underscore's debounce() function: this takes a function and returns a new version of the function which, when invoked, will not be executed until it has not been invoked for wait milliseconds. This means that if the function's called many times in quick succession the function will only execute once, after the blizzard of calls has finished. This could be useful, for example, if we are checking the user's keyboard input, and want to wait until they've paused in their typing before we do so.

Parameters

fn : function
The function to debounce.

wait : integer
The number of milliseconds to wait before the function is executed.

Returns

function : The debounced version of fn.

throttle(fn, wait, options)

From Underscore's throttle() function: this takes a function and returns a new version of the function which, when invoked repeatedly, will not excute the function more than once per wait milliseconds.

Parameters

fn : function
The function to debounce.

wait : integer
The number of milliseconds to wait before the function is executed.

options : object
By default the function is called as soon as it is invoked (the leading edge of the wait period), and at the end of wait (the trailing edge of the wait period). Pass {leading : false} to stop the function being called at the leading edge, and {trailing : false} to stop it being called at the trailing edge.

Returns

function : The throttled version of fn.