wu.js


wu.js is a JavaScript library providing higher order functions (such as map, filter, and reduce) for ECMAScript 6 iterators.


Getting Started

In Modern Browsers Supporting ES6

Download the ES6 version
<script src="path/to/wu.js"></script>

In Legacy ES5 Browsers

Download the compiled-to-ES5 version
<script src="path/to/traceur-runtime.js"></script>
<script src="path/to/wu.es5.js"></script>

Node and npm

$ npm install wu

and

var wu = require("wu");

Note that this is the compiled-to-ES5 version.

Basics

Iterators represent a stream of data. To get the next value in the stream, you call the iterator's next method. This enables both lazy and infinite sequences. Most of the time you don't need to call next yourself: when you use a for-of loop, you're using iterators behind the scenes.

Anything can create iterators — they just need to make an object with the proper next interface — but generator functions and the yield expression provide convenient syntactic sugar.

// Generate an infinite sequence of the fibonacci numbers.
function* fibs() {
  let a = 0;
  let b = 1;
  while (true) {
    yield a;
    [a, b] = [b, a + b];
  }
}

// Log each even fibonacci number that is less than ten.

const isEven      = n => n % 2 == 0;
const lessThanTen = n => n < 10;

for (let n of fibs()) {
  if (!lessThanTen(n)) {
    break;
  }
  if (isEven(n)) {
    console.log(n);
  }
}

wu.js provides the higher order functions you've come to love from working with arrays (such as map and filter) as well as ones that may be new to JavaScript developers (such as takeWhile). With wu.js, we can rewrite the above example like this:

wu(fibs())
  .filter(isEven)
  .takeWhile(lessThanTen)
  .forEach(console.log.bind(console));

Learn more about the ES6 iterator protocol at MDN.

Examples

Binary trees

The following is a simple immutable sorted set implementation that doesn't do tree balancing for simplicity. It has an iterator method which yields items in sorted order.

const theEmptySet = null;

function SortedSet(value, left=theEmptySet, right=theEmptySet) {
  this.value = value;
  this.left  = left;
  this.right = right;
}

SortedSet.prototype[wu.iteratorSymbol] = function* () {
  if (this.left !== theEmptySet) {
    yield* this.left;
  }

  yield this.value;

  if (this.right !== theEmptySet) {
    yield* this.right;
  }
};

const insert = (set, x) => {
  if (set === theEmptySet) {
    return new SortedSet(x);
  }

  const { value, left, right } = set;

  if (x < value) {
    return new SortedSet(value, insert(left, x), right);
  } else if (x > value) {
    return new SortedSet(value, left, insert(right, x));
  } else {
    return set;
  }
};

We can initialize a set of 100 random floats to work with:

let s = theEmptySet;

let n = 100;
while (n--) {
  s = insert(s, Math.random());
}

To get the sum of all elements greater than .8 in the set:

wu(s).dropWhile(n => n <= .8).reduce((x, y) => x + y);

To find the number of elements that are less than .25:

wu(s).takeWhile(n => n < .25).length();

To find the first element whose square is greater than .5:

wu(s).filter(n => n * n > .5).find(n => n > .5);

API


zipWith

wu.zipWith(fn, ...iterables)

Given n iterables, yield fn(itemFromIter1, itemFromIter2, ..., itemFromIterN) until the shortest iterable is exhausted. This is equivalent to wu.zip(...iterables).spreadMap(fn).

wu.zipWith(Math.pow, wu.count(), wu.repeat(2));
// (0, 1, 4, 9, 16, 25, 36, 49, ...)

zipLongest

wu.zipLongest(...iterables)

The same as wu.zip, but keeps going until the longest iterable is exhausted. When shorter iterables have been exhausted, undefined is used in place of their next items.

wu.zipLongest("hello", [3, 2, 1]);
// (["h", 3], ["e", 2], ["l", 1], ["l", undefined], ["o", undefined])

zip

wu.zip(...iterables)

Given n iterables, yield the next item from each iterable as an array until the shortest iterable is exhausted.

wu.zip("hello", [3, 2, 1]);
// (["h", 3], ["e", 2], ["l", 1])

values

wu.values(object)

Yield the property value of each enumerable property on the object.

const obj = { uno: 1, dos: 2, tres: 3 };
wu.values(obj);
// (1, 2, 3)

unzip

wu(iterable).unzip(n=2)
wu.unzip(n, iterable) curryable

Given an iterable whose items are of the form [a, b, c, ...], return an array of iterators of the form [as, bs, cs, ...].

const pairs = [
  ["one", 1],
  ["two", 2],
  ["three", 3]
];

const [i1, i2] = wu(pairs).unzip();

i1;
("one", "two", "three")

i2;
(1, 2, 3)

unique

wu(iterable).unique()
wu.unique(iterable) curryable

For each item in the iterable, yield only the first occurence of the item.

Note that all yielded items from the iterable are kept in a Set, so memory overhead may become significant while iterating over large collections.

wu([1, 2, 1, 1, 3, 2, 3]).unique();
// (1, 2, 3)

tee

wu(iterable).tee(n=2)
wu.tee(n, iterable) curryable

Split the given iterable into n duplicate iterators.

Warning: once you’ve split an iterator with tee, you shouldn’t use the original iterator again, or else the new iterators will get out of sync!

function* fibs() {
  let a = 0;
  let b = 1;
  while (true) {
    yield a;
    [a, b] = [b, a + b];
  }
}

const [fibs1, fibs2] = wu(fibs())
                         .tap(console.log.bind(console, "Calculated a fib:"))
                         .tee();

fibs1.next().value;
// console.log: Calculated a fib: 0
// 0
fibs1.next().value;
// console.log: Calculated a fib: 1
// 1
fibs1.next().value;
// console.log: Calculated a fib: 1
// 1
fibs1.next().value;
// console.log: Calculated a fib: 2
// 2
fibs1.next().value;
// console.log: Calculated a fib: 3
// 3
fibs1.next().value;
// console.log: Calculated a fib: 5
// 5

// Note that each value is only calculated once!

fibs2.next().value;
// 0
fibs2.next().value;
// 1
fibs2.next().value;
// 1

tap

wu(iterable).tap(fn=console.log.bind(console))
wu.tap(fn, iterable) curryable

For each item in the iterable, call fn(item) and then yield item regardless of the function’s returned value. This is useful for debugging chained methods.

const pairs = [
  [2, 1],
  [2, 2],
  [2, 3],
  [2, 4]
];

const log = msg => console.log.bind(console, msg);

const iter = wu(pairs)
  .tap(log("initial: "))
  .spreadMap(Math.pow)
  .tap(log("after spreadMap: "))
  .map(n => n + 1)
  .tap(log("after + 1: "))
  .reject(n => n < 7)
  .tap(log("after reject: "));

iter.next().value;
// console.log: initial: [2, 1]
// console.log: after spreadMap: 2
// console.log: after + 1: 3
// console.log: initial: [2, 2]
// console.log: after spreadMap: 4
// console.log: after + 1: 5
// console.log: initial: [2, 3]
// console.log: after spreadMap: 8
// console.log: after + 1: 9
// console.log: after reject: 9
// 9

iter.next().value;
// console.log: initial: [2, 4]
// console.log: after spreadMap: 16
// console.log: after + 1: 17
// console.log: after reject: 17
// 17

takeWhile

wu(iterable).takeWhile(fn=Boolean)
wu.takeWhile(fn, iterable) curryable

Yield items from the iterable while fn(item) is truthy.

wu([2, 4, 6, 5, 8]).takeWhile(n => n % 2 === 0);
// (2, 4, 6)

wu(["foo", "bar", null, "baz"]).takeWhile();
// ("foo", "bar")

take

wu(iterable).take(n)
wu.take(n, iterable) curryable

Yield the first n items from the iterable.

wu.count().take(5);
// (0, 1, 2, 3, 4)

spreadMap

wu(iterable).spreadMap(fn)
wu.spreadMap(fn, iterable) curryable

For each item in the iterable, yield fn(...item).

const pairs = [
  [2, 1],
  [2, 2],
  [2, 3],
  [2, 4]
];
wu(pairs).spreadMap(Math.pow);
// (2, 4, 8, 16)

some

wu(iterable).some(fn=Boolean)
wu.some(fn, iterable) curryable

Return true if fn(item) is truthy for any of the items in the iterable, otherwise return false.

wu([false, false, true, false]).some();
// true
wu([1,2,3,4,5]).some(n => n > 10);
// false

slice

wu(iterable).slice(start=0, stop=Infinity)
wu.slice(start, stop, iterable) curryable

Like Array.prototype.slice, but for any iterable.

wu.slice(start, end, iterable) is equivalent to wu(iterable).drop(start).take(end - start).

wu.count(10).slice(1, 4);
// (11, 12, 13)

repeat

wu.repeat(thing, n=Inifinity)

Create an iterable that yields thing n times.

wu.repeat(42)
// (42, 42, 42, 42, 42, ...)
wu.repeat("hello", 2)
// ("hello", "hello")

reject

wu(iterable).reject(fn=Boolean)
wu.reject(fn, iterable) curryable

For each item in the iterable, yield the item if !fn(item) is truthy.

wu([false, true, false, true]).reject()
// (false, false)
wu([1, 2, 3, 4]).reject(x => x % 2 === 0)
// (1, 3)

reductions

wu(iterable).reductions(fn[, initial])
wu.reductions(fn, initial, iterable) curryable

Similar to wu.reduce but yields each intermediate reduction as the iterable is reduced.

const multiply = (x, y) => x * y;
wu.count(1).reductions(multiply);
// (1, 2, 6, 24, 120, ...)

reduce

wu(iterable).reduce(fn[, initial])
wu.reduce(fn, initial, iterable) curryable

Reduce the iterable from left to right with the binary function fn. If initial is supplied, start with that value, otherwise use the first value in the iterable.

const plus = (x, y) => x + y;

wu([1,2,3,4,5]).reduce(plus);
// 15

wu.reduce(plus, 100, [1,2,3,4,5]);
// 115

pluck

wu(iterable).pluck(propertyName)
wu.pluck(propertyName, iterable) curryable

For each item in the iterable, yield item[propertyName].

const myTeam = [
  { name: "Robert Fitzgerald Diggs", alias: "RZA"              },
  { name: "Gary Grice",              alias: "GZA"              },
  { name: "Clifford Smith",          alias: "Method Man"       },
  { name: "Corey Woods",             alias: "Raekwon"          },
  { name: "Dennis Coles",            alias: "Ghostface Killah" },
  { name: "Jason Hunter",            alias: "Inspectah Deck"   },
  { name: "Lamont Jody Hawkins",     alias: "U-God"            },
  { name: "Elgin Turner",            alias: "Masta Killah"     },
  { name: "Russell Tyrone Jones",    alias: "ODB"              }
];
wu(myTeam).pluck("alias");
// ("RZA", "GZA", "Method Man", ...)

map

wu(iterable).map(fn)
wu.map(fn, iterable) curryable

Applies the given function to each item in the iterable and yields the result.

wu([1, 2, 3]).map(x => x * x);
// (1, 4, 9)

keys

wu.keys(object)

Yield the property name of each enumerable property on the object.

const obj = { uno: 1, dos: 2, tres: 3 };
wu.keys(obj);
// ("uno", "dos", "tres")

invoke

wu(iterable).invoke(methodName, ...args)
wu.invoke(methodName, ...args, iterable) curryable

For each item in the iterable, yield item[methodName](...args).

wu([0,1,2,3,4]).invoke("toString", 2);
// ("0", "1", "10", "11", "100")

function Animal(type, noise) {
  this.type  = type;
  this.noise = noise;
}

Animal.prototype.makeNoise = function () {
  return this.type " says '" + this.noise + "'";
}

const animals = [
  new Animal("cat", "meow"),
  new Animal("dog", "woof"),
  new Animal("rat", "squeek"),
  new Animal("hog", "oink")
];

wu(animals).invoke("makeNoise");
// ("cat says 'meow'",
//  "dog says 'woof'",
//  "rat says 'squeek'",
//  "hog says 'oink'")

has

wu(iterable).has(thing)
wu.has(thing, iterable) curryable

Returns true if thing is in the iterable (using === comparison), otherwise returns false.

wu(["uno", "dos", "tres"]).has(1);
// false
wu.count().has(5);
// true

forEach

wu(iterable).forEach(fn)
wu.forEach(fn, iterable) curryable

Call fn(item) for each item in the iterable.

Note that this can cause slow script dialogs or even permanently block the main thread if used with large or infite iterators. In such cases, either use this method inside a Worker (preferrable) or use wu.asyncEach.

wu.forEach(x => console.log("x is " + x),
           [1, 2, 3]);
// console.log: "x is 1"
// console.log: "x is 2"
// console.log: "x is 3"

flatten

wu(iterable).flatten(shallow=false)
wu.flatten(shallow, iterable) curryable

Flatten the given iterable. If shallow is truthy, only flatten by one level.

wu(["I", ["like", ["LISP"]]]).flatten()
// ("I", "like", "LISP")
wu.flatten(true, [1, [2], [3, [[4]]]])
// (1, 2, 3, [[4]]),

find

wu(iterable).find(fn)
wu.find(fn, iterable) curryable

Return the first item from the iterable for which fn(item) is truthy. If no item is found, undefined is returned.

const myTeam = [
  { name: "Robert Fitzgerald Diggs", alias: "RZA"              },
  { name: "Gary Grice",              alias: "GZA"              },
  { name: "Clifford Smith",          alias: "Method Man"       },
  { name: "Corey Woods",             alias: "Raekwon"          },
  { name: "Dennis Coles",            alias: "Ghostface Killah" },
  { name: "Jason Hunter",            alias: "Inspectah Deck"   },
  { name: "Lamont Jody Hawkins",     alias: "U-God"            },
  { name: "Elgin Turner",            alias: "Masta Killah"     },
  { name: "Russell Tyrone Jones",    alias: "ODB"              }
];
wu(myTeam).find(({ name }) => name.contains("Fitzgerald"));
// { name: "Robert Fitzgerald Diggs", alias: "RZA" }

filter

wu(iterable).filter(fn=Boolean)
wu.filter(fn, iterable) curryable

Yield only the items from the iterable for which fn(item) is truthy.

wu([false, true, false, true]).filter()
// (true, true)
wu([1, 2, 3, 4]).filter(x => x % 2 === 0)
// (2, 4)

every

wu(iterable).every(fn=Boolean)
wu.every(fn, iterable) curryable

Return true if fn(item) is truthy for every item in the iterable, otherwise return false.

wu([true, 36, "chambers"]).every();
// true

wu([true, false, true]).every();
// false

const allLessThan100 = wu.every(x => x < 100);
allLessThan100([1, 2, 3, 4, 5]);
// true

enumerate

wu(iterable).enumerate()
wu.enumerate(iterable) curryable

For each item in the iterable, yield a pair [item, index].

wu.enumerate(["cats", "dogs", "rats", "hogs"]);
// (["cats", 0], ["dogs", 1], ["rats", 2], ["hogs", 3])

entries

wu.entries(object)

Yield [key, value] pairs from the given object. Ordering of the pairs is undefined and cannot be relied upon.

const obj = { foo: 1, bar: 2, baz: 3 };
wu.entries(obj);
// (["foo", 1], ["bar", 2], ["baz", 3])

dropWhile

wu(iterable).dropWhile(fn=Boolean)
wu.dropWhile(fn, iterable) curryable

Drop items from the iterable while the predicate is truthy.

wu([2, 4, 6, 5, 8, 10]).dropWhile(x => x % 2 === 0)
// (5, 8, 10)

drop

wu(iterable).drop(n)
wu.drop(n, iterable) curryable

Drop the first n items from the iterable.

wu([5, 4, 3, 2, 1]).drop(2);
// (3, 2, 1)

cycle

wu(iterable).cycle()
wu.cycle(iterable) curryable

Yield each item from the iterable and when the iterable is exhausted, start yielding its items all over again, and again, and again.

wu.cycle([1, 2, 3])
// (1, 2, 3, 1, 2, 3, 1, 2, 3, ...)

curryable

wu.curryable(fn, expected=fn.length)

Returns a new function that keeps currying until it receives expected arguments, at which point it evaluates fn with those arguments applied.

Learn more about currying at Wikipedia.

Most of the functions attached directly to wu (eg wu.filter(fn, iterable), as opposed to wu(iterable).filter(fn)) are curryable.

You generally shouldn’t need to explicitly specify the number of arguments expected unless you’re using rest parameters or optional parameters (which don’t add increment the function’s length property).

const add = wu.curryable((a, b) => a + b);

add(3, 4);
// 7

const add2 = add(2);
add2(10)
// 12

add()()()()()()()()();
// function

const sum = wu.reduce(add, 0);
sum([1,2,3,4,5]);
// 15

const hasProp = wu.curryable((prop, obj) => prop in obj);
const withAlias = wu.filter(hasProp("alias"));

const wantedDeadOrAlive = [
  { name: "Sammy Jones",    alias: "Crime Time"  },
  { name: "Jessica Carter", alias: "Sugar Killa" },
  { name: "Nick Fitzgerald"                      }
];

withAlias(wantedDeadOrAlive);
// ( { name: "Sammy Jones",    alias: "Crime Time"  },
//   { name: "Jessica Carter", alias: "Sugar Killa" } )

count

wu.count(start=0, step=1)

Yield an infinite set of numbers starting with start and incrementing by step.

wu.count()
// (0, 1, 2, 3, 4, 5, 6, ...)
wu.count(5)
// (5, 6, 7, 8, 9, 10, ...)
wu.count(0, 5)
// (0, 5, 10, 15, 20, 25, ...)

concatMap

wu(iterable).concatMap(fn)
wu.concatMap(fn, iterable) curryable

Applies the given function to each item in the iterable and yields each item from the result.

wu([1, 2, 3]).concatMap(x => [x, x * x])
// (1, 1, 2, 4, 3, 9)

chunk

wu(iterable).chunk(n=2)
wu.chunk(n, iterable) curryable

Accumulate items from the iterable into arrays of size n and yield each array.

wu("abcdef").chunk(2);
// (["a", "b"], ["c", "d"], ["e", "f"])
wu("abcdef").chunk(3);
// (["a", "b", "c"], ["d", "e", "f"])
wu("abcdef").chunk(4);
// (["a", "b", "c", "d"], ["e", "f"])

chain

wu.chain(...iterables)

Form a single iterator from consequtive iterables. Yields items from the first iterable until it is exhausted, then yields items from the second iterable until that one is exhausted, and so on until all elements from all iterables have been yielded.

wu.chain("ab", "cd", "ef")
// ("a", "b", "c", "d", "e", "f")

asyncEach

wu(iterable).asyncEach(fn, maxBlock=wu.MAX_BLOCK, timeout=wu.TIMEOUT)
wu.asyncEach(fn, maxBlock, timeout, iterable) curryable

Call fn(item) for each item in the (possibly infinite) iterable. Every maxBlock milliseconds, do a setTimeout for timeout milliseconds so that we don’t hog the thread to ourselves. This gives the browser a chance to paint, fire an event handler, or run another concurrent asyncEach’s set of calls.

asyncEach returns a Promise that is resolved when iteration has completed.

Note: It is generally preferrable to use a Worker instead of asyncEach when possible, as this will give you better throughput and responsiveness. However, if you absolutely must do iteration over a very large number of items on the main thread, asyncEach will let you do it without getting a slow-script-dialog for the tab.

wu.count().asyncEach(x => console.log(x));
// console.log: 0
// console.log: 1
// console.log: 2
// console.log: 3
// ...

Contributing

Development happens on GitHub. Include test(s) and documentation updates in your pull requests.

File bugs and feature requests in the GitHub issue tracker. When filing bugs, include:

  • Whether the bug occurs in the normal ES6 version, the compiled ES5 version, or both and what environment (eg specific browser or node version).
  • A testcase and steps to reproduce the bug with the testcase.
  • The expected results of executing the above steps.
  • The actual results of executing the above steps.

Building

To compile wu.js and its tests to ES5 using Traceur Compiler, run:

$ npm run build

This command regenerates:

  • wu.es5.js — The ES5 compatible version of wu.js with the Traceur runtime library included.
  • wu.es5.map — The source map for the ES5 compatible version of wu.js.
  • test-es5/ — A copy of the test directory with all tests compiled down to ES5 and uses the ES5 version of wu.js.

Tests

Running the Test Suite

There are two testing modes, and you should ensure that both modes pass when submitting pull requests.

Creating New Tests

To add a new test, find or create the appropriate file in test/test-X.js. If creating a new test file, make sure to add a script tag to test/test.html. Mocha is the test runner. Chai's assert module is used for assertions.

Note that new tests will be copied into the test-es5/ directory and compiled down to ES5 automatically when you rebuild the project.

Documentation

This documentation is created with the static site generator Jekyll. To set up jekyll, run:

$ gem install jekyll bundler
$ cd path/to/wu.js
$ bundle install

Once Jekyll is set up, to serve the docs locally and automatically recompile them on change, run:

$ npm run docs

The documentation will be served at http://0.0.0.0:4000.

The sources for this documentation live in index.html and markdown files in the _posts directory. Each wu method has its own markdown file in the _posts directory, and the table of contents for thewu methods is generated automatically. The CSS styles live in index.css.