Neptune: Planet or Myth?

    iterator-worker

    1.0.0 • Public • Published

    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

    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

    Install

    npm i iterator-worker

    DownloadsWeekly Downloads

    2

    Version

    1.0.0

    License

    ISC

    Unpacked Size

    20.6 kB

    Total Files

    9

    Last publish

    Collaborators

    • paulkiddle