nodejs/promises

Document how promises work

benjamingr opened this issue · 6 comments

benjamingr commented

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 commented

+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 commented

I would be happy to work on this.

MadaraUchiha commented

Perhaps, common patterns like

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

Or would that be too broad?

kriskowal commented

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
#7 (comment).

petkaantonov commented

@kriskowal this is very good, thanks for posting it

chrisdickinson commented

@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.