@gjsify/utils 0.0.3 → 0.1.0

package/lib/types/main-loop.d.ts

@@ -0,0 +1,20 @@
+import type GLib from '@girs/glib-2.0';
+/**
+ * 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.
+ */
+export declare function ensureMainLoop(): GLib.MainLoop | undefined;
+/**
+ * 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.
+ */
+export declare function quitMainLoop(): void;

package/lib/types/next-tick.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Schedule a function on the microtask queue.
+ * Fallback chain: process.nextTick → queueMicrotask → Promise.resolve().then()
+ */
+export declare const nextTick: (fn: (...args: unknown[]) => void, ...args: unknown[]) => void;

package/lib/types/structured-clone.d.ts

@@ -0,0 +1,15 @@
+/**
+ * structuredClone polyfill implementing the HTML structured clone algorithm.
+ *
+ * Supports: primitives (incl. -0, NaN, Infinity, BigInt), wrapper objects,
+ * Date, RegExp, Error types, ArrayBuffer, TypedArrays, DataView, Map, Set,
+ * Blob, File, circular/shared references, plain objects and arrays.
+ *
+ * Throws DataCloneError for: functions, symbols, WeakMap, WeakSet, WeakRef, Promise.
+ *
+ * @param value The value to clone
+ * @param _options Reserved for future transfer list support (currently ignored)
+ */
+export declare function structuredClone<T>(value: T, _options?: {
+    transfer?: unknown[];
+}): T;

package/package.json

@@ -1,32 +1,29 @@
 {
   "name": "@gjsify/utils",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "Utils module for gjsify",
-  "main": "lib/cjs/index.js",
   "module": "lib/esm/index.js",
   "types": "lib/types/index.d.ts",
   "type": "module",
   "exports": {
     ".": {
-      "import": {
-        "types": "./lib/types/index.d.ts",
-        "default": "./lib/esm/index.js"
-      },
-      "require": {
-        "types": "./lib/types/index.d.ts",
-        "default": "./lib/cjs/index.js"
-      }
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/esm/index.js"
+    },
+    "./main-loop": {
+      "types": "./lib/types/main-loop.d.ts",
+      "default": "./lib/esm/main-loop.js"
     }
   },
   "scripts": {
-    "clear": "rm -rf lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo || exit 0",
-    "print:name": "echo '@gjsify/utils'",
-    "build": "yarn print:name && yarn build:gjsify && yarn build:types",
+    "clear": "rm -rf lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs test.node.mjs || exit 0",
+    "check": "tsc --noEmit",
+    "build": "yarn build:gjsify && yarn build:types",
     "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
-    "build:types": "tsc --project tsconfig.types.json",
+    "build:types": "tsc",
     "build:test": "yarn build:test:gjs",
     "build:test:gjs": "gjsify build src/test.ts --app gjs --outfile test.gjs.js",
-    "test": "yarn print:name && yarn build:gjsify && yarn build:test && yarn test:gjs",
+    "test": "yarn build:gjsify && yarn build:test && yarn test:gjs",
     "test:gjs": "gjs -m test.gjs.js"
   },
   "keywords": [
@@ -35,12 +32,13 @@
     "fs"
   ],
   "devDependencies": {
-    "@gjsify/cli": "^0.0.3",
-    "typescript": "^5.1.3"
+    "@gjsify/cli": "^0.1.0",
+    "typescript": "^6.0.2"
   },
   "dependencies": {
-    "@girs/gio-2.0": "2.76.1-3.1.0",
-    "@girs/gjs": "^3.1.0",
-    "@girs/glib-2.0": "2.76.1-3.1.0"
+    "@girs/gio-2.0": "^2.88.0-4.0.0-beta.42",
+    "@girs/giounix-2.0": "^2.0.0-4.0.0-beta.42",
+    "@girs/gjs": "^4.0.0-beta.42",
+    "@girs/glib-2.0": "^2.88.0-4.0.0-beta.42"
   }
 }

package/src/base64.ts

@@ -0,0 +1,78 @@
+// Base64 encoding/decoding utilities for GJS
+// Shared by @gjsify/buffer and @gjsify/string_decoder
+// Reference: RFC 4648
+
+const B64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const B64_LOOKUP = new Uint8Array(256);
+for (let i = 0; i < B64_CHARS.length; i++) B64_LOOKUP[B64_CHARS.charCodeAt(i)] = i;
+
+/** Decode a base64 string to a binary string. Uses native atob when available. */
+export function atobPolyfill(str: string): string {
+  if (typeof globalThis.atob === 'function') return globalThis.atob(str);
+  const cleaned = str.replace(/[=\s]/g, '');
+  let result = '';
+  let bits = 0;
+  let collected = 0;
+  for (let i = 0; i < cleaned.length; i++) {
+    bits = (bits << 6) | B64_LOOKUP[cleaned.charCodeAt(i)];
+    collected += 6;
+    if (collected >= 8) {
+      collected -= 8;
+      result += String.fromCharCode((bits >> collected) & 0xff);
+    }
+  }
+  return result;
+}
+
+/** Encode a binary string to base64. Uses native btoa when available. */
+export function btoaPolyfill(str: string): string {
+  if (typeof globalThis.btoa === 'function') return globalThis.btoa(str);
+  let result = '';
+  let i = 0;
+  for (; i + 2 < str.length; i += 3) {
+    const n = (str.charCodeAt(i) << 16) | (str.charCodeAt(i + 1) << 8) | str.charCodeAt(i + 2);
+    result += B64_CHARS[(n >> 18) & 63] + B64_CHARS[(n >> 12) & 63] + B64_CHARS[(n >> 6) & 63] + B64_CHARS[n & 63];
+  }
+  if (i + 1 === str.length) {
+    const n = str.charCodeAt(i) << 16;
+    result += B64_CHARS[(n >> 18) & 63] + B64_CHARS[(n >> 12) & 63] + '==';
+  } else if (i + 2 === str.length) {
+    const n = (str.charCodeAt(i) << 16) | (str.charCodeAt(i + 1) << 8);
+    result += B64_CHARS[(n >> 18) & 63] + B64_CHARS[(n >> 12) & 63] + B64_CHARS[(n >> 6) & 63] + '=';
+  }
+  return result;
+}
+
+/** Decode a base64 string directly to Uint8Array (avoids lossy atob string round-trip). */
+export function base64Decode(str: string): Uint8Array {
+  const cleaned = str.replace(/[=\s]/g, '');
+  const bytes = new Uint8Array((cleaned.length * 3) >> 2);
+  let bits = 0;
+  let collected = 0;
+  let pos = 0;
+  for (let i = 0; i < cleaned.length; i++) {
+    bits = (bits << 6) | B64_LOOKUP[cleaned.charCodeAt(i)];
+    collected += 6;
+    if (collected >= 8) {
+      collected -= 8;
+      bytes[pos++] = (bits >> collected) & 0xff;
+    }
+  }
+  return bytes.subarray(0, pos);
+}
+
+/** Encode a Uint8Array to base64 string. */
+export function base64Encode(bytes: Uint8Array): string {
+  let result = '';
+  const len = bytes.length;
+  for (let i = 0; i < len; i += 3) {
+    const b0 = bytes[i];
+    const b1 = i + 1 < len ? bytes[i + 1] : 0;
+    const b2 = i + 2 < len ? bytes[i + 2] : 0;
+    result += B64_CHARS[b0 >> 2];
+    result += B64_CHARS[((b0 & 3) << 4) | (b1 >> 4)];
+    result += i + 1 < len ? B64_CHARS[((b1 & 0xf) << 2) | (b2 >> 6)] : '=';
+    result += i + 2 < len ? B64_CHARS[b2 & 0x3f] : '=';
+  }
+  return result;
+}

package/src/byte-array.ts

@@ -0,0 +1,12 @@
+import type GLib from '@girs/glib-2.0';
+
+declare const imports: { byteArray: { fromGBytes(input: GLib.Bytes): Uint8Array } };
+
+/**
+ * Convert GLib.Bytes to Uint8Array using GJS's byteArray module.
+ * This wraps the GJS-specific `imports.byteArray.fromGBytes()` API
+ * with proper typing to eliminate `as any` casts throughout the codebase.
+ */
+export function gbytesToUint8Array(bytes: GLib.Bytes): Uint8Array {
+  return imports.byteArray.fromGBytes(bytes);
+}

package/src/defer.ts

@@ -0,0 +1,11 @@
+/**
+ * Defer an event emission to the next macrotask, matching Node.js behavior
+ * for server 'listening', 'close', and 'error' events.
+ */
+export function deferEmit(
+  emitter: { emit(event: string | symbol, ...args: unknown[]): boolean },
+  event: string,
+  ...args: unknown[]
+): void {
+  setTimeout(() => emitter.emit(event, ...args), 0);
+}

package/src/encoding.ts

@@ -0,0 +1,36 @@
+// Shared encoding normalization utilities.
+// Used by buffer, string_decoder, crypto, and other packages that deal with encodings.
+
+/** Canonical encoding names (matches BufferEncoding from @types/node). */
+export type Encoding = 'utf8' | 'ascii' | 'latin1' | 'base64' | 'base64url' | 'hex' | 'utf16le' | 'binary' | 'ucs2' | 'ucs-2' | 'utf-8';
+
+const VALID_ENCODINGS = ['utf8', 'ascii', 'latin1', 'binary', 'base64', 'base64url', 'hex', 'ucs2', 'utf16le'];
+
+/**
+ * Normalize an encoding string to a canonical encoding value.
+ * Returns 'utf8' as default for undefined/null/empty input.
+ */
+export function normalizeEncoding(enc?: string): Encoding {
+  if (!enc || enc === 'utf8' || enc === 'utf-8') return 'utf8';
+  const lower = ('' + enc).toLowerCase().replace(/-/g, '');
+  switch (lower) {
+    case 'utf8': return 'utf8';
+    case 'ascii': return 'ascii';
+    case 'latin1': case 'binary': return 'latin1';
+    case 'base64': return 'base64';
+    case 'base64url': return 'base64url';
+    case 'hex': return 'hex';
+    case 'ucs2': case 'utf16le': return 'utf16le';
+    default: return 'utf8';
+  }
+}
+
+/**
+ * Check that an encoding string is valid. Throws TypeError if not.
+ */
+export function checkEncoding(encoding: string): void {
+  const lower = ('' + encoding).toLowerCase().replace(/-/g, '');
+  if (!VALID_ENCODINGS.includes(lower)) {
+    throw new TypeError(`Unknown encoding: ${encoding}`);
+  }
+}

package/src/fs.ts

@@ -1,9 +1,9 @@
 import Gio from '@girs/gio-2.0';
-
+import GioUnix from '@girs/giounix-2.0';
 /** Check if a file descriptor exists */
 export const existsFD = (fd: number) => {
     try {
-        let stream = Gio.UnixInputStream.new(fd, false);
+        let stream = GioUnix.InputStream.new(fd, false);
         stream.close(null);
         // File descriptor 12345 exists
         return true

package/src/gio-errors.ts

@@ -0,0 +1,101 @@
+// Shared Gio.IOErrorEnum → Node.js error code mapping.
+// Used by fs, net, http, dns, child-process, and other packages that wrap Gio operations.
+//
+// The enum values are numeric constants from GLib — we use numbers directly
+// to avoid importing Gio just for error handling (keeps this usable in Node.js tests too).
+
+/** Map from Gio.IOErrorEnum numeric values to Node.js error code strings. */
+export const GIO_ERROR_TO_NODE: Record<number, string> = {
+  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
+};
+
+export interface NodeErrorDetails {
+  path?: string;
+  dest?: string;
+  address?: string;
+  port?: number;
+  hostname?: string;
+}
+
+/** Node.js-style ErrnoException (defined locally to avoid @types/node dependency). */
+export interface ErrnoException extends Error {
+  errno?: number;
+  code?: string;
+  path?: string;
+  syscall?: string;
+  address?: string;
+  port?: number;
+  hostname?: string;
+}
+
+/**
+ * Create a Node.js-style ErrnoException from a Gio error.
+ * Works for fs, net, dns, child-process, and other modules.
+ */
+export function createNodeError(
+  err: unknown,
+  syscall: string,
+  details?: NodeErrorDetails
+): ErrnoException {
+  const errObj = err as { code?: number; message?: string } | null | undefined;
+  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) as ErrnoException;
+  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.
+ */
+export function isNotFoundError(err: unknown): boolean {
+  const errObj = err as { code?: number | string } | null | undefined;
+  return errObj?.code === 1 || errObj?.code === 'ENOENT';
+}

package/src/gio.ts

@@ -0,0 +1,67 @@
+import Gio from '@girs/gio-2.0';
+import GLib from '@girs/glib-2.0';
+
+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);
+ */
+export function gioAsync<T>(
+    obj: any,
+    asyncMethod: string,
+    finishMethod: string,
+    ...args: any[]
+): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+        obj[asyncMethod](...args, (_self: any, asyncRes: Gio.AsyncResult) => {
+            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.
+ */
+export async function readBytesAsync(
+    inputStream: Gio.InputStream,
+    count = 4096,
+    ioPriority = GLib.PRIORITY_DEFAULT,
+    cancellable: Gio.Cancellable | null = null
+): Promise<Uint8Array | null> {
+    return new Promise<Uint8Array | null>((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`.
+ */
+export async function* inputStreamAsyncIterator(
+    inputStream: Gio.InputStream,
+    count = 4096,
+    ioPriority = GLib.PRIORITY_DEFAULT,
+    cancellable: Gio.Cancellable | null = null
+): AsyncGenerator<Uint8Array> {
+    let chunk: Uint8Array | null;
+    while ((chunk = await readBytesAsync(inputStream, count, ioPriority, cancellable)) !== null) {
+        yield chunk;
+    }
+}

package/src/globals.ts

@@ -0,0 +1,13 @@
+// Shared utility for registering global polyfills.
+// Used by web packages (abort-controller, dom-exception, streams, webcrypto, etc.)
+// to consistently register globals only when they're missing.
+
+/**
+ * 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).
+ */
+export function registerGlobal(name: string, value: unknown): void {
+  if (typeof (globalThis as any)[name] === 'undefined') {
+    (globalThis as any)[name] = value;
+  }
+}

package/src/index.ts

@@ -1,15 +1,16 @@
-export * from './types/index.js';
-
-export * from './cancel-handler.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 './log.js';
+export * from './gio.js';
+export * from './gio-errors.js';
 export * from './message.js';
-export * from './os.js';
+export * from './next-tick.js';
 export * from './path.js';
-export * from './process.js';
-export * from './system.js';
-export * from './tty.js';
-export * from './version.js';
+export * from './structured-clone.js';
+export * from './main-loop.js';

package/src/main-loop.ts

@@ -0,0 +1,62 @@
+// GLib MainLoop management for GJS — original implementation
+// Provides an implicit event loop analogous to Node.js's built-in event loop.
+
+import type GLib from '@girs/glib-2.0';
+
+/** Sentinel to prevent double-start (setMainLoopHook throws if called twice). */
+let _started = false;
+
+/** The singleton MainLoop instance, if created. */
+let _loop: GLib.MainLoop | null = 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.
+ */
+export function ensureMainLoop(): GLib.MainLoop | undefined {
+  const gjsImports = (globalThis as any).imports;
+  if (!gjsImports) return undefined; // Not GJS
+  if (_started) return _loop!;
+
+  const GLibModule = gjsImports.gi.GLib;
+  _loop = new GLibModule.MainLoop(null, false);
+  _started = true;
+
+  // Only call runAsync() if no mainloop is currently running on the default
+  // context. If one is already running (e.g., test runner's mainloop.run()
+  // or Gtk.Application.runAsync()), async I/O already works through the
+  // shared default context — calling runAsync() would register a
+  // setMainLoopHook whose loop.run() blocks forever after tests quit it
+  // (g_main_loop_run resets the quit flag on entry).
+  if (GLibModule.main_depth() === 0) {
+    try {
+      (_loop as any).runAsync();
+    } catch {
+      // setMainLoopHook throws if already called (e.g., Gtk.Application.runAsync()).
+      // In that case, a main loop hook is already registered — no action needed.
+    }
+  }
+
+  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.
+ */
+export function quitMainLoop(): void {
+  if (_loop) {
+    _loop.quit();
+    _started = false;
+    _loop = null;
+  }
+}

package/src/next-tick.ts

@@ -0,0 +1,16 @@
+// Microtask scheduling utility for GJS
+// Shared by @gjsify/stream, @gjsify/web-streams, and other packages
+// Matches Node.js process.nextTick semantics with cross-platform fallbacks
+
+declare const queueMicrotask: ((cb: () => void) => void) | undefined;
+
+/**
+ * Schedule a function on the microtask queue.
+ * Fallback chain: process.nextTick → queueMicrotask → Promise.resolve().then()
+ */
+export const nextTick: (fn: (...args: unknown[]) => void, ...args: unknown[]) => void =
+  typeof globalThis.process?.nextTick === 'function'
+    ? globalThis.process.nextTick
+    : typeof globalThis.queueMicrotask === 'function'
+      ? (fn: (...args: unknown[]) => void, ...args: unknown[]) => queueMicrotask!(() => fn(...args))
+      : (fn: (...args: unknown[]) => void, ...args: unknown[]) => { Promise.resolve().then(() => fn(...args)); };