@gjsify/v8 0.22.0 → 0.23.0

package/README.md

@@ -1,6 +1,8 @@
 # @gjsify/v8
 
-GJS stub implementation of the Node.js `v8` module. Provides getHeapStatistics and JSON-based serialize/deserialize.
+GJS implementation of the Node.js `v8` module. Provides V8-wire-format
+`serialize`/`deserialize` (`Serializer`, `Deserializer`, `DefaultSerializer`,
+`DefaultDeserializer`) plus `getHeapStatistics()`.
 
 Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
 
@@ -25,6 +27,57 @@ const buf = serialize({ hello: 'world' });
 const obj = deserialize(buf);
 ```
 
+## `getHeapStatistics()` — what the numbers mean
+
+Node's `v8.getHeapStatistics()` reports V8's own accounting of its heap.
+GJS runs on SpiderMonkey, which exposes no equivalent surface (there is nothing
+like `HeapStatistics` on `imports.system`), so the memory-derived fields are
+approximated from the **operating system's view of the whole process** instead
+of the JS heap alone. Fields V8 computes from engine internals we cannot reach
+are reported as `0`.
+
+The result always has all 14 Node fields, always numeric — this function never
+throws, on any platform.
+
+| Field | Value on GJS |
+|---|---|
+| `total_heap_size` | process virtual size |
+| `total_physical_size` | process resident set size |
+| `used_heap_size` | process resident set size |
+| `malloced_memory` | process data-segment size (Linux only) |
+| `peak_malloced_memory` | peak process virtual size (Linux only) |
+| `total_heap_size_executable`, `total_available_size`, `heap_size_limit`, `does_zap_garbage`, `number_of_native_contexts`, `number_of_detached_contexts`, `total_global_handles_size`, `used_global_handles_size`, `external_memory` | `0` — no SpiderMonkey equivalent |
+
+### Platform support
+
+The reader lives in `src/heap/` (`linux.ts` / `darwin.ts` / `win32.ts` behind an
+`index.ts`, mirroring `@gjsify/os`). Detection is capability-based — the
+filesystem is probed for what is actually there, not a `uname` string parsed.
+
+| Platform | Source | Coverage |
+|---|---|---|
+| Linux (incl. Android, Flatpak, containers) | `/proc/self/status` — one `g_file_get_contents()`, no subprocess | `VmSize`, `VmRSS`, `VmData`, `VmPeak` |
+| macOS | `ps -o rss=,vsz=` — no procfs; Mach's `task_info()` (what libuv uses) needs a native bridge | `rss`, `vsz` only; `malloced_memory` and `peak_malloced_memory` stay `0` |
+| Windows | none reachable | all memory fields `0` — see below |
+| any other POSIX | none reachable | all memory fields `0` |
+
+**Degraded contract on Windows.** There is no `/proc` and no `ps(1)`. The native
+source is `GetProcessMemoryInfo()` (psapi), which GLib does not wrap and GJS
+cannot call without a native bridge; shelling out to `wmic` / `tasklist` /
+PowerShell would cost hundreds of milliseconds per call and `wmic` is deprecated
+and removed from recent Windows builds. `getHeapStatistics()` therefore returns
+the **all-zero** shape: every field present and numeric so destructuring callers
+keep working, none of them meaningful. This is byte-for-byte the same value the
+Linux reader already produced when `/proc` was unreadable, so no consumer sees a
+new shape. Callers that need a real number should check for `0`.
+
+### Not implemented
+
+`getHeapSpaceStatistics()` returns `[]`, `getHeapCodeStatistics()` returns
+zeros, and `writeHeapSnapshot()` / `setFlagsFromString()` / the profiler and
+`promiseHooks` surfaces are stubs — all of them are V8-internal APIs with no
+SpiderMonkey counterpart.
+
 ## License
 
 MIT

package/lib/esm/heap/darwin.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import e from"@girs/glib-2.0";function readProcessMemory(){try{let[t,n]=e.spawn_command_line_sync(`sh -c 'ps -o rss=,vsz= -p $PPID'`);if(!t||!n)return null;let r=new TextDecoder().decode(n).trim(),i=/^(\d+)\s+(\d+)$/.exec(r);return i?{virtual:parseInt(i[2],10)*1024,resident:parseInt(i[1],10)*1024,data:0,peak:0}:null}catch{return null}}export{readProcessMemory};

package/lib/esm/heap/index.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";import{readProcessMemory as e}from"./darwin.js";import{readProcessMemory as t}from"./linux.js";import{readProcessMemory as n}from"./win32.js";import r from"@girs/glib-2.0";let i=null;function detectHeapPlatform(){return i===null&&(i=r.get_current_dir().startsWith(`/`)?r.file_test(`/proc/self/status`,r.FileTest.EXISTS)?`linux`:r.file_test(`/System/Library/CoreServices/SystemVersion.plist`,r.FileTest.EXISTS)?`darwin`:`unknown`:`win32`),i}const a={virtual:0,resident:0,data:0,peak:0};function readProcessMemory(){switch(detectHeapPlatform()){case`linux`:return t();case`darwin`:return e();case`win32`:return n();default:return null}}function getHeapStatistics(){let e=readProcessMemory()??a;return{total_heap_size:e.virtual,total_heap_size_executable:0,total_physical_size:e.resident,total_available_size:0,used_heap_size:e.resident,heap_size_limit:0,malloced_memory:e.data,peak_malloced_memory:e.peak,does_zap_garbage:0,number_of_native_contexts:0,number_of_detached_contexts:0,total_global_handles_size:0,used_global_handles_size:0,external_memory:0}}export{detectHeapPlatform,getHeapStatistics,readProcessMemory};

package/lib/esm/heap/linux.js

@@ -0,0 +1,2 @@
+import"../_virtual/_rolldown/runtime.js";import e from"@girs/glib-2.0";function readProcessMemory(){let t;try{let[n,r]=e.file_get_contents(`/proc/self/status`);if(!n||!r)return null;t=new TextDecoder().decode(r)}catch{return null}let n=new Map;for(let e of t.split(`
+`)){let t=/^(\w+):\s+(\d+)(\s+kB)?/.exec(e);t&&n.set(t[1],parseInt(t[2])*(t[3]?1024:1))}return n.size===0?null:{virtual:n.get(`VmSize`)??0,resident:n.get(`VmRSS`)??0,data:n.get(`VmData`)??0,peak:n.get(`VmPeak`)??0}}export{readProcessMemory};

package/lib/esm/heap/win32.js

@@ -0,0 +1 @@
+import"../_virtual/_rolldown/runtime.js";function readProcessMemory(){return null}export{readProcessMemory};

package/lib/esm/index.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{getHeapStatistics as e}from"./heap.js";import{DefaultDeserializer as t,DefaultSerializer as n,Deserializer as r,Serializer as i}from"./serdes.js";function serialize(e){let t=new n;return t.writeHeader(),t.writeValue(e),t.releaseBuffer()}function deserialize(e){let n=new t(e);return n.readHeader(),n.readValue()}function getHeapSpaceStatistics(){return[]}function getHeapCodeStatistics(){return{code_and_metadata_size:0,bytecode_and_metadata_size:0,external_script_source_size:0,cpu_profiler_metadata_size:0}}function setFlagsFromString(e){}function getHeapSnapshot(e){return null}function writeHeapSnapshot(e){return``}function isStringOneByteRepresentation(e){for(let t=0;t<e.length;t++)if(e.charCodeAt(t)>255)return!1;return!0}var GCProfiler=class{#e=!1;#t=0;start(){this.#e||(this.#e=!0,this.#t=Date.now())}stop(){if(this.#e){this.#e=!1;try{let e=globalThis.imports?.system;typeof e?.gc==`function`&&e.gc()}catch{}return{version:1,startTime:this.#t,endTime:Date.now(),stats:[]}}}[Symbol.dispose](){this.stop()}},SyncCPUProfileHandle=class{stop(){}[Symbol.dispose](){this.stop()}};function startCpuProfile(){return new SyncCPUProfileHandle}var a={getHeapStatistics:e,getHeapSpaceStatistics,getHeapCodeStatistics,setFlagsFromString,getHeapSnapshot,writeHeapSnapshot,serialize,deserialize,isStringOneByteRepresentation,Serializer:i,Deserializer:r,DefaultSerializer:n,DefaultDeserializer:t,GCProfiler,startCpuProfile};export{t as DefaultDeserializer,n as DefaultSerializer,r as Deserializer,GCProfiler,i as Serializer,SyncCPUProfileHandle,a as default,deserialize,getHeapCodeStatistics,getHeapSnapshot,getHeapSpaceStatistics,e as getHeapStatistics,isStringOneByteRepresentation,serialize,setFlagsFromString,startCpuProfile,writeHeapSnapshot};
+import"./_virtual/_rolldown/runtime.js";import{getHeapStatistics as e}from"./heap/index.js";import{DefaultDeserializer as t,DefaultSerializer as n,Deserializer as r,Serializer as i}from"./serdes.js";function serialize(e){let t=new n;return t.writeHeader(),t.writeValue(e),t.releaseBuffer()}function deserialize(e){let n=new t(e);return n.readHeader(),n.readValue()}function getHeapSpaceStatistics(){return[]}function getHeapCodeStatistics(){return{code_and_metadata_size:0,bytecode_and_metadata_size:0,external_script_source_size:0,cpu_profiler_metadata_size:0}}function setFlagsFromString(e){}function getHeapSnapshot(e){return null}function writeHeapSnapshot(e){return``}function isStringOneByteRepresentation(e){for(let t=0;t<e.length;t++)if(e.charCodeAt(t)>255)return!1;return!0}var GCProfiler=class{#e=!1;#t=0;start(){this.#e||(this.#e=!0,this.#t=Date.now())}stop(){if(this.#e){this.#e=!1;try{let e=globalThis.imports?.system;typeof e?.gc==`function`&&e.gc()}catch{}return{version:1,startTime:this.#t,endTime:Date.now(),stats:[]}}}[Symbol.dispose](){this.stop()}},SyncCPUProfileHandle=class{stop(){}[Symbol.dispose](){this.stop()}};function startCpuProfile(){return new SyncCPUProfileHandle}var a={getHeapStatistics:e,getHeapSpaceStatistics,getHeapCodeStatistics,setFlagsFromString,getHeapSnapshot,writeHeapSnapshot,serialize,deserialize,isStringOneByteRepresentation,Serializer:i,Deserializer:r,DefaultSerializer:n,DefaultDeserializer:t,GCProfiler,startCpuProfile};export{t as DefaultDeserializer,n as DefaultSerializer,r as Deserializer,GCProfiler,i as Serializer,SyncCPUProfileHandle,a as default,deserialize,getHeapCodeStatistics,getHeapSnapshot,getHeapSpaceStatistics,e as getHeapStatistics,isStringOneByteRepresentation,serialize,setFlagsFromString,startCpuProfile,writeHeapSnapshot};

package/lib/types/heap/darwin.d.ts

@@ -0,0 +1,14 @@
+import type { ProcessMemory } from './types.js';
+/**
+ * Read this process's `rss` / `vsz` via `ps`.
+ *
+ * The pid is obtained without any extra binding by asking a short-lived shell
+ * for its OWN parent — `g_spawn_command_line_sync()` forks us, so the shell's
+ * `$PPID` is this process. Both `ps` columns are in KiB on macOS; `-o rss=`
+ * suppresses the header so the output is a bare `<rss> <vsz>` line.
+ *
+ * Spawning for a memory reading is heavier than Linux's single file read, but
+ * `getHeapStatistics()` is a diagnostics call, not a hot path. Returns `null`
+ * on any failure so the caller falls back to the all-zero contract.
+ */
+export declare function readProcessMemory(): ProcessMemory | null;

package/lib/types/heap/index.d.ts

@@ -0,0 +1,43 @@
+import type { ProcessMemory } from './types.js';
+export type { ProcessMemory };
+export type HeapPlatform = 'linux' | 'darwin' | 'win32' | 'unknown';
+/**
+ * Detect which reader applies, once per process:
+ *
+ *   - Windows — GLib returns native paths, so `g_get_current_dir()` is
+ *     drive-rooted (`C:\…`) instead of `/`-rooted.
+ *   - Linux — `/proc/self/status` exists (procfs is Linux-only).
+ *   - macOS — no procfs, but the system version plist is always present.
+ *   - anything else — no reader; the all-zero contract applies.
+ */
+export declare function detectHeapPlatform(): HeapPlatform;
+/** Read the current process's memory figures, or `null` if unavailable here. */
+export declare function readProcessMemory(): ProcessMemory | null;
+export interface HeapStatistics {
+    total_heap_size: number;
+    total_heap_size_executable: number;
+    total_physical_size: number;
+    total_available_size: number;
+    used_heap_size: number;
+    heap_size_limit: number;
+    malloced_memory: number;
+    peak_malloced_memory: number;
+    does_zap_garbage: number;
+    number_of_native_contexts: number;
+    number_of_detached_contexts: number;
+    total_global_handles_size: number;
+    used_global_handles_size: number;
+    external_memory: number;
+}
+/**
+ * Node-shaped `v8.getHeapStatistics()`.
+ *
+ * Every field is always present and numeric — Node never throws here and
+ * neither do we. Fields V8 computes from engine internals we have no access to
+ * (`heap_size_limit`, `does_zap_garbage`, the context/handle counters, …) are
+ * reported as `0`; the memory-derived fields come from the platform reader
+ * above and are `0` too when no reader is available (Windows, or a Linux host
+ * with `/proc` masked). Callers that destructure the result keep working
+ * everywhere; callers that need a meaningful number should check for `0`.
+ */
+export declare function getHeapStatistics(): HeapStatistics;

package/lib/types/heap/linux.d.ts

@@ -0,0 +1,10 @@
+import type { ProcessMemory } from './types.js';
+/**
+ * Read `VmSize` / `VmRSS` / `VmData` / `VmPeak` out of `/proc/self/status`.
+ *
+ * procfs is Linux-only but is present on every mainstream distribution and
+ * inside Flatpak/OCI containers, so this is the fast path (a single
+ * `g_file_get_contents()`, no subprocess). Returns `null` when procfs is not
+ * readable so the caller can fall back to the documented all-zero contract.
+ */
+export declare function readProcessMemory(): ProcessMemory | null;

package/lib/types/heap/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Process memory figures, in BYTES. A reader sets `0` for any figure the
+ * platform does not expose (rather than guessing), and returns `null` from
+ * `readProcessMemory()` when it can read nothing at all.
+ */
+export interface ProcessMemory {
+    /** Virtual memory size (Linux `VmSize`, BSD `vsz`). */
+    virtual: number;
+    /** Resident set size (Linux `VmRSS`, BSD `rss`). */
+    resident: number;
+    /** Data-segment size (Linux `VmData`). */
+    data: number;
+    /** Peak virtual memory size (Linux `VmPeak`). */
+    peak: number;
+}

package/lib/types/heap/win32.d.ts

@@ -0,0 +1,2 @@
+import type { ProcessMemory } from './types.js';
+export declare function readProcessMemory(): ProcessMemory | null;

package/lib/types/index.d.ts

@@ -1,4 +1,4 @@
-import { getHeapStatistics } from './heap.js';
+import { getHeapStatistics } from './heap/index.js';
 import { Serializer, Deserializer, DefaultSerializer, DefaultDeserializer } from './serdes.js';
 export { getHeapStatistics };
 export { Serializer, Deserializer, DefaultSerializer, DefaultDeserializer };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/v8",
-    "version": "0.22.0",
+    "version": "0.23.0",
     "description": "Node.js v8 module for Gjs",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -33,11 +33,14 @@
         "v8"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.22.0",
-        "@gjsify/unit": "^0.22.0",
+        "@gjsify/cli": "^0.23.0",
+        "@gjsify/unit": "^0.23.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
+    "dependencies": {
+        "@girs/glib-2.0": "^4.1.0"
+    },
     "gjsify": {
         "runtimes": {
             "gjs": "polyfill",

package/lib/esm/heap.js

@@ -1,2 +0,0 @@
-import"./_virtual/_rolldown/runtime.js";import e from"@girs/glib-2.0";function readProcStatus(){let t=new Map;try{let[n,r]=e.file_get_contents(`/proc/self/status`);if(!n||!r)return t;let i=new TextDecoder().decode(r);for(let e of i.split(`
-`)){let n=/^(\w+):\s+(\d+)(\s+kB)?/.exec(e);n&&t.set(n[1],parseInt(n[2])*(n[3]?1024:1))}}catch{}return t}function getHeapStatistics(){let e=readProcStatus();return{total_heap_size:e.get(`VmSize`)??0,total_heap_size_executable:0,total_physical_size:e.get(`VmRSS`)??0,total_available_size:0,used_heap_size:e.get(`VmRSS`)??0,heap_size_limit:0,malloced_memory:e.get(`VmData`)??0,peak_malloced_memory:e.get(`VmPeak`)??0,does_zap_garbage:0,number_of_native_contexts:0,number_of_detached_contexts:0,total_global_handles_size:0,used_global_handles_size:0,external_memory:0}}export{getHeapStatistics};

package/lib/types/heap.d.ts

@@ -1,16 +0,0 @@
-export declare function getHeapStatistics(): {
-    total_heap_size: number;
-    total_heap_size_executable: number;
-    total_physical_size: number;
-    total_available_size: number;
-    used_heap_size: number;
-    heap_size_limit: number;
-    malloced_memory: number;
-    peak_malloced_memory: number;
-    does_zap_garbage: number;
-    number_of_native_contexts: number;
-    number_of_detached_contexts: number;
-    total_global_handles_size: number;
-    used_global_handles_size: number;
-    external_memory: number;
-};