Documentation needs better examples

[joshuambg]

Consider this example for map

async.map(['file1','file2','file3'], fs.stat, function(err, results) {
    // results is now an array of stats for each file
});

This basically tells me nothing except syntax. In most cases people aren't going to pass fs.stat. The examples should include use of all possible options. All examples for all functions and methods need to be updated. They are too simplistic

[aearly]

I agree, we need much better docs. I'd also like to change many of the examples (or add mroe examples) to use async/await. However, this is something that takes time I don't have at the moment.

[mayur-gupta]

Maybe I can help.

[siniestro-mx]

How can I help with examples?

[aearly]

• Examples with more async/await, less with callbacks
• More concrete examples from real-world applications, less foo/bar
• Things that show the "sweet spot" for Async -- things that are hard to do without the library
• Examples the are accessible to newcomers to Node/JS that show how parameters flow through
• More comprehensive examples showing more features of individual methods

There are @example blocks in the JSDoc comments for most methods. Go nuts!

[caub]

note for that particular example, you could do

await async.map(['file1','file2','file3'], fs.promises.stat);
// or without async lib
await Promise.all(['file1','file2','file3'].map(name => fs.promises.stat(name))

or if you want an object as result

await async.auto({
  file1: async()=>fs.promises.stat('file1'),
  file2: async()=>fs.promises.stat('file2')
  file3: async()=>fs.promises.stat('file3')
})
// or without async lib
Object.fromEntries(
  await Promise.all(['file1','file2','file3'].map(async name => [name, await fs.promises.stat(name)]))
)

[flatcoding]

I'm in particular looking for a (simple) Promise-based example of async.mapLimit, even without async/await. Haven't found any non-callback example so far at all.

[caub]

@flatcoding https://github.com/caub/misc/blob/master/utils/promise-concurrent.js, if you don't want await, you can replace it by a recursive function

[flatcoding]

Hi Cyril @caub,
thanks for your reply. I'm not particularly against 'await', rather for the sake of 'good examples' for the 'async' module I'd like to start with and see an implementation with basic Promise handling, including .then .catch.
I honestly struggle using async with Promises in general, so before using async/await I'd just like to start with step 1) ...
Btw., thanks for sharing your example, I'm not perfectly sure though how it relates to the async module.

[caub]

I thought by "simple Promise-based example", you meant an example without any library

if you wanted an example with this library, I'm sure there are plenty

[flatcoding]

Right, so I'm fine in general with using Promises, and also I understand how to use the 'async' modules in callback style. As documentation states, without callbacks supplied it would return a Promise. So far, I couldn't fine examples, not for async.map(Limit) at least. As this thread is about 'better examples' in the documentation, I chimed in on this here...
And as said, I really couldn't get it up and running with a Promise either, even raised an issue on that.

[romanbalayan]

Hi @caub, took a shot at improving the docs for collection methods, adding use cases for callbacks, Promises, and async/await.

[caub]

@romanbalayan nice

the methods we use the most are async.parallel, and async.auto, do you plan to cover those too?

note: I think you could avoid the async IIFE (async ()=>{ in async/await examples, to make things lighter