@gjsify/utils 0.4.0 → 0.4.3

package/src/main-loop.ts

@@ -1,62 +0,0 @@
-// 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/message.ts

@@ -1,11 +0,0 @@
-// See https://github.com/denoland/deno_std/blob/44d05e7a8d445888d989d49eb3e59eee3055f2c5/node/_utils.ts#L21
-export const notImplemented = (msg: string) => {
-    const message = msg ? `Not implemented: ${msg}` : "Not implemented";
-    throw new Error(message);
-}
-
-export const warnNotImplemented = (msg) => {
-    const message = msg ? `Not implemented: ${msg}` : "Not implemented";
-    console.warn(message);
-    return message;
-}

package/src/microtask.ts

@@ -1,4 +0,0 @@
-// Unlike nextTick (GLib.idle_add, lets GTK events interleave), queueMicrotask fires before any GLib source.
-export const queueMicrotask = (fn: () => void): void => {
-  Promise.resolve().then(fn);
-};

package/src/next-tick.spec.ts

@@ -1,116 +0,0 @@
-// Tests for packages/gjs/utils/src/next-tick.ts
-// Regression: nextTick on GJS must route through GLib.idle_add(PRIORITY_HIGH_IDLE)
-// instead of queueMicrotask, so GTK events (PRIORITY_DEFAULT = 0) can interleave
-// between stream operations and prevent window freezes under heavy I/O.
-
-import { describe, it, expect, on } from '@gjsify/unit';
-import { nextTick, __resetBurstStateForTests } from './next-tick.js';
-
-export default async () => {
-  await describe('nextTick', async () => {
-    await it('should execute the callback', async () => {
-      let called = false;
-      await new Promise<void>(resolve => {
-        nextTick(() => { called = true; resolve(); });
-      });
-      expect(called).toBeTruthy();
-    });
-
-    await it('should be deferred — not synchronous', async () => {
-      let ranBeforeReturn = false;
-      let scheduled = false;
-      nextTick(() => { scheduled = true; });
-      // nextTick callback must not have run before this line
-      ranBeforeReturn = scheduled;
-      // Wait for callback
-      await new Promise<void>(resolve => nextTick(resolve));
-      expect(ranBeforeReturn).toBeFalsy();
-      expect(scheduled).toBeTruthy();
-    });
-
-    await it('should pass arguments to the callback', async () => {
-      const result = await new Promise<string>(resolve => {
-        nextTick((a: string, b: string) => resolve(a + b), 'hello', ' world');
-      });
-      expect(result).toBe('hello world');
-    });
-
-    await it('should run callbacks in scheduling order', async () => {
-      const order: number[] = [];
-      await new Promise<void>(resolve => {
-        nextTick(() => order.push(1));
-        nextTick(() => order.push(2));
-        nextTick(() => { order.push(3); resolve(); });
-      });
-      // Additional tick so all three have fired
-      await new Promise<void>(resolve => nextTick(resolve));
-      expect(order[0]).toBe(1);
-      expect(order[1]).toBe(2);
-      expect(order[2]).toBe(3);
-    });
-
-    // GJS-specific: nextTick must use GLib.idle_add so that GLib I/O callbacks
-    // (PRIORITY_DEFAULT = 0) can fire between nextTick callbacks (PRIORITY_HIGH_IDLE = 100).
-    // We verify that a resolved Promise (microtask, highest priority) fires before
-    // a nextTick, whereas a GLib.idle_add at PRIORITY_DEFAULT fires before one at PRIORITY_HIGH_IDLE.
-    await on('Gjs', async () => {
-      await it('GJS: nextTick does not block GLib I/O callbacks (priority ordering)', async () => {
-        // A Promise.resolve microtask fires before any GLib idle (same GLib dispatch).
-        // A nextTick (GLib idle 100) must not block a higher-priority GLib source (priority 0).
-        // We test indirectly: schedule two nextTick callbacks and one via Promise.resolve().
-        // The Promise.resolve microtask runs within the current GLib dispatch (before the idle).
-        const order: string[] = [];
-        await new Promise<void>(resolve => {
-          // Schedule nextTick (GLib idle priority 100 on GJS)
-          nextTick(() => { order.push('tick'); resolve(); });
-          // Schedule a microtask (Promise.resolve runs in current dispatch, before idle)
-          Promise.resolve().then(() => order.push('microtask'));
-        });
-        // On GJS: microtask fires before GLib idle, so 'microtask' comes first
-        // On Node.js: nextTick fires before Promise.resolve microtasks by spec
-        expect(order).toContain('tick');
-        expect(order).toContain('microtask');
-      });
-
-      // Burst-yield behavior. When hundreds of nextTicks fire in a tight
-      // loop (webtorrent DHT bootstrap, streamx pipe bursts, …) GLib
-      // dispatches the whole batch at PRIORITY_DEFAULT before coming back
-      // to collect GTK input events — the window appears frozen. After
-      // BURST_YIELD_THRESHOLD consecutive calls within BURST_IDLE_MS, the
-      // scheduler switches to delay=1ms timeouts, forcing a main-loop
-      // iteration between bursts so GTK events can drain. Normal,
-      // non-bursty code pays zero latency because the counter resets on
-      // any gap > BURST_IDLE_MS.
-      await it('GJS: a tight burst of 256 nextTicks still completes', async () => {
-        __resetBurstStateForTests();
-        let fired = 0;
-        const target = 256;
-        await new Promise<void>(resolve => {
-          for (let i = 0; i < target; i++) {
-            nextTick(() => {
-              fired++;
-              if (fired === target) resolve();
-            });
-          }
-        });
-        expect(fired).toBe(target);
-      });
-
-      await it('GJS: order is preserved inside and across bursts', async () => {
-        __resetBurstStateForTests();
-        const order: number[] = [];
-        const target = 128;
-        await new Promise<void>(resolve => {
-          for (let i = 0; i < target; i++) {
-            nextTick(() => {
-              order.push(i);
-              if (order.length === target) resolve();
-            });
-          }
-        });
-        // FIFO across the whole burst, including the yield points.
-        for (let i = 0; i < target; i++) expect(order[i]).toBe(i);
-      });
-    });
-  });
-};

package/src/next-tick.ts

@@ -1,112 +0,0 @@
-// 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;
-
-// Burst-yield scheduler. GTK input events (move, click, scroll) are dispatched
-// from GLib's main context at PRIORITY_DEFAULT (0). Historically every nextTick
-// became its own GLib.timeout_add(PRIORITY_DEFAULT, 0) source — ready
-// immediately. When user code (webtorrent DHT bootstrap, streamx pipe bursts)
-// scheduled hundreds of nextTicks in a tight loop, GLib dispatched the whole
-// batch before cycling back to collect GTK input events, freezing the window.
-//
-// Instead, we maintain a FIFO queue owned by this module:
-//   • nextTick(cb) pushes onto _queue
-//   • A single GLib.timeout_add(PRIORITY_DEFAULT, 0) drains up to CHUNK_SIZE
-//     callbacks per iteration
-//   • If more remain, the drainer re-arms with delay=1ms — forcing at least
-//     one main-loop iteration before continuing, so GTK events that arrived
-//     during the chunk get dispatched
-//   • When _queue empties, the drainer goes idle (zero ambient cost)
-//
-// Guarantees:
-//   • FIFO: single shared queue + single drainer preserves call order
-//   • Throughput: short bursts under CHUNK_SIZE drain with zero added latency
-//   • Responsiveness: longer bursts cost at most 1ms per CHUNK_SIZE callbacks
-//     of added latency, in exchange for GTK input dispatch
-//   • GC safety: one timeout source lives while _queue is non-empty; no
-//     per-call BoxedInstance retention
-const CHUNK_SIZE = 64;
-const YIELD_DELAY_MS = 1;
-const _queue: Array<() => void> = [];
-let _drainerArmed = false;
-
-function drainOnce(GLib: any): void {
-  // Process up to CHUNK_SIZE callbacks. Errors don't abort the queue —
-  // Node's process.nextTick guarantees later ticks still run even if an
-  // earlier one throws (the throw is delivered asynchronously via
-  // 'uncaughtException'). We keep the same contract by catching per-cb.
-  const end = Math.min(CHUNK_SIZE, _queue.length);
-  for (let i = 0; i < end; i++) {
-    const cb = _queue.shift()!;
-    try { cb(); }
-    catch (err) {
-      // Surface as an emitted error rather than swallow. In GJS there is no
-      // 'uncaughtException'; fall back to logging on stderr via GLib.
-      try { GLib.log_default_handler('gjsify-nextTick', GLib.LogLevelFlags.LEVEL_WARNING, String((err as any)?.stack || err), null); }
-      catch { /* best-effort */ }
-    }
-  }
-  if (_queue.length > 0) {
-    // More work remains — re-arm with a 1 ms yield so GTK events dispatch.
-    GLib.timeout_add(GLib.PRIORITY_DEFAULT, YIELD_DELAY_MS, () => {
-      drainOnce(GLib);
-      return false;
-    });
-  } else {
-    _drainerArmed = false;
-  }
-}
-
-// On GJS, nextTick goes through the GLib main loop instead of the JS
-// microtask queue, so I/O events are interleaved between stream/pipe steps.
-//
-// PRIORITY_DEFAULT (0) is required: GJS 1.86 maintains an internal
-// Promise/microtask-drain source at priority 0 that returns SOURCE_CONTINUE,
-// permanently blocking any source at priority > 0 (including PRIORITY_HIGH_IDLE
-// = 100) from ever dispatching. Using PRIORITY_DEFAULT ensures nextTick
-// callbacks fire within the same GLib dispatch band as I/O events.
-//
-// We use GLib.timeout_add rather than GLib.idle_add: timeout_add returns a
-// numeric source ID (no BoxedInstance, no GC race). GLib.idle_add has the same
-// GC-race hazard as the old GLib.Source BoxedInstance approach fixed in
-// @gjsify/node-globals timers.
-function tryGLibTimeout(cb: () => void): boolean {
-  const GLib = (globalThis as any).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. */
-export function __resetBurstStateForTests(): void {
-  _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().
- */
-export const nextTick = (fn: (...args: unknown[]) => void, ...args: unknown[]): void => {
-  const cb = args.length > 0 ? () => fn(...args) : fn as () => void;
-  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);
-};

package/src/path.ts

@@ -1,52 +0,0 @@
-import Gio from '@girs/gio-2.0';
-import GLib from '@girs/glib-2.0';
-const { File } = Gio;
-
-const _getProgramDir = (programFile: Gio.File) => {
-    const info = programFile.query_info('standard::', Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS, null);
-
-    if (info.get_is_symlink()) {
-        const symlinkFile = programFile.get_parent().resolve_relative_path(info.get_symlink_target());
-        return symlinkFile.get_parent();
-    } else {
-        return programFile.get_parent();
-    }
-}
-
-export const resolve = (dir: string, ...filenames: string[]) => {
-    let file = File.new_for_path(dir);
-    for (const filename of filenames) {
-      file = file.resolve_relative_path(filename);
-    }
-    return file;
-}
-
-export const getProgramExe = () => {
-    const currentDir = GLib.get_current_dir();
-    return File.new_for_path(currentDir).resolve_relative_path(imports.system.programInvocationName);
-}
-
-export const getProgramDir = () => {
-    return _getProgramDir(getProgramExe()).get_path();
-}
-
-export const getPathSeparator = () => {
-    const currentDir = GLib.get_current_dir();
-    return /^\//.test(currentDir) ? '/' : '\\';
-}
-
-export const getNodeModulesPath = () => {
-    let dir = File.new_for_path(getProgramDir());
-    let found = false;
-
-    do {
-        dir = dir.resolve_relative_path("..");
-        const nodeModulesDir = dir.resolve_relative_path("node_modules");
-        found = nodeModulesDir.query_exists(null);
-        if (found) {
-            dir = nodeModulesDir;
-        }
-    } while (dir.has_parent(null) && !found)
-
-    return dir;
-}