doc: add troubleshooting guide for AsyncLocalStorage

PR-URL: #33248 Reviewed-By: Chengzhong Wu <[email protected]> Reviewed-By: Gerhard Stöbich <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]>
nodejs · Jun 7, 2020 · ad7a890 · ad7a890
1 parent 2262962
commit ad7a890
Showing 1 changed file with 16 additions and 0 deletions.
diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md
@@ -1085,6 +1085,21 @@ In this example, the store is only available in the callback function and the
 functions called by `foo`. Outside of `run`, calling `getStore` will return
 `undefined`.
 
+### Troubleshooting
+
+In most cases your application or library code should have no issues with
+`AsyncLocalStorage`. But in rare cases you may face situations when the
+current store is lost in one of asynchronous operations. Then you should
+consider the following options.
+
+If your code is callback-based, it is enough to promisify it with
+[`util.promisify()`][], so it starts working with native promises.
+
+If you need to keep using callback-based API, or your code assumes
+a custom thenable implementation, you should use [`AsyncResource`][] class
+to associate the asynchronous operation with the correct execution context.
+
+[`AsyncResource`]: #async_hooks_class_asyncresource
 [`after` callback]: #async_hooks_after_asyncid
 [`before` callback]: #async_hooks_before_asyncid
 [`destroy` callback]: #async_hooks_destroy_asyncid
@@ -1094,3 +1109,4 @@ functions called by `foo`. Outside of `run`, calling `getStore` will return
 [PromiseHooks]: https://docs.google.com/document/d/1rda3yKGHimKIhg5YeoAmCOtyURgsbTH_qaYR79FELlk/edit
 [`Worker`]: worker_threads.html#worker_threads_class_worker
 [promise execution tracking]: #async_hooks_promise_execution_tracking
+[`util.promisify()`]: util.html#util_util_promisify_original