diff options
Diffstat (limited to 'v3/index.html')
| -rw-r--r-- | v3/index.html | 289 |
1 files changed, 289 insertions, 0 deletions
diff --git a/v3/index.html b/v3/index.html new file mode 100644 index 0000000..b37cb89 --- /dev/null +++ b/v3/index.html @@ -0,0 +1,289 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>Home - Documentation</title> + + + <link rel="icon" href="favicon.ico?v=2"> + <link rel="stylesheet" href="https://cdn.jsdelivr.net/bootstrap/3.3.6/css/bootstrap.min.css"> + + <link rel="stylesheet" href="styles/prettify-tomorrow.css"> + + <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Montserrat:400,700"> + <link rel="stylesheet" href="styles/jsdoc-default.css"> + + <!--[if lt IE 9]> + <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script> + <![endif]--> + <link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/ionicons/2.0.1/css/ionicons.min.css"> +</head> +<body> + +<div class="navbar navbar-default navbar-fixed-top"> + <div class="navbar-header"> + <a class="navbar-brand" href="../"> + <img src="img/async-logo.svg" alt="Async.js"> + </a> + </div> + <ul class="nav navbar-nav"> + <li id="version-dropdown" class="dropdown"> + <a href="#" class="dropdown-toggle vertically-centered" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">v3.0.1 <span class="caret"></span> + </a> + <ul class="dropdown-menu"> + <li><a href="../v3/">v3.0.x</a></li> + <li><a href="../v2/">v2.6.2</a></li> + <li> + <a href="https://github.com/caolan/async/blob/v1.5.2/README.md">v1.5.x</a> + </li> + </ul> + </li> + <li><a href="./index.html">Home</a></li> + <li><a href="./docs.html">Docs</a></li> + <li><a href="https://github.com/caolan/async/blob/master/CHANGELOG.md">Changelog</a></li> + <li><a href="https://github.com/caolan/async"><i class="ion-social-github" aria-hidden="true"></i></a></li> + </ul> + <ul class="nav navbar-nav navbar-right"> + <form class="navbar-form navbar-left" role="search"> + <div class="form-group"> + <input type="text" class="form-control typeahead" id="doc-search" placeholder="Search" autofocus> + </div> + </form> + </ul> +</div> + + +<input type="checkbox" id="nav-trigger" class="nav-trigger"> +<label for="nav-trigger" class="navicon-button x"> + <div class="navicon"></div> +</label> + +<label for="nav-trigger" class="overlay"></label> + +<div id="main"> + <div id="main-container" data-spy="scroll" data-target="#toc" data-offset="50"> + + + + + + + + + + + + + + + + + + + + <section class="readme"> + <article><p><img src="https://raw.githubusercontent.com/caolan/async/master/logo/async-logo_readme.jpg" alt="Async Logo"></p> +<p><a href="https://travis-ci.org/caolan/async"><img src="https://travis-ci.org/caolan/async.svg?branch=master" alt="Build Status via Travis CI"></a> +<a href="https://www.npmjs.com/package/async"><img src="https://img.shields.io/npm/v/async.svg" alt="NPM version"></a> +<a href="https://coveralls.io/r/caolan/async?branch=master"><img src="https://coveralls.io/repos/caolan/async/badge.svg?branch=master" alt="Coverage Status"></a> +<a href="https://gitter.im/caolan/async?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Join the chat at https://gitter.im/caolan/async"></a></p> +<p><em>For Async v1.5.x documentation, go <a href="https://github.com/caolan/async/blob/v1.5.2/README.md">HERE</a></em></p> +<p>Async is a utility module which provides straight-forward, powerful functions +for working with asynchronous JavaScript. Although originally designed for +use with <a href="https://nodejs.org/">Node.js</a> and installable via <code>npm install async</code>, +it can also be used directly in the browser.</p> +<p>Async is also installable via:</p> +<ul> +<li><a href="https://yarnpkg.com/en/">yarn</a>: <code>yarn add async</code></li> +<li><a href="http://bower.io/">bower</a>: <code>bower install async</code></li> +</ul> +<p>Async provides around 70 functions that include the usual 'functional' +suspects (<code>map</code>, <code>reduce</code>, <code>filter</code>, <code>each</code>…) as well as some common patterns +for asynchronous control flow (<code>parallel</code>, <code>series</code>, <code>waterfall</code>…). All these +functions assume you follow the Node.js convention of providing a single +callback as the last argument of your asynchronous function -- a callback which expects an Error as its first argument -- and calling the callback once.</p> +<h2>Quick Examples</h2><pre class="prettyprint source lang-js"><code>async.map(['file1','file2','file3'], fs.stat, function(err, results) { + // results is now an array of stats for each file +}); + +async.filter(['file1','file2','file3'], function(filePath, callback) { + fs.access(filePath, function(err) { + callback(null, !err) + }); +}, function(err, results) { + // results now equals an array of the existing files +}); + +async.parallel([ + function(callback) { ... }, + function(callback) { ... } +], function(err, results) { + // optional callback +}); + +async.series([ + function(callback) { ... }, + function(callback) { ... } +]);</code></pre><p>There are many more functions available so take a look at the docs below for a +full list. This module aims to be comprehensive, so if you feel anything is +missing please create a GitHub issue for it.</p> +<h2>Common Pitfalls <a href="http://stackoverflow.com/questions/tagged/async.js">(StackOverflow)</a></h2><h3>Synchronous iteration functions</h3><p>If you get an error like <code>RangeError: Maximum call stack size exceeded.</code> or other stack overflow issues when using async, you are likely using a synchronous iteratee. By <em>synchronous</em> we mean a function that calls its callback on the same tick in the javascript event loop, without doing any I/O or using any timers. Calling many callbacks iteratively will quickly overflow the stack. If you run into this issue, just defer your callback with <code>async.setImmediate</code> to start a new call stack on the next tick of the event loop.</p> +<p>This can also arise by accident if you callback early in certain cases:</p> +<pre class="prettyprint source lang-js"><code>async.eachSeries(hugeArray, function iteratee(item, callback) { + if (inCache(item)) { + callback(null, cache[item]); // if many items are cached, you'll overflow + } else { + doSomeIO(item, callback); + } +}, function done() { + //... +});</code></pre><p>Just change it to:</p> +<pre class="prettyprint source lang-js"><code>async.eachSeries(hugeArray, function iteratee(item, callback) { + if (inCache(item)) { + async.setImmediate(function() { + callback(null, cache[item]); + }); + } else { + doSomeIO(item, callback); + //... + } +});</code></pre><p>Async does not guard against synchronous iteratees for performance reasons. If you are still running into stack overflows, you can defer as suggested above, or wrap functions with <a href="#ensureAsync"><code>async.ensureAsync</code></a> Functions that are asynchronous by their nature do not have this problem and don't need the extra callback deferral.</p> +<p>If JavaScript's event loop is still a bit nebulous, check out <a href="http://blog.carbonfive.com/2013/10/27/the-javascript-event-loop-explained/">this article</a> or <a href="http://2014.jsconf.eu/speakers/philip-roberts-what-the-heck-is-the-event-loop-anyway.html">this talk</a> for more detailed information about how it works.</p> +<h3>Multiple callbacks</h3><p>Make sure to always <code>return</code> when calling a callback early, otherwise you will cause multiple callbacks and unpredictable behavior in many cases.</p> +<pre class="prettyprint source lang-js"><code>async.waterfall([ + function(callback) { + getSomething(options, function (err, result) { + if (err) { + callback(new Error("failed getting something:" + err.message)); + // we should return here + } + // since we did not return, this callback still will be called and + // `processData` will be called twice + callback(null, result); + }); + }, + processData +], done)</code></pre><p>It is always good practice to <code>return callback(err, result)</code> whenever a callback call is not the last statement of a function.</p> +<h3>Using ES2017 <code>async</code> functions</h3><p>Async accepts <code>async</code> functions wherever we accept a Node-style callback function. However, we do not pass them a callback, and instead use the return value and handle any promise rejections or errors thrown.</p> +<pre class="prettyprint source lang-js"><code>async.mapLimit(files, 10, async file => { // <- no callback! + const text = await util.promisify(fs.readFile)(dir + file, 'utf8') + const body = JSON.parse(text) // <- a parse error here will be caught automatically + if (!(await checkValidity(body))) { + throw new Error(`${file} has invalid contents`) // <- this error will also be caught + } + return body // <- return a value! +}, (err, contents) => { + if (err) throw err + console.log(contents) +})</code></pre><p>We can only detect native <code>async</code> functions, not transpiled versions (e.g. with Babel). Otherwise, you can wrap <code>async</code> functions in <code>async.asyncify()</code>.</p> +<h3>Binding a context to an iteratee</h3><p>This section is really about <code>bind</code>, not about Async. If you are wondering how to +make Async execute your iteratees in a given context, or are confused as to why +a method of another library isn't working as an iteratee, study this example:</p> +<pre class="prettyprint source lang-js"><code>// Here is a simple object with an (unnecessarily roundabout) squaring method +var AsyncSquaringLibrary = { + squareExponent: 2, + square: function(number, callback){ + var result = Math.pow(number, this.squareExponent); + setTimeout(function(){ + callback(null, result); + }, 200); + } +}; + +async.map([1, 2, 3], AsyncSquaringLibrary.square, function(err, result) { + // result is [NaN, NaN, NaN] + // This fails because the `this.squareExponent` expression in the square + // function is not evaluated in the context of AsyncSquaringLibrary, and is + // therefore undefined. +}); + +async.map([1, 2, 3], AsyncSquaringLibrary.square.bind(AsyncSquaringLibrary), function(err, result) { + // result is [1, 4, 9] + // With the help of bind we can attach a context to the iteratee before + // passing it to Async. Now the square function will be executed in its + // 'home' AsyncSquaringLibrary context and the value of `this.squareExponent` + // will be as expected. +});</code></pre><h3>Subtle Memory Leaks</h3><p>There are cases where you might want to exit early from async flow, when calling an Async method inside another async function:</p> +<pre class="prettyprint source lang-javascript"><code>function myFunction (args, outerCallback) { + async.waterfall([ + //... + function (arg, next) { + if (someImportantCondition()) { + return outerCallback(null) + } + }, + function (arg, next) {/*...*/} + ], function done (err) { + //... + }) +}</code></pre><p>Something happened in a waterfall where you want to skip the rest of the execution, so you call an outer callack. However, Async will still wait for that inner <code>next</code> callback to be called, leaving some closure scope allocated.</p> +<p>As of version 3.0, you can call any Async callback with <code>false</code> as the <code>error</code> argument, and the rest of the execution of the Async method will be stopped or ignored.</p> +<pre class="prettyprint source lang-javascript"><code> function (arg, next) { + if (someImportantCondition()) { + outerCallback(null) + return next(false) // ← signal that you called an outer callback + } + },</code></pre><h3>Mutating collections</h3><p>If you pass an array to a collection method (such as <code>each</code>, <code>mapLimit</code>, or <code>filterSeries</code>), and then attempt to <code>push</code>, <code>pop</code>, or <code>splice</code> additional items on to the array, this could lead to unexpected or undefined behavior. Async will iterate until the original <code>length</code> of the array is met, and the indexes of items <code>pop()</code>ed or <code>splice()</code>d could already have been processed. Therefore, it is not recommended to modify the array after Async has begun iterating over it. If you do need to <code>push</code>, <code>pop</code>, or <code>splice</code>, use a <code>queue</code> instead.</p> +<h2>Download</h2><p>The source is available for download from +<a href="https://raw.githubusercontent.com/caolan/async/master/dist/async.min.js">GitHub</a>. +Alternatively, you can install using npm:</p> +<pre class="prettyprint source lang-bash"><code>$ npm install async</code></pre><p>As well as using Bower:</p> +<pre class="prettyprint source lang-bash"><code>$ bower install async</code></pre><p>You can then <code>require()</code> async as normal:</p> +<pre class="prettyprint source lang-js"><code>var async = require("async");</code></pre><p>Or require individual methods:</p> +<pre class="prettyprint source lang-js"><code>var waterfall = require("async/waterfall"); +var map = require("async/map");</code></pre><p><strong>Development:</strong> <a href="https://raw.githubusercontent.com/caolan/async/master/dist/async.js">async.js</a> - 29.6kb Uncompressed</p> +<h3>In the Browser</h3><p>Async should work in any ES2015 environment (Node 6+ and all modern browsers).</p> +<p>If you want to use Async in an older environment, (e.g. Node 4, IE11) you will have to transpile.</p> +<p>Usage:</p> +<pre class="prettyprint source lang-html"><code><script type="text/javascript" src="async.js"></script> +<script type="text/javascript"> + + async.map(data, asyncProcess, function(err, results) { + alert(results); + }); + +</script></code></pre><p>The portable versions of Async, including <code>async.js</code> and <code>async.min.js</code>, are +included in the <code>/dist</code> folder. Async can also be found on the <a href="http://www.jsdelivr.com/projects/async">jsDelivr CDN</a>.</p> +<h3>ES Modules</h3><p>Async includes a <code>.mjs</code> version that should automatically be used by compatible bundlers such as Webpack or Rollup, anything that uses the <code>module</code> field of the <code>package.json</code>.</p> +<p>We also provide Async as a collection of purely ES2015 modules, in an alternative <code>async-es</code> package on npm.</p> +<pre class="prettyprint source lang-bash"><code>$ npm install async-es</code></pre><pre class="prettyprint source lang-js"><code>import waterfall from 'async-es/waterfall'; +import async from 'async-es';</code></pre><h2>Other Libraries</h2><ul> +<li><a href="https://www.npmjs.com/package/limiter"><code>limiter</code></a> a package for rate-limiting based on requests per sec/hour.</li> +<li><a href="https://www.npmjs.com/package/neo-async"><code>neo-async</code></a> an altername implementation of Async, focusing on speed.</li> +<li><a href="https://www.npmjs.com/package/co-async"><code>co-async</code></a> a library inspired by Async for use with <a href="https://www.npmjs.com/package/co"><code>co</code></a> and generator functions.</li> +<li><a href="https://www.npmjs.com/package/promise-async"><code>promise-async</code></a> a version of Async where all the methods are Promisified.</li> +</ul></article> + </section> + + + + + + + <footer> + Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> using the Minami theme. +</footer></div> +</div> + +<nav id="toc"> + <h3>Methods:</h3><ul class="nav methods"><li class="toc-header"><a href="docs.html#collections">Collections</a></li><li data-type="method" class="toc-method"><a href="docs.html#concat">concat</a></li><li data-type="method" class="toc-method"><a href="docs.html#concatLimit">concatLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#concatSeries">concatSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#detect">detect</a></li><li data-type="method" class="toc-method"><a href="docs.html#detectLimit">detectLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#detectSeries">detectSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#each">each</a></li><li data-type="method" class="toc-method"><a href="docs.html#eachLimit">eachLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#eachOf">eachOf</a></li><li data-type="method" class="toc-method"><a href="docs.html#eachOfLimit">eachOfLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#eachOfSeries">eachOfSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#eachSeries">eachSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#every">every</a></li><li data-type="method" class="toc-method"><a href="docs.html#everyLimit">everyLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#everySeries">everySeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#filter">filter</a></li><li data-type="method" class="toc-method"><a href="docs.html#filterLimit">filterLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#filterSeries">filterSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#groupBy">groupBy</a></li><li data-type="method" class="toc-method"><a href="docs.html#groupByLimit">groupByLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#groupBySeries">groupBySeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#map">map</a></li><li data-type="method" class="toc-method"><a href="docs.html#mapLimit">mapLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#mapSeries">mapSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#mapValues">mapValues</a></li><li data-type="method" class="toc-method"><a href="docs.html#mapValuesLimit">mapValuesLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#mapValuesSeries">mapValuesSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#reduce">reduce</a></li><li data-type="method" class="toc-method"><a href="docs.html#reduceRight">reduceRight</a></li><li data-type="method" class="toc-method"><a href="docs.html#reject">reject</a></li><li data-type="method" class="toc-method"><a href="docs.html#rejectLimit">rejectLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#rejectSeries">rejectSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#some">some</a></li><li data-type="method" class="toc-method"><a href="docs.html#someLimit">someLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#someSeries">someSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#sortBy">sortBy</a></li><li data-type="method" class="toc-method"><a href="docs.html#transform">transform</a></li><li class="toc-header"><a href="docs.html#controlflow">Control Flow</a></li><li data-type="method" class="toc-method"><a href="docs.html#applyEach">applyEach</a></li><li data-type="method" class="toc-method"><a href="docs.html#applyEachSeries">applyEachSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#auto">auto</a></li><li data-type="method" class="toc-method"><a href="docs.html#autoInject">autoInject</a></li><li data-type="method" class="toc-method"><a href="docs.html#cargo">cargo</a></li><li data-type="method" class="toc-method"><a href="docs.html#cargoQueue">cargoQueue</a></li><li data-type="method" class="toc-method"><a href="docs.html#compose">compose</a></li><li data-type="method" class="toc-method"><a href="docs.html#doUntil">doUntil</a></li><li data-type="method" class="toc-method"><a href="docs.html#doWhilst">doWhilst</a></li><li data-type="method" class="toc-method"><a href="docs.html#forever">forever</a></li><li data-type="method" class="toc-method"><a href="docs.html#parallel">parallel</a></li><li data-type="method" class="toc-method"><a href="docs.html#parallelLimit">parallelLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#priorityQueue">priorityQueue</a></li><li data-type="method" class="toc-method"><a href="docs.html#queue">queue</a></li><li data-type="method" class="toc-method"><a href="docs.html#race">race</a></li><li data-type="method" class="toc-method"><a href="docs.html#retry">retry</a></li><li data-type="method" class="toc-method"><a href="docs.html#retryable">retryable</a></li><li data-type="method" class="toc-method"><a href="docs.html#seq">seq</a></li><li data-type="method" class="toc-method"><a href="docs.html#series">series</a></li><li data-type="method" class="toc-method"><a href="docs.html#times">times</a></li><li data-type="method" class="toc-method"><a href="docs.html#timesLimit">timesLimit</a></li><li data-type="method" class="toc-method"><a href="docs.html#timesSeries">timesSeries</a></li><li data-type="method" class="toc-method"><a href="docs.html#tryEach">tryEach</a></li><li data-type="method" class="toc-method"><a href="docs.html#until">until</a></li><li data-type="method" class="toc-method"><a href="docs.html#waterfall">waterfall</a></li><li data-type="method" class="toc-method"><a href="docs.html#whilst">whilst</a></li><li class="toc-header"><a href="docs.html#utils">Utils</a></li><li data-type="method" class="toc-method"><a href="docs.html#apply">apply</a></li><li data-type="method" class="toc-method"><a href="docs.html#asyncify">asyncify</a></li><li data-type="method" class="toc-method"><a href="docs.html#constant">constant</a></li><li data-type="method" class="toc-method"><a href="docs.html#dir">dir</a></li><li data-type="method" class="toc-method"><a href="docs.html#ensureAsync">ensureAsync</a></li><li data-type="method" class="toc-method"><a href="docs.html#log">log</a></li><li data-type="method" class="toc-method"><a href="docs.html#memoize">memoize</a></li><li data-type="method" class="toc-method"><a href="docs.html#nextTick">nextTick</a></li><li data-type="method" class="toc-method"><a href="docs.html#reflect">reflect</a></li><li data-type="method" class="toc-method"><a href="docs.html#reflectAll">reflectAll</a></li><li data-type="method" class="toc-method"><a href="docs.html#setImmediate">setImmediate</a></li><li data-type="method" class="toc-method"><a href="docs.html#timeout">timeout</a></li><li data-type="method" class="toc-method"><a href="docs.html#unmemoize">unmemoize</a></li></ul><h3>Methods:</h3> +</nav> + +<br class="clear"> + + + + +<script src="https://cdn.jsdelivr.net/prettify/0.1/prettify.js"></script> + +<script src="https://cdn.jsdelivr.net/jquery/2.2.4/jquery.min.js"></script> +<script src="https://cdn.jsdelivr.net/bootstrap/3.3.6/js/bootstrap.min.js"></script> +<script src="https://cdn.jsdelivr.net/typeahead.js/0.11.1/typeahead.bundle.min.js"></script> +<script>prettyPrint();</script> +<script src="scripts/async.js"></script> + +<script src="scripts/linenumber.js" async></script> +<script src="scripts/jsdoc-custom.js" async></script> +</body>
\ No newline at end of file |