feat: implement ES2021 WeakRef and FinalizationRegistry

Adds complete ES2021 WeakRef and FinalizationRegistry implementations to Rhino.

WeakRef:
- Constructor and deref() method for weak references to objects
- Prevents memory leaks in caches and mappings
- Follows ES2021 specification for object-only targets

FinalizationRegistry:
- register() for cleanup callback registration
- unregister() for removal by token
- cleanupSome() for manual cleanup triggering
- Thread-safe implementation using Java WeakReference/ReferenceQueue

Implementation follows Rhino patterns:
- LambdaConstructor for native object construction
- realThis pattern for method validation
- Proper Context management for callbacks

Tests: 98% pass rate (83/84 tests passing)

Closes #943

Author: anivar

rhino/src/main/java/org/mozilla/javascript/NativeFinalizationRegistry.java

@@ -0,0 +1,102 @@
+/* -*- Mode: java; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+package org.mozilla.javascript;
+
+import java.lang.ref.WeakReference;
+
+/**
+ * Implementation of the ES2021 WeakRef constructor and prototype.
+ *
+ * <p>WeakRef allows holding a weak reference to an object without preventing its garbage
+ * collection. This is useful for caches, mappings, or any scenario where you want to reference an
+ * object without keeping it alive.
+ *
+ * <p>The WeakRef object provides a single method, deref(), which returns the referenced object if
+ * it's still alive, or undefined if it has been collected.
+ *
+ * @see <a href="https://tc39.es/ecma262/#sec-weak-ref-objects">ECMAScript WeakRef Objects</a>
+ */
+public class NativeWeakRef extends ScriptableObject {
+    private static final long serialVersionUID = 1L;
+    private static final String CLASS_NAME = "WeakRef";
+
+    private boolean instanceOfWeakRef = false;
+    private WeakReference<Object> weakReference;
+
+    static Object init(Context cx, Scriptable scope, boolean sealed) {
+        LambdaConstructor constructor =
+                new LambdaConstructor(
+                        scope,
+                        CLASS_NAME,
+                        1,
+                        LambdaConstructor.CONSTRUCTOR_NEW,
+                        NativeWeakRef::jsConstructor);
+        constructor.setPrototypePropertyAttributes(DONTENUM | READONLY | PERMANENT);
+
+        constructor.definePrototypeMethod(
+                scope,
+                "deref",
+                0,
+                (Context lcx, Scriptable lscope, Scriptable thisObj, Object[] args) ->
+                        realThis(thisObj, "deref").js_deref(),
+                DONTENUM,
+                DONTENUM | READONLY);
+
+        constructor.definePrototypeProperty(
+                SymbolKey.TO_STRING_TAG, CLASS_NAME, DONTENUM | READONLY);
+
+        if (sealed) {
+            constructor.sealObject();
+            ((ScriptableObject) constructor.getPrototypeProperty()).sealObject();
+        }
+        return constructor;
+    }
+
+    private static Scriptable jsConstructor(Context cx, Scriptable scope, Object[] args) {
+        if (args.length < 1) {
+            throw ScriptRuntime.typeErrorById("msg.weakref.no.target");
+        }
+
+        Object target = args[0];
+        if (!canBeHeldWeakly(target)) {
+            throw ScriptRuntime.typeErrorById("msg.weakref.target.not.object");
+        }
+
+        NativeWeakRef ref = new NativeWeakRef();
+        ref.instanceOfWeakRef = true;
+        ref.weakReference = new WeakReference<>(target);
+        return ref;
+    }
+
+    private static boolean canBeHeldWeakly(Object target) {
+        // ES2021: Only objects can be held weakly in WeakRef
+        return ScriptRuntime.isObject(target);
+    }
+
+    private static NativeWeakRef realThis(Scriptable thisObj, String name) {
+        if (thisObj instanceof NativeWeakRef) {
+            NativeWeakRef ref = (NativeWeakRef) thisObj;
+            if (ref.instanceOfWeakRef) {
+                return ref;
+            }
+        }
+        throw ScriptRuntime.typeErrorById("msg.incompat.call", name);
+    }
+
+    private Object js_deref() {
+        if (weakReference == null) {
+            return Undefined.instance;
+        }
+        Object target = weakReference.get();
+        return (target == null) ? Undefined.instance : target;
+    }
+
+    @Override
+    public String getClassName() {
+        return CLASS_NAME;
+    }
+}

rhino/src/main/java/org/mozilla/javascript/NativeWeakRef.java

@@ -265,6 +265,13 @@ public static ScriptableObject initSafeStandardObjects(
             new LazilyLoadedCtor(scope, "Reflect", sealed, true, NativeReflect::init);
         }
 
+        // ES2021 features
+        if (cx.getLanguageVersion() >= Context.VERSION_ES6) {
+            new LazilyLoadedCtor(scope, "WeakRef", sealed, true, NativeWeakRef::init);
+            new LazilyLoadedCtor(
+                    scope, "FinalizationRegistry", sealed, true, NativeFinalizationRegistry::init);
+        }
+
         if (scope instanceof TopLevel) {
             ((TopLevel) scope).cacheBuiltins(scope, sealed);
         }

rhino/src/main/java/org/mozilla/javascript/ScriptRuntime.java

@@ -1021,6 +1021,22 @@ msg.promise.all.toobig =\
 msg.promise.any.toobig =\
   Too many inputs to Promise.any
 
+# WeakRef and FinalizationRegistry
+msg.weakref.no.target =\
+  WeakRef constructor requires an object argument
+
+msg.weakref.target.not.object =\
+  WeakRef target must be an object
+
+msg.finalization.registry.no.callback =\
+  FinalizationRegistry constructor requires a function argument
+
+msg.finalization.registry.register.not.object =\
+  FinalizationRegistry.register: target must be an object
+
+msg.finalization.registry.register.same.target =\
+  FinalizationRegistry.register: target and heldValue must not be the same object
+
 msg.typed.array.receiver.incompatible = \
   Method %TypedArray%.{0} called on incompatible receiver
 

rhino/src/main/resources/org/mozilla/javascript/resources/Messages.properties

@@ -0,0 +1,191 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+package org.mozilla.javascript.tests.es2021;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.util.concurrent.ConcurrentHashMap;
+import org.junit.Test;
+import org.mozilla.javascript.Context;
+import org.mozilla.javascript.Function;
+import org.mozilla.javascript.NativeFinalizationRegistry;
+import org.mozilla.javascript.Scriptable;
+import org.mozilla.javascript.ScriptableObject;
+import org.mozilla.javascript.Undefined;
+
+/**
+ * Internal tests for FinalizationRegistry using reflection to test private methods. These are
+ * "white box" tests as requested by reviewer.
+ */
+public class FinalizationRegistryInternalTest {
+
+    @Test
+    public void testProcessPendingCleanupsMethod() throws Exception {
+        try (Context cx = Context.enter()) {
+            cx.setLanguageVersion(Context.VERSION_ES6);
+            Scriptable scope = cx.initStandardObjects();
+
+            // Create a FinalizationRegistry
+            String script = "new FinalizationRegistry(function(heldValue) {})";
+            Object registry = cx.evaluateString(scope, script, "test", 1, null);
+            assertTrue(registry instanceof NativeFinalizationRegistry);
+
+            // Use reflection to access processPendingCleanups method
+            Method method =
+                    NativeFinalizationRegistry.class.getDeclaredMethod("processPendingCleanups");
+            method.setAccessible(true);
+
+            // Should not throw exception
+            method.invoke(registry);
+        }
+    }
+
+    @Test
+    public void testRegistrationsMapInitialization() throws Exception {
+        try (Context cx = Context.enter()) {
+            cx.setLanguageVersion(Context.VERSION_ES6);
+            Scriptable scope = cx.initStandardObjects();
+
+            // Create a FinalizationRegistry
+            String script = "new FinalizationRegistry(function(heldValue) {})";
+            Object registry = cx.evaluateString(scope, script, "test", 1, null);
+            assertTrue(registry instanceof NativeFinalizationRegistry);
+
+            // Use reflection to access registrations field
+            Field field = NativeFinalizationRegistry.class.getDeclaredField("registrations");
+            field.setAccessible(true);
+            Object registrations = field.get(registry);
+
+            assertNotNull(registrations);
+            assertTrue(registrations instanceof ConcurrentHashMap);
+            assertEquals(0, ((ConcurrentHashMap<?, ?>) registrations).size());
+        }
+    }
+
+    @Test
+    public void testTokenMapInitialization() throws Exception {
+        try (Context cx = Context.enter()) {
+            cx.setLanguageVersion(Context.VERSION_ES6);
+            Scriptable scope = cx.initStandardObjects();
+
+            // Create a FinalizationRegistry
+            String script = "new FinalizationRegistry(function(heldValue) {})";
+            Object registry = cx.evaluateString(scope, script, "test", 1, null);
+            assertTrue(registry instanceof NativeFinalizationRegistry);
+
+            // Use reflection to access tokenMap field
+            Field field = NativeFinalizationRegistry.class.getDeclaredField("tokenMap");
+            field.setAccessible(true);
+            Object tokenMap = field.get(registry);
+
+            assertNotNull(tokenMap);
+            assertTrue(tokenMap instanceof ConcurrentHashMap);
+            assertEquals(0, ((ConcurrentHashMap<?, ?>) tokenMap).size());
+        }
+    }
+
+    @Test
+    public void testCleanupCallbackStorage() throws Exception {
+        try (Context cx = Context.enter()) {
+            cx.setLanguageVersion(Context.VERSION_ES6);
+            Scriptable scope = cx.initStandardObjects();
+
+            // Create a FinalizationRegistry
+            String script =
+                    "var callback = function(heldValue) {}; new FinalizationRegistry(callback)";
+            Object registry = cx.evaluateString(scope, script, "test", 1, null);
+            assertTrue(registry instanceof NativeFinalizationRegistry);
+
+            // Use reflection to access cleanupCallback field
+            Field field = NativeFinalizationRegistry.class.getDeclaredField("cleanupCallback");
+            field.setAccessible(true);
+            Object cleanupCallback = field.get(registry);
+
+            assertNotNull(cleanupCallback);
+            assertTrue(cleanupCallback instanceof Function);
+        }
+    }
+
+    @Test
+    public void testExecuteCleanupCallbackMethod() throws Exception {
+        try (Context cx = Context.enter()) {
+            cx.setLanguageVersion(Context.VERSION_ES6);
+            Scriptable scope = cx.initStandardObjects();
+
+            // Create a FinalizationRegistry with a callback that sets a flag
+            String script =
+                    "var called = false;"
+                            + "var callback = function(heldValue) { called = true; };"
+                            + "new FinalizationRegistry(callback)";
+            Object registry = cx.evaluateString(scope, script, "test", 1, null);
+            assertTrue(registry instanceof NativeFinalizationRegistry);
+
+            // Use reflection to call executeCleanupCallback
+            Method method =
+                    NativeFinalizationRegistry.class.getDeclaredMethod(
+                            "executeCleanupCallback", Object.class);
+            method.setAccessible(true);
+            method.invoke(registry, "test value");
+
+            // Check if callback was called
+            Object called = ScriptableObject.getProperty(scope, "called");
+            assertEquals(Boolean.TRUE, called);
+        }
+    }
+
+    @Test
+    public void testPerformCleanupSomeMethod() throws Exception {
+        try (Context cx = Context.enter()) {
+            cx.setLanguageVersion(Context.VERSION_ES6);
+            Scriptable scope = cx.initStandardObjects();
+
+            // Create a FinalizationRegistry
+            String script = "new FinalizationRegistry(function(heldValue) {})";
+            Object registry = cx.evaluateString(scope, script, "test", 1, null);
+            assertTrue(registry instanceof NativeFinalizationRegistry);
+
+            // Use reflection to access performCleanupSome method
+            Method method =
+                    NativeFinalizationRegistry.class.getDeclaredMethod(
+                            "performCleanupSome", Context.class, Function.class);
+            method.setAccessible(true);
+
+            // Should not throw exception
+            method.invoke(registry, cx, null);
+        }
+    }
+
+    @Test
+    public void testIsValidTargetMethod() throws Exception {
+        // Use reflection to test the static isValidTarget method
+        Method method =
+                NativeFinalizationRegistry.class.getDeclaredMethod("isValidTarget", Object.class);
+        method.setAccessible(true);
+
+        try (Context cx = Context.enter()) {
+            cx.setLanguageVersion(Context.VERSION_ES6);
+            Scriptable scope = cx.initStandardObjects();
+
+            // Test with valid object
+            Object obj = cx.evaluateString(scope, "({})", "test", 1, null);
+            assertTrue((Boolean) method.invoke(null, obj));
+
+            // Test with undefined
+            assertEquals(false, method.invoke(null, Undefined.instance));
+
+            // Test with null
+            assertEquals(false, method.invoke(null, new Object[] {null}));
+
+            // Test with primitive wrapped as Object
+            assertEquals(false, method.invoke(null, "string"));
+            assertEquals(false, method.invoke(null, 42));
+            assertEquals(false, method.invoke(null, true));
+        }
+    }
+}