queue.io
An events based queue iteration JavaScript module, under the MIT license.
This tool is useful when in combination of your asynchronous operations, when you need to wait the entire queue to create some iterators on it.
queue.io offers a way to make it simply, to create some iterators after and/or before the queue is entire and you can invert the iteration direction, before/after too (separately, for each iterator, for a same queue)
Install :
npm install queue.io
Reference :
Queue([eventEmitter], [eventName = 'value']) :
var queue; queue = Queue();
Notes :
- The eventEmitter, first argument of
Queue(eventEmitter, [eventName = 'value'])
, awaits 2 event types :eventName
to fill the queuedone
(once) to indicate a done state to all the queue iterators
- When eventEmitter receives the done event, it removes the value listeners and starts the iterations, on each iterator, if any
Queue.from(arrayLike)
creates an auto-done queue, it must be an array-like object
(Array, DOM NodeList, ...)- An
error
event sent to the eventEmitter is relayed on the queue itself - A queue created without eventEmitter is empty and auto-dones at the next tick if no queues are joined by intercept/listen/append
- A queue emits a
done
event when full-filled
Queue.from(iterable, [eventName = 'value']) :
var queue; queue = Queue.from([1, 2, 3]);queue = Queue.from('test');queue = Queue.from(document.getElementsByTagName('*'));
Directions :
Queue.NEXT
: used to indicate the direction to the current iterator, first -> lastQueue.PREV
: used to indicate the direction to the current iterator, last -> first
queue.iterate([direction = Queue.NEXT]) :
var iterator; iterator = queue.iterate();
Iterator events :
-
eventName
:- `value' : the current value
next
: a method to jump to the next iterationqueue
: the current queue
-
done
:queue
: the current queue
Note :
eventName
is related to theeventName
passed at the queue creation (default : 'value')
Fill a queue :
var EventEmitter, Queue, eventName, eventEmitter, queue; EventEmitter = require('events').EventEmitter;Queue = require('queue.io'); eventName = 'value'; // the default event nameeventEmitter = new EventEmitter();queue = Queue(eventEmitter, eventName); eventEmitter.emit(eventName, 1);eventEmitter.emit(eventName, 2);eventEmitter.emit(eventName, 3); eventEmitter.emit('done');
queue.append(queue, [event = 'value'], [direction = Queue.NEXT]) :
Appends a queue to an another, after its last value
var queue; queue = Queue.from([1, 2, 3]); queue.append(Queue.from([4, 5, 6]));queue.append(Queue.from([7, 8, 9])); /* queue values :1, 2, 3, 4, 5, 6, 7, 8, 9*/
queue.listen(queue, [event = 'value'], [direction = Queue.NEXT]) :
Same as queue.append but this method adds its values FIFO
var queue; queue = Queue.from([1, 2, 3]); queue.listen(Queue.from([4, 5, 6]));queue.append(Queue.from([7, 8, 9])); /* queue values :1, 2, 3, 4, 7, 5, 8, 6, 9*/
queue.intercept(callback, [event = 'value'], [direction = Queue.NEXT]) :
This method sends a callback based async function response to the callback argument
If that function returns an error, queue.intercept sends the error to the queue itself
var fs, queue; fs = require('fs'); queue = Queue(); fs.readdir('.', queue.intercept(queue.append)); // sends the values to the current queue like queue.appendfs.readdir('.', queue.intercept(queue.listen)); // sends the values to the current queue like queue.listen queue.on('error', function (error) { // fired if no readable directory});
The iteration :
var iterator; iterator = queue.iterate(); iterator.on(eventName, function onvalue(value, next, queue) { console.log('Iteration value = %d on :', value, queue); next();}); iterator.on('done', function (queue) { console.log('Iterator done on :', queue);});
Note :
- The iterator creation isn't dependent to the queue state, then you can create them before and/or after the queue done state
Requirements :
- ES5 support
Browser-side :
Simply use the browserified version
<script src="https://raw.githubusercontent.com/Lcfvs/queue.io/master/queue.io.browserified.js"></script><script>var EventEmitter, Queue; EventEmitter = require('events').EventEmitter;Queue = require('queue.io'); // ...</script>