From 159a119fbb1a585c61f33b4b3b5036f5d332ebbb Mon Sep 17 00:00:00 2001 From: Roman Lorenzo Balayan Date: Fri, 6 Aug 2021 06:58:10 +0800 Subject: Enhance examples for Collections methods. (#1726) * Enhance examples for Collections methods. * Update collection example code, avoiding usage of IIFE on async/await examples * Convert examples on async.auto, async.series, and async.parallel to samples using Promises and async/await Co-authored-by: Roman Balayan --- docs/v3/auto.js.html | 88 ++- docs/v3/concat.js.html | 72 +- docs/v3/detect.js.html | 45 +- docs/v3/docs.html | 1486 ++++++++++++++++++++++++++++++++++----- docs/v3/each.js.html | 89 ++- docs/v3/eachOf.js.html | 87 ++- docs/v3/every.js.html | 77 +- docs/v3/filter.js.html | 52 +- docs/v3/groupBy.js.html | 68 +- docs/v3/groupBySeries.js.html | 2 +- docs/v3/map.js.html | 84 ++- docs/v3/mapValues.js.html | 112 ++- docs/v3/module-Collections.html | 1170 ++++++++++++++++++++++++++---- docs/v3/module-ControlFlow.html | 316 ++++++++- docs/v3/parallel.js.html | 99 ++- docs/v3/reduce.js.html | 88 ++- docs/v3/reject.js.html | 48 +- docs/v3/series.js.html | 120 +++- docs/v3/some.js.html | 78 +- docs/v3/sortBy.js.html | 134 +++- docs/v3/transform.js.html | 122 +++- docs/v3/until.js.html | 2 +- lib/auto.js | 88 ++- lib/concat.js | 72 +- lib/detect.js | 45 +- lib/each.js | 89 ++- lib/eachOf.js | 87 ++- lib/every.js | 77 +- lib/filter.js | 52 +- lib/groupBy.js | 68 +- lib/map.js | 84 ++- lib/mapValues.js | 112 ++- lib/parallel.js | 99 ++- lib/reduce.js | 88 ++- lib/reject.js | 48 +- lib/series.js | 120 +++- lib/some.js | 78 +- lib/sortBy.js | 134 +++- lib/transform.js | 122 +++- package-lock.json | 2 +- 40 files changed, 5267 insertions(+), 637 deletions(-) diff --git a/docs/v3/auto.js.html b/docs/v3/auto.js.html index e380d65..a1d65db 100644 --- a/docs/v3/auto.js.html +++ b/docs/v3/auto.js.html @@ -121,15 +121,40 @@ import { promiseCallback, PROMISE_SYMBOL } from './internal/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'); @@ -143,21 +168,62 @@ import { promiseCallback, PROMISE_SYMBOL } from './internal/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); + * } + * } + * */ export default function auto(tasks, concurrency, callback) { if (typeof concurrency !== 'number') { diff --git a/docs/v3/concat.js.html b/docs/v3/concat.js.html index 023a089..3f04061 100644 --- a/docs/v3/concat.js.html +++ b/docs/v3/concat.js.html @@ -100,9 +100,77 @@ import awaitify from './internal/awaitify' * @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(coll, Infinity, iteratee, callback) diff --git a/docs/v3/detect.js.html b/docs/v3/detect.js.html index fe6d4c9..056000e 100644 --- a/docs/v3/detect.js.html +++ b/docs/v3/detect.js.html @@ -107,13 +107,48 @@ import awaitify from './internal/awaitify' * @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, coll, iteratee, callback) diff --git a/docs/v3/docs.html b/docs/v3/docs.html index ddfa6c2..e4ff9a3 100644 --- a/docs/v3/docs.html +++ b/docs/v3/docs.html @@ -484,9 +484,76 @@ containing the concatenated results of the iteratee function. Invok
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
+    }
+}
@@ -1167,13 +1234,47 @@ Result will be the first item in the array that passes the truth test
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);
+    }
+}
@@ -1868,37 +1969,77 @@ If you need the index, use eachOf.

Example
- 
// assuming openFiles is an array of file names and saveFile is a function
-// to save the modified contents of that file:
+    
// 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/file2.txt', 'dir2/file3.txt', 'dir/file5.txt'];
+const withMissingFileList = ['dir1/file1.txt', 'dir4/file2.txt'];
+
+// asynchronous function that deletes a file
+const deleteFile = function(file, callback) {
+    fs.unlink(file, callback);
+};
+
+// Using callbacks
+async.each(fileList, deleteFile, function(err) {
+    if( err ) {
+        console.log(err);
+    } else {
+        console.log('All files have been deleted successfully');
+    }
+});
 
-async.each(openFiles, saveFile, function(err){
-  // if any of the saves produced an error, err would equal that error
+// 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
 });
 
-// assuming openFiles is an array of file names
-async.each(openFiles, function(file, callback) {
+// Using Promises
+async.each(fileList, deleteFile)
+.then( () => {
+    console.log('All files have been deleted successfully');
+}).catch( err => {
+    console.log(err);
+});
 
-    // Perform operation on file here.
-    console.log('Processing file ' + file);
+// 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
+});
 
-    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();
+// Using async/await
+async () => {
+    try {
+        await async.each(files, deleteFile);
     }
-}, function(err) {
-    // if any of the file processing produced an error, err would equal that error
-    if( err ) {
-      // One of the iterations produced an error.
-      // All processing will now stop.
-      console.log('A file failed to process');
-    } else {
-      console.log('All files have been processed successfully');
+    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
+    }
+}
@@ -2379,12 +2520,19 @@ Invoked with (item, key, callback).

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) {
@@ -2392,11 +2540,72 @@ async.forEachOf(obj, function (value, key, 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
+    }
+}
@@ -3345,13 +3554,77 @@ depending on the values of the async tests. Invoked with (err, result).

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);
+    }
+}
@@ -4062,13 +4335,52 @@ with a boolean argument once it has completed. Invoked with (item, callback).

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);
+    }
+}
@@ -4778,15 +5090,68 @@ properties are arrays of values which returned the corresponding key.

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);
+    }
+}
@@ -5220,7 +5585,7 @@ Invoked with (value, 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.

@@ -5494,9 +5859,88 @@ transformed items from the coll. Invoked with (err, results).

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 ]
+    }
+}
@@ -6192,20 +6636,109 @@ Invoked with (err, result).

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 ]
+    }
+}
@@ -6923,14 +7456,89 @@ Invoked with (memo, item, callback).

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 ]
+    }
+}
@@ -7398,14 +8006,47 @@ Invoked with (item, callback).

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);
+    }
+}
@@ -8115,13 +8756,78 @@ tests. Invoked with (err, result).

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);
+    }
+}
@@ -8830,31 +9536,132 @@ calls. Invoked with (err, results).

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 ]
+    }
+}
@@ -9104,24 +9911,115 @@ Invoked with (err, result).

Examples
- 
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]
-});

+}
 
-    
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}
-})

+// 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);
+    }
+})();
+ + 
// 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);
+    }
+}
@@ -9982,15 +10880,40 @@ will only contain partial results. Invoked with (err, results).

Example
- 
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
-        // ...
+    
//Using Callbacks
+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'});
     }]
-}, 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');
@@ -10004,21 +10927,61 @@ async.auto({
         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);
+    }
+}
@@ -11821,7 +12784,8 @@ Invoked with (err, results).

Example
- 
async.parallel([
+    
//Using Callbacks
+async.parallel([
     function(callback) {
         setTimeout(function() {
             callback(null, 'one');
@@ -11832,10 +12796,9 @@ Invoked with (err, results).

             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.
 });
 
@@ -11852,8 +12815,95 @@ async.parallel({
         }, 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);
+    }
+}
@@ -13642,35 +14692,133 @@ with (err, result).

Example
- 
async.series([
+    
//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);
+    }
+}
@@ -14781,7 +15929,7 @@ callback. Invoked with (err, [results]);

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) => {
diff --git a/docs/v3/each.js.html b/docs/v3/each.js.html
index d7b7cd8..a4b7c5b 100644
--- a/docs/v3/each.js.html
+++ b/docs/v3/each.js.html
@@ -106,37 +106,78 @@ import awaitify from './internal/awaitify'
  * @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:
+ * // 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
  *
- * async.each(openFiles, saveFile, function(err){
- *   // if any of the saves produced an error, err would equal that error
- * });
- *
- * // 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(coll, withoutIndex(wrapAsync(iteratee)), callback);
diff --git a/docs/v3/eachOf.js.html b/docs/v3/eachOf.js.html
index 70bacd2..132d37b 100644
--- a/docs/v3/eachOf.js.html
+++ b/docs/v3/eachOf.js.html
@@ -137,12 +137,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) {
@@ -150,11 +157,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;
diff --git a/docs/v3/every.js.html b/docs/v3/every.js.html
index a57e5eb..7a01ede 100644
--- a/docs/v3/every.js.html
+++ b/docs/v3/every.js.html
@@ -100,13 +100,78 @@ import awaitify from './internal/awaitify'
  * @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, coll, iteratee, callback)
diff --git a/docs/v3/filter.js.html b/docs/v3/filter.js.html
index 5dc2b05..9d191c7 100644
--- a/docs/v3/filter.js.html
+++ b/docs/v3/filter.js.html
@@ -99,13 +99,53 @@ import awaitify from './internal/awaitify'
  * @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, coll, iteratee, callback)
diff --git a/docs/v3/groupBy.js.html b/docs/v3/groupBy.js.html
index 52ee786..90f5788 100644
--- a/docs/v3/groupBy.js.html
+++ b/docs/v3/groupBy.js.html
@@ -104,15 +104,69 @@
  * @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);
+ *     }
+ * }
+ *
  */
 export default function groupBy (coll, iteratee, callback) {
     return groupByLimit(coll, Infinity, iteratee, callback)
diff --git a/docs/v3/groupBySeries.js.html b/docs/v3/groupBySeries.js.html
index 7ee5c78..65e18f6 100644
--- a/docs/v3/groupBySeries.js.html
+++ b/docs/v3/groupBySeries.js.html
@@ -92,7 +92,7 @@
  * 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
  */
diff --git a/docs/v3/map.js.html b/docs/v3/map.js.html
index dc5dd00..b527c06 100644
--- a/docs/v3/map.js.html
+++ b/docs/v3/map.js.html
@@ -112,9 +112,89 @@ import awaitify from './internal/awaitify'
  * @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 _map(eachOf, coll, iteratee, callback)
diff --git a/docs/v3/mapValues.js.html b/docs/v3/mapValues.js.html
index d86c326..d1c6dd0 100644
--- a/docs/v3/mapValues.js.html
+++ b/docs/v3/mapValues.js.html
@@ -107,20 +107,110 @@
  * @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 ]
+ *     }
+ * }
+ *
  */
 export default function mapValues(obj, iteratee, callback) {
     return mapValuesLimit(obj, Infinity, iteratee, callback)
diff --git a/docs/v3/module-Collections.html b/docs/v3/module-Collections.html
index a38a089..6d21404 100644
--- a/docs/v3/module-Collections.html
+++ b/docs/v3/module-Collections.html
@@ -344,9 +344,76 @@ containing the concatenated results of the iteratee function. Invok
 
     
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
+    }
+}

 
 
 
@@ -1027,13 +1094,47 @@ Result will be the first item in the array that passes the truth test
 
     
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);
+    }
+}

 
 
 
@@ -1728,37 +1829,77 @@ If you need the index, use eachOf.

 
     
Example

     
-    
// assuming openFiles is an array of file names and saveFile is a function
-// to save the modified contents of that file:
+    
// 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/file2.txt', 'dir2/file3.txt', 'dir/file5.txt'];
+const withMissingFileList = ['dir1/file1.txt', 'dir4/file2.txt'];
+
+// asynchronous function that deletes a file
+const deleteFile = function(file, callback) {
+    fs.unlink(file, callback);
+};
+
+// Using callbacks
+async.each(fileList, deleteFile, function(err) {
+    if( err ) {
+        console.log(err);
+    } else {
+        console.log('All files have been deleted successfully');
+    }
+});
 
-async.each(openFiles, saveFile, function(err){
-  // if any of the saves produced an error, err would equal that error
+// 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
 });
 
-// assuming openFiles is an array of file names
-async.each(openFiles, function(file, callback) {
+// Using Promises
+async.each(fileList, deleteFile)
+.then( () => {
+    console.log('All files have been deleted successfully');
+}).catch( err => {
+    console.log(err);
+});
 
-    // Perform operation on file here.
-    console.log('Processing file ' + file);
+// 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
+});
 
-    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();
+// Using async/await
+async () => {
+    try {
+        await async.each(files, deleteFile);
     }
-}, function(err) {
-    // if any of the file processing produced an error, err would equal that error
-    if( err ) {
-      // One of the iterations produced an error.
-      // All processing will now stop.
-      console.log('A file failed to process');
-    } else {
-      console.log('All files have been processed successfully');
+    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
     }
-});

+}

 
 
 
@@ -2239,12 +2380,19 @@ Invoked with (item, key, callback).

 
     
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) {
@@ -2252,11 +2400,72 @@ async.forEachOf(obj, function (value, key, 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
+    }
+}

 
 
 
@@ -3205,13 +3414,77 @@ depending on the values of the async tests. Invoked with (err, result).

 
     
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);
+    }
+}

 
 
 
@@ -3922,13 +4195,52 @@ with a boolean argument once it has completed. Invoked with (item, callback).
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);
+    }
+}

 
 
 
@@ -4638,15 +4950,68 @@ properties are arrays of values which returned the corresponding key.

 
     
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);
+    }
+}

 
 
 
@@ -5080,7 +5445,7 @@ Invoked with (value, 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.

         
 
@@ -5354,9 +5719,88 @@ transformed items from the coll. Invoked with (err, results).
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 ]
+    }
+}

 
 
 
@@ -6052,20 +6496,109 @@ Invoked with (err, result).

 
     
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 ]
+    }
+}

 
 
 
@@ -6783,14 +7316,89 @@ Invoked with (memo, item, callback).

 
     
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 ]
+    }
+}

 
 
 
@@ -7258,14 +7866,47 @@ Invoked with (item, callback).

 
     
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);
+    }
+}

 
 
 
@@ -7975,13 +8616,78 @@ tests. Invoked with (err, result).

 
     
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);
+    }
+}

 
 
 
@@ -8690,31 +9396,132 @@ calls. Invoked with (err, results).

 
     
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 ]
+    }
+}

 
 
 
@@ -8964,24 +9771,115 @@ Invoked with (err, result).

 
     
Examples

     
-    
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]
-});

+}
 
-    
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}
-})

+// 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);
+    }
+})();

+
+    
// 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);
+    }
+}

 
 
 
diff --git a/docs/v3/module-ControlFlow.html b/docs/v3/module-ControlFlow.html
index 0b41c93..d48a8a7 100644
--- a/docs/v3/module-ControlFlow.html
+++ b/docs/v3/module-ControlFlow.html
@@ -853,15 +853,40 @@ will only contain partial results. Invoked with (err, results).

 
     
Example

     
-    
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
-        // ...
+    
//Using Callbacks
+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'});
     }]
-}, 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');
@@ -875,21 +900,61 @@ async.auto({
         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);
+    }
+}

 
 
 
@@ -2692,7 +2757,8 @@ Invoked with (err, results).

 
     
Example

     
-    
async.parallel([
+    
//Using Callbacks
+async.parallel([
     function(callback) {
         setTimeout(function() {
             callback(null, 'one');
@@ -2703,10 +2769,9 @@ Invoked with (err, results).

             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.
 });
 
@@ -2723,8 +2788,95 @@ async.parallel({
         }, 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);
+    }
+}

 
 
 
@@ -4513,35 +4665,133 @@ with (err, result).

 
     
Example

     
-    
async.series([
+    
//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);
+    }
+}

 
 
 
@@ -5652,7 +5902,7 @@ callback. Invoked with (err, [results]);

     
     
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) => {
diff --git a/docs/v3/parallel.js.html b/docs/v3/parallel.js.html
index 946909e..40af8d3 100644
--- a/docs/v3/parallel.js.html
+++ b/docs/v3/parallel.js.html
@@ -114,6 +114,8 @@ import _parallel from './internal/parallel';
  * @returns {Promise} a promise, if a callback is not passed
  *
  * @example
+ *
+ * //Using Callbacks
  * async.parallel([
  *     function(callback) {
  *         setTimeout(function() {
@@ -125,10 +127,9 @@ import _parallel from './internal/parallel';
  *             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.
  * });
  *
@@ -145,8 +146,96 @@ import _parallel from './internal/parallel';
  *         }, 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);
+ *     }
+ * }
+ *
  */
 export default function parallel(tasks, callback) {
     return _parallel(eachOf, tasks, callback);
diff --git a/docs/v3/reduce.js.html b/docs/v3/reduce.js.html
index e85a14e..c0c3d9e 100644
--- a/docs/v3/reduce.js.html
+++ b/docs/v3/reduce.js.html
@@ -112,14 +112,90 @@ import awaitify from './internal/awaitify'
  * @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);
diff --git a/docs/v3/reject.js.html b/docs/v3/reject.js.html
index ddad843..18048d9 100644
--- a/docs/v3/reject.js.html
+++ b/docs/v3/reject.js.html
@@ -98,14 +98,48 @@ import awaitify from './internal/awaitify'
  * @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 (coll, iteratee, callback) {
     return _reject(eachOf, coll, iteratee, callback)
diff --git a/docs/v3/series.js.html b/docs/v3/series.js.html
index 02b62f3..bef4a61 100644
--- a/docs/v3/series.js.html
+++ b/docs/v3/series.js.html
@@ -113,35 +113,135 @@ import eachOfSeries from './eachOfSeries';
  * 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);
+ *     }
+ * }
+ *
  */
 export default function series(tasks, callback) {
     return _parallel(eachOfSeries, tasks, callback);
diff --git a/docs/v3/some.js.html b/docs/v3/some.js.html
index a4f8579..4d89fac 100644
--- a/docs/v3/some.js.html
+++ b/docs/v3/some.js.html
@@ -102,13 +102,79 @@ import awaitify from './internal/awaitify'
  * @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, coll, iteratee, callback)
diff --git a/docs/v3/sortBy.js.html b/docs/v3/sortBy.js.html
index 4198f85..7bd91ed 100644
--- a/docs/v3/sortBy.js.html
+++ b/docs/v3/sortBy.js.html
@@ -101,31 +101,133 @@ import awaitify from './internal/awaitify'
  * @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);
diff --git a/docs/v3/transform.js.html b/docs/v3/transform.js.html
index 2bce88e..cb5324a 100644
--- a/docs/v3/transform.js.html
+++ b/docs/v3/transform.js.html
@@ -102,26 +102,118 @@ import { promiseCallback, PROMISE_SYMBOL } from './internal/promiseCallback
  * @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);
+ *     }
+ * }
+ *
  */
 export default function transform (coll, accumulator, iteratee, callback) {
     if (arguments.length <= 3 && typeof accumulator === 'function') {
diff --git a/docs/v3/until.js.html b/docs/v3/until.js.html
index 6b5a272..5cb8c52 100644
--- a/docs/v3/until.js.html
+++ b/docs/v3/until.js.html
@@ -104,7 +104,7 @@ import wrapAsync from './internal/wrapAsync';
  * @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) => {
diff --git a/lib/auto.js b/lib/auto.js
index ad92d74..58a8c45 100644
--- a/lib/auto.js
+++ b/lib/auto.js
@@ -44,15 +44,40 @@ import { promiseCallback, PROMISE_SYMBOL } from './internal/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');
@@ -66,21 +91,62 @@ import { promiseCallback, PROMISE_SYMBOL } from './internal/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);
+ *     }
+ * }
+ *
  */
 export default function auto(tasks, concurrency, callback) {
     if (typeof concurrency !== 'number') {
diff --git a/lib/concat.js b/lib/concat.js
index c6dc11c..73435de 100644
--- a/lib/concat.js
+++ b/lib/concat.js
@@ -23,9 +23,77 @@ import awaitify from './internal/awaitify'
  * @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(coll, Infinity, iteratee, callback)
diff --git a/lib/detect.js b/lib/detect.js
index 4a6746a..0b63df4 100644
--- a/lib/detect.js
+++ b/lib/detect.js
@@ -30,13 +30,48 @@ import awaitify from './internal/awaitify'
  * @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, coll, iteratee, callback)
diff --git a/lib/each.js b/lib/each.js
index 7f6e689..e4cde8c 100644
--- a/lib/each.js
+++ b/lib/each.js
@@ -29,37 +29,78 @@ import awaitify from './internal/awaitify'
  * @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:
+ * // 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
  *
- * async.each(openFiles, saveFile, function(err){
- *   // if any of the saves produced an error, err would equal that error
- * });
- *
- * // 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(coll, withoutIndex(wrapAsync(iteratee)), callback);
diff --git a/lib/eachOf.js b/lib/eachOf.js
index 0b847ae..207cec0 100644
--- a/lib/eachOf.js
+++ b/lib/eachOf.js
@@ -60,12 +60,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) {
@@ -73,11 +80,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;
diff --git a/lib/every.js b/lib/every.js
index a5ce971..0a6bc54 100644
--- a/lib/every.js
+++ b/lib/every.js
@@ -23,13 +23,78 @@ import awaitify from './internal/awaitify'
  * @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, coll, iteratee, callback)
diff --git a/lib/filter.js b/lib/filter.js
index b0f3029..2428550 100644
--- a/lib/filter.js
+++ b/lib/filter.js
@@ -22,13 +22,53 @@ import awaitify from './internal/awaitify'
  * @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, coll, iteratee, callback)
diff --git a/lib/groupBy.js b/lib/groupBy.js
index 2993367..c6949b2 100644
--- a/lib/groupBy.js
+++ b/lib/groupBy.js
@@ -27,15 +27,69 @@ import groupByLimit from './groupByLimit';
  * @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);
+ *     }
+ * }
+ *
  */
 export default function groupBy (coll, iteratee, callback) {
     return groupByLimit(coll, Infinity, iteratee, callback)
diff --git a/lib/map.js b/lib/map.js
index c32bd2d..13646c9 100644
--- a/lib/map.js
+++ b/lib/map.js
@@ -35,9 +35,89 @@ import awaitify from './internal/awaitify'
  * @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 _map(eachOf, coll, iteratee, callback)
diff --git a/lib/mapValues.js b/lib/mapValues.js
index 79edfd4..0d44ce4 100644
--- a/lib/mapValues.js
+++ b/lib/mapValues.js
@@ -30,20 +30,110 @@ import mapValuesLimit from './mapValuesLimit';
  * @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 ]
+ *     }
+ * }
+ *
  */
 export default function mapValues(obj, iteratee, callback) {
     return mapValuesLimit(obj, Infinity, iteratee, callback)
diff --git a/lib/parallel.js b/lib/parallel.js
index fafae9d..1124ac3 100644
--- a/lib/parallel.js
+++ b/lib/parallel.js
@@ -37,6 +37,8 @@ import _parallel from './internal/parallel';
  * @returns {Promise} a promise, if a callback is not passed
  *
  * @example
+ *
+ * //Using Callbacks
  * async.parallel([
  *     function(callback) {
  *         setTimeout(function() {
@@ -48,10 +50,9 @@ import _parallel from './internal/parallel';
  *             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.
  * });
  *
@@ -68,8 +69,96 @@ import _parallel from './internal/parallel';
  *         }, 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);
+ *     }
+ * }
+ *
  */
 export default function parallel(tasks, callback) {
     return _parallel(eachOf, tasks, callback);
diff --git a/lib/reduce.js b/lib/reduce.js
index d13ace0..feaa959 100644
--- a/lib/reduce.js
+++ b/lib/reduce.js
@@ -35,14 +35,90 @@ import awaitify from './internal/awaitify'
  * @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);
diff --git a/lib/reject.js b/lib/reject.js
index c1de825..127430e 100644
--- a/lib/reject.js
+++ b/lib/reject.js
@@ -21,14 +21,48 @@ import awaitify from './internal/awaitify'
  * @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 (coll, iteratee, callback) {
     return _reject(eachOf, coll, iteratee, callback)
diff --git a/lib/series.js b/lib/series.js
index 71367a9..cbec2e8 100644
--- a/lib/series.js
+++ b/lib/series.js
@@ -36,35 +36,135 @@ import eachOfSeries from './eachOfSeries';
  * 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);
+ *     }
+ * }
+ *
  */
 export default function series(tasks, callback) {
     return _parallel(eachOfSeries, tasks, callback);
diff --git a/lib/some.js b/lib/some.js
index 378ccdf..1d7f6fd 100644
--- a/lib/some.js
+++ b/lib/some.js
@@ -25,13 +25,79 @@ import awaitify from './internal/awaitify'
  * @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, coll, iteratee, callback)
diff --git a/lib/sortBy.js b/lib/sortBy.js
index 4477677..7a1b9fb 100644
--- a/lib/sortBy.js
+++ b/lib/sortBy.js
@@ -24,31 +24,133 @@ import awaitify from './internal/awaitify'
  * @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);
diff --git a/lib/transform.js b/lib/transform.js
index 786f5d3..d2aa29e 100644
--- a/lib/transform.js
+++ b/lib/transform.js
@@ -25,26 +25,118 @@ import { promiseCallback, PROMISE_SYMBOL } from './internal/promiseCallback';
  * @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);
+ *     }
+ * }
+ *
  */
 export default function transform (coll, accumulator, iteratee, callback) {
     if (arguments.length <= 3 && typeof accumulator === 'function') {
diff --git a/package-lock.json b/package-lock.json
index f722fdb..bac0918 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,6 +1,6 @@
 {
   "name": "async",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {
-- 
cgit v1.2.1