@gjsify/node-gi 0.13.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 gjsify contributors
+
+Portions of this package are derived from node-gtk
+(https://github.com/romgrk/node-gtk):
+Copyright (c) romgrk and node-gtk contributors.
+node-gtk is licensed under the MIT License.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# @gjsify/node-gi
+
+**GObject-Introspection runtime for Node.js** — the native engine that lets
+unchanged GJS / GObject-Introspection code run under Node.js, the inverse of
+gjsify's Node/Web/DOM → GJS direction (see the gjsify `AGENTS.md`
+`### Axis 5 active track`).
+
+It loads `gi://` namespaces (GLib, GObject, Gio, …) via `libgirepository` and
+exposes them with GJS-compatible semantics, so the same source builds and runs
+on both GJS and Node via `gjsify build --app {gjs,node}`.
+
+> **Status: milestone 1 (headless core) — in progress.** The native engine over
+> the modern `girepository-2.0` API now does: resolve the default repository,
+> `require` a namespace, enumerate its infos; call namespace-level functions and
+> **instance methods** (own + implemented-interface methods, up the parent chain)
+> with value marshalling (numbers, booleans, strings, GObjects, enums/flags);
+> construct GObjects and read/write properties (GValue round-trip); connect /
+> emit / disconnect signals (incl. detailed names like `notify::prop`); and
+> **register GObject subclasses** (subtype + construct-by-type, inheriting the
+> parent's properties/methods, plus **custom properties + signals** declared on
+> the subclass). Ownership rides
+> N-API finalizers (no V8-GC reentrancy). On top of the engine, an **L1
+> GJS-compatibility layer** (`@gjsify/node-gi/gi`, `requireGi`) surfaces a
+> GJS-shaped namespace: `new Gio.SimpleAction({ name })`, `action.name` property
+> access, `action.get_name()` methods, `.connect()/.emit()/.disconnect()`, and
+> enums / flags / constants (`Gio.BusType.SESSION`, `GLib.PRIORITY_DEFAULT`);
+> constructor/static methods (`Gio.File.new_for_path(...)`); and both snake_case
+> and camelCase accessors. A **libuv↔GLib mainloop bridge** (`startMainLoop`,
+> auto-attached by `requireGi`) nests Node's libuv loop inside the GLib loop, so a
+> blocking `GLib.MainLoop.run()` keeps Node's timers/I/O alive — including the
+> **boxed/struct slice** that needs (`GLib.MainLoop.new(...)` → a boxed handle →
+> `.run()`/`.quit()`). **JS functions marshal as GI callbacks** via an ffi
+> closure (`GLib.timeout_add`/`idle_add` fire from the loop, the boolean return
+> drives source continuation; the hidden user_data/destroy slots are auto-filled).
+> register GObject subclasses (subtype + construct-by-type, inheriting the
+> parent's properties/methods, plus **custom properties + signals**, plus
+> **vfunc overrides** — a JS function overriding a parent GObject vfunc, hooked
+> into the new type's class vtable). The gjsify `--app node` bundler integration
+> already rewrites `gi://` onto the L1 layer. vfunc **chain-up** to the parent
+> implementation (with the toggle-ref GC bridge) and general struct field access
+> land in subsequent drops — for now a vfunc override fully replaces the inherited
+> implementation.
+
+## Provenance
+
+Derived from [node-gtk](https://github.com/romgrk/node-gtk) (romgrk and
+contributors, MIT) — vendored and rewritten under MIT (see `LICENSE`). The
+native binding is **retargeted to `girepository-2.0`** (the GIRepository merged
+into GLib ≥ 2.80); the standalone `libgirepository-1.0` node-gtk linked is no
+longer shipped on modern systems. GJS's own `gi/repo.cpp` is the reference for
+the `girepository-2.0` API surface. node-gtk's own examples and tests are **not**
+vendored as-is — gjsify ships its own dual (GJS + Node) example/test infra.
+
+## Requirements
+
+- Node.js ≥ 20
+- A C++ toolchain (`g++`/`clang`, `make`), `node-gyp`
+- GLib ≥ 2.80 development headers exposing `girepository-2.0`
+  (Fedora: `glib2-devel gobject-introspection-devel gcc-c++`;
+   Debian/Ubuntu: `libglib2.0-dev libgirepository-2.0-dev g++`)
+- At runtime, the target libraries' typelibs must be installed (same as `gi://`
+  under GJS).
+
+## Build & test
+
+```bash
+npm install          # builds the native addon via node-gyp (install script)
+npm test             # node --test (smoke tests)
+# or rebuild explicitly:
+npm run rebuild
+```
+
+## Usage (milestone 1)
+
+```js
+import {
+  requireNamespace, listInfoNames, callFunction,
+  newObject, getProperty, setProperty, callMethod,
+  connectSignal, emitSignal,
+} from '@gjsify/node-gi';
+
+requireNamespace('GLib', '2.0');
+console.log(listInfoNames('GLib').includes('MainLoop')); // true
+console.log(callFunction('GLib', 'get_host_name'));      // namespace function
+
+requireNamespace('Gio', '2.0');
+const action = newObject('Gio', 'SimpleAction', { name: 'greet', enabled: true });
+console.log(getProperty(action, 'name'));     // 'greet'  (GValue round-trip)
+console.log(callMethod(action, 'get_name'));  // 'greet'  (interface method)
+callMethod(action, 'set_enabled', [false]);   // method with an IN argument
+
+const c = newObject('Gio', 'Cancellable', {});
+connectSignal(c, 'cancelled', () => console.log('cancelled'));
+emitSignal(c, 'cancelled');
+```
+
+Register a GObject subclass and construct it (inherited properties + methods):
+
+```js
+import { registerClass, constructType, callMethod } from '@gjsify/node-gi';
+
+const MyAction = registerClass('MyAction', 'Gio', 'SimpleAction');
+const a = constructType(MyAction, { name: 'greet', enabled: true });
+console.log(callMethod(a, 'get_name')); // 'greet'  (inherited GAction method)
+```
+
+Declare custom properties and signals on the subclass:
+
+```js
+import { registerClass, constructType, getProperty, setProperty,
+         connectSignal, emitSignal } from '@gjsify/node-gi';
+
+const Counter = registerClass('Counter', 'GObject', 'Object', {
+  properties: [{ name: 'count', type: 'int', default: 0, minimum: 0, maximum: 100 }],
+  signals: [{ name: 'changed', paramTypes: ['int'] }],
+});
+
+const c = constructType(Counter, { count: 1 });
+connectSignal(c, 'notify::count', (pspec) => console.log('changed:', pspec.name));
+connectSignal(c, 'changed', (n) => console.log('count is now', n));
+setProperty(c, 'count', 5);          // fires notify::count
+emitSignal(c, 'changed', [5]);
+console.log(getProperty(c, 'count')); // 5
+```
+
+Override a parent GObject vfunc with a JS function (the override runs as a method
+on the instance — `this` is the GObject handle). Chain-up to the parent vfunc
+lands in a later drop, so an override fully replaces the inherited implementation:
+
+```js
+import { registerClass, constructType, getProperty } from '@gjsify/node-gi';
+
+const Greeter = registerClass('Greeter', 'Gio', 'SimpleAction', {
+  vfuncs: {
+    // GObject's `constructed` vfunc — runs once, after construct properties are
+    // set. `name` is a CONSTRUCT_ONLY property already available on `this`.
+    constructed() {
+      console.log('constructed:', getProperty(this, 'name'));
+    },
+  },
+});
+
+constructType(Greeter, { name: 'greet' }); // logs "constructed: greet"
+```
+
+### L1 — GJS-shaped surface (`@gjsify/node-gi/gi`)
+
+The ergonomic layer the gjsify `--app node` build rewrites `gi://` imports onto.
+This is the same code you would write under GJS:
+
+```js
+import { requireGi } from '@gjsify/node-gi/gi';
+
+const GLib = requireGi('GLib', '2.0');
+console.log(GLib.get_host_name());
+
+const Gio = requireGi('Gio', '2.0');
+const action = new Gio.SimpleAction({ name: 'greet', enabled: true });
+console.log(action.name);          // 'greet'   (property accessor)
+console.log(action.get_name());    // 'greet'   (method)
+action.enabled = false;            // property set → set_property
+
+const c = new Gio.Cancellable();
+c.connect('cancelled', () => console.log('cancelled'));
+c.cancel();                        // fires the signal
+
+// enums, flags and constants (GJS-style UPPER_CASE members)
+console.log(GLib.PRIORITY_DEFAULT);        // 0
+console.log(Gio.BusType.SESSION);          // 2
+console.log(Gio.ApplicationFlags.HANDLES_OPEN);  // 4
+
+// constructor/static methods + camelCase aliases
+const file = Gio.File.new_for_path('/usr/bin/gjs');
+console.log(file.get_path());      // '/usr/bin/gjs'
+console.log(file.getBasename());   // 'gjs'  (camelCase alias)
+
+// mainloop: a blocking GLib loop, with Node's libuv kept alive underneath
+const loop = GLib.MainLoop.new(null, false);
+setTimeout(() => loop.quit(), 100); // a libuv timer that fires during run()
+loop.run();                         // blocks like under GJS; returns on quit()
+
+// GI callbacks: a JS function passed where a GI callback is expected. The
+// GLib source fires from the loop; returning false (G_SOURCE_REMOVE) stops it.
+const ticker = GLib.MainLoop.new(null, false);
+let n = 0;
+GLib.timeout_add(GLib.PRIORITY_DEFAULT, 50, () => {
+  if (++n >= 3) { ticker.quit(); return false; }
+  return true;
+});
+ticker.run();
+```
+
+The mainloop bridge (`startMainLoop`) is auto-attached the first time `requireGi`
+loads a namespace, so `GLib.MainLoop.run()` / `Gio.Application.run()` block as
+they do under GJS while Node's timers, I/O and signal handlers keep running.
+
+### GJS ambient globals (`@gjsify/node-gi/globals`)
+
+GJS source relies on globals that exist implicitly under `gjs` — `print`,
+`printerr`, `log`, `logError`, `ARGV`, and the legacy `imports` object. Importing
+`@gjsify/node-gi/globals` (a side effect) installs Node-backed equivalents that
+route through the same backend:
+
+```js
+import '@gjsify/node-gi/globals';
+
+print('hello', 1, true);                 // → stdout, GJS String()-join
+const GLib = imports.gi.GLib;            // legacy imports.gi (honours .versions)
+imports.gi.versions.Gtk = '4.0';
+console.log(imports.gettext.gettext('x')); // no-translation passthrough
+```
+
+A follow-up `--app node` build step will inject this automatically for any
+bundle that references those globals (so `const Gtk = imports.gi.Gtk` /
+`print(...)` GJS source runs unmodified on Node); today it is an explicit import.
+
+The remaining GJS-compatible surface (`import GLib from 'gi://GLib?version=2.0'`,
+`const GLib = imports.gi.GLib`, the core overrides, `_promisify`, the legacy
+`imports.*` modules) is layered on top of this engine in the gjsify bundler
+integration and subsequent drops.

package/binding.gyp

@@ -0,0 +1,34 @@
+{
+  "targets": [
+    {
+      "target_name": "node_gi",
+      "sources": [
+        "src/addon.cc"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "cflags": [
+        "<!@(pkg-config --cflags girepository-2.0)"
+      ],
+      "cflags_cc": [
+        "<!@(pkg-config --cflags girepository-2.0)",
+        "-std=c++17"
+      ],
+      "libraries": [
+        "<!@(pkg-config --libs girepository-2.0)"
+      ],
+      "defines": [
+        "NAPI_VERSION=8",
+        "NAPI_DISABLE_CPP_EXCEPTIONS"
+      ],
+      "xcode_settings": {
+        "OTHER_CFLAGS": [
+          "<!@(pkg-config --cflags girepository-2.0)"
+        ],
+        "CLANG_CXX_LANGUAGE_STANDARD": "c++17",
+        "GCC_ENABLE_CPP_EXCEPTIONS": "NO"
+      }
+    }
+  ]
+}

package/gi.d.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi/gi — L1 GJS-compatibility layer type surface.
+//
+// The runtime returns a Proxy whose members are resolved dynamically from
+// introspection, so the precise per-namespace shape is not statically known
+// here. Under gjsify's bundler integration the call site
+// `import Ns from 'gi://Ns?version=X'` is typed by the platform-neutral ambient
+// `@girs/*` module declarations; this declaration types the bare runtime entry.
+
+/** A GJS-shaped namespace object (members resolved dynamically). */
+export type GiNamespace = Record<string, unknown>;
+
+/**
+ * Require a GObject-Introspection namespace and return a GJS-shaped namespace
+ * object. The Node twin of `import Ns from 'gi://Ns?version=X'` /
+ * `imports.gi.Ns`. Members are resolved lazily from introspection: namespace
+ * functions become callables, GObject types become constructors whose instances
+ * expose `.method(...)`, `.prop` get/set and `.connect()/.emit()/.disconnect()`.
+ */
+export function requireGi(namespace: string, version?: string): GiNamespace;
+
+/**
+ * Extract the raw native GObject handle from a wrapped instance (advanced /
+ * interop use). Returns the value unchanged if it is not a wrapped instance.
+ */
+export function unwrap(value: unknown): unknown;
+
+export default requireGi;

package/gi.js

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi/gi — the L1 GJS-compatibility layer over the native engine.
+//
+// Turns the low-level primitives (requireNamespace / findInfo / callFunction /
+// newObject / callMethod / get|setProperty / connect|emit|disconnectSignal) into
+// a GJS-shaped namespace object: `requireGi('Gio', '2.0')` returns an object
+// where `Gio.SomeFunction(...)` calls a namespace function, `new Gio.SomeClass({
+// prop: value })` constructs a GObject, and the instance exposes `.method(...)`,
+// `.prop` (property get/set) and `.connect()/.emit()/.disconnect()` — the same
+// surface `import Gio from 'gi://Gio?version=2.0'` gives under GJS.
+//
+// This is the seam the bundler's --app node target rewrites `gi://Ns?version=X`
+// onto. Reference: GJS's gi module (gjs/modules/esm/gi.js) for the require shape;
+// node-gtk (romgrk, MIT) for the binding lineage. Hand-authored JS (the package
+// ships no build step). Milestone 1 surfaces functions + GObject classes; enums,
+// flags, constants, structs/boxed, interface static methods and camelCase
+// aliases land in subsequent drops.
+import * as native from './index.js';
+
+// Symbol carrying the raw native GObject handle on a wrapped instance, so it can
+// be unwrapped again when passed back into the engine as a GI argument.
+const HANDLE = Symbol('nodeGiHandle');
+
+// JS-builtin / interop names that must NEVER be treated as a GI method or
+// property — otherwise awaiting, printing or inspecting a wrapper would call
+// into GObject (e.g. a stray `then` would make a wrapper look thenable).
+const RESERVED = new Set(['then', 'toString', 'valueOf', 'constructor', 'inspect']);
+
+// GJS accepts both snake_case and camelCase for methods/properties. Map a JS
+// accessor to the GI method name (snake_case) and to a GObject property name
+// (kebab-case); a name that is already in the target case passes through.
+function camelToSnake(name) {
+  return name.replace(/([A-Z])/g, '_$1').toLowerCase();
+}
+
+function toKebab(name) {
+  return name.replace(/([A-Z])/g, '-$1').replace(/_/g, '-').toLowerCase();
+}
+
+function unwrapArg(value) {
+  if (value !== null && typeof value === 'object' && value[HANDLE] !== undefined) {
+    return value[HANDLE];
+  }
+  return value;
+}
+
+function unwrapArgs(args) {
+  return args.map(unwrapArg);
+}
+
+function unwrapProps(props) {
+  const out = {};
+  for (const key of Object.keys(props)) out[key] = unwrapArg(props[key]);
+  return out;
+}
+
+// Object-typed return values become chainable instance proxies; boxed/struct
+// handles (e.g. GMainLoop) become method-routing proxies; everything else
+// (primitives, strings, null) passes through.
+function wrapReturn(value) {
+  if (native.isGObjectHandle(value)) return wrapInstance(value);
+  if (native.isBoxedHandle(value)) return wrapBoxed(value);
+  return value;
+}
+
+// Wrap a boxed/struct handle so its methods are callable GJS-style
+// (`mainLoop.run()`, `mainLoop.quit()`, snake_case or camelCase). Boxed types
+// have no GObject properties/signals, so only method routing is provided.
+function wrapBoxed(handle) {
+  const target = { [HANDLE]: handle };
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === HANDLE) return handle;
+      if (typeof prop !== 'string' || RESERVED.has(prop)) return t[prop];
+      return (...args) =>
+        wrapReturn(native.callBoxedMethod(handle, camelToSnake(prop), unwrapArgs(args)));
+    },
+    has(t, prop) {
+      return prop === HANDLE || prop in t;
+    },
+  });
+}
+
+function wrapInstance(handle) {
+  const target = { [HANDLE]: handle };
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === HANDLE) return handle;
+      if (typeof prop !== 'string' || RESERVED.has(prop)) return t[prop];
+      switch (prop) {
+        case 'connect':
+          return (signal, cb) => native.connectSignal(handle, signal, cb, false);
+        case 'connect_after':
+          return (signal, cb) => native.connectSignal(handle, signal, cb, true);
+        case 'emit':
+          return (signal, ...args) =>
+            wrapReturn(native.emitSignal(handle, signal, unwrapArgs(args)));
+        case 'disconnect':
+          return (id) => native.disconnectSignal(handle, id);
+        default:
+          break;
+      }
+      const propName = toKebab(prop);
+      if (native.hasProperty(handle, propName)) {
+        return wrapReturn(native.getProperty(handle, propName));
+      }
+      return (...args) => wrapReturn(native.callMethod(handle, camelToSnake(prop), unwrapArgs(args)));
+    },
+    set(t, prop, value) {
+      if (typeof prop === 'string') {
+        const propName = toKebab(prop);
+        if (native.hasProperty(handle, propName)) {
+          native.setProperty(handle, propName, unwrapArg(value));
+          return true;
+        }
+      }
+      t[prop] = value;
+      return true;
+    },
+    has(t, prop) {
+      return prop === HANDLE || prop in t;
+    },
+  });
+}
+
+function makeClass(namespace, typeName) {
+  const ctor = function ctor(props) {
+    const handle = native.newObject(namespace, typeName, props ? unwrapProps(props) : {});
+    return wrapInstance(handle);
+  };
+  Object.defineProperty(ctor, 'name', { value: typeName, configurable: true });
+  ctor.$gtypeName = `${namespace}.${typeName}`;
+  // Expose constructor/static methods lazily: Ns.Class.new(...) /
+  // Ns.Class.new_for_path(...) (and the camelCase aliases). `new Ns.Class({...})`
+  // still goes through the target's [[Construct]] (the default Proxy behaviour).
+  return new Proxy(ctor, {
+    get(t, prop) {
+      if (typeof prop !== 'string' || prop in t || RESERVED.has(prop)) return t[prop];
+      const giName = camelToSnake(prop);
+      return (...args) =>
+        wrapReturn(native.callStaticMethod(namespace, typeName, giName, unwrapArgs(args)));
+    },
+  });
+}
+
+// Surface a boxed/struct type (e.g. GLib.MainLoop) as a class-like object whose
+// static/constructor methods route through the engine: `GLib.MainLoop.new(...)`
+// and the camelCase alias, plus `new GLib.MainLoop(...)` mapped to the `new`
+// constructor. Returned boxed instances are wrapped by {@link wrapBoxed}.
+function makeStruct(namespace, typeName) {
+  const base = function () {};
+  Object.defineProperty(base, 'name', { value: typeName, configurable: true });
+  base.$gtypeName = `${namespace}.${typeName}`;
+  return new Proxy(base, {
+    get(t, prop) {
+      if (typeof prop !== 'string' || prop in t || RESERVED.has(prop)) return t[prop];
+      const giName = camelToSnake(prop);
+      return (...args) =>
+        wrapReturn(native.callStaticMethod(namespace, typeName, giName, unwrapArgs(args)));
+    },
+    construct(_t, args) {
+      return wrapReturn(native.callStaticMethod(namespace, typeName, 'new', unwrapArgs(args)));
+    },
+  });
+}
+
+// Build a frozen enum/flags object keyed GJS-style: member names UPPER_CASED
+// with '-' → '_' (e.g. Gio.BusType.SYSTEM, Gio.ApplicationFlags.HANDLES_OPEN).
+function makeEnum(namespace, typeName) {
+  const raw = native.getEnumValues(namespace, typeName);
+  const out = {};
+  for (const key of Object.keys(raw)) {
+    out[key.toUpperCase().replace(/-/g, '_')] = raw[key];
+  }
+  return Object.freeze(out);
+}
+
+function createNamespace(namespace) {
+  const cache = new Map();
+  return new Proxy(Object.create(null), {
+    get(_t, prop) {
+      if (typeof prop !== 'string' || RESERVED.has(prop)) return undefined;
+      if (cache.has(prop)) return cache.get(prop);
+      const info = native.findInfo(namespace, prop);
+      let value;
+      if (info === null) {
+        value = undefined;
+      } else if (info.kind === 'function') {
+        value = (...args) => wrapReturn(native.callFunction(namespace, prop, unwrapArgs(args)));
+      } else if (info.kind === 'object' || info.kind === 'interface') {
+        // Interfaces are not constructible (`new` throws via newObject) but
+        // carry static/constructor methods, e.g. Gio.File.new_for_path.
+        value = makeClass(namespace, prop);
+      } else if (info.kind === 'enum' || info.kind === 'flags') {
+        value = makeEnum(namespace, prop);
+      } else if (info.kind === 'constant') {
+        value = native.getConstantValue(namespace, prop);
+      } else if (info.kind === 'struct' || info.kind === 'union') {
+        // Boxed/struct types: static/constructor methods + boxed instances
+        // (GLib.MainLoop, …). Field access lands with the broader structs drop.
+        value = makeStruct(namespace, prop);
+      } else {
+        // interface / callback: surfaced in a later drop.
+        value = undefined;
+      }
+      cache.set(prop, value);
+      return value;
+    },
+    has(_t, prop) {
+      return typeof prop === 'string' && native.findInfo(namespace, prop) !== null;
+    },
+  });
+}
+
+const namespaceCache = new Map();
+
+// Whether the libuv↔GLib bridge has been attached this process. The native
+// startMainLoop is itself idempotent; this just avoids the extra call.
+let loopAttached = false;
+
+/**
+ * Require a GObject-Introspection namespace and return a GJS-shaped namespace
+ * object. The Node twin of `import Ns from 'gi://Ns?version=X'` /
+ * `imports.gi.Ns`.
+ * @param {string} namespace e.g. "Gio"
+ * @param {string} [version] e.g. "2.0"
+ * @returns {Record<string, unknown>}
+ */
+export function requireGi(namespace, version) {
+  native.requireNamespace(namespace, version);
+  // Attach the libuv-in-GLib bridge once, so any later blocking GLib loop
+  // (GLib.MainLoop.run / Gio.Application.run) keeps Node's event loop alive.
+  if (!loopAttached) {
+    native.startMainLoop();
+    loopAttached = true;
+  }
+  const key = version ? `${namespace}@${version}` : namespace;
+  let ns = namespaceCache.get(key);
+  if (ns === undefined) {
+    ns = createNamespace(namespace);
+    namespaceCache.set(key, ns);
+  }
+  return ns;
+}
+
+/**
+ * Extract the raw native GObject handle from a wrapped instance (advanced /
+ * interop use). Returns the value unchanged if it is not a wrapped instance.
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function unwrap(value) {
+  return unwrapArg(value);
+}
+
+export default requireGi;

package/globals.d.ts

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi/globals — types for the GJS ambient-globals shim.
+
+/** The legacy GJS `imports` object (a minimal Node-backed subset). */
+export interface GjsImports {
+  /** `imports.gi.<Ns>` resolves a namespace; `imports.gi.versions.<Ns>` pins a version. */
+  gi: {
+    versions: Record<string, string | undefined>;
+    [namespace: string]: unknown;
+  };
+  /** `imports.system` — process identity + lifecycle (Node-backed subset). */
+  system: {
+    exit(code?: number): void;
+    gc(): void;
+    readonly programInvocationName: string;
+    readonly programPath: string | null;
+    version: number;
+    addressOf(): string;
+    refcount(): number;
+    breakpoint(): void;
+    dumpHeap(): void;
+    dumpMemoryInfo(): void;
+  };
+  /** `imports.gettext` — a no-translation passthrough. */
+  gettext: {
+    gettext(s: string): string;
+    dgettext(domain: string, s: string): string;
+    dcgettext(domain: string, s: string): string;
+    ngettext(s: string, p: string, n: number): string;
+    dngettext(domain: string, s: string, p: string, n: number): string;
+    pgettext(ctx: string, s: string): string;
+    dpgettext(domain: string, ctx: string, s: string): string;
+    domain(domain: string): {
+      gettext(s: string): string;
+      ngettext(s: string, p: string, n: number): string;
+      pgettext(ctx: string, s: string): string;
+    };
+    setlocale(): null;
+    bindtextdomain(): null;
+    textdomain(): null;
+    bindtextdomainCodeset(): null;
+    LocaleCategory: Record<string, number>;
+  };
+  versions: Record<string, unknown>;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var print: (...args: unknown[]) => void;
+  // eslint-disable-next-line no-var
+  var printerr: (...args: unknown[]) => void;
+  // eslint-disable-next-line no-var
+  var log: (...args: unknown[]) => void;
+  // eslint-disable-next-line no-var
+  var logError: (error: unknown, prefix?: string) => void;
+  // eslint-disable-next-line no-var
+  var ARGV: string[];
+  // eslint-disable-next-line no-var
+  var imports: GjsImports;
+}
+
+/** Install the GJS ambient globals on `globalThis` (idempotent). */
+export function installGjsGlobals(): GjsImports;
+
+declare const _default: typeof installGjsGlobals;
+export default _default;