iterator-worker

IteratorWorker

A class for running an (async or sync) iterator on the current event loop, with methods for starting and stopping its execution.

Beware

The iterator will be run in the same event loop as the calling code. This means your worker can affect the performance of the rest of your code, including causing it to block your program's execution completely.

It is advised you only use this library in situations that do not have high performance requirements, such as development environments and user scripts. Otherwise you should be running your worker in a separate thread.

Example

import IteratorWorker from 'iterator-worker';

// Use a sleep functon to simulate waiting on i/o
const sleep = n => new Promise(resolve=>setTimeout(resolve, n));

// Example worker function
// Counts upwards, one number per second
async function* count(){
	let i = 0;
	while(true) {
		await sleep(1000);
		console.log(++i);
		yield i;
	}
}

// Start the worker
const worker = IteratorWorker.start(count());

// The worker is now running and will count every second.
// Sleep our code to simulate doing work.
await sleep(10000);

// Stop the worker
await worker.stop();

You can also use the class in a for-await loop, which takes care of starting and stopping the worker automatically:

for await(const {} of new IteratorWorker(count())) {
	// This is equivalent to the previous code
	await sleep(10000);
}

The advantage of doing this is that it will also close the iterator in case your code throws an error.

Dependencies

None

iterator-worker

Iterator Worker

See: default

• iterator-worker
  • module.exports ⏏
    • new module.exports(worker, callback)
    • instance
      • .started
      • .finished
      • .start() ⇒ Boolean
      • .join() ⇒ Promise
      • .stop() ⇒ Promise
    • static
      • .IteratorWorkerError
      • .default
      • .start()

module.exports ⏏

Kind: Exported class

new module.exports(worker, callback)

Create an instance of IteratorWorker for a given iterator. The callback's signature is the same as general node-style callbacks: function callback(error, result){} In the case of an error the callback will be called with only one argument, and the worker will exit. Otherwise, each time the iterator yields, the callback will be called with the yeilded value as the second argument, and undefined as the first.

Param	Type	Description
worker	Iterable | AsyncIterable	An iterable object
callback	function	A function called with each iteration result or error

module.exports.started

True if the worker has started

Kind: instance property of module.exports

module.exports.finished

True if the worker has finished

Kind: instance property of module.exports

module.exports.start() ⇒ Boolean

Starts the iterator in the same event loop.

Kind: instance method of module.exports
Returns: Boolean - False if the iterator had been started previously, otherwise True
Throws:

• IteratorWorkerError If the worker has already finished.

module.exports.join() ⇒ Promise

Wait for your worker to finish naturally. If your worker uses an infinite loop, this will never resolve; instead you should call stop

Kind: instance method of module.exports
Returns: Promise - Promise that resolves when the worker stops

module.exports.stop() ⇒ Promise

Stop the worker after the current iteration. and wait for it to finish.

Kind: instance method of module.exports
Returns: Promise - Promise that resolves when the worker stops

module.exports.IteratorWorkerError

An error that occurs as part of the management of an IteratorWorker

Kind: static class of module.exports

module.exports.default

A class representing an (async or sync) iterator, with methods for starting or stopping its execution.

The iterator will be run in the same event loop, meaning synchronous code in the worker can still block the execution of your program.

It is advised you only use this library in low-risk environments such as development environments and user scripts. Otherwise you should be running your worker in a separate thread.

Kind: static property of module.exports

module.exports.start()

Constructs and starts the iterator worker. Has the same signature as the regular constructor, and includes the behaviour of the start method.

Kind: static method of module.exports