@gjsify/v8 0.1.15 → 0.2.0

package/lib/types/heap.d.ts

@@ -0,0 +1,16 @@
+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;
+};

package/lib/types/index.d.ts

@@ -1,19 +1,58 @@
-export declare function getHeapStatistics(): Record<string, number>;
-export declare function getHeapSpaceStatistics(): any[];
+import { getHeapStatistics } from './heap.js';
+import { Serializer, Deserializer, DefaultSerializer, DefaultDeserializer } from './serdes.js';
+export { getHeapStatistics };
+export { Serializer, Deserializer, DefaultSerializer, DefaultDeserializer };
+export declare function serialize(value: unknown): Buffer;
+export declare function deserialize(buffer: NodeJS.ArrayBufferView | ArrayBuffer): unknown;
+export interface HeapSpaceInfo {
+    space_name: string;
+    space_size: number;
+    space_used_size: number;
+    space_available_size: number;
+    physical_space_size: number;
+}
+export declare function getHeapSpaceStatistics(): HeapSpaceInfo[];
+export declare function getHeapCodeStatistics(): {
+    code_and_metadata_size: number;
+    bytecode_and_metadata_size: number;
+    external_script_source_size: number;
+    cpu_profiler_metadata_size: number;
+};
 export declare function setFlagsFromString(_flags: string): void;
-export declare function getHeapSnapshot(): any;
+export declare function getHeapSnapshot(_options?: object): null;
 export declare function writeHeapSnapshot(_filename?: string): string;
-export declare function getHeapCodeStatistics(): Record<string, number>;
-export declare function serialize(value: any): Buffer;
-export declare function deserialize(buffer: Buffer): any;
+export declare function isStringOneByteRepresentation(content: string): boolean;
+export declare class GCProfiler {
+    #private;
+    start(): void;
+    stop(): {
+        version: number;
+        startTime: number;
+        endTime: number;
+        stats: never[];
+    } | undefined;
+    [Symbol.dispose](): void;
+}
+export declare class SyncCPUProfileHandle {
+    stop(): undefined;
+    [Symbol.dispose](): void;
+}
+export declare function startCpuProfile(): SyncCPUProfileHandle;
 declare const _default: {
     getHeapStatistics: typeof getHeapStatistics;
     getHeapSpaceStatistics: typeof getHeapSpaceStatistics;
+    getHeapCodeStatistics: typeof getHeapCodeStatistics;
     setFlagsFromString: typeof setFlagsFromString;
     getHeapSnapshot: typeof getHeapSnapshot;
     writeHeapSnapshot: typeof writeHeapSnapshot;
-    getHeapCodeStatistics: typeof getHeapCodeStatistics;
     serialize: typeof serialize;
     deserialize: typeof deserialize;
+    isStringOneByteRepresentation: typeof isStringOneByteRepresentation;
+    Serializer: typeof Serializer;
+    Deserializer: typeof Deserializer;
+    DefaultSerializer: typeof DefaultSerializer;
+    DefaultDeserializer: typeof DefaultDeserializer;
+    GCProfiler: typeof GCProfiler;
+    startCpuProfile: typeof startCpuProfile;
 };
 export default _default;

package/lib/types/serdes.d.ts

@@ -0,0 +1,42 @@
+import { Buffer } from 'node:buffer';
+export declare class Serializer {
+    protected _bytes: number[];
+    protected _seen: object[];
+    protected _treatAbvAsHostObjects: boolean;
+    _getDataCloneError: ErrorConstructor;
+    writeHeader(): void;
+    writeValue(value: unknown): void;
+    releaseBuffer(): Buffer;
+    writeUint32(n: number): void;
+    writeUint64(hi: number, lo: number): void;
+    writeDouble(d: number): void;
+    writeRawBytes(source: NodeJS.ArrayBufferView): void;
+    _writeHostObject(_obj: object): void;
+    _setTreatArrayBufferViewsAsHostObjects(flag: boolean): void;
+    private _writeString;
+    private _writeBigInt;
+}
+export declare class Deserializer {
+    protected _pos: number;
+    protected _wireVersion: number;
+    protected _seen: unknown[];
+    readonly buffer: Buffer;
+    constructor(buffer: NodeJS.ArrayBufferView | ArrayBuffer);
+    readHeader(): boolean;
+    getWireFormatVersion(): number;
+    readValue(): unknown;
+    readUint32(): number;
+    readUint64(): [number, number];
+    readDouble(): number;
+    _readRawBytes(length: number): number;
+    readRawBytes(length: number): Buffer;
+    _readHostObject(): unknown;
+    private _readBigInt;
+}
+export declare class DefaultSerializer extends Serializer {
+    constructor();
+    _writeHostObject(abView: NodeJS.ArrayBufferView): void;
+}
+export declare class DefaultDeserializer extends Deserializer {
+    _readHostObject(): NodeJS.ArrayBufferView;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/v8",
-  "version": "0.1.15",
+  "version": "0.2.0",
   "description": "Node.js v8 module for Gjs",
   "type": "module",
   "module": "lib/esm/index.js",
@@ -21,7 +21,7 @@
     "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
     "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
     "test": "yarn build:gjsify && yarn build:test && yarn test:node && yarn test:gjs",
-    "test:gjs": "gjs -m test.gjs.mjs",
+    "test:gjs": "gjsify run test.gjs.mjs",
     "test:node": "node test.node.mjs"
   },
   "keywords": [
@@ -30,9 +30,9 @@
     "v8"
   ],
   "devDependencies": {
-    "@gjsify/cli": "^0.1.15",
-    "@gjsify/unit": "^0.1.15",
+    "@gjsify/cli": "^0.2.0",
+    "@gjsify/unit": "^0.2.0",
     "@types/node": "^25.6.0",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.3"
   }
 }

package/src/heap.ts

@@ -0,0 +1,53 @@
+// Reference: Node.js lib/v8.js (getHeapStatistics)
+// Reimplemented for GJS using /proc/self/status (Linux)
+
+import GLib from '@girs/glib-2.0';
+
+function readProcStatus(): Map<string, number> {
+  const map = new Map<string, number>();
+  try {
+    const [ok, contents] = GLib.file_get_contents('/proc/self/status');
+    if (!ok || !contents) return map;
+    const text = new TextDecoder().decode(contents as unknown as Uint8Array);
+    for (const line of text.split('\n')) {
+      const m = /^(\w+):\s+(\d+)(\s+kB)?/.exec(line);
+      if (m) map.set(m[1], parseInt(m[2]) * (m[3] ? 1024 : 1));
+    }
+  } catch { /* /proc not available on non-Linux */ }
+  return map;
+}
+
+export 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;
+} {
+  const proc = readProcStatus();
+  return {
+    total_heap_size: proc.get('VmSize') ?? 0,
+    total_heap_size_executable: 0,
+    total_physical_size: proc.get('VmRSS') ?? 0,
+    total_available_size: 0,
+    used_heap_size: proc.get('VmRSS') ?? 0,
+    heap_size_limit: 0,
+    malloced_memory: proc.get('VmData') ?? 0,
+    peak_malloced_memory: proc.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,
+  };
+}

package/src/index.spec.ts

@@ -1,28 +1,270 @@
+// Ported from refs/node-test/parallel/test-v8-stats.js,
+//   refs/node-test/parallel/test-v8-serdes.js,
+//   refs/node-test/parallel/test-v8-deserialize-buffer.js
+// Original: MIT, Node.js contributors.
+// Rewritten for @gjsify/unit — behavior preserved, assertion dialect adapted.
+
 import { describe, it, expect } from '@gjsify/unit';
-import { getHeapStatistics, getHeapCodeStatistics, serialize, deserialize } from 'node:v8';
+import {
+  getHeapStatistics,
+  getHeapCodeStatistics,
+  getHeapSpaceStatistics,
+  serialize,
+  deserialize,
+  Serializer,
+  Deserializer,
+  DefaultSerializer,
+  DefaultDeserializer,
+  isStringOneByteRepresentation,
+  GCProfiler,
+  startCpuProfile,
+} from 'node:v8';
 
 export default async () => {
-  await describe('v8', async () => {
-    await it('should export getHeapStatistics as a function', async () => {
-      expect(typeof getHeapStatistics).toBe('function');
+  await describe('v8.getHeapStatistics', async () => {
+    await it('returns an object with all 14 required fields', async () => {
+      const stats = getHeapStatistics();
+      const fields = [
+        'total_heap_size',
+        'total_heap_size_executable',
+        'total_physical_size',
+        'total_available_size',
+        'used_heap_size',
+        'heap_size_limit',
+        'malloced_memory',
+        'peak_malloced_memory',
+        'does_zap_garbage',
+        'number_of_native_contexts',
+        'number_of_detached_contexts',
+        'total_global_handles_size',
+        'used_global_handles_size',
+        'external_memory',
+      ];
+      for (const field of fields) {
+        expect(typeof (stats as any)[field]).toBe('number');
+      }
     });
 
-    await it('should return heap statistics object', async () => {
+    await it('used_heap_size is a positive number on Linux (via /proc)', async () => {
       const stats = getHeapStatistics();
-      expect(stats).toBeDefined();
-      expect(typeof stats.total_heap_size).toBe('number');
-      expect(typeof stats.used_heap_size).toBe('number');
+      expect(stats.used_heap_size).toBeGreaterThan(0);
     });
+  });
 
-    await it('should return heap code statistics', async () => {
-      const stats = getHeapCodeStatistics();
-      expect(stats).toBeDefined();
+  await describe('v8.getHeapCodeStatistics', async () => {
+    await it('returns object with 4 numeric fields', async () => {
+      const stats = getHeapCodeStatistics() as any;
       expect(typeof stats.code_and_metadata_size).toBe('number');
+      expect(typeof stats.bytecode_and_metadata_size).toBe('number');
+      expect(typeof stats.external_script_source_size).toBe('number');
+      expect(typeof stats.cpu_profiler_metadata_size).toBe('number');
+    });
+  });
+
+  await describe('v8.getHeapSpaceStatistics', async () => {
+    await it('returns an array', async () => {
+      expect(Array.isArray(getHeapSpaceStatistics())).toBe(true);
+    });
+  });
+
+  await describe('v8.serialize / v8.deserialize round-trips', async () => {
+    await it('null', async () => {
+      expect(deserialize(serialize(null))).toBe(null);
+    });
+
+    await it('undefined', async () => {
+      expect(deserialize(serialize(undefined))).toBe(undefined);
+    });
+
+    await it('boolean true', async () => {
+      expect(deserialize(serialize(true))).toBe(true);
+    });
+
+    await it('boolean false', async () => {
+      expect(deserialize(serialize(false))).toBe(false);
+    });
+
+    await it('integer', async () => {
+      expect(deserialize(serialize(42))).toBe(42);
+    });
+
+    await it('negative integer', async () => {
+      expect(deserialize(serialize(-7))).toBe(-7);
+    });
+
+    await it('float', async () => {
+      expect(deserialize(serialize(3.14))).toBe(3.14);
+    });
+
+    await it('ASCII string', async () => {
+      expect(deserialize(serialize('hello'))).toBe('hello');
+    });
+
+    await it('Unicode string', async () => {
+      expect(deserialize(serialize('héllo wörld'))).toBe('héllo wörld');
+    });
+
+    await it('Date', async () => {
+      const d = new Date('2020-01-01T00:00:00Z');
+      const result = deserialize(serialize(d)) as Date;
+      expect(result instanceof Date).toBe(true);
+      expect(result.getTime()).toBe(d.getTime());
+    });
+
+    await it('plain object', async () => {
+      const obj = { a: 1, b: 'two', c: true };
+      const result = deserialize(serialize(obj)) as typeof obj;
+      expect(result.a).toBe(1);
+      expect(result.b).toBe('two');
+      expect(result.c).toBe(true);
+    });
+
+    await it('array', async () => {
+      const arr = [1, 'two', null, true];
+      const result = deserialize(serialize(arr)) as typeof arr;
+      expect(result[0]).toBe(1);
+      expect(result[1]).toBe('two');
+      expect(result[2]).toBe(null);
+      expect(result[3]).toBe(true);
+    });
+
+    await it('Uint8Array', async () => {
+      const ta = new Uint8Array([1, 2, 3]);
+      const result = deserialize(serialize(ta)) as Uint8Array;
+      expect(result instanceof Uint8Array).toBe(true);
+      expect(result[0]).toBe(1);
+      expect(result[1]).toBe(2);
+      expect(result[2]).toBe(3);
+    });
+
+    await it('Int32Array', async () => {
+      const ta = new Int32Array([-1, 0, 1]);
+      const result = deserialize(serialize(ta)) as Int32Array;
+      expect(result instanceof Int32Array).toBe(true);
+      expect(result[0]).toBe(-1);
+      expect(result[2]).toBe(1);
     });
 
-    await it('should export serialize and deserialize', async () => {
-      expect(typeof serialize).toBe('function');
-      expect(typeof deserialize).toBe('function');
+    await it('Float64Array', async () => {
+      const ta = new Float64Array([1.1, 2.2, 3.3]);
+      const result = deserialize(serialize(ta)) as Float64Array;
+      expect(result instanceof Float64Array).toBe(true);
+      expect(Math.abs(result[0] - 1.1) < 1e-9).toBe(true);
+    });
+
+    await it('Buffer', async () => {
+      const buf = Buffer.from([10, 20, 30]);
+      const result = deserialize(serialize(buf)) as Buffer;
+      expect(Buffer.isBuffer(result)).toBe(true);
+      expect(result[0]).toBe(10);
+      expect(result[2]).toBe(30);
+    });
+
+    await it('BigInt', async () => {
+      const big = 9007199254740993n;
+      expect(deserialize(serialize(big))).toBe(big);
+    });
+
+    await it('negative BigInt', async () => {
+      expect(deserialize(serialize(-42n))).toBe(-42n);
+    });
+
+    await it('circular object produces backref on deserialize', async () => {
+      const obj: any = { a: 1 };
+      obj.self = obj;
+      const result = deserialize(serialize(obj)) as any;
+      expect(result.a).toBe(1);
+      expect(result.self).toBe(result);
+    });
+  });
+
+  await describe('v8.Serializer / Deserializer classes', async () => {
+    await it('Serializer can write header + value → Buffer', async () => {
+      const s = new Serializer();
+      s.writeHeader();
+      s.writeValue(42);
+      const buf = s.releaseBuffer();
+      expect(Buffer.isBuffer(buf)).toBe(true);
+      expect(buf.length).toBeGreaterThan(0);
+    });
+
+    await it('Deserializer can read header + value', async () => {
+      const s = new Serializer();
+      s.writeHeader();
+      s.writeValue('test');
+      const buf = s.releaseBuffer();
+
+      const d = new Deserializer(buf);
+      d.readHeader();
+      expect(d.readValue()).toBe('test');
+    });
+
+    await it('getWireFormatVersion returns 15', async () => {
+      const s = new Serializer();
+      s.writeHeader();
+      s.writeValue(null);
+      const buf = s.releaseBuffer();
+      const d = new Deserializer(buf);
+      d.readHeader();
+      expect(d.getWireFormatVersion()).toBe(15);
+    });
+  });
+
+  await describe('v8.DefaultSerializer / DefaultDeserializer', async () => {
+    await it('TypedArray host-object round-trip', async () => {
+      const original = new Uint32Array([100, 200, 300]);
+      const s = new DefaultSerializer();
+      s.writeHeader();
+      s.writeValue(original);
+      const buf = s.releaseBuffer();
+
+      const d = new DefaultDeserializer(buf);
+      d.readHeader();
+      const result = d.readValue() as Uint32Array;
+      expect(result instanceof Uint32Array).toBe(true);
+      expect(result[0]).toBe(100);
+      expect(result[1]).toBe(200);
+      expect(result[2]).toBe(300);
+    });
+  });
+
+  await describe('v8.isStringOneByteRepresentation', async () => {
+    await it('ASCII string returns true', async () => {
+      expect(isStringOneByteRepresentation('hello')).toBe(true);
+    });
+
+    await it('string with ü (>255 codepoint) returns false', async () => {
+      // ü = U+00FC (fits in Latin-1), 日 = U+65E5 (does not)
+      expect(isStringOneByteRepresentation('日本語')).toBe(false);
+    });
+
+    await it('empty string returns true', async () => {
+      expect(isStringOneByteRepresentation('')).toBe(true);
+    });
+  });
+
+  await describe('v8.GCProfiler', async () => {
+    await it('start/stop returns defined object with version and timing', async () => {
+      const profiler = new GCProfiler();
+      profiler.start();
+      const stats = profiler.stop() as any;
+      expect(stats).toBeDefined();
+      expect(stats.version).toBe(1);
+      expect(typeof stats.startTime).toBe('number');
+      expect(typeof stats.endTime).toBe('number');
+    });
+
+    await it('stop without start returns undefined', async () => {
+      const profiler = new GCProfiler();
+      expect(profiler.stop()).toBe(undefined);
+    });
+  });
+
+  await describe('v8.startCpuProfile', async () => {
+    await it('returns an object with a stop() method that does not throw', async () => {
+      const handle = startCpuProfile();
+      expect(typeof handle.stop).toBe('function');
+      expect(() => handle.stop()).not.toThrow();
     });
   });
 };

package/src/index.ts

@@ -1,37 +1,45 @@
-// Reference: Node.js lib/v8.js — stub for GJS
+// Reference: Node.js lib/v8.js
+// Reimplemented for GJS — heap stats via /proc/self/status, serialization via V8 wire format
 
-export function getHeapStatistics(): Record<string, number> {
-  return {
-    total_heap_size: 0,
-    total_heap_size_executable: 0,
-    total_physical_size: 0,
-    total_available_size: 0,
-    used_heap_size: 0,
-    heap_size_limit: 0,
-    malloced_memory: 0,
-    peak_malloced_memory: 0,
-    does_zap_garbage: 0,
-    number_of_native_contexts: 0,
-    number_of_detached_contexts: 0,
-    external_memory: 0,
-  };
+import { getHeapStatistics } from './heap.js';
+import {
+  Serializer, Deserializer, DefaultSerializer, DefaultDeserializer,
+} from './serdes.js';
+
+export { getHeapStatistics };
+export { Serializer, Deserializer, DefaultSerializer, DefaultDeserializer };
+
+export function serialize(value: unknown): Buffer {
+  const ser = new DefaultSerializer();
+  ser.writeHeader();
+  ser.writeValue(value);
+  return ser.releaseBuffer();
 }
 
-export function getHeapSpaceStatistics(): any[] {
-  return [];
+export function deserialize(buffer: NodeJS.ArrayBufferView | ArrayBuffer): unknown {
+  const des = new DefaultDeserializer(buffer);
+  des.readHeader();
+  return des.readValue();
 }
 
-export function setFlagsFromString(_flags: string): void {}
+// ─── Stubs — no GJS equivalent ────────────────────────────────────────────────
 
-export function getHeapSnapshot(): any {
-  return null;
+export interface HeapSpaceInfo {
+  space_name: string;
+  space_size: number;
+  space_used_size: number;
+  space_available_size: number;
+  physical_space_size: number;
 }
 
-export function writeHeapSnapshot(_filename?: string): string {
-  return '';
-}
+export function getHeapSpaceStatistics(): HeapSpaceInfo[] { return []; }
 
-export function getHeapCodeStatistics(): Record<string, number> {
+export function getHeapCodeStatistics(): {
+  code_and_metadata_size: number;
+  bytecode_and_metadata_size: number;
+  external_script_source_size: number;
+  cpu_profiler_metadata_size: number;
+} {
   return {
     code_and_metadata_size: 0,
     bytecode_and_metadata_size: 0,
@@ -40,21 +48,71 @@ export function getHeapCodeStatistics(): Record<string, number> {
   };
 }
 
-export function serialize(value: any): Buffer {
-  return Buffer.from(JSON.stringify(value));
+export function setFlagsFromString(_flags: string): void {}
+
+export function getHeapSnapshot(_options?: object): null { return null; }
+
+export function writeHeapSnapshot(_filename?: string): string { return ''; }
+
+export function isStringOneByteRepresentation(content: string): boolean {
+  for (let i = 0; i < content.length; i++) {
+    if (content.charCodeAt(i) > 255) return false;
+  }
+  return true;
+}
+
+// ─── GCProfiler ───────────────────────────────────────────────────────────────
+
+export class GCProfiler {
+  #running = false;
+  #startTime = 0;
+
+  start(): void {
+    if (this.#running) return;
+    this.#running = true;
+    this.#startTime = Date.now();
+  }
+
+  stop(): { version: number; startTime: number; endTime: number; stats: never[] } | undefined {
+    if (!this.#running) return undefined;
+    this.#running = false;
+    try {
+      const system = (globalThis as any).imports?.system;
+      if (typeof system?.gc === 'function') system.gc();
+    } catch { /* ignore */ }
+    return { version: 1, startTime: this.#startTime, endTime: Date.now(), stats: [] };
+  }
+
+  [Symbol.dispose](): void { this.stop(); }
 }
 
-export function deserialize(buffer: Buffer): any {
-  return JSON.parse(buffer.toString());
+// ─── SyncCPUProfileHandle / startCpuProfile ───────────────────────────────────
+
+export class SyncCPUProfileHandle {
+  stop(): undefined { return undefined; }
+  [Symbol.dispose](): void { this.stop(); }
 }
 
+export function startCpuProfile(): SyncCPUProfileHandle {
+  return new SyncCPUProfileHandle();
+}
+
+// ─── default export ───────────────────────────────────────────────────────────
+
 export default {
   getHeapStatistics,
   getHeapSpaceStatistics,
+  getHeapCodeStatistics,
   setFlagsFromString,
   getHeapSnapshot,
   writeHeapSnapshot,
-  getHeapCodeStatistics,
   serialize,
   deserialize,
+  isStringOneByteRepresentation,
+  Serializer,
+  Deserializer,
+  DefaultSerializer,
+  DefaultDeserializer,
+  GCProfiler,
+  startCpuProfile,
 };