domain: support promises

Fixes: https://github.com/nodejs/node/issues/10724
PR-URL: https://github.com/nodejs/node/pull/12489
Reviewed-By: Matthew Loring <mattloring@google.com>
Reviewed-By: Julien Gilli <jgilli@nodejs.org>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

1 files changed, 50 insertions, 0 deletions

diff --git a/doc/api/domain.md b/doc/api/domain.md
index eb04987f08..4ada1c2ca0 100644
--- a/doc/api/domain.md
+++ b/doc/api/domain.md
@@ -1,4 +1,11 @@
 # Domain
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/12489
+    description: Handlers for `Promise`s are now invoked in the domain in which
+                 the first promise of a chain was created.
+-->
 
 > Stability: 0 - Deprecated
 
@@ -444,6 +451,49 @@ d.run(() => {
 In this example, the `d.on('error')` handler will be triggered, rather
 than crashing the program.
 
+## Domains and Promises
+
+As of Node REPLACEME, the handlers of Promises are run inside the domain in
+which the call to `.then` or `.catch` itself was made:
+
+```js
+const d1 = domain.create();
+const d2 = domain.create();
+
+let p;
+d1.run(() => {
+  p = Promise.resolve(42);
+});
+
+d2.run(() => {
+  p.then((v) => {
+    // running in d2
+  });
+});
+```
+
+A callback may be bound to a specific domain using [`domain.bind(callback)`][]:
+
+```js
+const d1 = domain.create();
+const d2 = domain.create();
+
+let p;
+d1.run(() => {
+  p = Promise.resolve(42);
+});
+
+d2.run(() => {
+  p.then(p.domain.bind((v) => {
+    // running in d1
+  }));
+});
+```
+
+Note that domains will not interfere with the error handling mechanisms for
+Promises, i.e. no `error` event will be emitted for unhandled Promise
+rejections.
+
 [`domain.add(emitter)`]: #domain_domain_add_emitter
 [`domain.bind(callback)`]: #domain_domain_bind_callback
 [`domain.dispose()`]: #domain_domain_dispose