wu.js
wu.js
is a JavaScript library providing higher order
functions (such as map
, filter
,
and reduce
) for ECMAScript 6 iterators.
or
and
Note that this is the compiled-to-ES5 version.
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.
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:
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.
We can initialize a set of 100 random floats to work with:
To get the sum of all elements greater than .8 in the set:
To find the number of elements that are less than .25:
To find the first element whose square is greater than .5:
wu(iterable).asyncEach(fn, maxBlock=wu.MAX_BLOCK, timeout=wu.TIMEOUT)
wu.asyncEach(fn, maxBlock, timeout, iterable)
curryableCall 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.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(iterable).chunk(n=2)
wu.chunk(n, iterable)
curryableAccumulate items from the iterable into arrays of size n
and yield each
array.
wu(iterable).concatMap(fn)
wu.concatMap(fn, iterable)
curryableApplies the given function to each item in the iterable and yields each item from the result.
wu.count(start=0, step=1)
Yield an infinite set of numbers starting with start
and incrementing by
step
.
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).
wu(iterable).cycle()
wu.cycle(iterable)
curryableYield each item from the iterable and when the iterable is exhausted, start yielding its items all over again, and again, and again.
wu(iterable).drop(n)
wu.drop(n, iterable)
curryableDrop the first n
items from the iterable.
wu(iterable).dropWhile(fn=Boolean)
wu.dropWhile(fn, iterable)
curryableDrop items from the iterable while the predicate is truthy.
wu.entries(object)
Yield [key, value]
pairs from the given object. Ordering of the pairs is
undefined and cannot be relied upon.
wu(iterable).enumerate()
wu.enumerate(iterable)
curryableFor each item in the iterable, yield a pair [item, index]
.
wu(iterable).every(fn=Boolean)
wu.every(fn, iterable)
curryableReturn true
if fn(item)
is truthy for every item in the iterable, otherwise
return false
.
wu(iterable).filter(fn=Boolean)
wu.filter(fn, iterable)
curryableYield only the items from the iterable for which fn(item)
is truthy.
wu(iterable).find(fn)
wu.find(fn, iterable)
curryableReturn the first item from the iterable for which fn(item)
is truthy. If no
item is found, undefined
is returned.
wu(iterable).flatten(shallow=false)
wu.flatten(shallow, iterable)
curryableFlatten the given iterable. If shallow
is truthy, only flatten by one level.
wu(iterable).forEach(fn)
wu.forEach(fn, iterable)
curryableCall 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(iterable).has(thing)
wu.has(thing, iterable)
curryableReturns true
if thing
is in the iterable (using ===
comparison), otherwise
returns false
.
wu(iterable).invoke(methodName, ...args)
wu.invoke(methodName, ...args, iterable)
curryableFor each item in the iterable, yield item[methodName](...args)
.
wu.keys(object)
Yield the property name of each enumerable property on the object.
wu(iterable).map(fn)
wu.map(fn, iterable)
curryableApplies the given function to each item in the iterable and yields the result.
wu(iterable).nth(n)
wu.nth(n, iterable)
curryableReturn the nth item from the iterable. If n
is out of bounds, undefined
is returned.
wu(iterable).pluck(propertyName)
wu.pluck(propertyName, iterable)
curryableFor each item in the iterable, yield item[propertyName]
.
wu(iterable).reduce(fn[, initial])
wu.reduce(fn, initial, iterable)
curryableReduce 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.
wu(iterable).reductions(fn[, initial])
wu.reductions(fn, initial, iterable)
curryableSimilar to wu.reduce
but yields each intermediate reduction as the
iterable is reduced.
wu(iterable).reject(fn=Boolean)
wu.reject(fn, iterable)
curryableFor each item in the iterable, yield the item if !fn(item)
is truthy.
wu.repeat(thing, n=Inifinity)
Create an iterable that yields thing
n
times.
wu(iterable).slice(start=0, stop=Infinity)
wu.slice(start, stop, iterable)
curryableLike Array.prototype.slice
, but for any iterable.
wu.slice(start, end, iterable)
is equivalent to
wu(iterable).drop(start).take(end - start)
.
wu(iterable).some(fn=Boolean)
wu.some(fn, iterable)
curryableReturn true
if fn(item)
is truthy for any of the items in the iterable,
otherwise return false
.
wu(iterable).spreadMap(fn)
wu.spreadMap(fn, iterable)
curryableFor each item in the iterable, yield fn(...item)
.
wu(iterable).take(n)
wu.take(n, iterable)
curryableYield the first n
items from the iterable.
wu(iterable).takeWhile(fn=Boolean)
wu.takeWhile(fn, iterable)
curryableYield items from the iterable while fn(item)
is truthy.
wu(iterable).tap(fn=console.log.bind(console))
wu.tap(fn, iterable)
curryableFor 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.
wu(iterable).tee(n=2)
wu.tee(n, iterable)
curryableSplit 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!
wu(iterable).toArray()
Converts an iterable to an Array.
wu(iterable).unique()
wu.unique(iterable)
curryableFor 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(iterable).unzip(n=2)
wu.unzip(n, iterable)
curryableGiven an iterable whose items are of the form [a, b, c, ...]
, return an array
of iterators of the form [as, bs, cs, ...]
.
wu.values(object)
Yield the property value of each enumerable property on the object.
wu.zip(...iterables)
Given n
iterables, yield the next item from each iterable as an array until
the shortest iterable is exhausted.
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.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)
.
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:
To compile wu.js
and its tests to ES5 using the Babel compiler,
run:
$ npm run build
This command regenerates:
dist/wu.js
— The ES5 compatible version of wu.js
.
dist/wu.debug.js
— The ES5 compatible version of wu.js
with
an inline source map included.
dist/wu.min.js
— The minified ES5 compartible version of wu.js
.
$ npm test
To add a new test, find or create the appropriate file
in test/test-X.js
. Mocha
is the test
runner. Chai's assert
module is used for assertions.
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
.