Document how promises work

[benjamingr]

We should document in this repo how promises work with several examples.

• How chaining and combining promises looks like in a typical Node program.
• How a typical error handling flow looks like in a promise based NodeJS server.
• How debugging is performed.
• What hooks are available and what are important.
• Userland solutions.

This would help communication and allow people who are not domain experts to better get acquainted and get involved in the WG.

[spion]

+1

Another thing that can be discussed is safe resource and state management in the face of errors using finally (and patterns that can be built on top of it)

[chrisdickinson]

I would be happy to work on this.

[MadaraUchiha]

Perhaps, common patterns like

Promise.all(arrayOfData.map(promisingAction)).then(allDataResult => {
  // use
});

Or would that be too broad?

[kriskowal]

This is the approach I took to explaining how promise libraries are designed (partially):

https://github.com/kriskowal/q/blob/v1/design/README.js

On Mon, Feb 15, 2016 at 12:45 PM Madara Uchiha notifications@github.com wrote:

Perhaps, common patterns like

Promise.all(arrayOfData.map(promisingAction)).then(allDataResult => { // use });

Or would that be too broad?

— Reply to this email directly or view it on GitHub https://github.com/nodejs/promises/issues/7#issuecomment-184386788.

[petkaantonov]

@kriskowal this is very good, thanks for posting it

[chrisdickinson]

@kriskowal Thanks! I will definitely draw from this. I am leaning towards making an easily digestible, 300-500 word guide that describes how promises are commonly used by users, including async/await examples alongside raw promise use — the goal is to convey the core use cases of promises. As a separate guide I will try to document how promises are implemented in V8 so we have a common understanding there.