[bun:jsc] expose `getProtectedObjects` gc hook

2 files changed, 40 insertions, 2 deletions

diff --git a/src/bun.js/bindings/BunJSCModule.cpp b/src/bun.js/bindings/BunJSCModule.cpp
index 027cb3778..b81f2db93 100644
--- a/src/bun.js/bindings/BunJSCModule.cpp
+++ b/src/bun.js/bindings/BunJSCModule.cpp
@@ -289,6 +289,19 @@ JSC_DEFINE_HOST_FUNCTION(functionTotalCompileTime, (JSGlobalObject*, CallFrame*)
     return JSValue::encode(jsNumber(JIT::totalCompileTime().milliseconds()));
 }
 
+JSC_DECLARE_HOST_FUNCTION(functionGetProtectedObjects);
+JSC_DEFINE_HOST_FUNCTION(functionGetProtectedObjects, (JSGlobalObject * globalObject, CallFrame*))
+{
+    MarkedArgumentBuffer list;
+    size_t result = 0;
+    globalObject->vm().heap.forEachProtectedCell(
+        [&](JSCell* cell) {
+            list.append(cell);
+        });
+    RELEASE_ASSERT(!list.hasOverflowed());
+    return JSC::JSValue::encode(constructArray(globalObject, static_cast<JSC::ArrayAllocationProfile*>(nullptr), list));
+}
+
 JSC_DECLARE_HOST_FUNCTION(functionReoptimizationRetryCount);
 JSC_DEFINE_HOST_FUNCTION(functionReoptimizationRetryCount, (JSGlobalObject*, CallFrame* callFrame))
 {
@@ -320,7 +333,7 @@ JSC::JSObject* createJSCModule(JSC::JSGlobalObject* globalObject)
 
     {
         JSC::ObjectInitializationScope initializationScope(vm);
-        object = JSC::constructEmptyObject(globalObject, globalObject->objectPrototype(), 21);
+        object = JSC::constructEmptyObject(globalObject, globalObject->objectPrototype(), 22);
         object->putDirectNativeFunction(vm, globalObject, JSC::Identifier::fromString(vm, "callerSourceOrigin"_s), 1, functionCallerSourceOrigin, NoIntrinsic, JSC::PropertyAttribute::ReadOnly | JSC::PropertyAttribute::DontDelete | 0);
         object->putDirectNativeFunction(vm, globalObject, JSC::Identifier::fromString(vm, "describe"_s), 1, functionDescribe, NoIntrinsic, JSC::PropertyAttribute::ReadOnly | JSC::PropertyAttribute::DontDelete | 0);
         object->putDirectNativeFunction(vm, globalObject, JSC::Identifier::fromString(vm, "describeArray"_s), 1, functionDescribeArray, NoIntrinsic, JSC::PropertyAttribute::ReadOnly | JSC::PropertyAttribute::DontDelete | 0);
@@ -342,6 +355,7 @@ JSC::JSObject* createJSCModule(JSC::JSGlobalObject* globalObject)
         object->putDirectNativeFunction(vm, globalObject, JSC::Identifier::fromString(vm, "setRandomSeed"_s), 1, functionSetRandomSeed, NoIntrinsic, JSC::PropertyAttribute::ReadOnly | JSC::PropertyAttribute::DontDelete | 0);
         object->putDirectNativeFunction(vm, globalObject, JSC::Identifier::fromString(vm, "startRemoteDebugger"_s), 2, functionStartRemoteDebugger, NoIntrinsic, JSC::PropertyAttribute::ReadOnly | JSC::PropertyAttribute::DontDelete | 0);
         object->putDirectNativeFunction(vm, globalObject, JSC::Identifier::fromString(vm, "totalCompileTime"_s), 1, functionTotalCompileTime, NoIntrinsic, JSC::PropertyAttribute::ReadOnly | JSC::PropertyAttribute::DontDelete | 0);
+        object->putDirectNativeFunction(vm, globalObject, JSC::Identifier::fromString(vm, "getProtectedObjects"_s), 1, functionGetProtectedObjects, NoIntrinsic, JSC::PropertyAttribute::ReadOnly | JSC::PropertyAttribute::DontDelete | 0);
     }
 
     return object;
diff --git a/types/bun/jsc.d.ts b/types/bun/jsc.d.ts
index a43e87745..b59f8adee 100644
--- a/types/bun/jsc.d.ts
+++ b/types/bun/jsc.d.ts
@@ -5,7 +5,16 @@ declare module "bun:jsc" {
   export function fullGC(): void;
   export function edenGC(): void;
   export function heapSize(): number;
-  export function heapStats();
+  export function heapStats(): {
+    heapSize: number;
+    heapCapacity: number;
+    extraMemorySize: number;
+    objectCount: number;
+    protectedObjectCount: number;
+    globalObjectCount: number;
+    protectedGlobalObjectCount: number;
+    objectTypeCounts: Record<string, number>;
+  };
   export function memoryUsage(): {
     current: number;
     peak: number;
@@ -27,9 +36,24 @@ declare module "bun:jsc" {
   export function drainMicrotasks(): void;
 
   /**
+   * This returns objects which native code has explicitly protected from being
+   * garbage collected
+   *
+   * By calling this function you create another reference to the object, which
+   * will further prevent it from being garbage collected
+   *
+   * This function is mostly a debugging tool for bun itself.
+   *
+   * Warning: not all objects returned are supposed to be observable from JavaScript
+   */
+  export function getProtectedObjects(): any[];
+
+  /**
    * Start a remote debugging socket server on the given port.
    *
    * This exposes JavaScriptCore's built-in debugging server.
+   *
+   * This is untested. May not be supported yet on macOS
    */
   export function startRemoteDebugger(host?: string, port?: number): void;
 }