diff options
Diffstat (limited to 'index.html')
| -rw-r--r-- | index.html | 289 |
1 files changed, 1 insertions, 288 deletions
@@ -1,288 +1 @@ -<!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="docs.html">v3.0.1</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> on Sun May 26 2019 14:43:28 GMT-0700 (Pacific Daylight Time) using the Minami theme. - Documentation has been modified from the original. For more information, please see the <a href="https://github.com/caolan/async">async</a> repository.</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 +<meta http-equiv="refresh" content="0; url=v3/" /> |