Skip to content

Commit

Permalink
Enhance examples for Collections methods. (#1726)
Browse files Browse the repository at this point in the history 
* 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>
  • Loading branch information
@romanbalayan
romanbalayan and Roman Balayan authored Aug 5, 2021
1 parent 89255fe commit 159a119
Show file tree
Hide file tree
Showing 40 changed files with 5,267 additions and 637 deletions.
88 changes: 77 additions & 11 deletions docs/v3/auto.js.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,15 +121,40 @@ <h1 class="page-title">auto.js</h1>
* @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, &apos;data.txt&apos;, &apos;utf-8&apos;),
* showData: [&apos;readData&apos;, function(results, cb) {
* // results.readData is the file&apos;s contents
* // ...
* get_data: function(callback) {
* // async code to get some data
* callback(null, &apos;data&apos;, &apos;converted to array&apos;);
* },
* 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, &apos;folder&apos;);
* },
* write_file: [&apos;get_data&apos;, &apos;make_folder&apos;, function(results, callback) {
* // once there is some data and the directory exists,
* // write the data to a file in the directory
* callback(null, &apos;filename&apos;);
* }],
* email_link: [&apos;write_file&apos;, function(results, callback) {
* // once the file is written let&apos;s email a link to it...
* callback(null, {&apos;file&apos;:results.write_file, &apos;email&apos;:&apos;user@example.com&apos;});
* }]
* }, callback);
* }, function(err, results) {
* if (err) {
* console.log(&apos;err = &apos;, err);
* }
* console.log(&apos;results = &apos;, results);
* // results = {
* // get_data: [&apos;data&apos;, &apos;converted to array&apos;]
* // make_folder; &apos;folder&apos;,
* // write_file: &apos;filename&apos;
* // email_link: { file: &apos;filename&apos;, email: &apos;user@example.com&apos; }
* // }
* });
*
* //Using Promises
* async.auto({
* get_data: function(callback) {
* console.log(&apos;in get_data&apos;);
Expand All @@ -143,21 +168,62 @@ <h1 class="page-title">auto.js</h1>
* callback(null, &apos;folder&apos;);
* },
* write_file: [&apos;get_data&apos;, &apos;make_folder&apos;, function(results, callback) {
* console.log(&apos;in write_file&apos;, JSON.stringify(results));
* // once there is some data and the directory exists,
* // write the data to a file in the directory
* callback(null, &apos;filename&apos;);
* }],
* email_link: [&apos;write_file&apos;, function(results, callback) {
* console.log(&apos;in email_link&apos;, JSON.stringify(results));
* // once the file is written let&apos;s email a link to it...
* // results.write_file contains the filename returned by write_file.
* callback(null, {&apos;file&apos;:results.write_file, &apos;email&apos;:&apos;user@example.com&apos;});
* }]
* }, function(err, results) {
* console.log(&apos;err = &apos;, err);
* }).then(results =&gt; {
* console.log(&apos;results = &apos;, results);
* // results = {
* // get_data: [&apos;data&apos;, &apos;converted to array&apos;]
* // make_folder; &apos;folder&apos;,
* // write_file: &apos;filename&apos;
* // email_link: { file: &apos;filename&apos;, email: &apos;user@example.com&apos; }
* // }
* }).catch(err =&gt; {
* console.log(&apos;err = &apos;, err);
* });
*
* //Using async/await
* async () =&gt; {
* try {
* let results = await async.auto({
* get_data: function(callback) {
* // async code to get some data
* callback(null, &apos;data&apos;, &apos;converted to array&apos;);
* },
* 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, &apos;folder&apos;);
* },
* write_file: [&apos;get_data&apos;, &apos;make_folder&apos;, function(results, callback) {
* // once there is some data and the directory exists,
* // write the data to a file in the directory
* callback(null, &apos;filename&apos;);
* }],
* email_link: [&apos;write_file&apos;, function(results, callback) {
* // once the file is written let&apos;s email a link to it...
* callback(null, {&apos;file&apos;:results.write_file, &apos;email&apos;:&apos;user@example.com&apos;});
* }]
* });
* console.log(&apos;results = &apos;, results);
* // results = {
* // get_data: [&apos;data&apos;, &apos;converted to array&apos;]
* // make_folder; &apos;folder&apos;,
* // write_file: &apos;filename&apos;
* // email_link: { file: &apos;filename&apos;, email: &apos;user@example.com&apos; }
* // }
* }
* catch (err) {
* console.log(err);
* }
* }
*
*/
export default function auto(tasks, concurrency, callback) {
if (typeof concurrency !== &apos;number&apos;) {
Expand Down
72 changes: 70 additions & 2 deletions docs/v3/concat.js.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,9 +100,77 @@ <h1 class="page-title">concat.js</h1>
* @returns A Promise, if no callback is passed
* @example
*
* async.concat([&apos;dir1&apos;,&apos;dir2&apos;,&apos;dir3&apos;], 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 = [&apos;dir1&apos;,&apos;dir2&apos;,&apos;dir3&apos;];
* let withMissingDirectoryList = [&apos;dir1&apos;,&apos;dir2&apos;,&apos;dir3&apos;, &apos;dir4&apos;];
*
* // Using callbacks
* async.concat(directoryList, fs.readdir, function(err, results) {
* if (err) {
* console.log(err);
* } else {
* console.log(results);
* // [ &apos;file1.txt&apos;, &apos;file2.txt&apos;, &apos;file3.txt&apos;, &apos;file4.txt&apos;, 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 =&gt; {
* console.log(results);
* // [ &apos;file1.txt&apos;, &apos;file2.txt&apos;, &apos;file3.txt&apos;, &apos;file4.txt&apos;, file5.txt ]
* }).catch(err =&gt; {
* console.log(err);
* });
*
* // Error Handling
* async.concat(withMissingDirectoryList, fs.readdir)
* .then(results =&gt; {
* console.log(results);
* }).catch(err =&gt; {
* console.log(err);
* // [ Error: ENOENT: no such file or directory ]
* // since dir4 does not exist
* });
*
* // Using async/await
* async () =&gt; {
* try {
* let results = await async.concat(directoryList, fs.readdir);
* console.log(results);
* // [ &apos;file1.txt&apos;, &apos;file2.txt&apos;, &apos;file3.txt&apos;, &apos;file4.txt&apos;, file5.txt ]
* } catch (err) {
* console.log(err);
* }
* }
*
* // Error Handling
* async () =&gt; {
* 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)
Expand Down
45 changes: 40 additions & 5 deletions docs/v3/detect.js.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -107,13 +107,48 @@ <h1 class="page-title">detect.js</h1>
* @returns A Promise, if no callback is passed
* @example
*
* async.detect([&apos;file1&apos;,&apos;file2&apos;,&apos;file3&apos;], 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) =&gt; {
* callback(null, !err);
* });
* }
*
* async.detect([&apos;file3.txt&apos;,&apos;file2.txt&apos;,&apos;dir1/file1.txt&apos;], 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([&apos;file3.txt&apos;,&apos;file2.txt&apos;,&apos;dir1/file1.txt&apos;], fileExists)
* .then(result =&gt; {
* console.log(result);
* // dir1/file1.txt
* // result now equals the first file in the list that exists
* }).catch(err =&gt; {
* console.log(err);
* });
*
* // Using async/await
* async () =&gt; {
* try {
* let result = await async.detect([&apos;file3.txt&apos;,&apos;file2.txt&apos;,&apos;dir1/file1.txt&apos;], 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 =&gt; bool, (res, item) =&gt; item)(eachOf, coll, iteratee, callback)
Expand Down
Loading

0 comments on commit 159a119

Please sign in to comment.