Skip to content

bun-compat: implement the bun:jsc heapStats surface #9743

Description

@proggeramlug

Problem

Perry's parity table lists the entire bun:jsc module as unsupported. Bun-target applications can use heapStats() for optional memory diagnostics, including through a dynamic import. Perry currently warns that bun:jsc cannot be resolved.

This issue intentionally covers only the small heapStats surface, not the profiler, debugger, or JSC optimization-control APIs.

Minimal repro

const { heapStats } = await import("bun:jsc");
const stats = heapStats(true);

console.log(typeof stats.heapSize);
console.log(typeof stats.objectCount);
console.log(typeof stats.objectTypeCounts);
console.log(typeof stats.protectedObjectTypeCounts);
console.log(typeof stats.mimalloc);

Bun 1.3.14 prints five lines containing number, number, object, object, object.

The currently observable key set is:

extraMemorySize
globalObjectCount
heapCapacity
heapSize
mimalloc
objectCount
objectTypeCounts
protectedGlobalObjectCount
protectedObjectCount
protectedObjectTypeCounts

Acceptance criteria

  • bun:jsc resolves as a built-in in Bun-platform compilations without an unresolved-import warning.
  • Static import, await import("bun:jsc"), and require("bun:jsc") expose the same heapStats function.
  • heapStats() and the compatibility spelling heapStats(true) return the keys above.
  • Scalar counters are finite, non-negative numbers.
  • objectTypeCounts, protectedObjectTypeCounts, and mimalloc are objects whose reported counters are finite, non-negative numbers.
  • Values describe Perry's own heap/allocator where an exact JavaScriptCore concept does not exist; the implementation documents any intentionally approximate counters.
  • A compiled-binary test checks shape, types, monotonic sanity, and both argument forms without asserting machine-specific counts.

Upstream Bun uses this surface for leak diagnostics and its Node v8 compatibility layer.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew capability or improvementparityCompatibility gap with Node.js, ECMAScript, or the supported ecosystem

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions