RaptorJuice

Preface

RaptorJuice originated as a utility library for Elixir. It implements iterators, type checking and other generally missed utilities in JavaScript. It is lightweight, (and may become lighter in the future) at around 6.5k uglified.

• The source.
• The docs.

Purpose

The main goal for RaptorJuice is to implement iterators, or generator objects, with a concise and robust API.

Installation

• Ensure that you have Node.js on your system.

RaptorJuice is entirely self contained and published on npm so all you need to do is:

npm install raptorjuice

Development

• Ensure that you have Node.js on your system.

• Prepare your environment by executing the following commands:

  git clone https://github.com/junglefresh/RaptorJuice.js raptorjuice
  cd raptorjuice
  npm install
  sudo npm install -g grunt-cli mocha

Testing

To automatically run tests upon saving changes to the source or tests run the following:

mocha --reporter spec ./spec/**/*.js ./spec/*.js

• Upon execution of the following command, after each write:

  • The unit tests will be confirmed.

Building

To begin automatically building the project, run:

grunt watch

• Please note that a Java Runtime is required due to the jsdoc dependency.

• By executing the following command, upon each write:

  • The unit tests will be confirmed.
  • Documentation will be regenerated if all tests pass.

Demonstration

If you are interested in any of RaptorJuice's secondary functionality, please refer to the documentation. As stated above, RaptorJuice's primary goal is to create generator objects, and more specifically, to greatly simplify asynchronous iteration.

Forward Iteration

An iterator object's default direction is forward.

var gen = R.iterate([ 1, 2, 3 ]);

while(gen.remaining()) {
  console.log(gen.next());
}

As you probably expect, this prints the values: 1, 2, and 3.

Backward Iteration

Iterators can also be reversed.

var gen = R.iterate([ 1, 2, 3 ]).reversed();

while(gen.remaining()) {
  console.log(gen.next());
}

Note thate the reversed method actually makes a new iterator.

This prints the values in the array in reversed order.

Previous Values and Reverse

An example of iterator reversal follows.

var gen = R.iterate([ 1, 2, 3, 4 ]);

gen.next(); // 1
gen.next(); // 2

gen.reverse().next(); // 2
gen.reverse({ discard : true }).next(); // 3

As a convenience, a prev method also exists. It calls the reverse method, then the next method, followed by reverse again. It takes no parameters.

var gen = R.iterate([ 1, 2, 3, 4 ]);

gen.next(); // 1
gen.next(); // 2

gen.prev(); // 2
gen.next(); // 2

gen.next(); // 3

Remaining and Length Counts

The remaining count is direction dependent.

var gen = R.iterate([ 1, 2, 3 ]);

gen.next();
gen.remaining(); // 2

gen.reverse();
gen.remaining(); // 1

gen.reverse();
gen.remaining(); // 2

This is in contrast to the length method, which always returns the actual length of the underlying data model.

var gen = R.iterate([ 1, 2, 3 ]);

gen.next();
gen.length(); // 3

gen.reverse();
gen.length(); // 3

gen.reverse();
gen.length(); // 3

The length is modified automatically by the push and pop methods.

Copyable Iterators

Iterator objects can be copied at any time. The copy will have the same state as the original.

var gen = R.iterate([ 1, 2, 3 ]);

gen.next(); // 1

var cpy = gen.copy();

cpy.next(); // 2
gen.next(); // 2

Each copy will have it's own model, so modifications to one will not affect the other.

Push and Pop

The push and pop methods allow us to modify the modet itself are indexed absolutely. Indexes are 1 based, as opposed to the standard 0 based indicies we are used to.

This was done for mathematical simplicity.

var gen = R.iterate([ 1, 2, 3 ]);

gen.push(1, [ 4 ]);
gen.data(); // [ 4, 1, 2, 3 ];

gen.next(); // 4
gen.pop(1); // [ 4 ]

Iterators can be created empty, then populated later.

var gen = R.iterate();

gen.push([ 1 ]);
gen.push([ 2, 3 ]);

gen.data(); // [ 1, 2, 3 ]

The pop method also may also be supplied with a count parameter to specify how many elements to remove.

var gen = R.iterate([ 1, 2, 3, 4 ]);

gen.next(); // 1
gen.next(); // 2

gen.pop(1, 2); // [ 1, 2 ]

gen.prev(); // undefined
gen.next(); // 3
gen.prev(); // 3

Data and Index

The underlying model and cursor index are available through the data and index methods.

var gen = R.iterate([ 1, 2, 3, 4 ]);

gen.data(); // [ 1, 2, 3, 4 ]

gen.next(); // 1
gen.next(); // 2

gen.index(); // 2

Transform and Generate

To generate the Fibonacci Sequence we could do something like the following.

var fib = R.iterate([ 0, 1 ]);

fib.transform(function(v, u) {
  this.push([ v + u(1) ]);
  return v;
});

fib.next(); // 0
fib.next(); // 1
fib.next(); // 1
fib.next(); // 2
fib.next(); // 3
fib.next(); // 5, and so on...

This allows us to quite concisely calculate the set of Fibonacci numbers up to the first one over 10,000.

var fib = R.iterate([ 0, 1 ]).transform(function(v, u) {
  this.push([ v + u(1) ]);
  return v;
});

while(fib.cursor(true) < 10000) {
  R.log(fib.next());
};

Passing a truthy value to the cursor method ensures that it returns a value, meaning it will be bumped off either end. This lets us initiate a while loop more simply.

Our previous implementation isn't very robust. What would happen if we were to traverse our iterator in reverse? We would be appending values to the end of our iterator and this is not what we want.

var fib = R.iterate([ 0, 1 ]);

fib.transform(function(v, u) {
  if( (this.direction() === 'forward') && !u(2) && u(1) ) {
    this.push([ v + u(1) ]);
  }
  return v;
});

This second version of our Fibonacci generator works as expected. We generate values when traversing forward, and only when we need them.

fib.next(); // 0
fib.next(); // 1
fib.next(); // 1
fib.next(); // 2
fib.next(); // 3

There is only one catch. Since we generate our values with the transform method, we always have more elements in the array than we actually need. In most cases, this shouldn't be a problem, but what if this is unacceptable for your implementation? You need the generate method, which is called when attempting to move off either end of the model. The value returned by the generate method will be added to the model before actually moving allowing us to create our values on the fly.

var fib = R.iterate([ 0, 1 ]);

fib.generate(function(u) {
  var n = u(-2) + u(-1);
  if(!isNaN(n)) { return n; }
});

Now we have a Fibonacci sequence generator from zero to infinity. Not too shabby, but it gets slightly better. As you'd probably expect, the tranform method will still be called on generated values.

fib.transform(function(v, u) {
  return Math.pow(2, v);
});

We can now generate and caches the Fibbonacci sequence only when we need to. When our generator returns a value from its next or prev functions, those values will be returned as powers of two.

fib.next(); //   1
fib.next(); //   2
fib.next(); //   2
fib.next(); //   4
fib.next(); //   8
fib.next(); //  32
fib.next(); // 256

At any point the generate and transform methods can be unset by providing a falsy value to either method.

Chaining Iterators

We can acomplish some pretty interesting things by chaining iterators.

var a = R.iterate([ 1, 2, 3 ]);
var b = R.iterate([ 4, 5, 6 ]);
var c = R.iterate([ 7, 8, 9 ]);

var chain = R.chain(a, b, c);

while(chain.remaining()) {
  R.log(chain.next());
});

Again, it's slightly better than just that. Chains actually call their component iterator's next method. This means their remaining count is consistent even when being incremented as part of a chain.

Reversal of iterators that are part of a chain is not yet handled.

var a = R.iterate([ 1, 2, 3 ]);
var b = R.iterate([ 4, 5, 6 ]);
var c = R.iterate([ 7, 8, 9 ]);

var chain = R.chain(a, b, c);

chain.next(); // 1
chain.next(); // 2

a.remaining(); // 1
b.remaining(); // 3

chain.next(); // 3
chain.next(); // 4

a.remaining(); // 0
b.remaining(); // 2

Conclusion

By using RaptorJuice's iteration techniques, we can flatten, and iterate over a presently indeterminate sequence of values.

When all is said and done, RaptorJuice implements more of a dequeue than an iterator, strictly speaking.