diff options
Diffstat (limited to 'docs/v3/docs.html')
| -rw-r--r-- | docs/v3/docs.html | 1486 |
1 files changed, 1317 insertions, 169 deletions
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) => { |