a library to write nonblocking, asynchronous JavaScript
npm install breatheAs a simple example, in traditional JavaScript, you may have a long looping function:
``js`
function longLoopingFunction() {
var i;
for(i = 0; i < 100000; i++) {
trickyFunction();
}
}
Here trickyFunction() runs 100,000 times, without letting any other code run or UI respond. But with breathe.js, the same code can be written as:
`js`
function breathableLongLoopingFunction() {
return breathe.times(100000, function (i) {
trickyFunction();
});
}
Here the function also runs sequentially, but if it runs for too long (over 17 milliseconds by default), breathe.js relinquishes the main thread to allow other functions to run or UI to respond, then runs the remaining loop, repeatedly relinquishing if necessary.
By using promise conventions and nested functions, converting code is usually straightforward, preserving a function's overall structure and logic. Converting code makes it asynchronous, and adds methods to stop, pause, and unpause the code. Read more about how to use it on the 'Using breathe.js' page.
Web workers still use a single thread within the worker, so a computation-heavy function can block other code— namely message handling— from running. Breathe.js works within web workers, so they can respond in the middle of executing a long-running function. It also makes it easy to pause and unpause code running within the worker.
console.log statements or chunks that execute longer than expected, it can make the UI sluggish or nonresponsive. Without the warning, it can be more difficult to stop the page. loops, breathe.loop() creates an asynchronous loop, with a condition and a body. And breathe.times() creates a loop with a fixed number of iterations and a body, a replacement for some for loops. $3
Large functions can be subdivided into blocks of code, with variable declarations and synchronous and/or asynchronous code.
`js
function () {
var variablesSharedInsideOfThisBlock;
synchronousCode();
return asynchronousCode();
}
`You don't need to have both synchronous code or asynchronous code, but asynchronous code usually involves subsequent code blocks. For instance, breathe.loop takes a body as an argument, which is a code block. This allows you to nest loops:
js
function nestedLoop() {
var running;
running = true;
return breathe.loop(function () { return running; }, function () {
// another code block
var i;
i = 0;
return breathe.loop({ function () { return running && i++ < 50; },
function () {
running = doSomethingAwesome(c);
}
);
}
);
}
`You can use the .then() method of promises (the asynchronous code) to chain code blocks together, so you can run code after asynchronous code completes.
js
function sequentialLoops() {
var i = 0;
return breathe.loop(function () { i++ < 50;}, function () {
console.log('Counting up: ', i);
}
).then(function () {
// another code block
return breathe.loop(function () { i-- >= 0;}, function () {
console.log('Counting down: ', i);
});
});
}
`breathe.js API
$3
Breathable Chains are similar to traditional promises in that they implement and catch() methods, though they return the original chain object rather than a new promise. _Breathable chains_ implement additional methods to stop, pause, and unpause promise chains. # breathe.chain([initValue*])
* creates and returns a _breathable chain_, with a promise chain initialized to initValue.
# _breathableChain_.then(onFulfilled[, onRejected*])
adds functions onFulfilled and onRejected to the promise chain, which are called when the promise is fulfilled or rejected. Similar to
Promise.prototype.then(), except it alters its internal promise chain instead of returning a new promise. Both onFulfilled and onRejected* can optionally return a value to pass on to the next promise chain, or a promise (breathable or not), that are resolved or rejected before continuing down the promise chain. Returns the invoking _breathableChain_. # _breathableChain_.catch(onRejected*)
adds function onRejected to the promise chain, which is called when the promise is rejected. Similar to
Promise.prototype.catch(), except it alters its internal promise chain instead of returning a new promise. onRejected* can optionally return a value to pass on to the next promise chain that are resolved or rejected before continuing down the promise chain. Returns the invoking _breathableChain_.* # _breathableChain_.pause()
* requests _breathableChain_ to pause its current chain. Because not all promises in the chain may be pauseable, pausing may be delayed until the current promise resolves. Returns a promise that resolves when the current chain is paused.
* # _breathableChain_.unpause()
* requests _breathableChain_ to unpause its current chain. Returns a resolved promise.
* # _breathableChain_.stop()
* requests _breathableChain_ to stop its current chain. Because not all promises in the chain may be stoppable, stopping may be delayed until the current promise resolves. Returns a promise that resolves when the current chain is stopped.
$3
Breathable Loops are breathable chains that repeatedly iterate over a body while a condition is true. They can be stopped, paused, or unpaused. They can serve as a replacement to while loops.
# breathe.loop(config*)
config*.condition [required]
* an argumentless function that should return false (or a falsey value) if the loop should exit
config*.body [required]
* a function that gets called for every iteration of the loop. It can optionally return a value; if it returns a promise or chain (breathable or traditional), the loop does not continue iterating until the promise or chain resolves. # breathe.loop(condition, body, [config*])
equivalent to calling breathe.loop, with config.condition and config.body set to condition and body*
$3
Times Loops are breathable chains that repeatedly iterate over a body for a fixed number of iterations. They can be stopped, paused, or unpaused. They can serve as a replacement to some for` loops. # breathe.times(iterations, body, [config*])
equivalent to calling breathe.times, with config.iterations and config.body set to iterations and body*