doc: clarify ObjectWrap weak ref behavior

mildsunrise · web-flow · commit 6b8892a588a3 · 2022-03-25T03:14:36.000+01:00
Refs: nodejs/node#42461 We currently defer finalizer callbacks until the loop is idle. Warn users that the weak reference on ObjectWraps isn't guaranteed to be valid just because the object hasn't been finalized (destructed) yet.
diff --git a/doc/object_wrap.md b/doc/object_wrap.md
@@ -16,6 +16,10 @@ be directly invoked from JavaScript. The **wrap** word refers to a way of
 grouping methods and state of the class because it will be necessary write
 custom code to bridge each of your C++ class methods.
 
+**Caution:** When the JavaScript object is garbage collected, the call to the
+C++ destructor may be deferred until a later time. Within that period,
+`Value()` will return an empty value.
+
 ## Example
 
 ```cpp
