chunkify
What is it?
An API to prevent long-running scripts from blocking.
The idea is to do work in synchronous chunks, periodically letting go of the thread.
Here it is in the browser, integrated with Angular.js.
API
We'll use our TypeScript declarations for documentation.
Options
In API methods, an options literal can be passed:
declare interface IChunkifyOptions // The number of synchronous calls to make before yielding. // Default value is 10; must be positive. chunk: number; // The number of milliseconds to wait until calling again. // Default value is 50; must be non-negative. delay: number; // The context on which to invoke calls on. // Default value is null; must not be a Number, Boolean, or undefined. scope?: Object;
Exports
Core
chunkify.generator
var generator: start: number final: number options?: IChunkifyOptions IterableIterator<number|IPause>; declare interface IPause resume: void IPause;
Returns the core Generator used to power everything else.
It yields integers from start
and final
. Values are yielded synchronously within intervals of length chunk
. At every chunk
th call to .next()
, the generator yields a promise-like IPause
, with a single method .resume
.
An error will be thrown if the generator is advanced before the IPause
has .resume
'd. The pause resumes after delay
milliseconds, which is given in options
or using its default value.
Arrays
For chunking up functional work on arrays.
chunkify.each
var each: <T> tArray: T void options?: IChunkifyOptions Promise<void>
chunkify.map
// This Promise resolves with the mapped array.var map: <T> tArray: T T options?: IChunkifyOptions Promise<T>;
chunkify.reduce
// Virtually identical to the native reduce on Array.prototype. // This Promise resolves with the reduction result.var reduce: <T U> tArray: T U options?: IChunkifyOptions memo?: U Promise<U>;
Catching Errors
To catch any Error
thrown during processing, attach a .catch(...)
to the returned Promise
.
The error object in .catch(...)
has the shape
error: Error item: T index: number
where error
is the original error, index
is the index where it happened, and item
is tArray[index]
.
Processing stops when this happens.
Iteration
For chunking up work done in loops.
chunkify.interval
var interval: void start: number final: number options?: IChunkifyOptions Promise<void>;
chunkify.range
// This is the same as chunkify.interval // with the start parameter set to 0.var range: void length: number options?: IChunkifyOptions Promise<void>;
Catching Errors
Just like catching errors in the Arrays API, except an item
key isn't part of the error object.
Contributing
Development is in TypeScript/ES6.
Get the source:
$ git clone git@github.com:username/chunkify
Install dependencies:
$ npm i && npm i babel-polyfill && node_modules/.bin/tsd install
Compile:
$ npm run-script compile
Develop:
$ npm run-script dev
License
MIT © 2016, Victor Alvarez