@contrast/agent 4.16.0 → 4.17.0

package/node_modules/async/dist/async.mjs

@@ -56,6 +56,7 @@ function initialParams (fn) {
 
 /* istanbul ignore file */
 
+var hasQueueMicrotask = typeof queueMicrotask === 'function' && queueMicrotask;
 var hasSetImmediate = typeof setImmediate === 'function' && setImmediate;
 var hasNextTick = typeof process === 'object' && typeof process.nextTick === 'function';
 
@@ -69,7 +70,9 @@ function wrap(defer) {
 
 var _defer;
 
-if (hasSetImmediate) {
+if (hasQueueMicrotask) {
+    _defer = queueMicrotask;
+} else if (hasSetImmediate) {
     _defer = setImmediate;
 } else if (hasNextTick) {
     _defer = process.nextTick;
@@ -294,6 +297,9 @@ function createObjectIterator(obj) {
     var len = okeys.length;
     return function next() {
         var key = okeys[++i];
+        if (key === '__proto__') {
+            return next();
+        }
         return i < len ? {value: obj[key], key} : null;
     };
 }
@@ -521,12 +527,19 @@ function eachOfGeneric (coll, iteratee, callback) {
  * @returns {Promise} a promise, if a callback is omitted
  * @example
  *
- * var obj = {dev: "/dev.json", test: "/test.json", prod: "/prod.json"};
- * var configs = {};
+ * // dev.json is a file containing a valid json object config for dev environment
+ * // dev.json is a file containing a valid json object config for test environment
+ * // prod.json is a file containing a valid json object config for prod environment
+ * // invalid.json is a file with a malformed json object
  *
- * async.forEachOf(obj, function (value, key, callback) {
- *     fs.readFile(__dirname + value, "utf8", function (err, data) {
- *         if (err) return callback(err);
+ * let configs = {}; //global variable
+ * let validConfigFileMap = {dev: 'dev.json', test: 'test.json', prod: 'prod.json'};
+ * let invalidConfigFileMap = {dev: 'dev.json', test: 'test.json', invalid: 'invalid.json'};
+ *
+ * // asynchronous function that reads a json file and parses the contents as json object
+ * function parseFile(file, key, callback) {
+ *     fs.readFile(file, "utf8", function(err, data) {
+ *         if (err) return calback(err);
  *         try {
  *             configs[key] = JSON.parse(data);
  *         } catch (e) {
@@ -534,11 +547,73 @@ function eachOfGeneric (coll, iteratee, callback) {
  *         }
  *         callback();
  *     });
- * }, function (err) {
- *     if (err) console.error(err.message);
- *     // configs is now a map of JSON data
- *     doSomethingWith(configs);
+ * }
+ *
+ * // Using callbacks
+ * async.forEachOf(validConfigFileMap, parseFile, function (err) {
+ *     if (err) {
+ *         console.error(err);
+ *     } else {
+ *         console.log(configs);
+ *         // configs is now a map of JSON data, e.g.
+ *         // { dev: //parsed dev.json, test: //parsed test.json, prod: //parsed prod.json}
+ *     }
  * });
+ *
+ * //Error handing
+ * async.forEachOf(invalidConfigFileMap, parseFile, function (err) {
+ *     if (err) {
+ *         console.error(err);
+ *         // JSON parse error exception
+ *     } else {
+ *         console.log(configs);
+ *     }
+ * });
+ *
+ * // Using Promises
+ * async.forEachOf(validConfigFileMap, parseFile)
+ * .then( () => {
+ *     console.log(configs);
+ *     // configs is now a map of JSON data, e.g.
+ *     // { dev: //parsed dev.json, test: //parsed test.json, prod: //parsed prod.json}
+ * }).catch( err => {
+ *     console.error(err);
+ * });
+ *
+ * //Error handing
+ * async.forEachOf(invalidConfigFileMap, parseFile)
+ * .then( () => {
+ *     console.log(configs);
+ * }).catch( err => {
+ *     console.error(err);
+ *     // JSON parse error exception
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let result = await async.forEachOf(validConfigFileMap, parseFile);
+ *         console.log(configs);
+ *         // configs is now a map of JSON data, e.g.
+ *         // { dev: //parsed dev.json, test: //parsed test.json, prod: //parsed prod.json}
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * //Error handing
+ * async () => {
+ *     try {
+ *         let result = await async.forEachOf(invalidConfigFileMap, parseFile);
+ *         console.log(configs);
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *         // JSON parse error exception
+ *     }
+ * }
+ *
  */
 function eachOf(coll, iteratee, callback) {
     var eachOfImplementation = isArrayLike(coll) ? eachOfArrayLike : eachOfGeneric;
@@ -550,7 +625,7 @@ var eachOf$1 = awaitify(eachOf, 3);
 /**
  * Produces a new collection of values by mapping each value in `coll` through
  * the `iteratee` function. The `iteratee` is called with an item from `coll`
- * and a callback for when it has finished processing. Each of these callback
+ * and a callback for when it has finished processing. Each of these callbacks
  * takes 2 arguments: an `error`, and the transformed item from `coll`. If
  * `iteratee` passes an error to its callback, the main `callback` (for the
  * `map` function) is immediately called with the error.
@@ -580,9 +655,89 @@ var eachOf$1 = awaitify(eachOf, 3);
  * @returns {Promise} a promise, if no callback is passed
  * @example
  *
- * async.map(['file1','file2','file3'], fs.stat, function(err, results) {
- *     // results is now an array of stats for each file
+ * // file1.txt is a file that is 1000 bytes in size
+ * // file2.txt is a file that is 2000 bytes in size
+ * // file3.txt is a file that is 3000 bytes in size
+ * // file4.txt does not exist
+ *
+ * const fileList = ['file1.txt','file2.txt','file3.txt'];
+ * const withMissingFileList = ['file1.txt','file2.txt','file4.txt'];
+ *
+ * // asynchronous function that returns the file size in bytes
+ * function getFileSizeInBytes(file, callback) {
+ *     fs.stat(file, function(err, stat) {
+ *         if (err) {
+ *             return callback(err);
+ *         }
+ *         callback(null, stat.size);
+ *     });
+ * }
+ *
+ * // Using callbacks
+ * async.map(fileList, getFileSizeInBytes, function(err, results) {
+ *     if (err) {
+ *         console.log(err);
+ *     } else {
+ *         console.log(results);
+ *         // results is now an array of the file size in bytes for each file, e.g.
+ *         // [ 1000, 2000, 3000]
+ *     }
+ * });
+ *
+ * // Error Handling
+ * async.map(withMissingFileList, getFileSizeInBytes, function(err, results) {
+ *     if (err) {
+ *         console.log(err);
+ *         // [ Error: ENOENT: no such file or directory ]
+ *     } else {
+ *         console.log(results);
+ *     }
+ * });
+ *
+ * // Using Promises
+ * async.map(fileList, getFileSizeInBytes)
+ * .then( results => {
+ *     console.log(results);
+ *     // results is now an array of the file size in bytes for each file, e.g.
+ *     // [ 1000, 2000, 3000]
+ * }).catch( err => {
+ *     console.log(err);
  * });
+ *
+ * // Error Handling
+ * async.map(withMissingFileList, getFileSizeInBytes)
+ * .then( results => {
+ *     console.log(results);
+ * }).catch( err => {
+ *     console.log(err);
+ *     // [ Error: ENOENT: no such file or directory ]
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let results = await async.map(fileList, getFileSizeInBytes);
+ *         console.log(results);
+ *         // results is now an array of the file size in bytes for each file, e.g.
+ *         // [ 1000, 2000, 3000]
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * // Error Handling
+ * async () => {
+ *     try {
+ *         let results = await async.map(withMissingFileList, getFileSizeInBytes);
+ *         console.log(results);
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *         // [ Error: ENOENT: no such file or directory ]
+ *     }
+ * }
+ *
  */
 function map (coll, iteratee, callback) {
     return _asyncMap(eachOf$1, coll, iteratee, callback)
@@ -756,15 +911,40 @@ function promiseCallback () {
  * @returns {Promise} a promise, if a callback is not passed
  * @example
  *
+ * //Using Callbacks
  * async.auto({
- *     // this function will just be passed a callback
- *     readData: async.apply(fs.readFile, 'data.txt', 'utf-8'),
- *     showData: ['readData', function(results, cb) {
- *         // results.readData is the file's contents
- *         // ...
+ *     get_data: function(callback) {
+ *         // async code to get some data
+ *         callback(null, 'data', 'converted to array');
+ *     },
+ *     make_folder: function(callback) {
+ *         // async code to create a directory to store a file in
+ *         // this is run at the same time as getting the data
+ *         callback(null, 'folder');
+ *     },
+ *     write_file: ['get_data', 'make_folder', function(results, callback) {
+ *         // once there is some data and the directory exists,
+ *         // write the data to a file in the directory
+ *         callback(null, 'filename');
+ *     }],
+ *     email_link: ['write_file', function(results, callback) {
+ *         // once the file is written let's email a link to it...
+ *         callback(null, {'file':results.write_file, 'email':'user@example.com'});
  *     }]
- * }, callback);
+ * }, function(err, results) {
+ *     if (err) {
+ *         console.log('err = ', err);
+ *     }
+ *     console.log('results = ', results);
+ *     // results = {
+ *     //     get_data: ['data', 'converted to array']
+ *     //     make_folder; 'folder',
+ *     //     write_file: 'filename'
+ *     //     email_link: { file: 'filename', email: 'user@example.com' }
+ *     // }
+ * });
  *
+ * //Using Promises
  * async.auto({
  *     get_data: function(callback) {
  *         console.log('in get_data');
@@ -778,21 +958,62 @@ function promiseCallback () {
  *         callback(null, 'folder');
  *     },
  *     write_file: ['get_data', 'make_folder', function(results, callback) {
- *         console.log('in write_file', JSON.stringify(results));
  *         // once there is some data and the directory exists,
  *         // write the data to a file in the directory
  *         callback(null, 'filename');
  *     }],
  *     email_link: ['write_file', function(results, callback) {
- *         console.log('in email_link', JSON.stringify(results));
  *         // once the file is written let's email a link to it...
- *         // results.write_file contains the filename returned by write_file.
  *         callback(null, {'file':results.write_file, 'email':'user@example.com'});
  *     }]
- * }, function(err, results) {
- *     console.log('err = ', err);
+ * }).then(results => {
  *     console.log('results = ', results);
+ *     // results = {
+ *     //     get_data: ['data', 'converted to array']
+ *     //     make_folder; 'folder',
+ *     //     write_file: 'filename'
+ *     //     email_link: { file: 'filename', email: 'user@example.com' }
+ *     // }
+ * }).catch(err => {
+ *     console.log('err = ', err);
  * });
+ *
+ * //Using async/await
+ * async () => {
+ *     try {
+ *         let results = await async.auto({
+ *             get_data: function(callback) {
+ *                 // async code to get some data
+ *                 callback(null, 'data', 'converted to array');
+ *             },
+ *             make_folder: function(callback) {
+ *                 // async code to create a directory to store a file in
+ *                 // this is run at the same time as getting the data
+ *                 callback(null, 'folder');
+ *             },
+ *             write_file: ['get_data', 'make_folder', function(results, callback) {
+ *                 // once there is some data and the directory exists,
+ *                 // write the data to a file in the directory
+ *                 callback(null, 'filename');
+ *             }],
+ *             email_link: ['write_file', function(results, callback) {
+ *                 // once the file is written let's email a link to it...
+ *                 callback(null, {'file':results.write_file, 'email':'user@example.com'});
+ *             }]
+ *         });
+ *         console.log('results = ', results);
+ *         // results = {
+ *         //     get_data: ['data', 'converted to array']
+ *         //     make_folder; 'folder',
+ *         //     write_file: 'filename'
+ *         //     email_link: { file: 'filename', email: 'user@example.com' }
+ *         // }
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function auto(tasks, concurrency, callback) {
     if (typeof concurrency !== 'number') {
@@ -970,10 +1191,36 @@ var FN_ARGS = /^(?:async\s+)?(?:function)?\s*\w*\s*\(\s*([^)]+)\s*\)(?:\s*{)/;
 var ARROW_FN_ARGS = /^(?:async\s+)?\(?\s*([^)=]+)\s*\)?(?:\s*=>)/;
 var FN_ARG_SPLIT = /,/;
 var FN_ARG = /(=.+)?(\s*)$/;
-var STRIP_COMMENTS = /((\/\/.*$)|(\/\*[\s\S]*?\*\/))/mg;
+
+function stripComments(string) {
+    let stripped = '';
+    let index = 0;
+    let endBlockComment = string.indexOf('*/');
+    while (index < string.length) {
+        if (string[index] === '/' && string[index+1] === '/') {
+            // inline comment
+            let endIndex = string.indexOf('\n', index);
+            index = (endIndex === -1) ? string.length : endIndex;
+        } else if ((endBlockComment !== -1) && (string[index] === '/') && (string[index+1] === '*')) {
+            // block comment
+            let endIndex = string.indexOf('*/', index);
+            if (endIndex !== -1) {
+                index = endIndex + 2;
+                endBlockComment = string.indexOf('*/', index);
+            } else {
+                stripped += string[index];
+                index++;
+            }
+        } else {
+            stripped += string[index];
+            index++;
+        }
+    }
+    return stripped;
+}
 
 function parseParams(func) {
-    const src = func.toString().replace(STRIP_COMMENTS, '');
+    const src = stripComments(func.toString());
     let match = src.match(FN_ARGS);
     if (!match) {
         match = src.match(ARROW_FN_ARGS);
@@ -1600,7 +1847,7 @@ function cargo$1(worker, concurrency, payload) {
  * @param {AsyncFunction} iteratee - A function applied to each item in the
  * array to produce the next step in the reduction.
  * The `iteratee` should complete with the next state of the reduction.
- * If the iteratee complete with an error, the reduction is stopped and the
+ * If the iteratee completes with an error, the reduction is stopped and the
  * main `callback` is immediately called with the error.
  * Invoked with (memo, item, callback).
  * @param {Function} [callback] - A callback which is called after all the
@@ -1609,14 +1856,90 @@ function cargo$1(worker, concurrency, payload) {
  * @returns {Promise} a promise, if no callback is passed
  * @example
  *
- * async.reduce([1,2,3], 0, function(memo, item, callback) {
- *     // pointless async:
- *     process.nextTick(function() {
- *         callback(null, memo + item)
+ * // file1.txt is a file that is 1000 bytes in size
+ * // file2.txt is a file that is 2000 bytes in size
+ * // file3.txt is a file that is 3000 bytes in size
+ * // file4.txt does not exist
+ *
+ * const fileList = ['file1.txt','file2.txt','file3.txt'];
+ * const withMissingFileList = ['file1.txt','file2.txt','file3.txt', 'file4.txt'];
+ *
+ * // asynchronous function that computes the file size in bytes
+ * // file size is added to the memoized value, then returned
+ * function getFileSizeInBytes(memo, file, callback) {
+ *     fs.stat(file, function(err, stat) {
+ *         if (err) {
+ *             return callback(err);
+ *         }
+ *         callback(null, memo + stat.size);
  *     });
- * }, function(err, result) {
- *     // result is now equal to the last value of memo, which is 6
+ * }
+ *
+ * // Using callbacks
+ * async.reduce(fileList, 0, getFileSizeInBytes, function(err, result) {
+ *     if (err) {
+ *         console.log(err);
+ *     } else {
+ *         console.log(result);
+ *         // 6000
+ *         // which is the sum of the file sizes of the three files
+ *     }
+ * });
+ *
+ * // Error Handling
+ * async.reduce(withMissingFileList, 0, getFileSizeInBytes, function(err, result) {
+ *     if (err) {
+ *         console.log(err);
+ *         // [ Error: ENOENT: no such file or directory ]
+ *     } else {
+ *         console.log(result);
+ *     }
+ * });
+ *
+ * // Using Promises
+ * async.reduce(fileList, 0, getFileSizeInBytes)
+ * .then( result => {
+ *     console.log(result);
+ *     // 6000
+ *     // which is the sum of the file sizes of the three files
+ * }).catch( err => {
+ *     console.log(err);
  * });
+ *
+ * // Error Handling
+ * async.reduce(withMissingFileList, 0, getFileSizeInBytes)
+ * .then( result => {
+ *     console.log(result);
+ * }).catch( err => {
+ *     console.log(err);
+ *     // [ Error: ENOENT: no such file or directory ]
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let result = await async.reduce(fileList, 0, getFileSizeInBytes);
+ *         console.log(result);
+ *         // 6000
+ *         // which is the sum of the file sizes of the three files
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * // Error Handling
+ * async () => {
+ *     try {
+ *         let result = await async.reduce(withMissingFileList, 0, getFileSizeInBytes);
+ *         console.log(result);
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *         // [ Error: ENOENT: no such file or directory ]
+ *     }
+ * }
+ *
  */
 function reduce(coll, memo, iteratee, callback) {
     callback = once(callback);
@@ -1654,7 +1977,7 @@ var reduce$1 = awaitify(reduce, 4);
  * app.get('/cats', function(request, response) {
  *     var User = request.models.User;
  *     async.seq(
- *         _.bind(User.get, User),  // 'User.get' has signature (id, callback(err, data))
+ *         User.get.bind(User),  // 'User.get' has signature (id, callback(err, data))
  *         function(user, fn) {
  *             user.getCats(fn);      // 'getCats' has signature (callback(err, data))
  *         }
@@ -1820,9 +2143,77 @@ var concatLimit$1 = awaitify(concatLimit, 4);
  * @returns A Promise, if no callback is passed
  * @example
  *
- * async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files) {
- *     // files is now a list of filenames that exist in the 3 directories
+ * // dir1 is a directory that contains file1.txt, file2.txt
+ * // dir2 is a directory that contains file3.txt, file4.txt
+ * // dir3 is a directory that contains file5.txt
+ * // dir4 does not exist
+ *
+ * let directoryList = ['dir1','dir2','dir3'];
+ * let withMissingDirectoryList = ['dir1','dir2','dir3', 'dir4'];
+ *
+ * // Using callbacks
+ * async.concat(directoryList, fs.readdir, function(err, results) {
+ *    if (err) {
+ *        console.log(err);
+ *    } else {
+ *        console.log(results);
+ *        // [ 'file1.txt', 'file2.txt', 'file3.txt', 'file4.txt', file5.txt ]
+ *    }
+ * });
+ *
+ * // Error Handling
+ * async.concat(withMissingDirectoryList, fs.readdir, function(err, results) {
+ *    if (err) {
+ *        console.log(err);
+ *        // [ Error: ENOENT: no such file or directory ]
+ *        // since dir4 does not exist
+ *    } else {
+ *        console.log(results);
+ *    }
+ * });
+ *
+ * // Using Promises
+ * async.concat(directoryList, fs.readdir)
+ * .then(results => {
+ *     console.log(results);
+ *     // [ 'file1.txt', 'file2.txt', 'file3.txt', 'file4.txt', file5.txt ]
+ * }).catch(err => {
+ *      console.log(err);
+ * });
+ *
+ * // Error Handling
+ * async.concat(withMissingDirectoryList, fs.readdir)
+ * .then(results => {
+ *     console.log(results);
+ * }).catch(err => {
+ *     console.log(err);
+ *     // [ Error: ENOENT: no such file or directory ]
+ *     // since dir4 does not exist
  * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let results = await async.concat(directoryList, fs.readdir);
+ *         console.log(results);
+ *         // [ 'file1.txt', 'file2.txt', 'file3.txt', 'file4.txt', file5.txt ]
+ *     } catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * // Error Handling
+ * async () => {
+ *     try {
+ *         let results = await async.concat(withMissingDirectoryList, fs.readdir);
+ *         console.log(results);
+ *     } catch (err) {
+ *         console.log(err);
+ *         // [ Error: ENOENT: no such file or directory ]
+ *         // since dir4 does not exist
+ *     }
+ * }
+ *
  */
 function concat(coll, iteratee, callback) {
     return concatLimit$1(coll, Infinity, iteratee, callback)
@@ -1954,13 +2345,48 @@ function _createTester(check, getResult) {
  * @returns A Promise, if no callback is passed
  * @example
  *
- * async.detect(['file1','file2','file3'], function(filePath, callback) {
- *     fs.access(filePath, function(err) {
- *         callback(null, !err)
- *     });
- * }, function(err, result) {
+ * // dir1 is a directory that contains file1.txt, file2.txt
+ * // dir2 is a directory that contains file3.txt, file4.txt
+ * // dir3 is a directory that contains file5.txt
+ *
+ * // asynchronous function that checks if a file exists
+ * function fileExists(file, callback) {
+ *    fs.access(file, fs.constants.F_OK, (err) => {
+ *        callback(null, !err);
+ *    });
+ * }
+ *
+ * async.detect(['file3.txt','file2.txt','dir1/file1.txt'], fileExists,
+ *    function(err, result) {
+ *        console.log(result);
+ *        // dir1/file1.txt
+ *        // result now equals the first file in the list that exists
+ *    }
+ *);
+ *
+ * // Using Promises
+ * async.detect(['file3.txt','file2.txt','dir1/file1.txt'], fileExists)
+ * .then(result => {
+ *     console.log(result);
+ *     // dir1/file1.txt
  *     // result now equals the first file in the list that exists
+ * }).catch(err => {
+ *     console.log(err);
  * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let result = await async.detect(['file3.txt','file2.txt','dir1/file1.txt'], fileExists);
+ *         console.log(result);
+ *         // dir1/file1.txt
+ *         // result now equals the file in the list that exists
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function detect(coll, iteratee, callback) {
     return _createTester(bool => bool, (res, item) => item)(eachOf$1, coll, iteratee, callback)
@@ -2024,12 +2450,15 @@ var detectSeries$1 = awaitify(detectSeries, 3);
 
 function consoleFunc(name) {
     return (fn, ...args) => wrapAsync(fn)(...args, (err, ...resultArgs) => {
+        /* istanbul ignore else */
         if (typeof console === 'object') {
+            /* istanbul ignore else */
             if (err) {
+                /* istanbul ignore else */
                 if (console.error) {
                     console.error(err);
                 }
-            } else if (console[name]) {
+            } else if (console[name]) { /* istanbul ignore else */
                 resultArgs.forEach(x => console[name](x));
             }
         }
@@ -2174,37 +2603,78 @@ function _withoutIndex(iteratee) {
  * @returns {Promise} a promise, if a callback is omitted
  * @example
  *
- * // assuming openFiles is an array of file names and saveFile is a function
- * // to save the modified contents of that file:
- *
- * async.each(openFiles, saveFile, function(err){
- *   // if any of the saves produced an error, err would equal that error
- * });
+ * // dir1 is a directory that contains file1.txt, file2.txt
+ * // dir2 is a directory that contains file3.txt, file4.txt
+ * // dir3 is a directory that contains file5.txt
+ * // dir4 does not exist
  *
- * // assuming openFiles is an array of file names
- * async.each(openFiles, function(file, callback) {
+ * const fileList = [ 'dir1/file2.txt', 'dir2/file3.txt', 'dir/file5.txt'];
+ * const withMissingFileList = ['dir1/file1.txt', 'dir4/file2.txt'];
  *
- *     // Perform operation on file here.
- *     console.log('Processing file ' + file);
+ * // asynchronous function that deletes a file
+ * const deleteFile = function(file, callback) {
+ *     fs.unlink(file, callback);
+ * };
  *
- *     if( file.length > 32 ) {
- *       console.log('This file name is too long');
- *       callback('File name too long');
- *     } else {
- *       // Do work to process file here
- *       console.log('File processed');
- *       callback();
- *     }
- * }, function(err) {
- *     // if any of the file processing produced an error, err would equal that error
+ * // Using callbacks
+ * async.each(fileList, deleteFile, function(err) {
  *     if( err ) {
- *       // One of the iterations produced an error.
- *       // All processing will now stop.
- *       console.log('A file failed to process');
+ *         console.log(err);
  *     } else {
- *       console.log('All files have been processed successfully');
+ *         console.log('All files have been deleted successfully');
  *     }
  * });
+ *
+ * // Error Handling
+ * async.each(withMissingFileList, deleteFile, function(err){
+ *     console.log(err);
+ *     // [ Error: ENOENT: no such file or directory ]
+ *     // since dir4/file2.txt does not exist
+ *     // dir1/file1.txt could have been deleted
+ * });
+ *
+ * // Using Promises
+ * async.each(fileList, deleteFile)
+ * .then( () => {
+ *     console.log('All files have been deleted successfully');
+ * }).catch( err => {
+ *     console.log(err);
+ * });
+ *
+ * // Error Handling
+ * async.each(fileList, deleteFile)
+ * .then( () => {
+ *     console.log('All files have been deleted successfully');
+ * }).catch( err => {
+ *     console.log(err);
+ *     // [ Error: ENOENT: no such file or directory ]
+ *     // since dir4/file2.txt does not exist
+ *     // dir1/file1.txt could have been deleted
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         await async.each(files, deleteFile);
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * // Error Handling
+ * async () => {
+ *     try {
+ *         await async.each(withMissingFileList, deleteFile);
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *         // [ Error: ENOENT: no such file or directory ]
+ *         // since dir4/file2.txt does not exist
+ *         // dir1/file1.txt could have been deleted
+ *     }
+ * }
+ *
  */
 function eachLimit(coll, iteratee, callback) {
     return eachOf$1(coll, _withoutIndex(wrapAsync(iteratee)), callback);
@@ -2339,13 +2809,78 @@ function ensureAsync(fn) {
  * @returns {Promise} a promise, if no callback provided
  * @example
  *
- * async.every(['file1','file2','file3'], function(filePath, callback) {
- *     fs.access(filePath, function(err) {
- *         callback(null, !err)
- *     });
- * }, function(err, result) {
- *     // if result is true then every file exists
+ * // dir1 is a directory that contains file1.txt, file2.txt
+ * // dir2 is a directory that contains file3.txt, file4.txt
+ * // dir3 is a directory that contains file5.txt
+ * // dir4 does not exist
+ *
+ * const fileList = ['dir1/file1.txt','dir2/file3.txt','dir3/file5.txt'];
+ * const withMissingFileList = ['file1.txt','file2.txt','file4.txt'];
+ *
+ * // asynchronous function that checks if a file exists
+ * function fileExists(file, callback) {
+ *    fs.access(file, fs.constants.F_OK, (err) => {
+ *        callback(null, !err);
+ *    });
+ * }
+ *
+ * // Using callbacks
+ * async.every(fileList, fileExists, function(err, result) {
+ *     console.log(result);
+ *     // true
+ *     // result is true since every file exists
+ * });
+ *
+ * async.every(withMissingFileList, fileExists, function(err, result) {
+ *     console.log(result);
+ *     // false
+ *     // result is false since NOT every file exists
  * });
+ *
+ * // Using Promises
+ * async.every(fileList, fileExists)
+ * .then( result => {
+ *     console.log(result);
+ *     // true
+ *     // result is true since every file exists
+ * }).catch( err => {
+ *     console.log(err);
+ * });
+ *
+ * async.every(withMissingFileList, fileExists)
+ * .then( result => {
+ *     console.log(result);
+ *     // false
+ *     // result is false since NOT every file exists
+ * }).catch( err => {
+ *     console.log(err);
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let result = await async.every(fileList, fileExists);
+ *         console.log(result);
+ *         // true
+ *         // result is true since every file exists
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * async () => {
+ *     try {
+ *         let result = await async.every(withMissingFileList, fileExists);
+ *         console.log(result);
+ *         // false
+ *         // result is false since NOT every file exists
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function every(coll, iteratee, callback) {
     return _createTester(bool => !bool, res => !res)(eachOf$1, coll, iteratee, callback)
@@ -2463,13 +2998,53 @@ function _filter(eachfn, coll, iteratee, callback) {
  * @returns {Promise} a promise, if no callback provided
  * @example
  *
- * 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
+ * // dir1 is a directory that contains file1.txt, file2.txt
+ * // dir2 is a directory that contains file3.txt, file4.txt
+ * // dir3 is a directory that contains file5.txt
+ *
+ * const files = ['dir1/file1.txt','dir2/file3.txt','dir3/file6.txt'];
+ *
+ * // asynchronous function that checks if a file exists
+ * function fileExists(file, callback) {
+ *    fs.access(file, fs.constants.F_OK, (err) => {
+ *        callback(null, !err);
+ *    });
+ * }
+ *
+ * // Using callbacks
+ * async.filter(files, fileExists, function(err, results) {
+ *    if(err) {
+ *        console.log(err);
+ *    } else {
+ *        console.log(results);
+ *        // [ 'dir1/file1.txt', 'dir2/file3.txt' ]
+ *        // results is now an array of the existing files
+ *    }
+ * });
+ *
+ * // Using Promises
+ * async.filter(files, fileExists)
+ * .then(results => {
+ *     console.log(results);
+ *     // [ 'dir1/file1.txt', 'dir2/file3.txt' ]
+ *     // results is now an array of the existing files
+ * }).catch(err => {
+ *     console.log(err);
  * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let results = await async.filter(files, fileExists);
+ *         console.log(results);
+ *         // [ 'dir1/file1.txt', 'dir2/file3.txt' ]
+ *         // results is now an array of the existing files
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function filter (coll, iteratee, callback) {
     return _filter(eachOf$1, coll, iteratee, callback)
@@ -2646,15 +3221,69 @@ var groupByLimit$1 = awaitify(groupByLimit, 4);
  * @returns {Promise} a promise, if no callback is passed
  * @example
  *
- * async.groupBy(['userId1', 'userId2', 'userId3'], function(userId, callback) {
- *     db.findById(userId, function(err, user) {
- *         if (err) return callback(err);
- *         return callback(null, user.age);
+ * // dir1 is a directory that contains file1.txt, file2.txt
+ * // dir2 is a directory that contains file3.txt, file4.txt
+ * // dir3 is a directory that contains file5.txt
+ * // dir4 does not exist
+ *
+ * const files = ['dir1/file1.txt','dir2','dir4']
+ *
+ * // asynchronous function that detects file type as none, file, or directory
+ * function detectFile(file, callback) {
+ *     fs.stat(file, function(err, stat) {
+ *         if (err) {
+ *             return callback(null, 'none');
+ *         }
+ *         callback(null, stat.isDirectory() ? 'directory' : 'file');
  *     });
- * }, function(err, result) {
- *     // result is object containing the userIds grouped by age
- *     // e.g. { 30: ['userId1', 'userId3'], 42: ['userId2']};
+ * }
+ *
+ * //Using callbacks
+ * async.groupBy(files, detectFile, function(err, result) {
+ *     if(err) {
+ *         console.log(err);
+ *     } else {
+ *	       console.log(result);
+ *         // {
+ *         //     file: [ 'dir1/file1.txt' ],
+ *         //     none: [ 'dir4' ],
+ *         //     directory: [ 'dir2']
+ *         // }
+ *         // result is object containing the files grouped by type
+ *     }
  * });
+ *
+ * // Using Promises
+ * async.groupBy(files, detectFile)
+ * .then( result => {
+ *     console.log(result);
+ *     // {
+ *     //     file: [ 'dir1/file1.txt' ],
+ *     //     none: [ 'dir4' ],
+ *     //     directory: [ 'dir2']
+ *     // }
+ *     // result is object containing the files grouped by type
+ * }).catch( err => {
+ *     console.log(err);
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let result = await async.groupBy(files, detectFile);
+ *         console.log(result);
+ *         // {
+ *         //     file: [ 'dir1/file1.txt' ],
+ *         //     none: [ 'dir4' ],
+ *         //     directory: [ 'dir2']
+ *         // }
+ *         // result is object containing the files grouped by type
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function groupBy (coll, iteratee, callback) {
     return groupByLimit$1(coll, Infinity, iteratee, callback)
@@ -2675,7 +3304,7 @@ function groupBy (coll, iteratee, callback) {
  * The iteratee should complete with a `key` to group the value under.
  * Invoked with (value, callback).
  * @param {Function} [callback] - A callback which is called when all `iteratee`
- * functions have finished, or an error occurs. Result is an `Object` whoses
+ * functions have finished, or an error occurs. Result is an `Object` whose
  * properties are arrays of values which returned the corresponding key.
  * @returns {Promise} a promise, if no callback is passed
  */
@@ -2779,20 +3408,110 @@ var mapValuesLimit$1 = awaitify(mapValuesLimit, 4);
  * @returns {Promise} a promise, if no callback is passed
  * @example
  *
- * async.mapValues({
- *     f1: 'file1',
- *     f2: 'file2',
- *     f3: 'file3'
- * }, function (file, key, callback) {
- *   fs.stat(file, callback);
- * }, function(err, result) {
- *     // result is now a map of stats for each file, e.g.
+ * // file1.txt is a file that is 1000 bytes in size
+ * // file2.txt is a file that is 2000 bytes in size
+ * // file3.txt is a file that is 3000 bytes in size
+ * // file4.txt does not exist
+ *
+ * const fileMap = {
+ *     f1: 'file1.txt',
+ *     f2: 'file2.txt',
+ *     f3: 'file3.txt'
+ * };
+ *
+ * const withMissingFileMap = {
+ *     f1: 'file1.txt',
+ *     f2: 'file2.txt',
+ *     f3: 'file4.txt'
+ * };
+ *
+ * // asynchronous function that returns the file size in bytes
+ * function getFileSizeInBytes(file, key, callback) {
+ *     fs.stat(file, function(err, stat) {
+ *         if (err) {
+ *             return callback(err);
+ *         }
+ *         callback(null, stat.size);
+ *     });
+ * }
+ *
+ * // Using callbacks
+ * async.mapValues(fileMap, getFileSizeInBytes, function(err, result) {
+ *     if (err) {
+ *         console.log(err);
+ *     } else {
+ *         console.log(result);
+ *         // result is now a map of file size in bytes for each file, e.g.
+ *         // {
+ *         //     f1: 1000,
+ *         //     f2: 2000,
+ *         //     f3: 3000
+ *         // }
+ *     }
+ * });
+ *
+ * // Error handling
+ * async.mapValues(withMissingFileMap, getFileSizeInBytes, function(err, result) {
+ *     if (err) {
+ *         console.log(err);
+ *         // [ Error: ENOENT: no such file or directory ]
+ *     } else {
+ *         console.log(result);
+ *     }
+ * });
+ *
+ * // Using Promises
+ * async.mapValues(fileMap, getFileSizeInBytes)
+ * .then( result => {
+ *     console.log(result);
+ *     // result is now a map of file size in bytes for each file, e.g.
  *     // {
- *     //     f1: [stats for file1],
- *     //     f2: [stats for file2],
- *     //     f3: [stats for file3]
+ *     //     f1: 1000,
+ *     //     f2: 2000,
+ *     //     f3: 3000
  *     // }
+ * }).catch (err => {
+ *     console.log(err);
  * });
+ *
+ * // Error Handling
+ * async.mapValues(withMissingFileMap, getFileSizeInBytes)
+ * .then( result => {
+ *     console.log(result);
+ * }).catch (err => {
+ *     console.log(err);
+ *     // [ Error: ENOENT: no such file or directory ]
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let result = await async.mapValues(fileMap, getFileSizeInBytes);
+ *         console.log(result);
+ *         // result is now a map of file size in bytes for each file, e.g.
+ *         // {
+ *         //     f1: 1000,
+ *         //     f2: 2000,
+ *         //     f3: 3000
+ *         // }
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * // Error Handling
+ * async () => {
+ *     try {
+ *         let result = await async.mapValues(withMissingFileMap, getFileSizeInBytes);
+ *         console.log(result);
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *         // [ Error: ENOENT: no such file or directory ]
+ *     }
+ * }
+ *
  */
 function mapValues(obj, iteratee, callback) {
     return mapValuesLimit$1(obj, Infinity, iteratee, callback)
@@ -2892,6 +3611,8 @@ function memoize(fn, hasher = v => v) {
     return memoized;
 }
 
+/* istanbul ignore file */
+
 /**
  * Calls `callback` on a later loop around the event loop. In Node.js this just
  * calls `process.nextTick`.  In the browser it will use `setImmediate` if
@@ -2985,6 +3706,8 @@ var _parallel = awaitify((eachfn, tasks, callback) => {
  * @returns {Promise} a promise, if a callback is not passed
  *
  * @example
+ *
+ * //Using Callbacks
  * async.parallel([
  *     function(callback) {
  *         setTimeout(function() {
@@ -2996,10 +3719,9 @@ var _parallel = awaitify((eachfn, tasks, callback) => {
  *             callback(null, 'two');
  *         }, 100);
  *     }
- * ],
- * // optional callback
- * function(err, results) {
- *     // the results array will equal ['one','two'] even though
+ * ], function(err, results) {
+ *     console.log(results);
+ *     // results is equal to ['one','two'] even though
  *     // the second function had a shorter timeout.
  * });
  *
@@ -3016,8 +3738,96 @@ var _parallel = awaitify((eachfn, tasks, callback) => {
  *         }, 100);
  *     }
  * }, function(err, results) {
- *     // results is now equals to: {one: 1, two: 2}
+ *     console.log(results);
+ *     // results is equal to: { one: 1, two: 2 }
  * });
+ *
+ * //Using Promises
+ * async.parallel([
+ *     function(callback) {
+ *         setTimeout(function() {
+ *             callback(null, 'one');
+ *         }, 200);
+ *     },
+ *     function(callback) {
+ *         setTimeout(function() {
+ *             callback(null, 'two');
+ *         }, 100);
+ *     }
+ * ]).then(results => {
+ *     console.log(results);
+ *     // results is equal to ['one','two'] even though
+ *     // the second function had a shorter timeout.
+ * }).catch(err => {
+ *     console.log(err);
+ * });
+ *
+ * // an example using an object instead of an array
+ * async.parallel({
+ *     one: function(callback) {
+ *         setTimeout(function() {
+ *             callback(null, 1);
+ *         }, 200);
+ *     },
+ *     two: function(callback) {
+ *         setTimeout(function() {
+ *             callback(null, 2);
+ *         }, 100);
+ *     }
+ * }).then(results => {
+ *     console.log(results);
+ *     // results is equal to: { one: 1, two: 2 }
+ * }).catch(err => {
+ *     console.log(err);
+ * });
+ *
+ * //Using async/await
+ * async () => {
+ *     try {
+ *         let results = await async.parallel([
+ *             function(callback) {
+ *                 setTimeout(function() {
+ *                     callback(null, 'one');
+ *                 }, 200);
+ *             },
+ *             function(callback) {
+ *                 setTimeout(function() {
+ *                     callback(null, 'two');
+ *                 }, 100);
+ *             }
+ *         ]);
+ *         console.log(results);
+ *         // results is equal to ['one','two'] even though
+ *         // the second function had a shorter timeout.
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * // an example using an object instead of an array
+ * async () => {
+ *     try {
+ *         let results = await async.parallel({
+ *             one: function(callback) {
+ *                 setTimeout(function() {
+ *                     callback(null, 1);
+ *                 }, 200);
+ *             },
+ *            two: function(callback) {
+ *                 setTimeout(function() {
+ *                     callback(null, 2);
+ *                 }, 100);
+ *            }
+ *         });
+ *         console.log(results);
+ *         // results is equal to: { one: 1, two: 2 }
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function parallel(tasks, callback) {
     return _parallel(eachOf$1, tasks, callback);
@@ -3075,7 +3885,7 @@ function parallelLimit(tasks, limit, callback) {
  * Invoke with `queue.unshift(task, [callback])`.
  * @property {AsyncFunction} pushAsync - the same as `q.push`, except this returns
  * a promise that rejects if an error occurs.
- * @property {AsyncFunction} unshirtAsync - the same as `q.unshift`, except this returns
+ * @property {AsyncFunction} unshiftAsync - the same as `q.unshift`, except this returns
  * a promise that rejects if an error occurs.
  * @property {Function} remove - remove items from the queue that match a test
  * function.  The test function will be passed an object with a `data` property,
@@ -3114,7 +3924,7 @@ function parallelLimit(tasks, limit, callback) {
  * should be pushed to the queue after calling this function. Invoke with `queue.kill()`.
  *
  * @example
- * const q = aync.queue(worker, 2)
+ * const q = async.queue(worker, 2)
  * q.push(item1)
  * q.push(item2)
  * q.push(item3)
@@ -3337,6 +4147,7 @@ function smaller(x, y) {
 function priorityQueue(worker, concurrency) {
     // Start with a normal queue
     var q = queue$1(worker, concurrency);
+    var processingScheduled = false;
 
     q._tasks = new Heap();
 
@@ -3364,7 +4175,13 @@ function priorityQueue(worker, concurrency) {
             q._tasks.push(item);
         }
 
-        setImmediate$1(q.process);
+        if (!processingScheduled) {
+            processingScheduled = true;
+            setImmediate$1(() => {
+                processingScheduled = false;
+                q.process();
+            });
+        }
     };
 
     // Remove unshift function
@@ -3435,7 +4252,7 @@ var race$1 = awaitify(race, 2);
  * @param {AsyncFunction} iteratee - A function applied to each item in the
  * array to produce the next step in the reduction.
  * The `iteratee` should complete with the next state of the reduction.
- * If the iteratee complete with an error, the reduction is stopped and the
+ * If the iteratee completes with an error, the reduction is stopped and the
  * main `callback` is immediately called with the error.
  * Invoked with (memo, item, callback).
  * @param {Function} [callback] - A callback which is called after all the
@@ -3617,14 +4434,48 @@ function reject(eachfn, arr, _iteratee, callback) {
  * @returns {Promise} a promise, if no callback is passed
  * @example
  *
- * async.reject(['file1','file2','file3'], function(filePath, callback) {
- *     fs.access(filePath, function(err) {
- *         callback(null, !err)
- *     });
- * }, function(err, results) {
- *     // results now equals an array of missing files
- *     createFiles(results);
+ * // dir1 is a directory that contains file1.txt, file2.txt
+ * // dir2 is a directory that contains file3.txt, file4.txt
+ * // dir3 is a directory that contains file5.txt
+ *
+ * const fileList = ['dir1/file1.txt','dir2/file3.txt','dir3/file6.txt'];
+ *
+ * // asynchronous function that checks if a file exists
+ * function fileExists(file, callback) {
+ *    fs.access(file, fs.constants.F_OK, (err) => {
+ *        callback(null, !err);
+ *    });
+ * }
+ *
+ * // Using callbacks
+ * async.reject(fileList, fileExists, function(err, results) {
+ *    // [ 'dir3/file6.txt' ]
+ *    // results now equals an array of the non-existing files
  * });
+ *
+ * // Using Promises
+ * async.reject(fileList, fileExists)
+ * .then( results => {
+ *     console.log(results);
+ *     // [ 'dir3/file6.txt' ]
+ *     // results now equals an array of the non-existing files
+ * }).catch( err => {
+ *     console.log(err);
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let results = await async.reject(fileList, fileExists);
+ *         console.log(results);
+ *         // [ 'dir3/file6.txt' ]
+ *         // results now equals an array of the non-existing files
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function reject$1 (coll, iteratee, callback) {
     return reject(eachOf$1, coll, iteratee, callback)
@@ -3917,35 +4768,135 @@ function retryable (opts, task) {
  * with (err, result).
  * @return {Promise} a promise, if no callback is passed
  * @example
+ *
+ * //Using Callbacks
  * async.series([
  *     function(callback) {
- *         // do some stuff ...
- *         callback(null, 'one');
+ *         setTimeout(function() {
+ *             // do some async task
+ *             callback(null, 'one');
+ *         }, 200);
  *     },
  *     function(callback) {
- *         // do some more stuff ...
- *         callback(null, 'two');
+ *         setTimeout(function() {
+ *             // then do another async task
+ *             callback(null, 'two');
+ *         }, 100);
  *     }
- * ],
- * // optional callback
- * function(err, results) {
- *     // results is now equal to ['one', 'two']
+ * ], function(err, results) {
+ *     console.log(results);
+ *     // results is equal to ['one','two']
  * });
  *
+ * // an example using objects instead of arrays
  * async.series({
  *     one: function(callback) {
  *         setTimeout(function() {
+ *             // do some async task
  *             callback(null, 1);
  *         }, 200);
  *     },
- *     two: function(callback){
+ *     two: function(callback) {
  *         setTimeout(function() {
+ *             // then do another async task
  *             callback(null, 2);
  *         }, 100);
  *     }
  * }, function(err, results) {
- *     // results is now equal to: {one: 1, two: 2}
+ *     console.log(results);
+ *     // results is equal to: { one: 1, two: 2 }
+ * });
+ *
+ * //Using Promises
+ * async.series([
+ *     function(callback) {
+ *         setTimeout(function() {
+ *             callback(null, 'one');
+ *         }, 200);
+ *     },
+ *     function(callback) {
+ *         setTimeout(function() {
+ *             callback(null, 'two');
+ *         }, 100);
+ *     }
+ * ]).then(results => {
+ *     console.log(results);
+ *     // results is equal to ['one','two']
+ * }).catch(err => {
+ *     console.log(err);
  * });
+ *
+ * // an example using an object instead of an array
+ * async.series({
+ *     one: function(callback) {
+ *         setTimeout(function() {
+ *             // do some async task
+ *             callback(null, 1);
+ *         }, 200);
+ *     },
+ *     two: function(callback) {
+ *         setTimeout(function() {
+ *             // then do another async task
+ *             callback(null, 2);
+ *         }, 100);
+ *     }
+ * }).then(results => {
+ *     console.log(results);
+ *     // results is equal to: { one: 1, two: 2 }
+ * }).catch(err => {
+ *     console.log(err);
+ * });
+ *
+ * //Using async/await
+ * async () => {
+ *     try {
+ *         let results = await async.series([
+ *             function(callback) {
+ *                 setTimeout(function() {
+ *                     // do some async task
+ *                     callback(null, 'one');
+ *                 }, 200);
+ *             },
+ *             function(callback) {
+ *                 setTimeout(function() {
+ *                     // then do another async task
+ *                     callback(null, 'two');
+ *                 }, 100);
+ *             }
+ *         ]);
+ *         console.log(results);
+ *         // results is equal to ['one','two']
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * // an example using an object instead of an array
+ * async () => {
+ *     try {
+ *         let results = await async.parallel({
+ *             one: function(callback) {
+ *                 setTimeout(function() {
+ *                     // do some async task
+ *                     callback(null, 1);
+ *                 }, 200);
+ *             },
+ *            two: function(callback) {
+ *                 setTimeout(function() {
+ *                     // then do another async task
+ *                     callback(null, 2);
+ *                 }, 100);
+ *            }
+ *         });
+ *         console.log(results);
+ *         // results is equal to: { one: 1, two: 2 }
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function series(tasks, callback) {
     return _parallel(eachOfSeries$1, tasks, callback);
@@ -3974,13 +4925,79 @@ function series(tasks, callback) {
  * @returns {Promise} a promise, if no callback provided
  * @example
  *
- * async.some(['file1','file2','file3'], function(filePath, callback) {
- *     fs.access(filePath, function(err) {
- *         callback(null, !err)
- *     });
- * }, function(err, result) {
- *     // if result is true then at least one of the files exists
+ * // dir1 is a directory that contains file1.txt, file2.txt
+ * // dir2 is a directory that contains file3.txt, file4.txt
+ * // dir3 is a directory that contains file5.txt
+ * // dir4 does not exist
+ *
+ * // asynchronous function that checks if a file exists
+ * function fileExists(file, callback) {
+ *    fs.access(file, fs.constants.F_OK, (err) => {
+ *        callback(null, !err);
+ *    });
+ * }
+ *
+ * // Using callbacks
+ * async.some(['dir1/missing.txt','dir2/missing.txt','dir3/file5.txt'], fileExists,
+ *    function(err, result) {
+ *        console.log(result);
+ *        // true
+ *        // result is true since some file in the list exists
+ *    }
+ *);
+ *
+ * async.some(['dir1/missing.txt','dir2/missing.txt','dir4/missing.txt'], fileExists,
+ *    function(err, result) {
+ *        console.log(result);
+ *        // false
+ *        // result is false since none of the files exists
+ *    }
+ *);
+ *
+ * // Using Promises
+ * async.some(['dir1/missing.txt','dir2/missing.txt','dir3/file5.txt'], fileExists)
+ * .then( result => {
+ *     console.log(result);
+ *     // true
+ *     // result is true since some file in the list exists
+ * }).catch( err => {
+ *     console.log(err);
  * });
+ *
+ * async.some(['dir1/missing.txt','dir2/missing.txt','dir4/missing.txt'], fileExists)
+ * .then( result => {
+ *     console.log(result);
+ *     // false
+ *     // result is false since none of the files exists
+ * }).catch( err => {
+ *     console.log(err);
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let result = await async.some(['dir1/missing.txt','dir2/missing.txt','dir3/file5.txt'], fileExists);
+ *         console.log(result);
+ *         // true
+ *         // result is true since some file in the list exists
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
+ * async () => {
+ *     try {
+ *         let result = await async.some(['dir1/missing.txt','dir2/missing.txt','dir4/missing.txt'], fileExists);
+ *         console.log(result);
+ *         // false
+ *         // result is false since none of the files exists
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function some(coll, iteratee, callback) {
     return _createTester(Boolean, res => res)(eachOf$1, coll, iteratee, callback)
@@ -4062,31 +5079,133 @@ var someSeries$1 = awaitify(someSeries, 3);
  * @returns {Promise} a promise, if no callback passed
  * @example
  *
- * async.sortBy(['file1','file2','file3'], function(file, callback) {
- *     fs.stat(file, function(err, stats) {
- *         callback(err, stats.mtime);
+ * // bigfile.txt is a file that is 251100 bytes in size
+ * // mediumfile.txt is a file that is 11000 bytes in size
+ * // smallfile.txt is a file that is 121 bytes in size
+ *
+ * // asynchronous function that returns the file size in bytes
+ * function getFileSizeInBytes(file, callback) {
+ *     fs.stat(file, function(err, stat) {
+ *         if (err) {
+ *             return callback(err);
+ *         }
+ *         callback(null, stat.size);
  *     });
- * }, function(err, results) {
- *     // results is now the original array of files sorted by
- *     // modified date
- * });
+ * }
+ *
+ * // Using callbacks
+ * async.sortBy(['mediumfile.txt','smallfile.txt','bigfile.txt'], getFileSizeInBytes,
+ *     function(err, results) {
+ *         if (err) {
+ *             console.log(err);
+ *         } else {
+ *             console.log(results);
+ *             // results is now the original array of files sorted by
+ *             // file size (ascending by default), e.g.
+ *             // [ 'smallfile.txt', 'mediumfile.txt', 'bigfile.txt']
+ *         }
+ *     }
+ * );
  *
  * // By modifying the callback parameter the
  * // sorting order can be influenced:
  *
  * // ascending order
- * async.sortBy([1,9,3,5], function(x, callback) {
- *     callback(null, x);
- * }, function(err,result) {
- *     // result callback
- * });
+ * async.sortBy(['mediumfile.txt','smallfile.txt','bigfile.txt'], function(file, callback) {
+ *     getFileSizeInBytes(file, function(getFileSizeErr, fileSize) {
+ *         if (getFileSizeErr) return callback(getFileSizeErr);
+ *         callback(null, fileSize);
+ *     });
+ * }, function(err, results) {
+ *         if (err) {
+ *             console.log(err);
+ *         } else {
+ *             console.log(results);
+ *             // results is now the original array of files sorted by
+ *             // file size (ascending by default), e.g.
+ *             // [ 'smallfile.txt', 'mediumfile.txt', 'bigfile.txt']
+ *         }
+ *     }
+ * );
  *
  * // descending order
- * async.sortBy([1,9,3,5], function(x, callback) {
- *     callback(null, x*-1);    //<- x*-1 instead of x, turns the order around
- * }, function(err,result) {
- *     // result callback
+ * async.sortBy(['bigfile.txt','mediumfile.txt','smallfile.txt'], function(file, callback) {
+ *     getFileSizeInBytes(file, function(getFileSizeErr, fileSize) {
+ *         if (getFileSizeErr) {
+ *             return callback(getFileSizeErr);
+ *         }
+ *         callback(null, fileSize * -1);
+ *     });
+ * }, function(err, results) {
+ *         if (err) {
+ *             console.log(err);
+ *         } else {
+ *             console.log(results);
+ *             // results is now the original array of files sorted by
+ *             // file size (ascending by default), e.g.
+ *             // [ 'bigfile.txt', 'mediumfile.txt', 'smallfile.txt']
+ *         }
+ *     }
+ * );
+ *
+ * // Error handling
+ * async.sortBy(['mediumfile.txt','smallfile.txt','missingfile.txt'], getFileSizeInBytes,
+ *     function(err, results) {
+ *         if (err) {
+ *             console.log(err);
+ *             // [ Error: ENOENT: no such file or directory ]
+ *         } else {
+ *             console.log(results);
+ *         }
+ *     }
+ * );
+ *
+ * // Using Promises
+ * async.sortBy(['mediumfile.txt','smallfile.txt','bigfile.txt'], getFileSizeInBytes)
+ * .then( results => {
+ *     console.log(results);
+ *     // results is now the original array of files sorted by
+ *     // file size (ascending by default), e.g.
+ *     // [ 'smallfile.txt', 'mediumfile.txt', 'bigfile.txt']
+ * }).catch( err => {
+ *     console.log(err);
+ * });
+ *
+ * // Error handling
+ * async.sortBy(['mediumfile.txt','smallfile.txt','missingfile.txt'], getFileSizeInBytes)
+ * .then( results => {
+ *     console.log(results);
+ * }).catch( err => {
+ *     console.log(err);
+ *     // [ Error: ENOENT: no such file or directory ]
  * });
+ *
+ * // Using async/await
+ * (async () => {
+ *     try {
+ *         let results = await async.sortBy(['bigfile.txt','mediumfile.txt','smallfile.txt'], getFileSizeInBytes);
+ *         console.log(results);
+ *         // results is now the original array of files sorted by
+ *         // file size (ascending by default), e.g.
+ *         // [ 'smallfile.txt', 'mediumfile.txt', 'bigfile.txt']
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * })();
+ *
+ * // Error handling
+ * async () => {
+ *     try {
+ *         let results = await async.sortBy(['missingfile.txt','mediumfile.txt','smallfile.txt'], getFileSizeInBytes);
+ *         console.log(results);
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *         // [ Error: ENOENT: no such file or directory ]
+ *     }
+ * }
+ *
  */
 function sortBy (coll, iteratee, callback) {
     var _iteratee = wrapAsync(iteratee);
@@ -4287,26 +5406,118 @@ function timesSeries (n, iteratee, callback) {
  * @returns {Promise} a promise, if no callback provided
  * @example
  *
- * async.transform([1,2,3], function(acc, item, index, callback) {
- *     // pointless async:
- *     process.nextTick(function() {
- *         acc[index] = item * 2
- *         callback(null)
+ * // file1.txt is a file that is 1000 bytes in size
+ * // file2.txt is a file that is 2000 bytes in size
+ * // file3.txt is a file that is 3000 bytes in size
+ *
+ * // helper function that returns human-readable size format from bytes
+ * function formatBytes(bytes, decimals = 2) {
+ *   // implementation not included for brevity
+ *   return humanReadbleFilesize;
+ * }
+ *
+ * const fileList = ['file1.txt','file2.txt','file3.txt'];
+ *
+ * // asynchronous function that returns the file size, transformed to human-readable format
+ * // e.g. 1024 bytes = 1KB, 1234 bytes = 1.21 KB, 1048576 bytes = 1MB, etc.
+ * function transformFileSize(acc, value, key, callback) {
+ *     fs.stat(value, function(err, stat) {
+ *         if (err) {
+ *             return callback(err);
+ *         }
+ *         acc[key] = formatBytes(stat.size);
+ *         callback(null);
  *     });
- * }, function(err, result) {
- *     // result is now equal to [2, 4, 6]
+ * }
+ *
+ * // Using callbacks
+ * async.transform(fileList, transformFileSize, function(err, result) {
+ *     if(err) {
+ *         console.log(err);
+ *     } else {
+ *         console.log(result);
+ *         // [ '1000 Bytes', '1.95 KB', '2.93 KB' ]
+ *     }
+ * });
+ *
+ * // Using Promises
+ * async.transform(fileList, transformFileSize)
+ * .then(result => {
+ *     console.log(result);
+ *     // [ '1000 Bytes', '1.95 KB', '2.93 KB' ]
+ * }).catch(err => {
+ *     console.log(err);
  * });
  *
+ * // Using async/await
+ * (async () => {
+ *     try {
+ *         let result = await async.transform(fileList, transformFileSize);
+ *         console.log(result);
+ *         // [ '1000 Bytes', '1.95 KB', '2.93 KB' ]
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * })();
+ *
  * @example
  *
- * async.transform({a: 1, b: 2, c: 3}, function (obj, val, key, callback) {
- *     setImmediate(function () {
- *         obj[key] = val * 2;
- *         callback();
- *     })
- * }, function (err, result) {
- *     // result is equal to {a: 2, b: 4, c: 6}
- * })
+ * // file1.txt is a file that is 1000 bytes in size
+ * // file2.txt is a file that is 2000 bytes in size
+ * // file3.txt is a file that is 3000 bytes in size
+ *
+ * // helper function that returns human-readable size format from bytes
+ * function formatBytes(bytes, decimals = 2) {
+ *   // implementation not included for brevity
+ *   return humanReadbleFilesize;
+ * }
+ *
+ * const fileMap = { f1: 'file1.txt', f2: 'file2.txt', f3: 'file3.txt' };
+ *
+ * // asynchronous function that returns the file size, transformed to human-readable format
+ * // e.g. 1024 bytes = 1KB, 1234 bytes = 1.21 KB, 1048576 bytes = 1MB, etc.
+ * function transformFileSize(acc, value, key, callback) {
+ *     fs.stat(value, function(err, stat) {
+ *         if (err) {
+ *             return callback(err);
+ *         }
+ *         acc[key] = formatBytes(stat.size);
+ *         callback(null);
+ *     });
+ * }
+ *
+ * // Using callbacks
+ * async.transform(fileMap, transformFileSize, function(err, result) {
+ *     if(err) {
+ *         console.log(err);
+ *     } else {
+ *         console.log(result);
+ *         // { f1: '1000 Bytes', f2: '1.95 KB', f3: '2.93 KB' }
+ *     }
+ * });
+ *
+ * // Using Promises
+ * async.transform(fileMap, transformFileSize)
+ * .then(result => {
+ *     console.log(result);
+ *     // { f1: '1000 Bytes', f2: '1.95 KB', f3: '2.93 KB' }
+ * }).catch(err => {
+ *     console.log(err);
+ * });
+ *
+ * // Using async/await
+ * async () => {
+ *     try {
+ *         let result = await async.transform(fileMap, transformFileSize);
+ *         console.log(result);
+ *         // { f1: '1000 Bytes', f2: '1.95 KB', f3: '2.93 KB' }
+ *     }
+ *     catch (err) {
+ *         console.log(err);
+ *     }
+ * }
+ *
  */
 function transform (coll, accumulator, iteratee, callback) {
     if (arguments.length <= 3 && typeof accumulator === 'function') {
@@ -4484,7 +5695,7 @@ var whilst$1 = awaitify(whilst, 3);
  * @example
  * const results = []
  * let finished = false
- * async.until(function test(page, cb) {
+ * async.until(function test(cb) {
  *     cb(null, finished)
  * }, function iter(next) {
  *     fetchPage(url, (err, body) => {