@gjsify/utils 0.30.0 → 0.32.0

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{notImplemented as l,warnNotImplemented as u}from"./message.js";import{queueMicrotask as d}from"./microtask.js";import{mapMachine as f,mapSysname as p}from"./platform-names.js";import{structuredClone as m}from"./structured-clone.js";import{ensureMainLoop as h,quitMainLoop as g}from"./main-loop.js";import{__resetBurstStateForTests as _,nextTick as v}from"./next-tick.js";export{r as GIO_ERROR_TO_NODE,i as GLIB_FILE_ERROR_TO_NODE,_ as __resetBurstStateForTests,a as createGLibFileError,o as createNodeError,t as deferEmit,h as ensureMainLoop,n as initErrorV8Methods,s as isNotFoundError,e as makeCallable,f as mapMachine,p as mapSysname,v as nextTick,l as notImplemented,d as queueMicrotask,g as quitMainLoop,c as registerGlobal,m as structuredClone,u 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{mapMachine as y,mapSysname as b}from"./platform-names.js";import{structuredClone as x}from"./structured-clone.js";import{hasProcfs as S,hostExecPath as C,hostPid as w,hostPpid as T,readProcessMemory as E}from"./host-process.js";import{ensureMainLoop as D,quitMainLoop as O}from"./main-loop.js";import{__resetBurstStateForTests as k,nextTick as A}from"./next-tick.js";export{r as GIO_ERROR_TO_NODE,i as GLIB_FILE_ERROR_TO_NODE,l as TARGET_OSES,k as __resetBurstStateForTests,a as createGLibFileError,o as createNodeError,t as deferEmit,D as ensureMainLoop,S as hasProcfs,C as hostExecPath,u as hostOs,w as hostPid,d as hostPlatform,T as hostPpid,n as initErrorV8Methods,f as isDarwin,p as isLinux,s as isNotFoundError,m as isTargetOs,h as isWin32,e as makeCallable,y as mapMachine,b as mapSysname,A as nextTick,g as notImplemented,v as queueMicrotask,O as quitMainLoop,E as readProcessMemory,c as registerGlobal,x as structuredClone,_ as warnNotImplemented};

package/lib/esm/host-os.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e=[`linux`,`darwin`,`win32`];function isTargetOs(t){return typeof t==`string`&&e.includes(t)}function hostPlatform(){let e=globalThis.process?.platform;return typeof e==`string`?e:void 0}function hostOs(){let e=hostPlatform();return isTargetOs(e)?e:void 0}function isWin32(){return hostPlatform()===`win32`}function isDarwin(){return hostPlatform()===`darwin`}function isLinux(){return hostPlatform()===`linux`}export{e as TARGET_OSES,hostOs,hostPlatform,isDarwin,isLinux,isTargetOs,isWin32};

package/lib/esm/host-process.js

@@ -0,0 +1,2 @@
+import"./_virtual/_rolldown/runtime.js";function hostGlib(){try{return globalThis.imports?.gi?.GLib}catch{return}}function readText(e,t){try{let[n,r]=e.file_get_contents(t);return!n||!r?null:new TextDecoder().decode(r)}catch{return null}}function shellOut(e,t){try{let[n,r]=e.spawn_command_line_sync(t);if(!n||!r)return null;let i=new TextDecoder().decode(r).trim();return i.length>0?i:null}catch{return null}}function hasProcfs(){let e=hostGlib();if(!e)return!1;try{return e.file_test(`/proc/self/status`,16)}catch{return!1}}let e=null;function hostPid(){if(e!==null)return e>0?e:void 0;let t=hostGlib();if(!t)return;let n=0,r=hasProcfs()?readText(t,`/proc/self/stat`):null;if(r)n=parseInt(r,10);else{let e=shellOut(t,`sh -c 'echo $PPID'`);e&&(n=parseInt(e,10))}return e=Number.isInteger(n)&&n>0?n:0,e>0?e:void 0}function hostPpid(){let e=hostGlib();if(!e)return;let t=hasProcfs()?readText(e,`/proc/self/status`):null;if(t){let e=/PPid:\s+(\d+)/.exec(t);if(e){let t=parseInt(e[1],10);return Number.isInteger(t)?t:void 0}}let n=hostPid();if(n===void 0)return;let r=shellOut(e,`ps -o ppid= -p ${n}`);if(!r)return;let i=parseInt(r,10);return Number.isInteger(i)?i:void 0}function hostExecPath(){let e=hostGlib();if(e){if(hasProcfs())try{let t=e.file_read_link(`/proc/self/exe`);if(t)return t}catch{}try{let t=e.get_prgname();if(t){let n=e.find_program_in_path(t);if(n)return n}}catch{return}}}function readProcessMemory(){let e=hostGlib();if(!e)return null;let t=hasProcfs()?readText(e,`/proc/self/status`):null;if(t){let e=new Map;for(let n of t.split(`
+`)){let t=/^(\w+):\s+(\d+)(\s+kB)?/.exec(n);t&&e.set(t[1],parseInt(t[2],10)*(t[3]?1024:1))}if(e.size>0)return{virtual:e.get(`VmSize`)??0,resident:e.get(`VmRSS`)??0,data:e.get(`VmData`)??0,peak:e.get(`VmPeak`)??0}}let n=shellOut(e,`sh -c 'ps -o rss=,vsz= -p $PPID'`);if(!n)return null;let r=/^(\d+)\s+(\d+)$/.exec(n);return r?{virtual:parseInt(r[2],10)*1024,resident:parseInt(r[1],10)*1024,data:0,peak:0}:null}export{hasProcfs,hostExecPath,hostPid,hostPpid,readProcessMemory};

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{notImplemented as d,warnNotImplemented as f}from"./message.js";import{queueMicrotask as p}from"./microtask.js";import{mapMachine as m,mapSysname as h}from"./platform-names.js";import{structuredClone as g}from"./structured-clone.js";import{ensureMainLoop as _,quitMainLoop as v}from"./main-loop.js";import{__resetBurstStateForTests as y,nextTick as b}from"./next-tick.js";import"./core.js";import{readJSON as x}from"./file.js";import{existsFD as S,existsSync as C}from"./fs.js";import{gioAsync as w,inputStreamAsyncIterator as T,readBytesAsync as E}from"./gio.js";import{getNodeModulesPath as D,getPathSeparator as O,getProgramDir as k,getProgramExe as A,resolve as j}from"./path.js";export{a as GIO_ERROR_TO_NODE,o as GLIB_FILE_ERROR_TO_NODE,y as __resetBurstStateForTests,n as cli,s as createGLibFileError,c as createNodeError,r as deferEmit,_ as ensureMainLoop,S as existsFD,C as existsSync,e as gbytesToUint8Array,D as getNodeModulesPath,O as getPathSeparator,k as getProgramDir,A as getProgramExe,w as gioAsync,i as initErrorV8Methods,T as inputStreamAsyncIterator,l as isNotFoundError,t as makeCallable,m as mapMachine,h as mapSysname,b as nextTick,d as notImplemented,p as queueMicrotask,v as quitMainLoop,E as readBytesAsync,x as readJSON,u as registerGlobal,j as resolve,g as structuredClone,f 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{mapMachine as x,mapSysname as S}from"./platform-names.js";import{structuredClone as C}from"./structured-clone.js";import{hasProcfs as w,hostExecPath as T,hostPid as E,hostPpid as D,readProcessMemory as O}from"./host-process.js";import{ensureMainLoop as k,quitMainLoop as A}from"./main-loop.js";import{__resetBurstStateForTests as j,nextTick as M}from"./next-tick.js";import"./core.js";import{readJSON as N}from"./file.js";import{existsFD as P,existsSync as F}from"./fs.js";import{gioAsync as I,inputStreamAsyncIterator as L,readBytesAsync as R}from"./gio.js";import{getNodeModulesPath as z,getPathSeparator as B,getProgramDir as V,getProgramExe as H,resolve as U}from"./path.js";export{a as GIO_ERROR_TO_NODE,o as GLIB_FILE_ERROR_TO_NODE,d as TARGET_OSES,j as __resetBurstStateForTests,n as cli,s as createGLibFileError,c as createNodeError,r as deferEmit,k as ensureMainLoop,P as existsFD,F as existsSync,e as gbytesToUint8Array,z as getNodeModulesPath,B as getPathSeparator,V as getProgramDir,H as getProgramExe,I as gioAsync,w as hasProcfs,T as hostExecPath,f as hostOs,E as hostPid,p as hostPlatform,D as hostPpid,i as initErrorV8Methods,L as inputStreamAsyncIterator,m as isDarwin,h as isLinux,l as isNotFoundError,g as isTargetOs,_ as isWin32,t as makeCallable,x as mapMachine,S as mapSysname,M as nextTick,v as notImplemented,b as queueMicrotask,A as quitMainLoop,R as readBytesAsync,N as readJSON,O as readProcessMemory,u as registerGlobal,U as resolve,C as structuredClone,y as warnNotImplemented};

package/lib/types/core.d.ts

@@ -3,9 +3,11 @@ export * from './defer.js';
 export * from './error.js';
 export * from './gio-errors.js';
 export * from './globals.js';
+export * from './host-os.js';
 export * from './message.js';
 export * from './microtask.js';
 export * from './platform-names.js';
 export * from './structured-clone.js';
+export * from './host-process.js';
 export * from './main-loop.js';
 export * from './next-tick.js';

package/lib/types/host-os.d.ts

@@ -0,0 +1,43 @@
+import type { ProcessPlatform } from './platform-names.js';
+/**
+ * The three operating systems ADR 0018 declares as the project's target set.
+ *
+ * Deliberately NARROWER than {@link ProcessPlatform}, which is Node's full
+ * vocabulary. `gjsify.os` keys are exactly these three: a package may not
+ * declare support for an OS the project does not claim, and `os-axis` fails on
+ * a key outside this set. The emulated `linux-{ppc64,s390x,riscv64}` targets
+ * are build-verified only and are an ARCH question, not an OS one — they live
+ * on the `gjsify.platforms` axis, which stays separate by design.
+ */
+export type TargetOs = 'linux' | 'darwin' | 'win32';
+/** The target set as data, so a check iterates it instead of restating it. */
+export declare const TARGET_OSES: readonly TargetOs[];
+/** Is `value` one of the three declared target operating systems? */
+export declare function isTargetOs(value: unknown): value is TargetOs;
+/**
+ * The host's `process.platform`, or `undefined` where nothing answers.
+ *
+ * `undefined` is the honest result on a runtime with no process object (the
+ * browser), and callers must treat it as "unknown", never as "not Windows" —
+ * which is why this returns an optional rather than defaulting to `'linux'`.
+ * The defaulting belongs to `@gjsify/process`'s `detectPlatform()`, which has a
+ * uname probe to fall back ON; this module has none and must not pretend.
+ */
+export declare function hostPlatform(): ProcessPlatform | undefined;
+/**
+ * The host OS as one of the three target names, or `undefined` when the host is
+ * not one of them (or could not be determined).
+ */
+export declare function hostOs(): TargetOs | undefined;
+/**
+ * Running on Windows?
+ *
+ * The predicate `it.failing(name, fn, reason, { when: isWin32() })` takes — the
+ * sanctioned way to carry a POSIX-only assertion through a win32 run without
+ * weakening it, and without an `if (platform)` guard that would hide it forever.
+ */
+export declare function isWin32(): boolean;
+/** Running on macOS? */
+export declare function isDarwin(): boolean;
+/** Running on Linux? */
+export declare function isLinux(): boolean;

package/lib/types/host-process.d.ts

@@ -0,0 +1,72 @@
+/** Does this host have a readable procfs for the current process? */
+export declare function hasProcfs(): boolean;
+/**
+ * This process's own pid, or `undefined` where nothing can answer.
+ *
+ * Two readers, capability-selected:
+ *
+ *   1. `/proc/self/stat` — its first field is the pid. One file read, no
+ *      subprocess.
+ *   2. `sh -c 'echo $PPID'` — the shell's PARENT is us, because
+ *      `g_spawn_command_line_sync()` forks this process and execs the shell in
+ *      the child. This is the same trick `@gjsify/v8`'s darwin heap reader has
+ *      used since it was written, and it is portable to every POSIX host that
+ *      has no procfs.
+ *
+ * Never `0`. `0` is a real pid, so returning it as "unknown" would hand every
+ * caller a number that looks answered.
+ */
+export declare function hostPid(): number | undefined;
+/**
+ * This process's parent pid, or `undefined` where nothing can answer.
+ *
+ * `/proc/self/status`' `PPid:` line where procfs exists, otherwise `ps -o ppid=`
+ * on our own pid — the POSIX-mandated spelling, so it needs no per-OS table.
+ * A parent pid of `1` (reparented to init/launchd) is a real answer and is
+ * returned as such; only a failed read is `undefined`.
+ */
+export declare function hostPpid(): number | undefined;
+/**
+ * The absolute path of the INTERPRETER running this process — what Node calls
+ * `process.execPath` — or `undefined` where nothing can answer.
+ *
+ * NOT `imports.system.programInvocationName`. That is the SCRIPT, and reporting
+ * it as `execPath` is a defect with teeth: `spawn(process.execPath, […])` is the
+ * documented portable way to start a second copy of the current runtime, and
+ * against a script path it fails `ENOENT` — or worse, `g_spawn` retries a
+ * non-executable text file through `/bin/sh` and the shell begins interpreting
+ * a bundle.
+ *
+ *   1. `/proc/self/exe` — a symlink to the running binary, exact by
+ *      construction.
+ *   2. `g_find_program_in_path(g_get_prgname())` — the PATH lookup for the name
+ *      this process was invoked under (`gjs`). Honest but not exact: a host with
+ *      two gjs installations can resolve the other one. That is why it is the
+ *      fallback and not the primary, and why nothing here defaults to a
+ *      hardcoded `/usr/bin/gjs` — a path that does not exist on macOS at all.
+ */
+export declare function hostExecPath(): string | undefined;
+/** The OS's view of a process's memory, in bytes. */
+export interface ProcessMemory {
+    /** Address space — Linux `VmSize`, `ps -o vsz`. */
+    virtual: number;
+    /** Resident set — Linux `VmRSS`, `ps -o rss`. */
+    resident: number;
+    /** Data segment — Linux `VmData`. `0` where the reader cannot see it. */
+    data: number;
+    /** Peak address space — Linux `VmPeak`. `0` where the reader cannot see it. */
+    peak: number;
+}
+/**
+ * This process's memory figures, or `null` when no reader applies.
+ *
+ * DEGRADED CONTRACT off procfs: `ps(1)` reports only `rss` and `vsz`, so `data`
+ * and `peak` stay `0` there. That is the same shape the Linux reader already
+ * produced for a procfs it could not parse, so no consumer meets a new one —
+ * but it is a real difference and `@gjsify/v8` documents it in
+ * `getHeapStatistics()`'s own contract.
+ *
+ * Both `ps` columns are in KiB on Linux and on macOS (POSIX mandates KiB for
+ * `rss`; BSD `vsz` follows), so one multiply serves both.
+ */
+export declare function readProcessMemory(): ProcessMemory | null;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/utils",
-    "version": "0.30.0",
+    "version": "0.32.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.30.0",
+        "@gjsify/cli": "^0.32.0",
         "typescript": "^6.0.3"
     },
     "dependencies": {
@@ -80,6 +80,11 @@
                 "browser": "polyfill",
                 "nativescript": "polyfill"
             }
+        },
+        "os": {
+            "linux": "supported",
+            "darwin": "supported",
+            "win32": "supported"
         }
     }
 }