diff options
| author | Roman Lorenzo Balayan <roman.balayan@gmail.com> | 2021-08-06 06:58:10 +0800 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-08-05 15:58:10 -0700 |
| commit | 159a119fbb1a585c61f33b4b3b5036f5d332ebbb (patch) | |
| tree | bbf78b2e8899c412ceede4a705d45368f61b51bf | |
| parent | 89255fe326050e80ce5394a9c00e11e9be8b1005 (diff) | |
| download | async-159a119fbb1a585c61f33b4b3b5036f5d332ebbb.tar.gz | |
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 <roman.balayan@paymaya.com>
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 <code>iteratee</code> function. Invok <h5>Example</h5> - <pre class="prettyprint"><code>async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files) { - // files is now a list of filenames that exist in the 3 directories -});</code></pre> + <pre class="prettyprint"><code>// 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 + } +}</code></pre> @@ -1167,13 +1234,47 @@ Result will be the first item in the array that passes the truth test <h5>Example</h5> - <pre class="prettyprint"><code>async.detect(['file1','file2','file3'], function(filePath, callback) { - fs.access(filePath, function(err) { - callback(null, !err) - }); -}, function(err, result) { + <pre class="prettyprint"><code>// 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 -});</code></pre> +}).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); + } +}</code></pre> @@ -1868,37 +1969,77 @@ If you need the index, use <code>eachOf</code>.</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>// assuming openFiles is an array of file names and saveFile is a function -// to save the modified contents of that file: + <pre class="prettyprint"><code>// 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); } -});</code></pre> +} + +// 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 + } +}</code></pre> @@ -2379,12 +2520,19 @@ Invoked with (item, key, callback).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>var obj = {dev: "/dev.json", test: "/test.json", prod: "/prod.json"}; -var configs = {}; + <pre class="prettyprint"><code>// 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); -});</code></pre> +} + +// 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 + } +}</code></pre> @@ -3345,13 +3554,77 @@ depending on the values of the async tests. Invoked with (err, result).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>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 -});</code></pre> + <pre class="prettyprint"><code>// 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); + } +}</code></pre> @@ -4062,13 +4335,52 @@ with a boolean argument once it has completed. Invoked with (item, callback).</p <h5>Example</h5> - <pre class="prettyprint"><code>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 -});</code></pre> + <pre class="prettyprint"><code>// 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); + } +}</code></pre> @@ -4778,15 +5090,68 @@ properties are arrays of values which returned the corresponding key.</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>async.groupBy(['userId1', 'userId2', 'userId3'], function(userId, callback) { - db.findById(userId, function(err, user) { - if (err) return callback(err); - return callback(null, user.age); + <pre class="prettyprint"><code>// 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']}; -});</code></pre> +} + +//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); + } +}</code></pre> @@ -5220,7 +5585,7 @@ Invoked with (value, callback).</p></td> <td class="description last"><p>A callback which is called when all <code>iteratee</code> -functions have finished, or an error occurs. Result is an <code>Object</code> whoses +functions have finished, or an error occurs. Result is an <code>Object</code> whose properties are arrays of values which returned the corresponding key.</p></td> </tr> @@ -5494,9 +5859,88 @@ transformed items from the <code>coll</code>. Invoked with (err, results).</p></ <h5>Example</h5> - <pre class="prettyprint"><code>async.map(['file1','file2','file3'], fs.stat, function(err, results) { - // results is now an array of stats for each file -});</code></pre> + <pre class="prettyprint"><code>// 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 ] + } +}</code></pre> @@ -6192,20 +6636,109 @@ Invoked with (err, result).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>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. + <pre class="prettyprint"><code>// 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 // } -});</code></pre> +}).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 ] + } +}</code></pre> @@ -6923,14 +7456,89 @@ Invoked with (memo, item, callback).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>async.reduce([1,2,3], 0, function(memo, item, callback) { - // pointless async: - process.nextTick(function() { - callback(null, memo + item) + <pre class="prettyprint"><code>// 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 -});</code></pre> +} + +// 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 ] + } +}</code></pre> @@ -7398,14 +8006,47 @@ Invoked with (item, callback).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>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); -});</code></pre> + <pre class="prettyprint"><code>// 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); + } +}</code></pre> @@ -8115,13 +8756,78 @@ tests. Invoked with (err, result).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>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 -});</code></pre> + <pre class="prettyprint"><code>// 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); + } +}</code></pre> @@ -8830,31 +9536,132 @@ calls. Invoked with (err, results).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>async.sortBy(['file1','file2','file3'], function(file, callback) { - fs.stat(file, function(err, stats) { - callback(err, stats.mtime); + <pre class="prettyprint"><code>// 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 -});</code></pre> +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 ] + } +}</code></pre> @@ -9104,24 +9911,115 @@ Invoked with (err, result).</p></td> <h5>Examples</h5> - <pre class="prettyprint"><code>async.transform([1,2,3], function(acc, item, index, callback) { - // pointless async: - process.nextTick(function() { - acc[index] = item * 2 - callback(null) + <pre class="prettyprint"><code>// 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] -});</code></pre> +} - <pre class="prettyprint"><code>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} -})</code></pre> +// 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); + } +})();</code></pre> + + <pre class="prettyprint"><code>// 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); + } +}</code></pre> @@ -9982,15 +10880,40 @@ will only contain partial results. Invoked with (err, results).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>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 - // ... + <pre class="prettyprint"><code>//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); -});</code></pre> + // 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); + } +}</code></pre> @@ -11821,7 +12784,8 @@ Invoked with (err, results).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>async.parallel([ + <pre class="prettyprint"><code>//Using Callbacks +async.parallel([ function(callback) { setTimeout(function() { callback(null, 'one'); @@ -11832,10 +12796,9 @@ Invoked with (err, results).</p></td> 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} -});</code></pre> + 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); + } +}</code></pre> @@ -13642,35 +14692,133 @@ with (err, result).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>async.series([ + <pre class="prettyprint"><code>//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} -});</code></pre> + 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); + } +}</code></pre> @@ -14781,7 +15929,7 @@ callback. Invoked with (err, [results]);</p></td> <pre class="prettyprint"><code>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 <code>iteratee</code> function. Invok <h5>Example</h5> - <pre class="prettyprint"><code>async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files) { - // files is now a list of filenames that exist in the 3 directories -});</code></pre> + <pre class="prettyprint"><code>// 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 + } +}</code></pre> @@ -1027,13 +1094,47 @@ Result will be the first item in the array that passes the truth test <h5>Example</h5> - <pre class="prettyprint"><code>async.detect(['file1','file2','file3'], function(filePath, callback) { - fs.access(filePath, function(err) { - callback(null, !err) - }); -}, function(err, result) { + <pre class="prettyprint"><code>// 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 -});</code></pre> +}).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); + } +}</code></pre> @@ -1728,37 +1829,77 @@ If you need the index, use <code>eachOf</code>.</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>// assuming openFiles is an array of file names and saveFile is a function -// to save the modified contents of that file: + <pre class="prettyprint"><code>// 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 } -});</code></pre> +}</code></pre> @@ -2239,12 +2380,19 @@ Invoked with (item, key, callback).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>var obj = {dev: "/dev.json", test: "/test.json", prod: "/prod.json"}; -var configs = {}; + <pre class="prettyprint"><code>// 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); -});</code></pre> +} + +// 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 + } +}</code></pre> @@ -3205,13 +3414,77 @@ depending on the values of the async tests. Invoked with (err, result).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>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 -});</code></pre> + <pre class="prettyprint"><code>// 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); + } +}</code></pre> @@ -3922,13 +4195,52 @@ with a boolean argument once it has completed. Invoked with (item, callback).</p <h5>Example</h5> - <pre class="prettyprint"><code>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 -});</code></pre> + <pre class="prettyprint"><code>// 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); + } +}</code></pre> @@ -4638,15 +4950,68 @@ properties are arrays of values which returned the corresponding key.</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>async.groupBy(['userId1', 'userId2', 'userId3'], function(userId, callback) { - db.findById(userId, function(err, user) { - if (err) return callback(err); - return callback(null, user.age); + <pre class="prettyprint"><code>// 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']}; -});</code></pre> +} + +//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); + } +}</code></pre> @@ -5080,7 +5445,7 @@ Invoked with (value, callback).</p></td> <td class="description last"><p>A callback which is called when all <code>iteratee</code> -functions have finished, or an error occurs. Result is an <code>Object</code> whoses +functions have finished, or an error occurs. Result is an <code>Object</code> whose properties are arrays of values which returned the corresponding key.</p></td> </tr> @@ -5354,9 +5719,88 @@ transformed items from the <code>coll</code>. Invoked with (err, results).</p></ <h5>Example</h5> - <pre class="prettyprint"><code>async.map(['file1','file2','file3'], fs.stat, function(err, results) { - // results is now an array of stats for each file -});</code></pre> + <pre class="prettyprint"><code>// 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 ] + } +}</code></pre> @@ -6052,20 +6496,109 @@ Invoked with (err, result).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>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. + <pre class="prettyprint"><code>// 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 // } -});</code></pre> +}).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 ] + } +}</code></pre> @@ -6783,14 +7316,89 @@ Invoked with (memo, item, callback).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>async.reduce([1,2,3], 0, function(memo, item, callback) { - // pointless async: - process.nextTick(function() { - callback(null, memo + item) + <pre class="prettyprint"><code>// 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 -});</code></pre> +} + +// 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 ] + } +}</code></pre> @@ -7258,14 +7866,47 @@ Invoked with (item, callback).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>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); -});</code></pre> + <pre class="prettyprint"><code>// 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); + } +}</code></pre> @@ -7975,13 +8616,78 @@ tests. Invoked with (err, result).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>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 -});</code></pre> + <pre class="prettyprint"><code>// 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); + } +}</code></pre> @@ -8690,31 +9396,132 @@ calls. Invoked with (err, results).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>async.sortBy(['file1','file2','file3'], function(file, callback) { - fs.stat(file, function(err, stats) { - callback(err, stats.mtime); + <pre class="prettyprint"><code>// 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 -});</code></pre> +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 ] + } +}</code></pre> @@ -8964,24 +9771,115 @@ Invoked with (err, result).</p></td> <h5>Examples</h5> - <pre class="prettyprint"><code>async.transform([1,2,3], function(acc, item, index, callback) { - // pointless async: - process.nextTick(function() { - acc[index] = item * 2 - callback(null) + <pre class="prettyprint"><code>// 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] -});</code></pre> +} - <pre class="prettyprint"><code>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} -})</code></pre> +// 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); + } +})();</code></pre> + + <pre class="prettyprint"><code>// 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); + } +}</code></pre> 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).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>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 - // ... + <pre class="prettyprint"><code>//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); -});</code></pre> + // 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); + } +}</code></pre> @@ -2692,7 +2757,8 @@ Invoked with (err, results).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>async.parallel([ + <pre class="prettyprint"><code>//Using Callbacks +async.parallel([ function(callback) { setTimeout(function() { callback(null, 'one'); @@ -2703,10 +2769,9 @@ Invoked with (err, results).</p></td> 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} -});</code></pre> + 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); + } +}</code></pre> @@ -4513,35 +4665,133 @@ with (err, result).</p></td> <h5>Example</h5> - <pre class="prettyprint"><code>async.series([ + <pre class="prettyprint"><code>//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} -});</code></pre> + 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); + } +}</code></pre> @@ -5652,7 +5902,7 @@ callback. Invoked with (err, [results]);</p></td> <pre class="prettyprint"><code>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) @@ -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": { |