Iterators.js NPM

iterators.js

Useful iterators.

iterators.js has no dependencies. Tests are available in the test/ directory. Run npm test or mocha to execute tests.

It is available on npm, bower, and directly via RawGit.

Warning: iterators.js requires ES6 features such as Set.

Install

If you're using npm, simply add it to your project (and package.json) by running:

$ npm install --save iterators.js

If you're using bower, run:

$ bower install iterators.js

Direct link for browsers, minified:

<script type="text/javascript" src="https://rawgit.com/nishanths/iterators.js/master/iterators.min.js"></script>

Usage

iterators.js works well both in node and the browser.

Node

Require 'iterators.js' in your JS file:

// index.js

var itr = require('iterators.js');
itr.distinct([1, 2, 1, 2, 3], function(item) {
  console.log(item);
});

Back at the terminal:

$ node index.js
1
2
3

Browser

Load it in your browser. Set the src for iterators.js to either a local copy (you can get it from bower) or to the online copy on GitHub (served via RawGit).

<!-- index.html -->

<html>
<head>
  <title>Example</title>
</head>
<body>
  Hello, world
  <script type="text/javascript" src="https://rawgit.com/nishanths/iterators.js/master/iterators.min.js"></script>
  <script type="text/javascript" src="./main.js"></script>
</body>
</html>

Use the itr global to access functions.

// main.js

console.log(itr); // Object {}

itr.distinct([1, 2, 1, 2, 3], function(item) {
  console.log(item);
});

// 1
// 2
// 3

Note on global variable conflicts: The previous itr variable can be retrieved by running itr.noConflict(). The function resets the itr variable back to its original value and returns a reference to the iterators.js's itr object which you can assign to the variable of your choosing.

var myItr = itr.noConflict();
// Previous itr is now restored
// myItr can be used to access iterator.js's library functions

Examples

count() – iterate from start to end (excluded) using the specified step

var start = 10;
var end = 20;
var step = 2;

itr.count(start, end, step, function(item) {
    console.log(item);
});

// 10
// 12
// 14
// 16
// 18

cycle() – cycle over the elements of an array

itr.cycle([1,2,3], 5, function(item) {
    console.log(item);
});

// 1
// 2
// 3
// 1
// 2

distinct() – iterate only over unencountered elements

itr.distinct([1,1,2,3], function(item) {
    console.log(item);
});

// 1
// 2
// 3

cartesianProduct() - iterate cartesian product pairs

itr.cartesianProduct([1,2], [3,4], function(pair) {
    console.log(pair[0] * pair[1]);
});

// 3
// 4
// 6
// 8

groupBy() – group elements into arrays depending on the result from applying the specified function

var firstCharNormalizedCase = function(str) { return str.charAt(0).toLowerCase(); };
var arr = itr.groupBy(['abc', 'gooey', 'foo', 'Gui'], firstCharNormalizedCase);

console.log(arr); // [ [ 'abc' ], [ 'gooey', 'Gui' ], [ 'foo' ] ]

imap() – applies a function to each element in the arrays and returns an array of results

var self = null;
var sum = function(a,b,c) {
  return a + b + c;
};

var arr = itr.imap(sum, self, [2,3,8], [0,4,6], [1,3,10]);

console.log(arr); // [3,10,24]

iterate() – successively applies a function to the value and returns an array of result

var x = 2;
var numTimes = 3;

var arr = itr.iterate(x, numTimes, function(value) {
    return value * 10;
});

console.log(arr); // [2,20,200]

slices() – iterate over slices each of size n; if the array does not slice "evenly", the last slice will have fewer elements

itr.slices([1,2,3,4,5], 2, function(slice) {
    console.log(slice);
});

// [1,2]
// [3,4]
// [5]

subsets() – iterate subsets (optionally specify a size, defaults to subsets of all sizes when null)

var arr = [];
var context = null;
var size = null;

itr.subsets([1,2,3], function(e) {
    arr.push(e)
}, context, size);

arr.sort(function(a,b) {
    return a.length - b.length;
});

console.log(arr); // [[],[1],[2],[3],[1,2],[1,3],[2,3],[1,2,3]]

takeNth() – iterate over every nth element

itr.takeNth([1,2,3,4,5], 2, function(item) {
    console.log(item);
});

// 2
// 4

takeStrict() – take n elements only if at least n elements exists, oherwise throw an Error

var reversed = true;
var arr = itr.takeStrict([1,2,3,4,5,6,10], 5, reversed);
console.log(arr); // [3,4,5,6,10]

times() – repeatedly call a function; call infinitely if the number of times is omitted

var arr = [];
var idxs = [];

itr.times(5, function(idx) {
    arr.push(42);
    idxs.push(idx);
});

console.log(arr); // [42,42,42,42,42]
console.log(idxs); // [0,1,2,3,4]

Functions

count
cycle
distinct
cartesianProduct
groupBy
imap
iterate
slices
subsets
takeNth
takeStrict
times

General notes

The test/ directory is a great place for in-depth examples.
Functions also provide the option to specify a context (this value) for your callback function.