@gjsify/node-gi 0.26.1 → 0.27.1

package/native-paths.js

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi — WHERE the native addon lives. ONE definition, shared by the
+// two decisions that must never disagree about it:
+//
+//   1. `index.js#loadNative()` — which binary a CONSUMER loads at runtime.
+//   2. `scripts/install.mjs` — whether the `install` lifecycle script has to run
+//      a node-gyp source build at all.
+//
+// WHY THIS MODULE EXISTS: those two used to be one implementation and one
+// hard-coded string in a different file. `prebuilds/<platform>-<arch>/node_gi.node`
+// spelled twice is the setup for the two silent failures nobody sees in CI — a
+// guard that skips the build because it looked in a directory the loader does not
+// probe (install succeeds, the first `import` throws), or a guard that rebuilds on
+// every install while a perfectly good prebuild sits right beside it (the defect
+// the guard was added to remove). Sharing the probe makes both impossible by
+// construction: the target-dir spelling, the addon filename and the candidate
+// ORDER exist exactly once, here.
+//
+// NOT the same question as `resolveAddonPath()` in
+// packages/infra/rolldown-plugin-gjsify (the `@gjsify/napi` bundler seam). That
+// one replicates node-gyp-build's probe order for ARBITRARY third-party addons
+// being bundled for `--app gjs`: `build/Release` → `build/Debug` → prebuild, with
+// node-gyp-build's `<runtime>.<abi|napi>.node` tag grammar. node-gi's own default
+// is deliberately the OPPOSITE way round (prebuild FIRST — see nativeCandidates
+// below) and its artifact is a plain `node_gi.node`. Two different questions, two
+// definitions; this file is the authority for node-gi's own binary, and the third
+// copy is the one that must never be written.
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+/**
+ * The package root. This module sits beside `index.js`, so its own directory IS
+ * the root — the same anchor `index.js` used before the extraction.
+ */
+export const packageRoot = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The addon's file name, identical in `build/{Release,Debug}/` and in a staged
+ * `prebuilds/<target>/` (scripts/stage-prebuild.mjs copies it verbatim). NOT
+ * node-gyp-build's tag grammar — nothing in this package parses tags.
+ */
+export const ADDON_FILENAME = 'node_gi.node';
+
+/**
+ * The `<os>-<arch>` prebuild target spelling — `${process.platform}-${process.arch}`,
+ * the ONE spelling used across the whole workspace (see AGENTS.md § Runtime &
+ * platform model: it is what a running process computes about itself, so
+ * resolution needs no translation).
+ *
+ * A pure function of its arguments so the darwin/win32 branches of anything
+ * built on it stay testable from a Linux host; the host values are read only at
+ * the outermost call site, as defaults.
+ * @param {string} [platform] defaults to `process.platform`
+ * @param {string} [arch] defaults to `process.arch`
+ * @returns {string} e.g. `linux-x64`, `win32-x64`, `darwin-arm64`
+ */
+export function hostTarget(platform = process.platform, arch = process.arch) {
+    return `${platform}-${arch}`;
+}
+
+/**
+ * Absolute path of the SHIPPED prebuild for a target. This is the path
+ * `scripts/stage-prebuild.mjs` writes, `files: ["prebuilds"]` publishes,
+ * `loadNative()` prefers, and `scripts/install.mjs` tests for.
+ * @param {string} [target] defaults to the running host's target
+ * @returns {string}
+ */
+export function prebuildAddonPath(target = hostTarget()) {
+    return join(packageRoot, 'prebuilds', target, ADDON_FILENAME);
+}
+
+/**
+ * Absolute path of a LOCALLY BUILT addon — what `node-gyp rebuild` writes.
+ * @param {'Release' | 'Debug'} [flavor]
+ * @returns {string}
+ */
+export function buildAddonPath(flavor = 'Release') {
+    return join(packageRoot, 'build', flavor, ADDON_FILENAME);
+}
+
+/**
+ * The ordered list of addon paths to try, most-preferred first.
+ *
+ * `NODE_GI_NATIVE` pins which binary loads. The package's own test scripts set
+ * `build` so local verification always exercises the JUST-BUILT addon — a stale
+ * staged prebuild would otherwise shadow build/Release and silently validate the
+ * wrong binary (the consumer-facing default below prefers the prebuild).
+ *
+ * Default order: prefer a shipped prebuild so a consumer needs no C toolchain and
+ * no node-gyp — the only install path Deno supports (it runs no postinstall build
+ * script). Fall back to a locally built addon (Release, then Debug).
+ * @param {Record<string, string | undefined>} [env] defaults to `process.env`
+ * @returns {string[]}
+ */
+export function nativeCandidates(env = process.env) {
+    const prebuild = prebuildAddonPath();
+    const release = buildAddonPath('Release');
+    const debug = buildAddonPath('Debug');
+    const prefer = env.NODE_GI_NATIVE;
+    if (prefer === 'build') return [release, debug, prebuild];
+    if (prefer === 'prebuild') return [prebuild];
+    if (prefer) return [prefer]; // an explicit path to a node_gi.node
+    return [prebuild, release, debug];
+}

package/overrides/_signals.js

@@ -16,152 +16,149 @@
 //    connections, but they may be to different signal names
 
 function _connectFull(name, callback, after) {
-  // be paranoid about callback arg since we'd start to throw from emit()
-  // if it was messed up
-  if (typeof callback !== 'function')
-    throw new Error('When connecting signal must give a callback that is a function');
-
-  // we instantiate the "signal machinery" only on-demand if anything
-  // gets connected.
-  if (this._signalConnections === undefined) {
-    this._signalConnections = Object.create(null);
-    this._signalConnectionsByName = Object.create(null);
-    this._nextConnectionId = 1;
-  }
-
-  const id = this._nextConnectionId;
-  this._nextConnectionId += 1;
-
-  this._signalConnections[id] = {
-    name,
-    callback,
-    after,
-  };
-
-  const connectionsByName = this._signalConnectionsByName[name] ?? [];
-
-  if (!connectionsByName.length)
-    this._signalConnectionsByName[name] = connectionsByName;
-  connectionsByName.push(id);
-
-  return id;
+    // be paranoid about callback arg since we'd start to throw from emit()
+    // if it was messed up
+    if (typeof callback !== 'function')
+        throw new Error('When connecting signal must give a callback that is a function');
+
+    // we instantiate the "signal machinery" only on-demand if anything
+    // gets connected.
+    if (this._signalConnections === undefined) {
+        this._signalConnections = Object.create(null);
+        this._signalConnectionsByName = Object.create(null);
+        this._nextConnectionId = 1;
+    }
+
+    const id = this._nextConnectionId;
+    this._nextConnectionId += 1;
+
+    this._signalConnections[id] = {
+        name,
+        callback,
+        after,
+    };
+
+    const connectionsByName = this._signalConnectionsByName[name] ?? [];
+
+    if (!connectionsByName.length) this._signalConnectionsByName[name] = connectionsByName;
+    connectionsByName.push(id);
+
+    return id;
 }
 
 export function _connect(name, callback) {
-  return _connectFull.call(this, name, callback, false);
+    return _connectFull.call(this, name, callback, false);
 }
 
 export function _connectAfter(name, callback) {
-  return _connectFull.call(this, name, callback, true);
+    return _connectFull.call(this, name, callback, true);
 }
 
 export function _disconnect(id) {
-  const connection = this._signalConnections?.[id];
+    const connection = this._signalConnections?.[id];
 
-  if (!connection)
-    throw new Error(`No signal connection ${id} found`);
+    if (!connection) throw new Error(`No signal connection ${id} found`);
 
-  if (connection.disconnected)
-    throw new Error(`Signal handler id ${id} already disconnected`);
+    if (connection.disconnected) throw new Error(`Signal handler id ${id} already disconnected`);
 
-  connection.disconnected = true;
-  delete this._signalConnections[id];
+    connection.disconnected = true;
+    delete this._signalConnections[id];
 
-  const ids = this._signalConnectionsByName[connection.name];
-  if (!ids)
-    return;
+    const ids = this._signalConnectionsByName[connection.name];
+    if (!ids) return;
 
-  const indexOfId = ids.indexOf(id);
-  if (indexOfId !== -1)
-    ids.splice(indexOfId, 1);
+    const indexOfId = ids.indexOf(id);
+    if (indexOfId !== -1) ids.splice(indexOfId, 1);
 
-  if (ids.length === 0)
-    delete this._signalConnectionsByName[connection.name];
+    if (ids.length === 0) delete this._signalConnectionsByName[connection.name];
 }
 
 export function _signalHandlerIsConnected(id) {
-  const connection = this._signalConnections?.[id];
-  return !!connection && !connection.disconnected;
+    const connection = this._signalConnections?.[id];
+    return !!connection && !connection.disconnected;
 }
 
 export function _disconnectAll() {
-  Object.values(this._signalConnections ?? {}).forEach(c => (c.disconnected = true));
-  delete this._signalConnections;
-  delete this._signalConnectionsByName;
+    Object.values(this._signalConnections ?? {}).forEach((c) => (c.disconnected = true));
+    delete this._signalConnections;
+    delete this._signalConnectionsByName;
 }
 
 export function _emit(name, ...args) {
-  const connections = this._signalConnectionsByName?.[name];
-
-  // may not be any signal handlers at all, if not then return
-  if (!connections)
-    return;
-
-  // To deal with re-entrancy (removal/addition while
-  // emitting), we copy out a list of what was connected
-  // at emission start; and just before invoking each
-  // handler we check its disconnected flag.
-  const handlers = connections.map(id => this._signalConnections[id]);
-
-  // create arg array which is emitter + everything passed in except
-  // signal name. Would be more convenient not to pass emitter to
-  // the callback, but trying to be 100% consistent with GObject
-  // which does pass it in. Also if we pass in the emitter here,
-  // people don't create closures with the emitter in them,
-  // which would be a cycle.
-  const argArray = [this, ...args];
-
-  const afterHandlers = [];
-  const beforeHandlers = handlers.filter(c => {
-    if (!c.after)
-      return true;
-
-    afterHandlers.push(c);
-    return false;
-  });
-
-  if (!_callHandlers(beforeHandlers, argArray))
-    _callHandlers(afterHandlers, argArray);
+    const connections = this._signalConnectionsByName?.[name];
+
+    // may not be any signal handlers at all, if not then return
+    if (!connections) return;
+
+    // To deal with re-entrancy (removal/addition while
+    // emitting), we copy out a list of what was connected
+    // at emission start; and just before invoking each
+    // handler we check its disconnected flag.
+    const handlers = connections.map((id) => this._signalConnections[id]);
+
+    // create arg array which is emitter + everything passed in except
+    // signal name. Would be more convenient not to pass emitter to
+    // the callback, but trying to be 100% consistent with GObject
+    // which does pass it in. Also if we pass in the emitter here,
+    // people don't create closures with the emitter in them,
+    // which would be a cycle.
+    const argArray = [this, ...args];
+
+    const afterHandlers = [];
+    const beforeHandlers = handlers.filter((c) => {
+        if (!c.after) return true;
+
+        afterHandlers.push(c);
+        return false;
+    });
+
+    if (!_callHandlers(beforeHandlers, argArray)) _callHandlers(afterHandlers, argArray);
 }
 
 function _callHandlers(handlers, argArray) {
-  for (const handler of handlers) {
-    if (handler.disconnected)
-      continue;
-
-    try {
-      // since we pass "null" for this, the global object will be used.
-      const ret = handler.callback.apply(null, argArray);
-
-      // if the callback returns true, we don't call the next
-      // signal handlers
-      if (ret === true)
-        return true;
-    } catch (e) {
-      // just log any exceptions so that callbacks can't disrupt
-      // signal emission
-      logError(e, `Exception in callback for signal: ${handler.name}`);
+    for (const handler of handlers) {
+        if (handler.disconnected) continue;
+
+        try {
+            // since we pass "null" for this, the global object will be used.
+            const ret = handler.callback.apply(null, argArray);
+
+            // if the callback returns true, we don't call the next
+            // signal handlers
+            if (ret === true) return true;
+        } catch (e) {
+            // just log any exceptions so that callbacks can't disrupt
+            // signal emission
+            logError(e, `Exception in callback for signal: ${handler.name}`);
+        }
     }
-  }
 
-  return false;
+    return false;
 }
 
 function _addSignalMethod(proto, functionName, func) {
-  if (proto[functionName] && proto[functionName] !== func)
-    log(`WARNING: addSignalMethods is replacing existing ${proto} ${functionName} method`);
+    if (proto[functionName] && proto[functionName] !== func)
+        log(`WARNING: addSignalMethods is replacing existing ${proto} ${functionName} method`);
 
-  proto[functionName] = func;
+    proto[functionName] = func;
 }
 
 export function addSignalMethods(proto) {
-  _addSignalMethod(proto, 'connect', _connect);
-  _addSignalMethod(proto, 'connectAfter', _connectAfter);
-  _addSignalMethod(proto, 'disconnect', _disconnect);
-  _addSignalMethod(proto, 'emit', _emit);
-  _addSignalMethod(proto, 'signalHandlerIsConnected', _signalHandlerIsConnected);
-  // this one is not in GObject, but useful
-  _addSignalMethod(proto, 'disconnectAll', _disconnectAll);
+    _addSignalMethod(proto, 'connect', _connect);
+    _addSignalMethod(proto, 'connectAfter', _connectAfter);
+    _addSignalMethod(proto, 'disconnect', _disconnect);
+    _addSignalMethod(proto, 'emit', _emit);
+    _addSignalMethod(proto, 'signalHandlerIsConnected', _signalHandlerIsConnected);
+    // this one is not in GObject, but useful
+    _addSignalMethod(proto, 'disconnectAll', _disconnectAll);
 }
 
-export default { addSignalMethods, _connect, _connectAfter, _disconnect, _emit, _signalHandlerIsConnected, _disconnectAll };
+export default {
+    addSignalMethods,
+    _connect,
+    _connectAfter,
+    _disconnect,
+    _emit,
+    _signalHandlerIsConnected,
+    _disconnectAll,
+};