@gjsify/utils 0.3.12 → 0.3.14

package/lib/esm/gio-errors.js

@@ -1,135 +1,116 @@
+//#region src/gio-errors.ts
+/** Map from Gio.IOErrorEnum numeric values to Node.js error code strings. */
 const GIO_ERROR_TO_NODE = {
-  0: "EIO",
-  // FAILED
-  1: "ENOENT",
-  // NOT_FOUND
-  2: "EEXIST",
-  // EXISTS
-  3: "EISDIR",
-  // IS_DIRECTORY
-  4: "ENOTDIR",
-  // NOT_DIRECTORY
-  5: "ENOTEMPTY",
-  // NOT_EMPTY
-  6: "ENOENT",
-  // NOT_REGULAR_FILE
-  7: "ENFILE",
-  // TOO_MANY_OPEN_FILES
-  9: "EACCES",
-  // NOT_MOUNTABLE_FILE
-  10: "ENFILE",
-  // FILENAME_TOO_LONG
-  11: "EINVAL",
-  // INVALID_FILENAME
-  12: "ELOOP",
-  // TOO_MANY_LINKS
-  13: "ENOSPC",
-  // NO_SPACE
-  14: "EACCES",
-  // PERMISSION_DENIED
-  17: "ELOOP",
-  // TOO_MANY_LINKS (duplicate guard)
-  19: "ENOSPC",
-  // NO_SPACE (duplicate guard)
-  20: "ENOTSUP",
-  // NOT_SUPPORTED
-  22: "EMFILE",
-  // TOO_MANY_OPEN_FILES
-  24: "EROFS",
-  // READ_ONLY
-  25: "ECANCELED",
-  // CANCELLED
-  26: "EBUSY",
-  // BUSY
-  27: "ETIMEDOUT",
-  // TIMED_OUT
-  28: "EHOSTUNREACH",
-  // HOST_NOT_FOUND (was WOULD_BLOCK)
-  30: "EHOSTUNREACH",
-  // HOST_NOT_FOUND
-  31: "ENETUNREACH",
-  // NETWORK_UNREACHABLE
-  32: "ECONNREFUSED",
-  // CONNECTION_REFUSED (legacy value)
-  33: "EADDRINUSE",
-  // ADDRESS_IN_USE
-  34: "ECONNRESET",
-  // CONNECTION_CLOSED (mapped to reset)
-  36: "EPIPE",
-  // BROKEN_PIPE
-  38: "ENETUNREACH",
-  // NETWORK_UNREACHABLE (actual GJS value)
-  39: "ECONNREFUSED",
-  // CONNECTION_REFUSED (actual GJS value)
-  40: "ECONNREFUSED",
-  // PROXY_FAILED
-  41: "EACCES",
-  // PROXY_AUTH_FAILED
-  44: "ECONNRESET",
-  // CONNECTION_CLOSED (actual GJS value)
-  46: "EMSGSIZE"
-  // MESSAGE_TOO_LARGE
+	0: "EIO",
+	1: "ENOENT",
+	2: "EEXIST",
+	3: "EISDIR",
+	4: "ENOTDIR",
+	5: "ENOTEMPTY",
+	6: "ENOENT",
+	7: "ENFILE",
+	9: "EACCES",
+	10: "ENFILE",
+	11: "EINVAL",
+	12: "ELOOP",
+	13: "ENOSPC",
+	14: "EACCES",
+	17: "ELOOP",
+	19: "ENOSPC",
+	20: "ENOTSUP",
+	22: "EMFILE",
+	24: "EROFS",
+	25: "ECANCELED",
+	26: "EBUSY",
+	27: "ETIMEDOUT",
+	28: "EHOSTUNREACH",
+	30: "EHOSTUNREACH",
+	31: "ENETUNREACH",
+	32: "ECONNREFUSED",
+	33: "EADDRINUSE",
+	34: "ECONNRESET",
+	36: "EPIPE",
+	38: "ENETUNREACH",
+	39: "ECONNREFUSED",
+	40: "ECONNREFUSED",
+	41: "EACCES",
+	44: "ECONNRESET",
+	46: "EMSGSIZE"
 };
+/**
+* Create a Node.js-style ErrnoException from a Gio error.
+* Works for fs, net, dns, child-process, and other modules.
+*/
 function createNodeError(err, syscall, details) {
-  const errObj = err;
-  const code = GIO_ERROR_TO_NODE[errObj?.code ?? -1] || "EIO";
-  let msg = `${code}: ${errObj?.message || "unknown error"}, ${syscall}`;
-  if (details?.path) msg += ` '${details.path}'`;
-  if (details?.dest) msg += ` -> '${details.dest}'`;
-  if (details?.address) msg += ` ${details.address}`;
-  if (details?.port != null) msg += `:${details.port}`;
-  const error = new Error(msg);
-  error.code = code;
-  error.syscall = syscall;
-  error.errno = -(errObj?.code || 0);
-  if (details?.path) error.path = details.path;
-  if (details?.address) error.address = details.address;
-  if (details?.port != null) error.port = details.port;
-  return error;
+	const errObj = err;
+	const code = GIO_ERROR_TO_NODE[errObj?.code ?? -1] || "EIO";
+	let msg = `${code}: ${errObj?.message || "unknown error"}, ${syscall}`;
+	if (details?.path) msg += ` '${details.path}'`;
+	if (details?.dest) msg += ` -> '${details.dest}'`;
+	if (details?.address) msg += ` ${details.address}`;
+	if (details?.port != null) msg += `:${details.port}`;
+	const error = new Error(msg);
+	error.code = code;
+	error.syscall = syscall;
+	error.errno = -(errObj?.code || 0);
+	if (details?.path) error.path = details.path;
+	if (details?.address) error.address = details.address;
+	if (details?.port != null) error.port = details.port;
+	return error;
 }
+/**
+* Check if a Gio error is a "not found" error.
+*/
 function isNotFoundError(err) {
-  const errObj = err;
-  return errObj?.code === 1 || errObj?.code === "ENOENT";
+	const errObj = err;
+	return errObj?.code === 1 || errObj?.code === "ENOENT";
 }
+/**
+* Map from GLib.FileError numeric values to Node.js error code strings.
+* Distinct from Gio.IOErrorEnum — GLib.IOChannel.new_file() and some other
+* low-level GLib APIs throw GLib.FileError (domain "g-file-error"), which
+* has different numeric values than Gio.IOErrorEnum (domain "g-io-error-quark").
+*/
 const GLIB_FILE_ERROR_TO_NODE = {
-  0: "EEXIST",
-  1: "EISDIR",
-  2: "EACCES",
-  3: "ENAMETOOLONG",
-  4: "ENOENT",
-  5: "ENOTDIR",
-  6: "ENXIO",
-  7: "ENODEV",
-  8: "EROFS",
-  11: "ELOOP",
-  12: "ENOSPC",
-  13: "ENOMEM",
-  14: "EMFILE",
-  15: "ENFILE",
-  16: "EBADF",
-  17: "EINVAL",
-  18: "EPIPE",
-  21: "EIO",
-  22: "EPERM",
-  24: "EIO"
+	0: "EEXIST",
+	1: "EISDIR",
+	2: "EACCES",
+	3: "ENAMETOOLONG",
+	4: "ENOENT",
+	5: "ENOTDIR",
+	6: "ENXIO",
+	7: "ENODEV",
+	8: "EROFS",
+	11: "ELOOP",
+	12: "ENOSPC",
+	13: "ENOMEM",
+	14: "EMFILE",
+	15: "ENFILE",
+	16: "EBADF",
+	17: "EINVAL",
+	18: "EPIPE",
+	21: "EIO",
+	22: "EPERM",
+	24: "EIO"
 };
+/**
+* Map a GLib.FileError to a Node.js-style ErrnoException. Counterpart to
+* `createNodeError` for the Gio.IOErrorEnum case; kept separate because the
+* enum domains differ.
+*/
 function createGLibFileError(err, syscall, details) {
-  const errObj = err;
-  const code = GLIB_FILE_ERROR_TO_NODE[errObj?.code ?? -1] ?? "EIO";
-  let msg = `${code}: ${errObj?.message || "unknown error"}, ${syscall}`;
-  if (details?.path) msg += ` '${details.path}'`;
-  if (details?.dest) msg += ` -> '${details.dest}'`;
-  const error = new Error(msg);
-  error.code = code;
-  error.syscall = syscall;
-  error.errno = -(errObj?.code || 0);
-  if (details?.path) error.path = details.path;
-  return error;
+	const errObj = err;
+	const code = GLIB_FILE_ERROR_TO_NODE[errObj?.code ?? -1] ?? "EIO";
+	let msg = `${code}: ${errObj?.message || "unknown error"}, ${syscall}`;
+	if (details?.path) msg += ` '${details.path}'`;
+	if (details?.dest) msg += ` -> '${details.dest}'`;
+	const error = new Error(msg);
+	error.code = code;
+	error.syscall = syscall;
+	error.errno = -(errObj?.code || 0);
+	if (details?.path) error.path = details.path;
+	return error;
 }
-export {
-  GIO_ERROR_TO_NODE,
-  GLIB_FILE_ERROR_TO_NODE,
-  createGLibFileError,
-  createNodeError,
-  isNotFoundError
-};
+
+//#endregion
+export { GIO_ERROR_TO_NODE, GLIB_FILE_ERROR_TO_NODE, createGLibFileError, createNodeError, isNotFoundError };

package/lib/esm/gio.js

@@ -1,39 +1,52 @@
 import GLib from "@girs/glib-2.0";
+
+//#region src/gio.ts
 const byteArray = imports.byteArray;
+/**
+* Generic promise wrapper for Gio async/finish method pairs.
+*
+* Example:
+*   const stream = await gioAsync<Gio.InputStream>(session, 'send_async', 'send_finish', msg, priority, null);
+*/
 function gioAsync(obj, asyncMethod, finishMethod, ...args) {
-  return new Promise((resolve, reject) => {
-    obj[asyncMethod](...args, (_self, asyncRes) => {
-      try {
-        resolve(obj[finishMethod](asyncRes));
-      } catch (error) {
-        reject(error);
-      }
-    });
-  });
+	return new Promise((resolve, reject) => {
+		obj[asyncMethod](...args, (_self, asyncRes) => {
+			try {
+				resolve(obj[finishMethod](asyncRes));
+			} catch (error) {
+				reject(error);
+			}
+		});
+	});
 }
+/**
+* Promise wrapper around `Gio.InputStream.read_bytes_async` / `read_bytes_finish`.
+* Returns a `Uint8Array` or `null` if the end of the stream is reached.
+*/
 async function readBytesAsync(inputStream, count = 4096, ioPriority = GLib.PRIORITY_DEFAULT, cancellable = null) {
-  return new Promise((resolve, reject) => {
-    inputStream.read_bytes_async(count, ioPriority, cancellable, (_self, asyncRes) => {
-      try {
-        const res = inputStream.read_bytes_finish(asyncRes);
-        if (res.get_size() === 0) {
-          return resolve(null);
-        }
-        return resolve(byteArray.fromGBytes(res));
-      } catch (error) {
-        reject(error);
-      }
-    });
-  });
+	return new Promise((resolve, reject) => {
+		inputStream.read_bytes_async(count, ioPriority, cancellable, (_self, asyncRes) => {
+			try {
+				const res = inputStream.read_bytes_finish(asyncRes);
+				if (res.get_size() === 0) {
+					return resolve(null);
+				}
+				return resolve(byteArray.fromGBytes(res));
+			} catch (error) {
+				reject(error);
+			}
+		});
+	});
 }
+/**
+* Async generator that yields `Uint8Array` chunks from a `Gio.InputStream`.
+*/
 async function* inputStreamAsyncIterator(inputStream, count = 4096, ioPriority = GLib.PRIORITY_DEFAULT, cancellable = null) {
-  let chunk;
-  while ((chunk = await readBytesAsync(inputStream, count, ioPriority, cancellable)) !== null) {
-    yield chunk;
-  }
+	let chunk;
+	while ((chunk = await readBytesAsync(inputStream, count, ioPriority, cancellable)) !== null) {
+		yield chunk;
+	}
 }
-export {
-  gioAsync,
-  inputStreamAsyncIterator,
-  readBytesAsync
-};
+
+//#endregion
+export { gioAsync, inputStreamAsyncIterator, readBytesAsync };

package/lib/esm/globals.js

@@ -1,8 +1,13 @@
+//#region src/globals.ts
+/**
+* Register a value as a global property if it doesn't already exist.
+* This is a no-op in environments where the global is already defined (e.g. Node.js).
+*/
 function registerGlobal(name, value) {
-  if (typeof globalThis[name] === "undefined") {
-    globalThis[name] = value;
-  }
+	if (typeof globalThis[name] === "undefined") {
+		globalThis[name] = value;
+	}
 }
-export {
-  registerGlobal
-};
+
+//#endregion
+export { registerGlobal };

package/lib/esm/index.js

@@ -1,18 +1,20 @@
-export * from "./callable.js";
-export * from "./base64.js";
-export * from "./byte-array.js";
-export * from "./cli.js";
-export * from "./defer.js";
-export * from "./encoding.js";
-export * from "./globals.js";
-export * from "./error.js";
-export * from "./file.js";
-export * from "./fs.js";
-export * from "./gio.js";
-export * from "./gio-errors.js";
-export * from "./message.js";
-export * from "./microtask.js";
-export * from "./next-tick.js";
-export * from "./path.js";
-export * from "./structured-clone.js";
-export * from "./main-loop.js";
+import { atobPolyfill, base64Decode, base64Encode, btoaPolyfill } from "./base64.js";
+import { gbytesToUint8Array } from "./byte-array.js";
+import { makeCallable } from "./callable.js";
+import { cli } from "./cli.js";
+import { deferEmit } from "./defer.js";
+import { checkEncoding, normalizeEncoding } from "./encoding.js";
+import { initErrorV8Methods } from "./error.js";
+import { readJSON } from "./file.js";
+import { existsFD, existsSync } from "./fs.js";
+import { GIO_ERROR_TO_NODE, GLIB_FILE_ERROR_TO_NODE, createGLibFileError, createNodeError, isNotFoundError } from "./gio-errors.js";
+import { gioAsync, inputStreamAsyncIterator, readBytesAsync } from "./gio.js";
+import { registerGlobal } from "./globals.js";
+import { notImplemented, warnNotImplemented } from "./message.js";
+import { queueMicrotask } from "./microtask.js";
+import { __resetBurstStateForTests, nextTick } from "./next-tick.js";
+import { getNodeModulesPath, getPathSeparator, getProgramDir, getProgramExe, resolve } from "./path.js";
+import { structuredClone } from "./structured-clone.js";
+import { ensureMainLoop, quitMainLoop } from "./main-loop.js";
+
+export { GIO_ERROR_TO_NODE, GLIB_FILE_ERROR_TO_NODE, __resetBurstStateForTests, atobPolyfill, base64Decode, base64Encode, btoaPolyfill, checkEncoding, cli, createGLibFileError, createNodeError, deferEmit, ensureMainLoop, existsFD, existsSync, gbytesToUint8Array, getNodeModulesPath, getPathSeparator, getProgramDir, getProgramExe, gioAsync, initErrorV8Methods, inputStreamAsyncIterator, isNotFoundError, makeCallable, nextTick, normalizeEncoding, notImplemented, queueMicrotask, quitMainLoop, readBytesAsync, readJSON, registerGlobal, resolve, structuredClone, warnNotImplemented };

package/lib/esm/main-loop.js

@@ -1,28 +1,46 @@
+//#region src/main-loop.ts
+/** Sentinel to prevent double-start (setMainLoopHook throws if called twice). */
 let _started = false;
+/** The singleton MainLoop instance, if created. */
 let _loop = null;
+/**
+* Ensure a GLib MainLoop is running for async I/O dispatch (Soup.Server,
+* Gio.SocketService, etc.). No-op on Node.js. Idempotent.
+*
+* - Called automatically by `http.Server.listen()`, `net.Server.listen()`,
+*   `dgram.Socket.bind()` etc.
+* - GTK apps should NOT call this — they use `Gtk.Application.runAsync()` instead.
+*
+* @returns The MainLoop instance on GJS, or `undefined` on Node.js.
+*/
 function ensureMainLoop() {
-  const gjsImports = globalThis.imports;
-  if (!gjsImports) return void 0;
-  if (_started) return _loop;
-  const GLibModule = gjsImports.gi.GLib;
-  _loop = new GLibModule.MainLoop(null, false);
-  _started = true;
-  if (GLibModule.main_depth() === 0) {
-    try {
-      _loop.runAsync();
-    } catch {
-    }
-  }
-  return _loop;
+	const gjsImports = globalThis.imports;
+	if (!gjsImports) return undefined;
+	if (_started) return _loop;
+	const GLibModule = gjsImports.gi.GLib;
+	_loop = new GLibModule.MainLoop(null, false);
+	_started = true;
+	if (GLibModule.main_depth() === 0) {
+		try {
+			_loop.runAsync();
+		} catch {}
+	}
+	return _loop;
 }
+/**
+* Quit the MainLoop created by `ensureMainLoop()`. Idempotent, no-op on Node.js.
+*
+* Calling `quit()` on a loop that hasn't started yet pre-quits it — when the
+* `setMainLoopHook` later fires and calls `run()`, it returns immediately.
+* This is used by `@gjsify/unit` to prevent the loop from blocking after tests.
+*/
 function quitMainLoop() {
-  if (_loop) {
-    _loop.quit();
-    _started = false;
-    _loop = null;
-  }
+	if (_loop) {
+		_loop.quit();
+		_started = false;
+		_loop = null;
+	}
 }
-export {
-  ensureMainLoop,
-  quitMainLoop
-};
+
+//#endregion
+export { ensureMainLoop, quitMainLoop };

package/lib/esm/message.js

@@ -1,13 +1,13 @@
+//#region src/message.ts
 const notImplemented = (msg) => {
-  const message = msg ? `Not implemented: ${msg}` : "Not implemented";
-  throw new Error(message);
+	const message = msg ? `Not implemented: ${msg}` : "Not implemented";
+	throw new Error(message);
 };
 const warnNotImplemented = (msg) => {
-  const message = msg ? `Not implemented: ${msg}` : "Not implemented";
-  console.warn(message);
-  return message;
-};
-export {
-  notImplemented,
-  warnNotImplemented
+	const message = msg ? `Not implemented: ${msg}` : "Not implemented";
+	console.warn(message);
+	return message;
 };
+
+//#endregion
+export { notImplemented, warnNotImplemented };

package/lib/esm/microtask.js

@@ -1,6 +1,7 @@
+//#region src/microtask.ts
 const queueMicrotask = (fn) => {
-  Promise.resolve().then(fn);
-};
-export {
-  queueMicrotask
+	Promise.resolve().then(fn);
 };
+
+//#endregion
+export { queueMicrotask };

package/lib/esm/next-tick.js

@@ -1,60 +1,65 @@
+//#region src/next-tick.ts
 const CHUNK_SIZE = 64;
 const YIELD_DELAY_MS = 1;
 const _queue = [];
 let _drainerArmed = false;
 function drainOnce(GLib) {
-  const end = Math.min(CHUNK_SIZE, _queue.length);
-  for (let i = 0; i < end; i++) {
-    const cb = _queue.shift();
-    try {
-      cb();
-    } catch (err) {
-      try {
-        GLib.log_default_handler("gjsify-nextTick", GLib.LogLevelFlags.LEVEL_WARNING, String(err?.stack || err), null);
-      } catch {
-      }
-    }
-  }
-  if (_queue.length > 0) {
-    GLib.timeout_add(GLib.PRIORITY_DEFAULT, YIELD_DELAY_MS, () => {
-      drainOnce(GLib);
-      return false;
-    });
-  } else {
-    _drainerArmed = false;
-  }
+	const end = Math.min(CHUNK_SIZE, _queue.length);
+	for (let i = 0; i < end; i++) {
+		const cb = _queue.shift();
+		try {
+			cb();
+		} catch (err) {
+			try {
+				GLib.log_default_handler("gjsify-nextTick", GLib.LogLevelFlags.LEVEL_WARNING, String(err?.stack || err), null);
+			} catch {}
+		}
+	}
+	if (_queue.length > 0) {
+		GLib.timeout_add(GLib.PRIORITY_DEFAULT, YIELD_DELAY_MS, () => {
+			drainOnce(GLib);
+			return false;
+		});
+	} else {
+		_drainerArmed = false;
+	}
 }
 function tryGLibTimeout(cb) {
-  const GLib = globalThis.imports?.gi?.GLib;
-  if (!GLib?.timeout_add) return false;
-  _queue.push(cb);
-  if (!_drainerArmed) {
-    _drainerArmed = true;
-    GLib.timeout_add(GLib.PRIORITY_DEFAULT, 0, () => {
-      drainOnce(GLib);
-      return false;
-    });
-  }
-  return true;
+	const GLib = globalThis.imports?.gi?.GLib;
+	if (!GLib?.timeout_add) return false;
+	_queue.push(cb);
+	if (!_drainerArmed) {
+		_drainerArmed = true;
+		GLib.timeout_add(GLib.PRIORITY_DEFAULT, 0, () => {
+			drainOnce(GLib);
+			return false;
+		});
+	}
+	return true;
 }
+/** @internal Test helper: reset burst state. */
 function __resetBurstStateForTests() {
-  _queue.length = 0;
-  _drainerArmed = false;
+	_queue.length = 0;
+	_drainerArmed = false;
 }
+/**
+* Schedule a function on the next turn of the event loop.
+* On GJS: uses GLib.timeout_add(PRIORITY_DEFAULT, delay=0).
+* On Node.js: uses process.nextTick → queueMicrotask → Promise.resolve().then().
+*/
 const nextTick = (fn, ...args) => {
-  const cb = args.length > 0 ? () => fn(...args) : fn;
-  if (tryGLibTimeout(cb)) return;
-  if (typeof globalThis.process?.nextTick === "function") {
-    globalThis.process.nextTick(fn, ...args);
-    return;
-  }
-  if (typeof queueMicrotask === "function") {
-    queueMicrotask(cb);
-    return;
-  }
-  Promise.resolve().then(cb);
-};
-export {
-  __resetBurstStateForTests,
-  nextTick
+	const cb = args.length > 0 ? () => fn(...args) : fn;
+	if (tryGLibTimeout(cb)) return;
+	if (typeof globalThis.process?.nextTick === "function") {
+		globalThis.process.nextTick(fn, ...args);
+		return;
+	}
+	if (typeof queueMicrotask === "function") {
+		queueMicrotask(cb);
+		return;
+	}
+	Promise.resolve().then(cb);
 };
+
+//#endregion
+export { __resetBurstStateForTests, nextTick };