breathe.js API

# Breathable Chains

Breathable Chains are similar to traditional promises in that they implement then() 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.

# Loops

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

# Special Loops

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(config)
  • config.iterations [required]
    • a value equal to the number of iterations of the loop.
  • config.body [required]
    • a function(iterationNumber) that gets called for every iteration of the loop. The first argument is the current iteration number (starting at 0). 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.times(iterations, body, [config])
  • equivalent to calling breathe.times, with config.iterations and config.body set to iterations and body