@gjsify/utils 0.64.5 → 0.64.7

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` / `holdMainLoop` / `quitMainLoop` |
+| `@gjsify/utils/main-loop` | GJS · Node · browser · NativeScript | just `ensureMainLoop` / `holdMainLoop` / `quitMainLoop` / `acquireMainLoop` / `releaseMainLoop` |
 
 ```typescript
 // Cross-runtime — safe from a package whose browser / nativescript slot is
@@ -46,6 +46,16 @@ spins the default context itself while a module's top-level await is pending, so
 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.
 
+`acquireMainLoop()` / `releaseMainLoop()` are the drain half, for consumers whose liveness
+follows a handle: one counted hold per live child — `@gjsify/worker_threads` acquires on spawn
+and follows `unref()` / `ref()` — released when that handle's exit or `unref()` lands, and the
+release reaching zero quits the loop, so the parked blocking `run()` returns and the process
+exits like Node's (`node:worker_threads` keeps a script alive while a `Worker` is referenced —
+the contract #2339 asked for). The primitives above have no release at all, only
+`process.exit()` ends them; a counted hold is the consumer's own — per acquire one release,
+never what someone else armed. The io packages that arm via `ensureMainLoop()` today keep
+their park-forever behavior until their close paths migrate to the pair.
+
 The root barrel adds `gbytesToUint8Array`, `cli`, `readJSON`, `existsFD`, `existsSync`,
 `gioAsync`, `readBytesAsync`, `inputStreamAsyncIterator`, `resolve`, `getProgramExe`,
 `getProgramDir`, `getPathSeparator` and `getNodeModulesPath` — all of which take a

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,dyldDefaultFallbackDirs as E,giLibraryDirsForTypelibDir as D,splitSearchPath as O,systemGiLibraryDirs as k}from"./system-gi-dirs.js";import{decodeXmlEntities as A,scanXml as j}from"./xml-scan.js";import{mapMachine as M,mapSysname as N}from"./platform-names.js";import{structuredClone as P}from"./structured-clone.js";import{hasProcfs as F,hostEnv as I,hostExecPath as L,hostPid as R,hostPpid as z,readProcessMemory as B}from"./host-process.js";import{ensureMainLoop as V,holdMainLoop as H,quitMainLoop as U}from"./main-loop.js";import{NativeLibraryLoadError as W,colocateNativeLibrary as G,loadOptionalNativeModule as K,missingLibraryDependency as q,openNativeLibrary as J,probeNativeLibrary as Y}from"./native-library.js";import{__resetBurstStateForTests as X,nextTick as Z}from"./next-tick.js";export{r as GIO_ERROR_TO_NODE,i as GLIB_FILE_ERROR_TO_NODE,W as NativeLibraryLoadError,w as PROBED_GI_LIBDIRS,l as TARGET_OSES,T as TYPELIB_SUBDIR,X as __resetBurstStateForTests,G as colocateNativeLibrary,a as createGLibFileError,o as createNodeError,A as decodeXmlEntities,t as deferEmit,E as dyldDefaultFallbackDirs,y as encodePathForFileUrl,V as ensureMainLoop,D as giLibraryDirsForTypelibDir,F as hasProcfs,H as holdMainLoop,I as hostEnv,L as hostExecPath,u as hostOs,R as hostPid,d as hostPlatform,z 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,K as loadOptionalNativeModule,e as makeCallable,M as mapMachine,N as mapSysname,q as missingLibraryDependency,Z as nextTick,g as notImplemented,J as openNativeLibrary,S as pathToFileUrlHref,Y as probeNativeLibrary,v as queueMicrotask,U as quitMainLoop,B as readProcessMemory,c as registerGlobal,j as scanXml,C as splitPathComponents,O as splitSearchPath,P as structuredClone,k 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,dyldDefaultFallbackDirs as E,giLibraryDirsForTypelibDir as D,splitSearchPath as O,systemGiLibraryDirs as k}from"./system-gi-dirs.js";import{decodeXmlEntities as A,scanXml as j}from"./xml-scan.js";import{mapMachine as M,mapSysname as N}from"./platform-names.js";import{structuredClone as P}from"./structured-clone.js";import{hasProcfs as F,hostEnv as I,hostExecPath as L,hostPid as R,hostPpid as z,readProcessMemory as B}from"./host-process.js";import{acquireMainLoop as V,ensureMainLoop as H,holdMainLoop as U,quitMainLoop as W,releaseMainLoop as G}from"./main-loop.js";import{NativeLibraryLoadError as K,colocateNativeLibrary as q,loadOptionalNativeModule as J,missingLibraryDependency as Y,openNativeLibrary as X,probeNativeLibrary as Z}from"./native-library.js";import{__resetBurstStateForTests as Q,nextTick as $}from"./next-tick.js";export{r as GIO_ERROR_TO_NODE,i as GLIB_FILE_ERROR_TO_NODE,K as NativeLibraryLoadError,w as PROBED_GI_LIBDIRS,l as TARGET_OSES,T as TYPELIB_SUBDIR,Q as __resetBurstStateForTests,V as acquireMainLoop,q as colocateNativeLibrary,a as createGLibFileError,o as createNodeError,A as decodeXmlEntities,t as deferEmit,E as dyldDefaultFallbackDirs,y as encodePathForFileUrl,H as ensureMainLoop,D as giLibraryDirsForTypelibDir,F as hasProcfs,U as holdMainLoop,I as hostEnv,L as hostExecPath,u as hostOs,R as hostPid,d as hostPlatform,z 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,J as loadOptionalNativeModule,e as makeCallable,M as mapMachine,N as mapSysname,Y as missingLibraryDependency,$ as nextTick,g as notImplemented,X as openNativeLibrary,S as pathToFileUrlHref,Z as probeNativeLibrary,v as queueMicrotask,W as quitMainLoop,B as readProcessMemory,c as registerGlobal,G as releaseMainLoop,j as scanXml,C as splitPathComponents,O as splitSearchPath,P as structuredClone,k 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,dyldDefaultFallbackDirs as O,giLibraryDirsForTypelibDir as k,splitSearchPath as A,systemGiLibraryDirs as j}from"./system-gi-dirs.js";import{decodeXmlEntities as M,scanXml as N}from"./xml-scan.js";import{mapMachine as P,mapSysname as F}from"./platform-names.js";import{structuredClone as I}from"./structured-clone.js";import{hasProcfs as L,hostEnv as R,hostExecPath as z,hostPid as B,hostPpid as V,readProcessMemory as H}from"./host-process.js";import{ensureMainLoop as U,holdMainLoop as W,quitMainLoop as G}from"./main-loop.js";import{NativeLibraryLoadError as K,colocateNativeLibrary as q,loadOptionalNativeModule as J,missingLibraryDependency as Y,openNativeLibrary as X,probeNativeLibrary as Z}from"./native-library.js";import{__resetBurstStateForTests as Q,nextTick as $}from"./next-tick.js";import"./core.js";import{readJSON as ee}from"./file.js";import{existsFD as te,existsSync as ne}from"./fs.js";import{gioAsync as re,inputStreamAsyncIterator as ie,readBytesAsync as ae}from"./gio.js";import{getNodeModulesPath as oe,getPathSeparator as se,getProgramDir as ce,getProgramExe as le,resolve as ue}from"./path.js";import{closeSocketService as de,releaseListenPort as fe}from"./socket-service.js";export{a as GIO_ERROR_TO_NODE,o as GLIB_FILE_ERROR_TO_NODE,K as NativeLibraryLoadError,E as PROBED_GI_LIBDIRS,d as TARGET_OSES,D as TYPELIB_SUBDIR,Q as __resetBurstStateForTests,n as cli,de as closeSocketService,q as colocateNativeLibrary,s as createGLibFileError,c as createNodeError,M as decodeXmlEntities,r as deferEmit,O as dyldDefaultFallbackDirs,x as encodePathForFileUrl,U as ensureMainLoop,te as existsFD,ne as existsSync,e as gbytesToUint8Array,oe as getNodeModulesPath,se as getPathSeparator,ce as getProgramDir,le as getProgramExe,k as giLibraryDirsForTypelibDir,re as gioAsync,L as hasProcfs,W as holdMainLoop,R as hostEnv,z as hostExecPath,f as hostOs,B as hostPid,p as hostPlatform,V as hostPpid,i as initErrorV8Methods,ie as inputStreamAsyncIterator,m as isDarwin,h as isLinux,l as isNotFoundError,g as isTargetOs,_ as isWin32,S as isWindowsPath,C as lastPathSeparatorIndex,J as loadOptionalNativeModule,t as makeCallable,P as mapMachine,F as mapSysname,Y as missingLibraryDependency,$ as nextTick,v as notImplemented,X as openNativeLibrary,w as pathToFileUrlHref,Z as probeNativeLibrary,b as queueMicrotask,G as quitMainLoop,ae as readBytesAsync,ee as readJSON,H as readProcessMemory,u as registerGlobal,fe as releaseListenPort,ue as resolve,N as scanXml,T as splitPathComponents,A as splitSearchPath,I as structuredClone,j 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,dyldDefaultFallbackDirs as O,giLibraryDirsForTypelibDir as k,splitSearchPath as A,systemGiLibraryDirs as j}from"./system-gi-dirs.js";import{decodeXmlEntities as M,scanXml as N}from"./xml-scan.js";import{mapMachine as P,mapSysname as F}from"./platform-names.js";import{structuredClone as I}from"./structured-clone.js";import{hasProcfs as L,hostEnv as R,hostExecPath as z,hostPid as B,hostPpid as V,readProcessMemory as H}from"./host-process.js";import{acquireMainLoop as U,ensureMainLoop as W,holdMainLoop as G,quitMainLoop as K,releaseMainLoop as q}from"./main-loop.js";import{NativeLibraryLoadError as J,colocateNativeLibrary as Y,loadOptionalNativeModule as X,missingLibraryDependency as Z,openNativeLibrary as Q,probeNativeLibrary as $}from"./native-library.js";import{__resetBurstStateForTests as ee,nextTick as te}from"./next-tick.js";import"./core.js";import{readJSON as ne}from"./file.js";import{existsFD as re,existsSync as ie}from"./fs.js";import{gioAsync as ae,inputStreamAsyncIterator as oe,readBytesAsync as se}from"./gio.js";import{getNodeModulesPath as ce,getPathSeparator as le,getProgramDir as ue,getProgramExe as de,resolve as fe}from"./path.js";import{closeSocketService as pe,releaseListenPort as me}from"./socket-service.js";export{a as GIO_ERROR_TO_NODE,o as GLIB_FILE_ERROR_TO_NODE,J as NativeLibraryLoadError,E as PROBED_GI_LIBDIRS,d as TARGET_OSES,D as TYPELIB_SUBDIR,ee as __resetBurstStateForTests,U as acquireMainLoop,n as cli,pe as closeSocketService,Y as colocateNativeLibrary,s as createGLibFileError,c as createNodeError,M as decodeXmlEntities,r as deferEmit,O as dyldDefaultFallbackDirs,x as encodePathForFileUrl,W as ensureMainLoop,re as existsFD,ie as existsSync,e as gbytesToUint8Array,ce as getNodeModulesPath,le as getPathSeparator,ue as getProgramDir,de as getProgramExe,k as giLibraryDirsForTypelibDir,ae as gioAsync,L as hasProcfs,G as holdMainLoop,R as hostEnv,z as hostExecPath,f as hostOs,B as hostPid,p as hostPlatform,V as hostPpid,i as initErrorV8Methods,oe as inputStreamAsyncIterator,m as isDarwin,h as isLinux,l as isNotFoundError,g as isTargetOs,_ as isWin32,S as isWindowsPath,C as lastPathSeparatorIndex,X as loadOptionalNativeModule,t as makeCallable,P as mapMachine,F as mapSysname,Z as missingLibraryDependency,te as nextTick,v as notImplemented,Q as openNativeLibrary,w as pathToFileUrlHref,$ as probeNativeLibrary,b as queueMicrotask,K as quitMainLoop,se as readBytesAsync,ne as readJSON,H as readProcessMemory,u as registerGlobal,me as releaseListenPort,q as releaseMainLoop,fe as resolve,N as scanXml,T as splitPathComponents,A as splitSearchPath,I as structuredClone,j as systemGiLibraryDirs,y as warnNotImplemented};

package/lib/esm/main-loop.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";let e=null,t=!1,n=!1;function glib(){let e=globalThis;if(typeof e.process?.versions?.gjs==`string`||e.process===void 0)return e.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};
+import"./_virtual/_rolldown/runtime.js";let e=null,t=!1,n=!1,r=0,i=!1;function glib(){let e=globalThis;if(typeof e.process?.versions?.gjs==`string`||e.process===void 0)return e.imports?.gi?.GLib}function arm(e){n||(n=!0,e.runAsync().catch(()=>{}))}function ensureMainLoop(){return i=!1,createLoop()}function createLoop(){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 acquireMainLoop(){let e=t,n=createLoop();if(n)return r===0&&(i=!e),r+=1,n}function releaseMainLoop(){if(!(r===0||!e)&&(--r,r===0&&i)){let e=n;quitMainLoop();let t=globalThis.process;if(e&&typeof t?.exit==`function`){let e=t.exitCode??0,n=glib();n?n.timeout_add(n.PRIORITY_DEFAULT,0,()=>(t.exit(e),n.SOURCE_REMOVE)):t.exit(e)}}}function quitMainLoop(){e&&(e.quit(),t=!1,n=!1,e=null,r=0,i=!1)}export{acquireMainLoop,ensureMainLoop,holdMainLoop,quitMainLoop,releaseMainLoop};

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

@@ -48,6 +48,39 @@ export declare function ensureMainLoop(): GLib.MainLoop | undefined;
  * for why a bare `imports.system.exit()` deadlocks.
  */
 export declare function holdMainLoop(): GLib.MainLoop | undefined;
+/**
+ * Acquire a Node-style counted hold on the running loop — the drain half of
+ * Node's event-loop liveness. Acquired again for every handle that must keep
+ * the process alive (`worker_threads` spawn, later child/IO migrations); the
+ * process is no longer held once the next {@link releaseMainLoop} drops the
+ * count to 0.
+ *
+ * Separate from the uncounted primitives for the same reason they exist:
+ * {@link ensureMainLoop} / {@link holdMainLoop} callers park FOREVER and exit
+ * via `process.exit()` — a consumer with a drain lifecycle must not be one of
+ * them, because releasing has to be reversible here without defeating those
+ * callers' expectations. GLib's `loop.run()` blocks until `quit()` — there is
+ * no "run until no sources remain" — so a drain cannot be observed by the loop
+ * itself; it has to be counted.
+ *
+ * Known limit, counted holds are only the `worker_threads` consumer today:
+ * `net`/`http`/`dgram`/`ws`/`child_process` park via {@link ensureMainLoop}
+ * forever (their close paths don't release yet), so an app holding BOTH a
+ * live server and a worker stays parked when the worker drains — same as on
+ * those packages' pre-existent behavior, and the slot for their migration is
+ * exactly this pair. Also inherits the {@link ensureMainLoop} depth note: a
+ * hold acquired inside a top-level-await continuation at `main_depth() !== 0`
+ * is counted but not armed, and the entry's spin ends at settle like it
+ * always did.
+ */
+export declare function acquireMainLoop(): GLib.MainLoop | undefined;
+/**
+ * Release one hold acquired with {@link acquireMainLoop}. Idempotent beyond
+ * the count (calls at 0 are a no-op), no-op on Node.js. At 0 the loop created
+ * by this module is quit, which returns from the blocking `run()` that gjs's
+ * `eval_module` parked in — the Node "refs drained, process exits" moment.
+ */
+export declare function releaseMainLoop(): void;
 /**
  * Quit the MainLoop created by `ensureMainLoop()`. Idempotent, no-op on Node.js.
  *

package/lib/types/system-gi-dirs.d.ts

@@ -63,7 +63,11 @@ export interface SystemGiLibraryDirsHost {
  * child launched through it searches LESS than one launched with the
  * variable unset — the regression `packages/infra/cli/src/utils/system-gi.ts`
  * (`composeDyldFallback`) and `packages/node-gi/node-gi/system-gi.js` both
- * exist to avoid. A THIRD caller that only needs the tail, not the rest of
+ * exist to avoid. The tail is necessary, not sufficient: a bare leaf such as
+ * `GjsPrivate`'s `libgjs.0.dylib` still resolves unset and not set (measured on
+ * macOS 27 / arm64), so a value that starts `gjs` also needs gjs's own `lib/` —
+ * see `dyldFallbackPreamble` in `packages/infra/cli/src/utils/bin-shim.ts`.
+ * A THIRD caller that only needs the tail, not the rest of
  * that composition (a launcher replacing the environment outright has no
  * "current value of the variable" to fold in), imports this rather than
  * hand-rolling the same four-entry array — see

package/package.json

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