No public weak reference API for `JsObject`

[jerry4718]

Summary

There is currently no way for an embedder to hold a weak reference to a JsObject.
The GC types WeakGc and Ephemeron are public, but they require &Gc<T> to construct,
and the only path from JsObject to its inner Gc<VTableObject<T>> — the inner() method — is pub(crate).
This leaves embedders without any mechanism to observe object liveness without keeping strong references that prevent collection.

The problem

Consider an embedder that maintains a Rust-side cache keyed by JS objects.
The cache should not keep JS objects alive on its own. When a JS object becomes unreachable and is collected by the GC, the corresponding cache entry should become invalid.

This requires a weak reference to JsObject: the ability to check whether the object is still alive, and to upgrade back to a strong JsObject when it is.

What is available

• WeakGc<T> and Ephemeron<K, V> are pub in boa_gc.
• WeakGc::upgrade() returns Option<Gc<T>> — exactly the right semantics.
• WeakGc::new() requires &Gc<T>.

What is blocked

• JsObject::inner() is pub(crate):

// core/engine/src/object/jsobject.rs:1041
pub(crate) fn inner(&self) -> &Gc<VTableObject<T>> {
    &self.inner
}

• JsObject::from_inner() is also pub(crate):

// core/engine/src/object/jsobject.rs:1045
pub(crate) fn from_inner(inner: Gc<VTableObject<T>>) -> Self {
    Self { inner }
}

• VTableObject itself is pub(crate).

So an external crate cannot write the type Gc<VTableObject<...>>, cannot call inner() to get it, and cannot call from_inner() to convert back. The entire WeakGc / Ephemeron API is unreachable for JsObject.

Where weak references are used today

FinalizationRegistry and WeakRef both use weak references inside boa_engine, where pub(crate) is accessible:

// finalization_registry/mod.rs
WeakGc::new(obj.inner())        // accessible within boa_engine
Ephemeron::new(target_obj.inner(), ...)  // accessible within boa_engine

This means the existing weak reference infrastructure is exercised internally, but is not currently reachable from external crates.

Why this matters

Without a weak reference API, embedders who need Rust-side structures keyed by JS objects have two options, neither of which is sound:

1. Hold strong JsObject references. This prevents GC collection, leading to memory leaks.

2. Store raw pointers via transmute or similar. This breaks GC safety: the pointer may dangle after collection, ref_count becomes inconsistent, and casting back to JsObject can trigger use-after-free or ref_count underflow.

Questions

• Is the absence of a public weak reference API for JsObject an intentional design decision, or something that hasn't been needed yet?
• If it is intentional, what approach would you recommend for embedders who need to observe object liveness without preventing GC collection?
• Is there any thoughts on exposing this kind of functionality in the future, or should embedders plan to maintain a fork for now?

[jedel1043]

We just haven't gotten a use case for it tbh. The design would seem to be straightforward enough, just create a WeakJsObject or something like that, so this should be free to be picked up by anyone :)

[jerry4718]

Wow, that's wonderful!

We just haven't gotten a use case for it tbh

I am building a toy project based on Blitz and Boa. When attempting to implement document.querySelector (modeled after the DOM API), I need to ensure that accessing the same node yields the same reference on the JavaScript side. I want to avoid using FinalizationRegistry in JavaScript to track garbage collection; doing so would shift the center of gravity for the DOM API toward JavaScript and necessitate callbacks to Rust to reclaim the underlying Blitz DOM nodes. Handling this directly in Rust would result in vastly different performance characteristics.

I don't know if these might offer some ...

[GordonYuanyc]

Hi! I'd like to claim this issue, per CONTRIBUTING.md. I'm a student in CodePath's open-source program and this one looked genuinely interesting, so I'd like to try it.

Reading through the code, the mechanism already exists and ships. WeakGc::new / upgrade / is_upgradable are public in core/gc/src/pointers/weak.rs, and the JS-level WeakRef builtin already constructs one at core/engine/src/builtins/weak/weak_ref.rs:90 via WeakGc::new(target.inner()). The only thing stopping an embedder from doing the same is that JsObject::inner() is pub(crate) (core/engine/src/object/jsobject.rs:1041), so there is no way to get the &Gc<VTableObject<T>> that WeakGc::new needs.

Following @jedel1043's suggestion, I'd add a WeakJsObject wrapping WeakGc<VTableObject<T>>, with new / upgrade / is_upgradable plus Clone / PartialEq / Eq / Hash mirroring WeakGc. Hash and Eq look load-bearing here, since without them you can't key a HashMap on the weak reference, which is the cache use case described above.

Two questions before I start:

1. Naming: I'd avoid JsWeakRef, since the Js* prefix in core/engine/src/object/builtins/ (JsWeakMap, JsWeakSet) seems to mean "Rust wrapper around a JS builtin object", and this isn't one. Does WeakJsObject sound right?
2. Scope: would you want the WeakRef builtin refactored onto the new type, or is that better as a follow-up?

[GordonYuanyc]

Hi! There is an implementation in #5437, currently open for review. Thank you!