@gjsify/node-gi 0.22.0 → 0.23.0

package/README.md

@@ -678,6 +678,16 @@ imports.signals.addSignalMethods(emitter);      // the pure-JS Signals mixin
 emitter.connect('ready', () => imports.mainloop.quit());
 imports.mainloop.timeout_add(50, () => { emitter.emit('ready'); return false; });
 imports.mainloop.run();                          // thin GLib.MainLoop wrapper
+
+// imports.byteArray — the legacy byte-array module, with GJS semantics
+// (fromString/toString are zero-terminated + fatal-decode; fromGBytes/toGBytes
+// round-trip GLib.Bytes; fromArray wraps in the legacy ByteArray class). This
+// is the seam @gjsify/utils' cli()/gbytesToUint8Array — and through them
+// @gjsify/os + @gjsify/child_process — read GLib subprocess output with:
+const [ok, out] = imports.gi.GLib.spawn_command_line_sync('echo hi');
+console.log(imports.byteArray.toString(out));    // 'hi\n'
+const bytes = imports.byteArray.toGBytes(Uint8Array.of(1, 2, 3));
+imports.byteArray.fromGBytes(bytes);             // Uint8Array [1, 2, 3] (a copy)
 ```
 
 A follow-up `--app node` build step will inject this automatically for any

package/gi.js

@@ -985,7 +985,10 @@ let pumpRefCount = 0;
  * @returns {() => void}
  */
 export function startMainContextPump() {
-  if (native.isNodeRuntime) return () => {};
+  // Node: the libuv↔GLib bridge already co-pumps. GJS: the host loop IS
+  // GLib's default main context — a JS-timer pump would only iterate the
+  // context recursively from within its own dispatch.
+  if (native.isNodeRuntime || native.RUNTIME === 'gjs') return () => {};
   pumpRefCount++;
   if (pumpTimer === null) {
     // ~4 ms cadence: low latency without busy-spinning. Each tick drains every
@@ -1011,7 +1014,7 @@ export function startMainContextPump() {
 
 /** Decrement the main-context pump reference count; clears the timer at zero. */
 export function stopMainContextPump() {
-  if (native.isNodeRuntime || pumpRefCount === 0) return;
+  if (native.isNodeRuntime || native.RUNTIME === 'gjs' || pumpRefCount === 0) return;
   pumpRefCount--;
   if (pumpRefCount === 0 && pumpTimer !== null) {
     clearInterval(pumpTimer);

package/globals.d.ts

@@ -15,6 +15,19 @@ export interface GjsImports {
   system: SystemModule;
   /** `imports.gettext` — the `@gjsify/node-gi/gettext` module (no-translation passthrough). */
   gettext: GettextModule;
+  /** `imports.byteArray` — the legacy GJS byte-array module (GJS semantics: zero-terminated, fatal decode). */
+  byteArray: {
+    ByteArray: new (arg?: number | Uint8Array) => {
+      length: number;
+      toString(encoding?: string): string;
+      toGBytes(): unknown;
+    };
+    fromArray(array: Iterable<number>): unknown;
+    fromGBytes(bytes: unknown): Uint8Array;
+    fromString(string: string, encoding?: string): Uint8Array;
+    toGBytes(array: Uint8Array): unknown;
+    toString(byteArray: Uint8Array, encoding?: string): string;
+  };
   versions: Record<string, unknown>;
 }
 

package/globals.js

@@ -22,6 +22,7 @@ import cairo from './cairo.js';
 // Legacy `imports.signals` (the pure-JS Signals mixin) + `imports.mainloop` (the
 // GLib.MainLoop convenience layer) — the GJS script modules many older sources use.
 import * as signalsModule from './overrides/_signals.js';
+import { createByteArray } from './overrides/byte-array.js';
 import { createMainloop } from './overrides/mainloop.js';
 import { createPackage } from './overrides/package.js';
 
@@ -109,6 +110,11 @@ function makeImports() {
     system,
     gettext,
     cairo,
+    // `imports.byteArray` — the legacy GJS byte-array module
+    // (fromGBytes/toGBytes/fromString/toString/fromArray/ByteArray), the seam
+    // `@gjsify/utils`' gbytesToUint8Array/cli() read subprocess output through.
+    // GLib is only pulled in lazily (toGBytes), so seeding it here is free.
+    byteArray: createByteArray(requireGi),
     signals: { addSignalMethods, _connect, _connectAfter, _disconnect, _emit, _signalHandlerIsConnected, _disconnectAll },
     // GJS's `imports.searchPath` — `imports.package.init` unshifts the app's
     // moduledir onto it. Inert on node-gi (ESM + gi://), but present + safe so

package/index.js

@@ -49,19 +49,25 @@ const require = createRequire(import.meta.url);
 const here = dirname(fileURLToPath(import.meta.url)); // package root
 
 /**
- * Which JS runtime we are on. The Node-API addon loads on all three, but the
+ * Which JS runtime we are on. The Node-API addon loads on all four: Node, Bun
+ * and Deno implement Node-API natively; under GJS the `@gjsify/napi` shim is
+ * the N-API host and the addon is loaded through it (`loadNative` below). The
  * libuv-backed main-loop bridge (startMainLoop) is Node-only — Deno exports no
  * libuv symbols and Bun panics on uv_backend_fd — so Bun/Deno use the portable
- * GLib-iteration pump instead (see gi.js). Detection order matters: Bun and Deno
- * both expose a `process` shim, so probe their own globals first.
- * @type {'bun' | 'deno' | 'node'}
+ * GLib-iteration pump instead (see gi.js), and GJS needs NEITHER: the host
+ * loop already IS GLib's default main context. Detection order matters: GJS is
+ * probed first via its own globals (`imports` + `print` — no other runtime
+ * defines both), then Bun/Deno (both expose a `process` shim), then Node.
+ * @type {'bun' | 'deno' | 'gjs' | 'node'}
  */
 export const RUNTIME =
-  typeof globalThis.Bun !== 'undefined'
-    ? 'bun'
-    : typeof globalThis.Deno !== 'undefined'
-      ? 'deno'
-      : 'node';
+  typeof globalThis.imports !== 'undefined' && typeof globalThis.print === 'function'
+    ? 'gjs'
+    : typeof globalThis.Bun !== 'undefined'
+      ? 'bun'
+      : typeof globalThis.Deno !== 'undefined'
+        ? 'deno'
+        : 'node';
 
 /** Whether we are on Node.js (the only runtime with the libuv main-loop bridge). */
 export const isNodeRuntime = RUNTIME === 'node';
@@ -84,9 +90,37 @@ function nativeCandidates() {
   return [prebuild, release, debug];
 }
 
+// GJS host mode: the addon is loaded through the @gjsify/napi shim, not
+// `require()`. The loader native is `globalThis.__gjsifyNapiLoadAddon`,
+// installed by `GjsifyNapi.init()`; if another consumer (the @gjsify/napi L1)
+// already captured + deleted it, init() re-defines it (idempotent). The
+// GjsifyNapi typelib must be resolvable (GI_TYPELIB_PATH/LD_LIBRARY_PATH →
+// the shim prebuild).
+function gjsLoadAddon(path) {
+  let load = globalThis.__gjsifyNapiLoadAddon;
+  if (typeof load !== 'function') {
+    const GjsifyNapi = globalThis.imports?.gi?.GjsifyNapi;
+    if (!GjsifyNapi || !GjsifyNapi.init()) {
+      throw new Error(
+        '@gjsify/node-gi: GJS host mode needs the @gjsify/napi shim — the GjsifyNapi ' +
+          'typelib is not loadable (point GI_TYPELIB_PATH and LD_LIBRARY_PATH at its prebuild).',
+      );
+    }
+    load = globalThis.__gjsifyNapiLoadAddon;
+    if (typeof load !== 'function') {
+      throw new Error('@gjsify/node-gi: GjsifyNapi.init() did not install the addon loader.');
+    }
+    // Capture-then-delete, the same no-side-channel discipline as the L1.
+    delete globalThis.__gjsifyNapiLoadAddon;
+  }
+  return load(path);
+}
+
 function loadNative() {
   for (const candidate of nativeCandidates()) {
-    if (existsSync(candidate)) return require(candidate);
+    if (existsSync(candidate)) {
+      return RUNTIME === 'gjs' ? gjsLoadAddon(candidate) : require(candidate);
+    }
   }
   throw new Error(
     `@gjsify/node-gi: native addon not found for ${RUNTIME} on ${process.platform}-${process.arch}. ` +
@@ -94,7 +128,8 @@ function loadNative() {
       'Run `node-gyp rebuild` in ' +
       here +
       ' (requires a C++ toolchain and the girepository-2.0 / glib-2.0 development headers), ' +
-      'or install a package build that ships a prebuild for your platform.',
+      'or install a package build that ships a prebuild for your platform. ' +
+      'Under a bundled GJS app (import.meta anchors at the bundle), set NODE_GI_NATIVE to the addon path.',
   );
 }
 
@@ -133,7 +168,10 @@ try {
 // matching Node's checkpoint and GJS (SpiderMonkey drains the promise-job queue
 // when the last JS frame exits). Node never registers — its checkpoint already
 // runs natively, so the Node path is byte-identical to before.
-if (!isNodeRuntime) {
+// GJS never registers: SpiderMonkey/GJS drains the promise-job queue from its
+// own main-loop source whenever the last JS frame exits — the exact semantic
+// this checkpoint recreates for Bun/Deno.
+if (!isNodeRuntime && RUNTIME !== 'gjs') {
   try {
     let drain = null;
     if (RUNTIME === 'bun') {

package/overrides/byte-array.js

@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: MIT OR LGPL-2.0-or-later
+// SPDX-FileCopyrightText: 2017 Philip Chimento <philip.chimento@gmail.com>
+//
+// Adapted from GJS (refs/gjs/modules/script/byteArray.js + the native
+// refs/gjs/gjs/byteArray.cpp `imports._byteArrayNative` functions). Copyright
+// (c) 2017 Philip Chimento. MIT OR LGPL-2.0-or-later.
+// Modifications: the legacy `imports.byteArray` module ported to
+// @gjsify/node-gi. The native `fromGBytes`/`fromString`/`toString` are
+// reimplemented in JS over the engine's boxed-GBytes surface and
+// TextEncoder/TextDecoder, preserving GJS semantics:
+//   - toString/fromString are ZERO-TERMINATED (data truncates at the first NUL
+//     byte — gjs/text-encoding.cpp `zero_terminated_length`), and decoding is
+//     FATAL (invalid sequences throw a TypeError, like gjs's fatal=true).
+//   - fromGBytes/fromString return a COPY as a plain Uint8Array carrying the
+//     legacy own `toString(encoding)` method gjs tacks on
+//     (`define_legacy_tostring`), minus gjs's once-per-callsite deprecation
+//     warning (stderr-only noise a byte-golden never sees).
+//   - toGBytes routes through `new GLib.Bytes(array)` exactly as the gjs
+//     script module does; GLib is loaded lazily so building `imports` never
+//     pulls the namespace in.
+
+// Truncate a byte array at the first NUL, per gjs's ZERO_TERMINATED handling
+// (gjs/text-encoding.cpp zero_terminated_length).
+function zeroTerminated(u8) {
+  const nul = u8.indexOf(0);
+  return nul === -1 ? u8 : u8.subarray(0, nul);
+}
+
+// gjs routes non-UTF-8 encodings through iconv; Node's TextDecoder (decode
+// side) accepts WHATWG labels which cover the practical iconv set, so decoding
+// just passes the label through. The ENCODE side has no general converter on
+// Node — map the labels gjs consumers actually use onto Buffer encodings and
+// throw a clear error for the rest.
+const ENCODE_LABELS = new Map([
+  ['latin1', 'latin1'],
+  ['iso-8859-1', 'latin1'],
+  ['iso8859-1', 'latin1'],
+  ['ascii', 'ascii'],
+  ['us-ascii', 'ascii'],
+  ['utf-16', 'utf16le'],
+  ['utf-16le', 'utf16le'],
+  ['utf16le', 'utf16le'],
+]);
+
+function isUtf8Label(encoding) {
+  const label = String(encoding).toLowerCase();
+  return label === 'utf-8' || label === 'utf8';
+}
+
+// The legacy own `toString(encoding)` gjs defines on arrays returned by
+// fromString/fromGBytes/fromArray (byteArray.cpp define_legacy_tostring).
+function defineLegacyToString(u8, toString) {
+  Object.defineProperty(u8, 'toString', {
+    value(encoding = 'utf-8') {
+      return toString(u8, encoding);
+    },
+    writable: true,
+    enumerable: false,
+    configurable: true,
+  });
+  return u8;
+}
+
+/**
+ * Build the legacy `imports.byteArray` module bound to the L1 backend.
+ * @param {(ns: string, version?: string) => Record<string, any>} requireGi
+ * @returns {{ ByteArray: any, fromArray: Function, fromGBytes: Function, fromString: Function, toGBytes: Function, toString: Function }}
+ */
+export function createByteArray(requireGi) {
+  /**
+   * @param {Uint8Array} byteArray bytes to decode
+   * @param {string} [encoding] a WHATWG/iconv label, default UTF-8
+   * @returns {string} the decoded string, stopping at the first NUL byte
+   */
+  function toString(byteArray, encoding = 'utf-8') {
+    // Plain Error, not TypeError — gjs raises these argument failures via
+    // gjs_throw (Error); only the GBytes typecheck below is a TypeError.
+    if (!(byteArray instanceof Uint8Array)) throw new Error('Argument to decode() must be a Uint8Array');
+    const data = zeroTerminated(byteArray);
+    if (data.length === 0) return '';
+    // fatal:true mirrors gjs's fatal decode (invalid sequences throw).
+    return new TextDecoder(encoding, { fatal: true }).decode(data);
+  }
+
+  /**
+   * @param {string} string the string to encode
+   * @param {string} [encoding] a WHATWG/iconv label, default UTF-8
+   * @returns {Uint8Array} the encoded bytes, truncated at the first NUL byte
+   */
+  function fromString(string, encoding = 'utf-8') {
+    if (typeof string !== 'string') throw new Error('Argument to fromString() must be a string');
+    let encoded;
+    if (isUtf8Label(encoding)) {
+      encoded = new TextEncoder().encode(string);
+    } else {
+      const bufferEncoding = ENCODE_LABELS.get(String(encoding).toLowerCase());
+      if (!bufferEncoding) throw new Error(`Unsupported encoding for fromString(): ${encoding}`);
+      const buf = Buffer.from(string, bufferEncoding);
+      encoded = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+    }
+    const data = zeroTerminated(encoded);
+    // Copy into a fresh plain Uint8Array (gjs returns a standalone buffer, and
+    // Buffer.from may hand out a view into Node's shared slab).
+    const out = new Uint8Array(data.length);
+    out.set(data);
+    return defineLegacyToString(out, toString);
+  }
+
+  /**
+   * @param {any} bytes a GLib.Bytes boxed handle
+   * @returns {Uint8Array} a copy of the bytes as a plain Uint8Array
+   */
+  function fromGBytes(bytes) {
+    // The engine's boxed GBytes proxy carries `toArray()` (gi.js wrapBoxed) —
+    // the same convenience gjs adds to GLib.Bytes.prototype. Its absence means
+    // the value is not a GBytes, matching gjs's G_TYPE_BYTES typecheck throw.
+    if (!bytes || typeof bytes.toArray !== 'function') {
+      throw new TypeError('Argument to fromGBytes() must be a GLib.Bytes');
+    }
+    const data = bytes.toArray();
+    // toArray() already returns a copy of the GBytes data; re-view it as a
+    // PLAIN Uint8Array (gjs returns Uint8Array, not Node's Buffer subclass).
+    const out = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    return defineLegacyToString(out, toString);
+  }
+
+  /**
+   * @param {Uint8Array} array the Uint8Array to convert to GLib.Bytes
+   * @returns {any} a GLib.Bytes boxed handle
+   */
+  function toGBytes(array) {
+    if (!(array instanceof Uint8Array)) throw new Error('Argument to ByteArray.toGBytes() must be a Uint8Array');
+    const GLib = requireGi('GLib', '2.0');
+    return new GLib.Bytes(array);
+  }
+
+  // The legacy ByteArray wrapper class, ported verbatim from
+  // refs/gjs/modules/script/byteArray.js (backwards compatibility only).
+  const ByteArray = class ByteArray {
+    constructor(arg = 0) {
+      if (arg instanceof Uint8Array) this._array = arg;
+      else this._array = new Uint8Array(arg);
+      return new Proxy(this, ByteArray);
+    }
+
+    static get(target, prop, receiver) {
+      if (!Number.isNaN(Number.parseInt(prop))) return Reflect.get(target._array, prop);
+      return Reflect.get(target, prop, receiver);
+    }
+
+    static set(target, prop, val, receiver) {
+      const ix = Number.parseInt(prop);
+      if (!Number.isNaN(ix)) {
+        if (ix >= target._array.length) {
+          const newArray = new Uint8Array(ix + 1);
+          newArray.set(target._array);
+          target._array = newArray;
+        }
+        return Reflect.set(target._array, prop, val);
+      }
+      return Reflect.set(target, prop, val, receiver);
+    }
+
+    get length() {
+      return this._array.length;
+    }
+
+    set length(newLength) {
+      if (newLength === this._array.length) return;
+      if (newLength < this._array.length) {
+        this._array = new Uint8Array(this._array.buffer, 0, newLength);
+        return;
+      }
+      const newArray = new Uint8Array(newLength);
+      newArray.set(this._array);
+      this._array = newArray;
+    }
+
+    toString(encoding = 'UTF-8') {
+      return toString(this._array, encoding);
+    }
+
+    toGBytes() {
+      return toGBytes(this._array);
+    }
+  };
+
+  /**
+   * @param {Iterable<number>} array an iterable to convert into a ByteArray wrapper
+   * @returns {InstanceType<ByteArray>}
+   */
+  function fromArray(array) {
+    return new ByteArray(Uint8Array.from(array));
+  }
+
+  return { ByteArray, fromArray, fromGBytes, fromString, toGBytes, toString };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/node-gi",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "GObject-Introspection runtime for Node.js — load gi:// namespaces (GLib/GObject/Gio/…) with GJS-compatible semantics. Vendored + rewritten from node-gtk under MIT.",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,12 @@
     "prebuilds"
   ],
   "gjsify": {
+    "platforms": [
+      "linux-x64",
+      "linux-arm64",
+      "darwin-arm64",
+      "win32-x64"
+    ],
     "runtimes": {
       "gjs": "none",
       "node": "polyfill",
@@ -79,6 +85,7 @@
     "test:dbus": "dbus-run-session -- env NODE_GI_NATIVE=build node --test --expose-gc test/dbus.test.mjs test/dbus-async.test.mjs",
     "test:bun": "node scripts/cross-runtime.mjs bun",
     "test:conformance": "node scripts/conformance.mjs",
+    "test:conformance:gjs-napi": "node scripts/conformance.mjs --runtimes=gjs-napi",
     "test:gimarshalling": "node scripts/gimarshalling.mjs",
     "test:deno": "node scripts/cross-runtime.mjs deno",
     "test:cairo": "NODE_GI_NATIVE=build node --test test/cairo.test.mjs",