@gjsify/utils 0.40.0 → 0.42.0

package/README.md

@@ -19,7 +19,7 @@ from decides which one you get. Pick the narrowest one that covers your imports.
 |---|---|---|
 | `@gjsify/utils/core` | GJS · Node · browser · NativeScript | everything that is well-defined without GLib/Gio |
 | `@gjsify/utils` | **GJS only** | `…/core` plus the six modules that call into GLib/Gio |
-| `@gjsify/utils/main-loop` | GJS · Node · browser · NativeScript | just `ensureMainLoop` / `quitMainLoop` |
+| `@gjsify/utils/main-loop` | GJS · Node · browser · NativeScript | just `ensureMainLoop` / `holdMainLoop` / `quitMainLoop` |
 
 ```typescript
 // Cross-runtime — safe from a package whose browser / nativescript slot is
@@ -36,7 +36,15 @@ import { cli, existsSync, readBytesAsync } from '@gjsify/utils';
 `GLIB_FILE_ERROR_TO_NODE` tables — `registerGlobal`, `notImplemented`,
 `warnNotImplemented`, `queueMicrotask`, `structuredClone`) plus the two
 **GJS-guarded** modules that probe `globalThis.imports?.gi` and fall back to a
-portable path (`ensureMainLoop` / `quitMainLoop`, `nextTick`).
+portable path (`ensureMainLoop` / `holdMainLoop` / `quitMainLoop`, `nextTick`).
+
+`ensureMainLoop()` arms the GJS main-loop hook only at `GLib.main_depth() === 0`, so it
+never stacks a loop under a test runner's `mainloop.run()` or a
+`Gtk.Application.runAsync()`. A command that must OUTLIVE its entry module — a watch
+loop, a daemon — needs `holdMainLoop()` instead, which arms regardless of depth: GJS
+spins the default context itself while a module's top-level await is pending, so a
+continuation resumed from a timer or a Gio callback runs at depth 1, where
+`ensureMainLoop()` declines and the process exits as soon as the module settles.
 
 The root barrel adds `gbytesToUint8Array`, `cli`, `readJSON`, `existsFD`, `existsSync`,
 `gioAsync`, `readBytesAsync`, `inputStreamAsyncIterator`, `resolve`, `getProgramExe`,

package/lib/esm/core.js

@@ -1 +1 @@
-import{makeCallable as e}from"./callable.js";import{deferEmit as t}from"./defer.js";import{initErrorV8Methods as n}from"./error.js";import{GIO_ERROR_TO_NODE as r,GLIB_FILE_ERROR_TO_NODE as i,createGLibFileError as a,createNodeError as o,isNotFoundError as s}from"./gio-errors.js";import{registerGlobal as c}from"./globals.js";import{TARGET_OSES as l,hostOs as u,hostPlatform as d,isDarwin as f,isLinux as p,isTargetOs as m,isWin32 as h}from"./host-os.js";import{notImplemented as g,warnNotImplemented as _}from"./message.js";import{queueMicrotask as v}from"./microtask.js";import{encodePathForFileUrl as y,isWindowsPath as b,lastPathSeparatorIndex as x,pathToFileUrlHref as S,splitPathComponents as C}from"./path-shape.js";import{PROBED_GI_LIBDIRS as w,TYPELIB_SUBDIR as T,splitSearchPath as E,systemGiLibraryDirs as D}from"./system-gi-dirs.js";import{mapMachine as O,mapSysname as k}from"./platform-names.js";import{structuredClone as A}from"./structured-clone.js";import{hasProcfs as j,hostExecPath as M,hostPid as N,hostPpid as P,readProcessMemory as F}from"./host-process.js";import{ensureMainLoop as I,quitMainLoop as L}from"./main-loop.js";import{__resetBurstStateForTests as R,nextTick as z}from"./next-tick.js";export{r as GIO_ERROR_TO_NODE,i as GLIB_FILE_ERROR_TO_NODE,w as PROBED_GI_LIBDIRS,l as TARGET_OSES,T as TYPELIB_SUBDIR,R as __resetBurstStateForTests,a as createGLibFileError,o as createNodeError,t as deferEmit,y as encodePathForFileUrl,I as ensureMainLoop,j as hasProcfs,M as hostExecPath,u as hostOs,N as hostPid,d as hostPlatform,P as hostPpid,n as initErrorV8Methods,f as isDarwin,p as isLinux,s as isNotFoundError,m as isTargetOs,h as isWin32,b as isWindowsPath,x as lastPathSeparatorIndex,e as makeCallable,O as mapMachine,k as mapSysname,z as nextTick,g as notImplemented,S as pathToFileUrlHref,v as queueMicrotask,L as quitMainLoop,F as readProcessMemory,c as registerGlobal,C as splitPathComponents,E as splitSearchPath,A as structuredClone,D as systemGiLibraryDirs,_ as warnNotImplemented};
+import{makeCallable as e}from"./callable.js";import{deferEmit as t}from"./defer.js";import{initErrorV8Methods as n}from"./error.js";import{GIO_ERROR_TO_NODE as r,GLIB_FILE_ERROR_TO_NODE as i,createGLibFileError as a,createNodeError as o,isNotFoundError as s}from"./gio-errors.js";import{registerGlobal as c}from"./globals.js";import{TARGET_OSES as l,hostOs as u,hostPlatform as d,isDarwin as f,isLinux as p,isTargetOs as m,isWin32 as h}from"./host-os.js";import{notImplemented as g,warnNotImplemented as _}from"./message.js";import{queueMicrotask as v}from"./microtask.js";import{encodePathForFileUrl as y,isWindowsPath as b,lastPathSeparatorIndex as x,pathToFileUrlHref as S,splitPathComponents as C}from"./path-shape.js";import{PROBED_GI_LIBDIRS as w,TYPELIB_SUBDIR as T,splitSearchPath as E,systemGiLibraryDirs as D}from"./system-gi-dirs.js";import{mapMachine as O,mapSysname as k}from"./platform-names.js";import{structuredClone as A}from"./structured-clone.js";import{hasProcfs as j,hostExecPath as M,hostPid as N,hostPpid as P,readProcessMemory as F}from"./host-process.js";import{ensureMainLoop as I,holdMainLoop as L,quitMainLoop as R}from"./main-loop.js";import{__resetBurstStateForTests as z,nextTick as B}from"./next-tick.js";export{r as GIO_ERROR_TO_NODE,i as GLIB_FILE_ERROR_TO_NODE,w as PROBED_GI_LIBDIRS,l as TARGET_OSES,T as TYPELIB_SUBDIR,z as __resetBurstStateForTests,a as createGLibFileError,o as createNodeError,t as deferEmit,y as encodePathForFileUrl,I as ensureMainLoop,j as hasProcfs,L as holdMainLoop,M as hostExecPath,u as hostOs,N as hostPid,d as hostPlatform,P as hostPpid,n as initErrorV8Methods,f as isDarwin,p as isLinux,s as isNotFoundError,m as isTargetOs,h as isWin32,b as isWindowsPath,x as lastPathSeparatorIndex,e as makeCallable,O as mapMachine,k as mapSysname,B as nextTick,g as notImplemented,S as pathToFileUrlHref,v as queueMicrotask,R as quitMainLoop,F as readProcessMemory,c as registerGlobal,C as splitPathComponents,E as splitSearchPath,A as structuredClone,D as systemGiLibraryDirs,_ as warnNotImplemented};

package/lib/esm/index.js

@@ -1 +1 @@
-import{gbytesToUint8Array as e}from"./byte-array.js";import{makeCallable as t}from"./callable.js";import{cli as n}from"./cli.js";import{deferEmit as r}from"./defer.js";import{initErrorV8Methods as i}from"./error.js";import{GIO_ERROR_TO_NODE as a,GLIB_FILE_ERROR_TO_NODE as o,createGLibFileError as s,createNodeError as c,isNotFoundError as l}from"./gio-errors.js";import{registerGlobal as u}from"./globals.js";import{TARGET_OSES as d,hostOs as f,hostPlatform as p,isDarwin as m,isLinux as h,isTargetOs as g,isWin32 as _}from"./host-os.js";import{notImplemented as v,warnNotImplemented as y}from"./message.js";import{queueMicrotask as b}from"./microtask.js";import{encodePathForFileUrl as x,isWindowsPath as S,lastPathSeparatorIndex as C,pathToFileUrlHref as w,splitPathComponents as T}from"./path-shape.js";import{PROBED_GI_LIBDIRS as E,TYPELIB_SUBDIR as D,splitSearchPath as O,systemGiLibraryDirs as k}from"./system-gi-dirs.js";import{mapMachine as A,mapSysname as j}from"./platform-names.js";import{structuredClone as M}from"./structured-clone.js";import{hasProcfs as N,hostExecPath as P,hostPid as F,hostPpid as I,readProcessMemory as L}from"./host-process.js";import{ensureMainLoop as R,quitMainLoop as z}from"./main-loop.js";import{__resetBurstStateForTests as B,nextTick as V}from"./next-tick.js";import"./core.js";import{readJSON as H}from"./file.js";import{existsFD as U,existsSync as W}from"./fs.js";import{gioAsync as G,inputStreamAsyncIterator as K,readBytesAsync as q}from"./gio.js";import{getNodeModulesPath as J,getPathSeparator as Y,getProgramDir as X,getProgramExe as Z,resolve as Q}from"./path.js";export{a as GIO_ERROR_TO_NODE,o as GLIB_FILE_ERROR_TO_NODE,E as PROBED_GI_LIBDIRS,d as TARGET_OSES,D as TYPELIB_SUBDIR,B as __resetBurstStateForTests,n as cli,s as createGLibFileError,c as createNodeError,r as deferEmit,x as encodePathForFileUrl,R as ensureMainLoop,U as existsFD,W as existsSync,e as gbytesToUint8Array,J as getNodeModulesPath,Y as getPathSeparator,X as getProgramDir,Z as getProgramExe,G as gioAsync,N as hasProcfs,P as hostExecPath,f as hostOs,F as hostPid,p as hostPlatform,I as hostPpid,i as initErrorV8Methods,K as inputStreamAsyncIterator,m as isDarwin,h as isLinux,l as isNotFoundError,g as isTargetOs,_ as isWin32,S as isWindowsPath,C as lastPathSeparatorIndex,t as makeCallable,A as mapMachine,j as mapSysname,V as nextTick,v as notImplemented,w as pathToFileUrlHref,b as queueMicrotask,z as quitMainLoop,q as readBytesAsync,H as readJSON,L as readProcessMemory,u as registerGlobal,Q as resolve,T as splitPathComponents,O as splitSearchPath,M as structuredClone,k as systemGiLibraryDirs,y as warnNotImplemented};
+import{gbytesToUint8Array as e}from"./byte-array.js";import{makeCallable as t}from"./callable.js";import{cli as n}from"./cli.js";import{deferEmit as r}from"./defer.js";import{initErrorV8Methods as i}from"./error.js";import{GIO_ERROR_TO_NODE as a,GLIB_FILE_ERROR_TO_NODE as o,createGLibFileError as s,createNodeError as c,isNotFoundError as l}from"./gio-errors.js";import{registerGlobal as u}from"./globals.js";import{TARGET_OSES as d,hostOs as f,hostPlatform as p,isDarwin as m,isLinux as h,isTargetOs as g,isWin32 as _}from"./host-os.js";import{notImplemented as v,warnNotImplemented as y}from"./message.js";import{queueMicrotask as b}from"./microtask.js";import{encodePathForFileUrl as x,isWindowsPath as S,lastPathSeparatorIndex as C,pathToFileUrlHref as w,splitPathComponents as T}from"./path-shape.js";import{PROBED_GI_LIBDIRS as E,TYPELIB_SUBDIR as D,splitSearchPath as O,systemGiLibraryDirs as k}from"./system-gi-dirs.js";import{mapMachine as A,mapSysname as j}from"./platform-names.js";import{structuredClone as M}from"./structured-clone.js";import{hasProcfs as N,hostExecPath as P,hostPid as F,hostPpid as I,readProcessMemory as L}from"./host-process.js";import{ensureMainLoop as R,holdMainLoop as z,quitMainLoop as B}from"./main-loop.js";import{__resetBurstStateForTests as V,nextTick as H}from"./next-tick.js";import"./core.js";import{readJSON as U}from"./file.js";import{existsFD as W,existsSync as G}from"./fs.js";import{gioAsync as K,inputStreamAsyncIterator as q,readBytesAsync as J}from"./gio.js";import{getNodeModulesPath as Y,getPathSeparator as X,getProgramDir as Z,getProgramExe as Q,resolve as $}from"./path.js";export{a as GIO_ERROR_TO_NODE,o as GLIB_FILE_ERROR_TO_NODE,E as PROBED_GI_LIBDIRS,d as TARGET_OSES,D as TYPELIB_SUBDIR,V as __resetBurstStateForTests,n as cli,s as createGLibFileError,c as createNodeError,r as deferEmit,x as encodePathForFileUrl,R as ensureMainLoop,W as existsFD,G as existsSync,e as gbytesToUint8Array,Y as getNodeModulesPath,X as getPathSeparator,Z as getProgramDir,Q as getProgramExe,K as gioAsync,N as hasProcfs,z as holdMainLoop,P as hostExecPath,f as hostOs,F as hostPid,p as hostPlatform,I as hostPpid,i as initErrorV8Methods,q as inputStreamAsyncIterator,m as isDarwin,h as isLinux,l as isNotFoundError,g as isTargetOs,_ as isWin32,S as isWindowsPath,C as lastPathSeparatorIndex,t as makeCallable,A as mapMachine,j as mapSysname,H as nextTick,v as notImplemented,w as pathToFileUrlHref,b as queueMicrotask,B as quitMainLoop,J as readBytesAsync,U as readJSON,L as readProcessMemory,u as registerGlobal,$ as resolve,T as splitPathComponents,O as splitSearchPath,M as structuredClone,k as systemGiLibraryDirs,y as warnNotImplemented};

package/lib/esm/main-loop.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";let e=!1,t=null;function ensureMainLoop(){let n=globalThis.imports;if(!n)return;if(e)return t;let r=n.gi?.GLib;if(r)return t=new r.MainLoop(null,!1),e=!0,r.main_depth()===0&&t.runAsync().catch(()=>{}),t}function quitMainLoop(){t&&=(t.quit(),e=!1,null)}export{ensureMainLoop,quitMainLoop};
+import"./_virtual/_rolldown/runtime.js";let e=null,t=!1,n=!1;function glib(){return globalThis.imports?.gi?.GLib}function arm(e){n||(n=!0,e.runAsync().catch(()=>{}))}function ensureMainLoop(){let n=glib();if(n)return t?e:(e=new n.MainLoop(null,!1),t=!0,n.main_depth()===0&&arm(e),e)}function holdMainLoop(){let e=ensureMainLoop();return e&&arm(e),e}function quitMainLoop(){e&&=(e.quit(),t=!1,n=!1,null)}export{ensureMainLoop,holdMainLoop,quitMainLoop};

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

@@ -5,18 +5,49 @@ import type GLib from '@girs/glib-2.0';
  *
  * Called automatically by `http.Server.listen()`, `net.Server.listen()`,
  * `dgram.Socket.bind()`. GTK apps must NOT call it — they use
- * `Gtk.Application.runAsync()` instead.
+ * `Gtk.Application.runAsync()` instead. A supervisor that must OUTLIVE its entry
+ * module wants {@link holdMainLoop} instead; see there for why this one cannot
+ * serve it.
  *
  * Teardown hazard: with a main-loop hook set, GJS's `eval_module` drives the
  * hook's *blocking* `loop.run()`, so terminating from an async continuation with
  * a bare `imports.system.exit()` DEADLOCKS — it only sets GJS's internal exit
  * flag, never calls `loop.quit()`, so the parked `loop.run()` never returns.
  * Microtask draining is unaffected; only the exit hangs
- * (`docs/poc/tla-microtask-draining.md`). Exit through `process.exit()` (which
- * idle-schedules `quitMainLoop()` + `system.exit()`) or call {@link quitMainLoop}
- * yourself first.
+ * (`docs/poc/tla-microtask-draining.md`). Calling {@link quitMainLoop} first
+ * does NOT lift it — measured, the bare exit still hangs afterwards. Exit
+ * through `process.exit()`, which schedules the syscall on an idle source and
+ * then drives the default main context until it fires, so the exit happens
+ * from inside a dispatch where it works and the call never returns
+ * (`tests/e2e/process-exit-terminates`).
  */
 export declare function ensureMainLoop(): GLib.MainLoop | undefined;
+/**
+ * Keep this process alive on the GLib main loop AFTER its entry module settles —
+ * for a command that SUPERVISES rather than finishes (a watch loop, a daemon).
+ * No-op on Node.js, where pending handles do this job. Idempotent.
+ *
+ * {@link ensureMainLoop} cannot serve that case, and the difference is the whole
+ * reason this exists: it declines to arm the hook at `main_depth() !== 0`, and
+ * under a GJS *module* entry point that depth is routinely 1. GJS spins the
+ * default main context itself while the entry module's top-level await is
+ * pending, so every continuation resumed from a dispatched source — a timer, a
+ * `Gio` async callback, anything but the first microtask drain — runs inside
+ * that spin. `ensureMainLoop()` then silently arms nothing, the spin ends when
+ * the module promise settles, and the process exits.
+ *
+ * Measured on gjs 1.88.1: a module that spawns a child and arms an `fs.watch`
+ * from such a continuation prints its startup lines and exits 0 the moment its
+ * top-level await settles, orphaning the child; the same code with the spawn
+ * BEFORE the first await stays alive. So the depth guard is not a safety net
+ * here, it is the defect.
+ *
+ * Arming regardless of depth is why this is opt-in rather than the default: only
+ * a caller that knows it will never unwind may stack a loop under one that may
+ * already be running. Exit through `process.exit()` — see {@link ensureMainLoop}
+ * for why a bare `imports.system.exit()` deadlocks.
+ */
+export declare function holdMainLoop(): GLib.MainLoop | undefined;
 /**
  * Quit the MainLoop created by `ensureMainLoop()`. Idempotent, no-op on Node.js.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/utils",
-    "version": "0.40.0",
+    "version": "0.42.0",
     "description": "Utils module for gjsify",
     "module": "lib/esm/index.js",
     "types": "lib/types/index.d.ts",
@@ -40,7 +40,7 @@
         "fs"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.40.0",
+        "@gjsify/cli": "^0.42.0",
         "typescript": "^6.0.3"
     },
     "dependencies": {