Big Data Processor

The JavaScript's functional programming helper library.

---

Usage

each(list, iteratee)

Iterates over a list of elements, yielding each in turn to an iteratee function. Each invocation of iteratee is called with three arguments: (element, index, list). If list is a JavaScript object, iteratee's arguments will be (value, key, list). Returns the list for chaining.

processor.each([1, 2, 3], alert);
=> alerts each number in turn...

processor.each({one: 1, two: 2, three: 3}, alert);
=> alerts each number value in turn...

map(list, iteratee)

Produces a new array of values by mapping each value in list through a transformation function (iteratee). The iteratee is passed three arguments: the value, then the index (or key) of the iteration, and finally a reference to the entire list.

processor.map([1, 2, 3], function(num){ return num * 3; });
=> [3, 6, 9]

processor.map({one: 1, two: 2, three: 3}, function(num, key){ return num * 3; });
=> [3, 6, 9]

processor.map([[1, 2], [3, 4]], processor.first);
=> [1, 3]

reduce(list, iteratee, [memo])

Also known as inject and foldl, reduce boils down a list of values into a single value. Memo is the initial state of the reduction, and each successive step of it should be returned by iteratee. The iteratee is passed four arguments: the memo, then the value and index (or key) of the iteration, and finally a reference to the entire list.

var sum = processor.reduce([1, 2, 3], function(memo, num){ return memo + num; }, 0);
=> 6

reduceRight(list, iteratee, [memo])

The right-associative version of reduce. Foldr is not as useful in JavaScript as it would be in a language with lazy evaluation.

var list = [[0, 1], [2, 3], [4, 5]];
var flat = processor.reduceRight(list, function(a, b) { return a.concat(b); }, []);
=> [4, 5, 2, 3, 0, 1]

find(list, predicate)

Looks through each value in the list, returning the first one that passes a truth test (predicate), or undefined if no value passes the test. The function returns as soon as it finds an acceptable element, and doesn't traverse the entire list.

var even = processor.find([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
=> 2

filter(list, predicate)

Looks through each value in the list, returning an array of all the values that pass a truth test (predicate).

var evens = processor.filter([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
=> [2, 4, 6]

where(list, properties)

Looks through each value in the list, returning an array of all the values that contain all of the key-value pairs listed in properties.

processor.where(listOfPlays, {author: "Shakespeare", year: 1611});
=> [{title: "Cymbeline", author: "Shakespeare", year: 1611}, {title: "The Tempest", author: "Shakespeare", year: 1611}]

findWhere(list, properties)

Looks through the list and returns the first value that matches all of the key-value pairs listed in properties. If no match is found, or if list is empty, undefined will be returned.

processor.findWhere(publicServicePulitzers, {newsroom: "The New York Times"});
=> {year: 1918, newsroom: "The New York Times", reason: "For its public service in publishing in full so many official reports, documents and speeches by European statesmen relating to the progress and conduct of the war."}

reject(list, predicate)

Returns the values in list without the elements that the truth test (predicate) passes. The opposite of filter.

var odds = processor.reject([1, 2, 3, 4, 5, 6], function(num){ return num % 2 == 0; });
=> [1, 3, 5]

every(list, [predicate])

Returns true if all of the values in the list pass the predicate truth test. Short-circuits and stops traversing the list if a false element is found.

processor.every([2, 4, 5], function(num) { return num % 2 == 0; });
=> false

some(list, [predicate])

Returns true if any of the values in the list pass the predicate truth test. Short-circuits and stops traversing the list if a true element is found.

processor.some([null, 0, 'yes', false]);
=> true

contains(list, value)

Returns true if the value is present in the list.

processor.contains([1, 2, 3], 3);
=> true

invoke(list, methodName, *arguments)

Calls the method named by methodName on each value in the list. Any extra arguments passed to invoke will be forwarded on to the method invocation.

processor.invoke([[5, 1, 7], [3, 2, 1]], 'sort');
=> [[1, 5, 7], [1, 2, 3]]

pluck(list, propertyName)

A convenient version of what is perhaps the most common use-case for map: extracting a list of property values.

var stooges = [{name: 'moe', age: 40}, {name: 'larry', age: 50}, {name: 'curly', age: 60}];
processor.pluck(stooges, 'name');
=> ["moe", "larry", "curly"]

max(list, [iteratee])

Returns the maximum value in list. If an iteratee function is provided, it will be used on each value to generate the criterion by which the value is ranked. -Infinity is returned if list is empty, so an isEmpty guard may be required. Non-numerical values in list will be ignored.

var stooges = [{name: 'moe', age: 40}, {name: 'larry', age: 50}, {name: 'curly', age: 60}];
processor.max(stooges, function(stooge){ return stooge.age; });
=> {name: 'curly', age: 60};

min(list, [iteratee])

Returns the minimum value in list. If an iteratee function is provided, it will be used on each value to generate the criterion by which the value is ranked. Infinity is returned if list is empty, so an isEmpty guard may be required. Non-numerical values in list will be ignored.

var numbers = [10, 5, 100, 2, 1000];
processor.min(numbers);
=> 2

sortBy(list, iteratee)

Returns a (stably) sorted copy of list, ranked in ascending order by the results of running each value through iteratee. Iteratee may also be the string name of the property to sort by (eg. length).

processor.sortBy([1, 2, 3, 4, 5, 6], function(num){ return Math.sin(num); });
=> [5, 4, 6, 3, 1, 2]

var stooges = [{name: 'moe', age: 40}, {name: 'larry', age: 50}, {name: 'curly', age: 60}];
processor.sortBy(stooges, 'name');
=> [{name: 'curly', age: 60}, {name: 'larry', age: 50}, {name: 'moe', age: 40}];

groupBy(list, iteratee)

Splits a collection into sets, grouped by the result of running each value through iteratee. If iteratee is a string instead of a function, groups by the property named by iteratee on each of the values.

processor.groupBy([1.3, 2.1, 2.4], function(num){ return Math.floor(num); });
=> {1: [1.3], 2: [2.1, 2.4]}

processor.groupBy(['one', 'two', 'three'], 'length');
=> {3: ["one", "two"], 5: ["three"]}

indexBy(list, iteratee)

Given a list, and an iteratee function that returns a key for each element in the list (or a property name), returns an object with an index of each item. Just like groupBy, but for when you know your keys are unique.

var stooges = [{name: 'moe', age: 40}, {name: 'larry', age: 50}, {name: 'curly', age: 60}];
processor.indexBy(stooges, 'age');
=> {
  "40": {name: 'moe', age: 40},
  "50": {name: 'larry', age: 50},
  "60": {name: 'curly', age: 60}
}

countBy(list, iteratee)

Sorts a list into groups and returns a count for the number of objects in each group. Similar to groupBy, but instead of returning a list of values, returns a count for the number of values in that group.

processor.countBy([1, 2, 3, 4, 5], function(num) {
  return num % 2 == 0 ? 'even': 'odd';
});
=> {odd: 3, even: 2}

shuffle(list)

Returns a shuffled copy of the list, using a version of the Fisher-Yates shuffle.

processor.shuffle([1, 2, 3, 4, 5, 6]);
=> [4, 1, 6, 3, 5, 2]

sample(list, [n])

Produce a random sample from the list. Pass a number to return n random elements from the list. Otherwise a single random item will be returned.

processor.sample([1, 2, 3, 4, 5, 6]);
=> 4

processor.sample([1, 2, 3, 4, 5, 6], 3);
=> [1, 6, 2]

size(list)

Return the number of values in the list.

processor.size({one: 1, two: 2, three: 3});
=> 3

partition(list, predicate)

Split list into two arrays: one whose elements all satisfy predicate and one whose elements all do not satisfy predicate.

processor.partition([0, 1, 2, 3, 4, 5], isOdd);
=> [[1, 3, 5], [0, 2, 4]]

first(array, [n])

Returns the first element of an array. Passing n will return the first n elements of the array.

processor.first([5, 4, 3, 2, 1]);
=> 5

initial(array, [n])

Returns everything but the last entry of the array. Especially useful on the arguments object. Pass n to exclude the last n elements from the result.

processor.initial([5, 4, 3, 2, 1]);
=> [5, 4, 3, 2]

last(array, [n])

Returns the last element of an array. Passing n will return the last n elements of the array.

processor.last([5, 4, 3, 2, 1]);
=> 1

rest(array, [index])

Returns the rest of the elements in an array. Pass an index to return the values of the array from that index onward.

processor.rest([5, 4, 3, 2, 1]);
=> [4, 3, 2, 1]

compact(array)

Returns a copy of the array with all falsy values removed. In JavaScript, false, null, 0, "", undefined and NaN are all falsy.

processor.compact([0, 1, false, 2, '', 3]);
=> [1, 2, 3]

flatten(array, [shallow])

Flattens a nested array (the nesting can be to any depth). If you pass shallow, the array will only be flattened a single level.

processor.flatten([1, [2], [3, [[4]]]]);
=> [1, 2, 3, 4];

processor.flatten([1, [2], [3, [[4]]]], true);
=> [1, 2, 3, [[4]]];

without(array, *values)

Returns a copy of the array with all instances of the values removed.

processor.without([1, 2, 1, 0, 3, 1, 4], 0, 1);
=> [2, 3, 4]

union(array, *values)

Computes the union of the passed-in arrays: the list of unique items, in order, that are present in one or more of the arrays.

processor.union([1, 2, 3], [101, 2, 1, 10], [2, 1]);
=> [1, 2, 3, 101, 10]

intersection(*arrays)

Computes the list of values that are the intersection of all the arrays. Each value in the result is present in each of the arrays.

processor.intersection([1, 2, 3], [101, 2, 1, 10], [2, 1]);
=> [1, 2]

difference(array, *others)

Similar to without, but returns the values from array that are not present in the other arrays.

processor.difference([1, 2, 3, 4, 5], [5, 2, 10]);
=> [1, 3, 4]

uniq(array, [iteratee])

Produces a duplicate-free version of the array, using === to test object equality. In particular only the first occurence of each value is kept. If you want to compute unique items based on a transformation, pass an iteratee function.

processor.uniq([1, 2, 1, 4, 1, 3]);
=> [1, 2, 4, 3]

zip(*arrays)

Merges together the values of each of the arrays with the values at the corresponding position. Useful when you have separate data sources that are coordinated through matching array indexes. Use with apply to pass in an array of arrays. If you're working with a matrix of nested arrays, this can be used to transpose the matrix.

processor.zip(['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]);
=> [["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]

unzip(array)

The opposite of zip. Given an array of arrays, returns a series of new arrays, the first of which contains all of the first elements in the input arrays, the second of which contains all of the second elements, and so on.

processor.unzip([["moe", 30, true], ["larry", 40, false], ["curly", 50, false]]);
=> [['moe', 'larry', 'curly'], [30, 40, 50], [true, false, false]]

object(list, [values])

Converts arrays into objects. Pass either a single list of [key, value] pairs, or a list of keys, and a list of values. If duplicate keys exist, the last value wins.

processor.object(['moe', 'larry', 'curly'], [30, 40, 50]);
=> {moe: 30, larry: 40, curly: 50}

processor.object([['moe', 30], ['larry', 40], ['curly', 50]]);
=> {moe: 30, larry: 40, curly: 50}

indexOf(array, value)

Returns the index at which value can be found in the array, or -1 if value is not present in the array.

processor.indexOf([1, 2, 3], 2);
=> 1

lastIndexOf(array, value, [fromIndex])

Returns the index of the last occurrence of value in the array, or -1 if value is not present. Pass fromIndex to start your search at a given index.

processor.lastIndexOf([1, 2, 3, 1, 2, 3], 2);
=> 4

sortedIndex(list, value, [iteratee])

Uses a binary search to determine the index at which the value should be inserted into the list in order to maintain the list's sorted order. If an iteratee function is provided, it will be used to compute the sort ranking of each value, including the value you pass. The iteratee may also be the string name of the property to sort by (eg. length).

processor.sortedIndex([10, 20, 30, 40, 50], 35);
=> 3

var stooges = [{name: 'moe', age: 40}, {name: 'curly', age: 60}];
processor.sortedIndex(stooges, {name: 'larry', age: 50}, 'age');
=> 1

findIndex(array, predicate)

Similar to processor.indexOf, returns the first index where the predicate truth test passes; otherwise returns -1.

processor.findIndex([4, 6, 8, 12], isPrime);
=> -1 // not found

processor.findIndex([4, 6, 7, 12], isPrime);
=> 2

findLastIndex(array, predicate)

Like processor.findIndex but iterates the array in reverse, returning the index closest to the end where the predicate truth test passes.

var users = [{'id': 1, 'name': 'Bob', 'last': 'Brown'},
             {'id': 2, 'name': 'Ted', 'last': 'White'},
             {'id': 3, 'name': 'Frank', 'last': 'James'},
             {'id': 4, 'name': 'Ted', 'last': 'Jones'}];
processor.findLastIndex(users, {name: 'Ted'});
=> 3

range([start], stop, [step])

A function to create flexibly-numbered lists of integers, handy for each and map loops. start, if omitted, defaults to 0; step defaults to 1. Returns a list of integers from start (inclusive) to stop (exclusive), incremented (or decremented) by step, exclusive. Note that ranges that stop before they start are considered to be zero-length instead of negative — if you'd like a negative range, use a negative step.

processor.range(10);
=> [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

processor.range(1, 11);
=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

processor.range(0, 30, 5);
=> [0, 5, 10, 15, 20, 25]

processor.range(0, -10, -1);
=> [0, -1, -2, -3, -4, -5, -6, -7, -8, -9]

processor.range(0);
=> []

keys(object)

Retrieve all the names of the object's own enumerable properties.

processor.keys({one: 1, two: 2, three: 3});
=> ["one", "two", "three"]

allKeys(object)

Retrieve all the names of object's own and inherited properties.

function Stooge(name) {
  this.name = name;
}
Stooge.prototype.silly = true;
processor.allKeys(new Stooge("Moe"));
=> ["name", "silly"]

values(object)

Return all of the values of the object's own properties.

processor.values({one: 1, two: 2, three: 3});
=> [1, 2, 3]

mapObject(object, iteratee)

Like map, but for objects.

processor.mapObject({start: 5, end: 12}, function(val, key) {
  return val + 5;
});
=> {start: 10, end: 17}

pairs(object)

Convert an object into a list of [key, value] pairs.

processor.pairs({one: 1, two: 2, three: 3});
=> [["one", 1], ["two", 2], ["three", 3]]

invert(object)

Returns a copy of the object where the keys have become the values and the values the keys. For this to work, all of your object's values should be unique and string serializable.

processor.invert({Moe: "Moses", Larry: "Louis", Curly: "Jerome"});
=> {Moses: "Moe", Louis: "Larry", Jerome: "Curly"};

functions(object)

Returns a list of the names of every method in an object — that is to say, the name of every function property of the object.

processor.functions(processor);
=> ["invert", "pairs", "mapObject" ...

findKey(object, predicate)

Similar to _.findIndex but for keys in objects. Returns the key where the predicate truth test passes or undefined.

extend(destination, *sources)

Shallowly copy all of the properties in the source objects over to the destination object, and return the destination object. Any nested objects or arrays will be copied by reference, not duplicated. It's in-order, so the last source will override properties of the same name in previous arguments.

processor.extend({name: 'moe'}, {age: 50});
=> {name: 'moe', age: 50}

extendOwn(destination, *sources)

Like extend, but only copies own properties over to the destination object.

pick(object, *keys)

Return a copy of the object, filtered to only have values for the whitelisted keys (or array of valid keys). Alternatively accepts a predicate indicating which keys to pick.

processor.pick({name: 'moe', age: 50, userid: 'moe1'}, 'name', 'age');
=> {name: 'moe', age: 50}

processor.pick({name: 'moe', age: 50, userid: 'moe1'}, function(value, key, object) {
  return processor.isNumber(value);
});
=> {age: 50}

omit(object, *keys)

Return a copy of the object, filtered to omit the blacklisted keys (or array of keys). Alternatively accepts a predicate indicating which keys to omit.

processor.omit({name: 'moe', age: 50, userid: 'moe1'}, 'userid');
=> {name: 'moe', age: 50}

processor.omit({name: 'moe', age: 50, userid: 'moe1'}, function(value, key, object) {
  return processor.isNumber(value);
});
=> {name: 'moe', userid: 'moe1'}

defaults(object, *defaults)

Fill in undefined properties in object with the first value present in the following list of defaults objects.

var iceCream = {flavor: "chocolate"};
processor.defaults(iceCream, {flavor: "vanilla", sprinkles: "lots"});
=> {flavor: "chocolate", sprinkles: "lots"}

clone(object)

Create a shallow-copied clone of the provided plain object. Any nested objects or arrays will be copied by reference, not duplicated.

processor.clone({name: 'moe'});
=> {name: 'moe'};

has(object, key)

Check whether there is a key property in the object.

processor.has({a: 1, b: 2, c: 3}, "b");
=> true

property(key)

Returns a function that will itself return the key property of any passed-in object.

processor.property('name')({name: 'moe'});
=> 'moe'

propertyOf(key)

Inverse of processor.property. Takes an object and returns a function which will return the value of a provided property.

processor.propertyOf({name: 'moe'})('name');
=> 'moe'

matcher(attrs)

Returns a predicate function that will tell you if a passed in object contains all of the key/value properties present in attrs.

var ready = processor.matcher({selected: true, visible: true});
var readyToGoList = processor.filter(list, ready);

isEqual(object, other)

Performs an optimized deep comparison between the two objects, to determine if they should be considered equal.

var stooge = {name: 'moe', luckyNumbers: [13, 27, 34]};
var clone  = {name: 'moe', luckyNumbers: [13, 27, 34]};
stooge == clone;
=> false
processor.isEqual(stooge, clone);
=> true

isMatch(object, properties)

Tells you if the keys and values in properties are contained in object.

var stooge = {name: 'moe', age: 32};
processor.isMatch(stooge, {age: 32});
=> true

isEmpty(object)

Returns true if an enumerable object contains no values (no enumerable own-properties).

processor.isEmpty([1, 2, 3]);
=> false

processor.isEmpty({});
=> true

isElement(object)

Returns true if object is a DOM element.

processor.isElement(jQuery('body')[0]);
=> true

isArray(object)

Returns true if object is an Array.

processor.isArray([1,2,3]);
=> true

isObject(object)

Returns true if object is an Object.

processor.isObject({});
=> true

processor.isObject(1);
=> false

isArguments(object)

Returns true if object is an Arguments object.

(function(){ return processor.isArguments(arguments); })(1, 2, 3);
=> true

processor.isArguments([1,2,3]);
=> false

isFunction(object)

Returns true if object is an Function.

processor.isFunction(alert);
=> true

isString(object)

Returns true if object is a String.

processor.isString("moe");
=> true

isNumber(object)

Returns true if object is a Number (including NaN).

processor.isNumber(8.4 * 5);
=> true

isFinite(object)

Returns true if object is a finite Number.

processor.isFinite(-101);
=> true

processor.isFinite(-Infinity);
=> false

isBoolean(object)

Returns true if object is either true or false.

processor.isBoolean(null);
=> false

isDate(object)

Returns true if object is a Date.

processor.isDate(new Date());
=> true

isRegExp(object)

Returns true if object is a RegExp.

processor.isRegExp(/moe/);
=> true

isError(object)

Returns true if object inherits from an Error.

try {
  throw new TypeError("Example");
} catch (o_O) {
  processor.isError(o_O);
}
=> true

isNaN(object)

Returns true if object is NaN.

processor.isNaN(NaN);
=> true

processor.isNaN(undefined);
=> false

isNull(object)

Returns true if object is null.

processor.isNull(null);
=> true

processor.isNull(undefined);
=> false

isUndefined(object)

Returns true if object is undefined.

processor.isUndefined(window.missingVariable);
=> true