doc: clarify napi_finalize behavior

mildsunrise · web-flow · commit 01a230032b99 · 2022-03-27T14:57:13.000+01:00
We currently defer finalizer callbacks until the loop is idle. Warn users that the weak reference returned by napi_wrap() isn't guaranteed to be valid just because the finalizer hasn't yet been called. PR-URL: #42461 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Tierney Cyren <hello@bnb.im> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/doc/api/n-api.md b/doc/api/n-api.md
@@ -5123,6 +5123,11 @@ invocation. If it is deleted before then, then the finalize callback may never
 be invoked. Therefore, when obtaining a reference a finalize callback is also
 required in order to enable correct disposal of the reference.
 
+Finalizer callbacks may be deferred, leaving a window where the object has
+been garbage collected (and the weak reference is invalid) but the finalizer
+hasn't been called yet. When using `napi_get_reference_value()` on weak
+references returned by `napi_wrap()`, you should still handle an empty result.
+
 Calling `napi_wrap()` a second time on an object will return an error. To
 associate another native instance with the object, use `napi_remove_wrap()`
 first.
