@gjsify/fs 0.35.0 → 0.37.0

package/lib/esm/file-handle.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{encodeUint8Array as e,getEncodingFromOptions as t}from"./encoding.js";import{normalizePath as n}from"./utils.js";import{ReadStream as r}from"./read-stream.js";import{normalizeMode as i,parseOpenFlags as a}from"./posix-flags.js";import{WriteStream as o}from"./write-stream.js";import{closeFd as s,fdPath as c,fsError as l,fsyncFd as u,isSeekableFd as d,openFd as f,readFd as p,releaseFd as m,seekFd as h,sizeOfFd as g,tellFd as _,truncateFd as v,writeFd as y}from"./fd-io.js";import{STAT_ATTRIBUTES as b,statsFrom as x}from"./stats.js";import{chmodSync as S,chownSync as C}from"./sync.js";import w from"@girs/glib-2.0";import T from"@girs/gio-2.0";import{Buffer as E}from"node:buffer";import{createInterface as D}from"node:readline";var O=class FileHandle{options;_gFile;_pathStr;_spec;_pos=0;_closed=!1;static instances={};constructor(e){this.options=e,this.options.flags??=`r`;let t=n(e.path);this._spec=a(this.options.flags),this.options.mode??=438;let r=i(this.options.mode,438);return this.fd=f(t,this._spec,r),this._pathStr=t,this._gFile=T.File.new_for_path(t),FileHandle.instances[this.fd]=this,FileHandle.getInstance(this.fd)}_readCore(e,t,n,r){if(this._assertOpen(`read`),!this._spec.readable)throw l(`EBADF`,`read`,this._pathStr);if(n>e.byteLength-t){let r=RangeError(`The value of "length" is out of range. It must be <= ${e.byteLength-t}. Received ${n}`);throw r.code=`ERR_OUT_OF_RANGE`,r}let i=r!=null&&r>=0,a=d(this.fd,this._pathStr);if(i&&!a)throw l(`ESPIPE`,`read`,this._pathStr);let o=i?r:this._pos;a&&h(this.fd,o);let s=p(this.fd,n);return s.length>0&&new Uint8Array(e.buffer,e.byteOffset+t,s.length).set(s),!i&&a&&(this._pos=o+s.length),s.length}_writeCore(e,t){if(this._assertOpen(`write`),!this._spec.writable)throw l(`EBADF`,`write`,this._pathStr);if(this._spec.append){let t=y(this.fd,e);return this._pos=_(this.fd)??g(this.fd,this._pathStr),t}let n=t!=null&&t>=0,r=d(this.fd,this._pathStr);if(n&&!r)throw l(`ESPIPE`,`write`,this._pathStr);let i=n?t:this._pos;r&&h(this.fd,i);let a=y(this.fd,e);return!n&&r&&(this._pos=i+a),a}_assertOpen(e){if(this._closed)throw l(`EBADF`,e,this._pathStr)}_truncateCore(e){if(this._assertOpen(`ftruncate`),!this._spec.writable)throw l(`EINVAL`,`ftruncate`,this._pathStr);v(this.fd,Math.max(0,e),this._pathStr)}_readToEnd(){let e=[],t=0;for(;;){let n=new Uint8Array(64*1024),r=this._readCore(n,0,n.length,null);if(r===0)break;e.push(n.subarray(0,r)),t+=r}let n=new Uint8Array(t),r=0;for(let t of e)n.set(t,r),r+=t.length;return n}_fdTarget(){return c(this.fd)??this._pathStr}fd;static getInstance(e,t=`read`){let n=e instanceof FileHandle?e.fd:e,r=FileHandle.instances[n];if(!r)throw l(`EBADF`,t);return r}async appendFile(e,t){await this.writeFile(e,t)}async chown(e,t){this._assertOpen(`fchown`),C(n(this.options.path),e,t)}async chmod(e){this._assertOpen(`fchmod`),S(this._fdTarget(),e)}createReadStream(e){return new r(this.options.path,{...e,fd:this.fd})}createWriteStream(e){return new o(this.options.path,{...e,fd:this.fd,fdFromHandle:!0})}async datasync(){this._assertOpen(`fdatasync`),u(this.fd)}async sync(){this._assertOpen(`fsync`),u(this.fd)}async read(...e){let t,n,r,i;if(typeof e[0]==`object`&&!(e[0]instanceof Uint8Array)&&!(e[0]instanceof E)){let a=e[0];t=a.buffer,n=a.offset,r=a.length,i=a.position}else t=e[0],n=e[1],r=e[2],i=e[3];let a=t,o=n??0,s=r??(a?a.byteLength-o:65536);return{bytesRead:this._readCore(t,o,s,i??null),buffer:t}}readableWebStream(){let e=globalThis.ReadableStream;if(typeof e!=`function`)throw Error(`readableWebStream() requires a global ReadableStream. Import "node:stream/web" or "@gjsify/streams" before calling this method.`);return new e}async readFile(n){return e(t(n,`buffer`),this._readToEnd())}readLines(e){return D({input:this.createReadStream(e),crlfDelay:1/0})}async stat(e){this._assertOpen(`fstat`);let t=T.File.new_for_path(this._fdTarget());return x(await new Promise((e,n)=>{t.query_info_async(b,T.FileQueryInfoFlags.NONE,w.PRIORITY_DEFAULT,null,(r,i)=>{try{e(t.query_info_finish(i))}catch(e){n(e)}})}),this._pathStr,`fstat`,e?.bigint)}async truncate(e=0){this._truncateCore(e)}async utimes(e,t){this._assertOpen(`futimes`);let{utimesSync:r}=await import(`./utimes.js`);r(n(this.options.path),e,t)}async writeFile(e,n){let r=t(n),i;i=typeof e==`string`?E.from(e,r||`utf8`):e,this._writeCore(i,null)}async write(e,...n){let r=null,i=null,a=null,o=null;typeof e==`string`?(r=n[0],i=n[1]):(a=n[0],o=n[1],r=n[2]),i=t(i,typeof e==`string`?`utf8`:null);let s;s=typeof e==`string`?new TextEncoder().encode(e):e;let c=a??0,l=o??s.byteLength-c,u=s.subarray(c,c+l);return{bytesWritten:this._writeCore(u,r??null),buffer:e}}async writev(e,t){let n=0;for(let r of e){let e=E.from(r.buffer,r.byteOffset,r.byteLength),i=await this.write(e,0,e.byteLength,t==null?null:t+n);n+=i.bytesWritten}return{bytesWritten:n,buffers:e}}async readv(e,t){let n=0;for(let r of e){let e=await this.read({buffer:E.from(r.buffer,r.byteOffset,r.byteLength),position:t==null?null:t+n});if(n+=e.bytesRead,e.bytesRead<r.byteLength)break}return{bytesRead:n,buffers:e}}_flushSync(){u(this.fd)}_closeSync(){this._teardown()}_readSync(e,t,n,r){return this._readCore(e,t,n,r)}_writeSync(e,t){return this._writeCore(e,t)}_readToEndSync(){return this._readToEnd()}_truncateSync(e){this._truncateCore(e)}_fdStatTarget(){return this._fdTarget()}_teardown(){if(this._closed)return;this._closed=!0,m(this.fd),s(this.fd);let e=FileHandle;delete e.instances[this.fd]}async close(){this._teardown()}async[Symbol.asyncDispose](){await this.close()}pull(...e){throw Error('FileHandle.pull() is not implemented in @gjsify/fs yet — requires `node:stream/iter` (Node 25.9+) which @gjsify/stream has not ported. Track gjsify Open TODO "Node 25 stream/iter integration".')}writer(e){throw Error('FileHandle.writer() is not implemented in @gjsify/fs yet — requires `node:stream/iter` (Node 25.9+) which @gjsify/stream has not ported. Track gjsify Open TODO "Node 25 stream/iter integration".')}};export{O as FileHandle};
+import"./_virtual/_rolldown/runtime.js";import{encodeUint8Array as e,getEncodingFromOptions as t}from"./encoding.js";import{normalizePath as n}from"./utils.js";import{ReadStream as r}from"./read-stream.js";import{normalizeMode as i,parseOpenFlags as a}from"./posix-flags.js";import{WriteStream as o}from"./write-stream.js";import{closeFd as s,fdPath as c,fsError as l,fsyncFd as u,isSeekableFd as d,openFd as f,readFd as p,releaseFd as m,seekFd as h,sizeOfFd as g,tellFd as _,truncateFd as v,writeFd as y}from"./fd-io.js";import{STAT_ATTRIBUTES as b,statsFrom as x}from"./stats.js";import{chmodSync as S,chownSync as C}from"./sync.js";import w from"@girs/glib-2.0";import T from"@girs/gio-2.0";import{Buffer as E}from"node:buffer";import{createInterface as D}from"node:readline";var O=class FileHandle{options;_gFile;_pathStr;_spec;_pos=0;_closed=!1;static instances={};constructor(e){this.options=e,this.options.flags??=`r`;let t=n(e.path);this._spec=a(this.options.flags),this.options.mode??=438;let r=i(this.options.mode,438);return this.fd=f(t,this._spec,r),this._pathStr=t,this._gFile=T.File.new_for_path(t),FileHandle.instances[this.fd]=this,FileHandle.getInstance(this.fd)}_readCore(e,t,n,r){if(this._assertOpen(`read`),!this._spec.readable)throw l(`EBADF`,`read`,this._pathStr);if(n>e.byteLength-t){let r=RangeError(`The value of "length" is out of range. It must be <= ${e.byteLength-t}. Received ${n}`);throw r.code=`ERR_OUT_OF_RANGE`,r}let i=r!=null&&r>=0,a=d(this.fd,this._pathStr);if(i&&!a)throw l(`ESPIPE`,`read`,this._pathStr);let o=i?r:this._pos;a&&h(this.fd,o);let s=p(this.fd,n);return s.length>0&&new Uint8Array(e.buffer,e.byteOffset+t,s.length).set(s),!i&&a&&(this._pos=o+s.length),s.length}_writeCore(e,t){if(this._assertOpen(`write`),!this._spec.writable)throw l(`EBADF`,`write`,this._pathStr);if(this._spec.append){let t=y(this.fd,e);return this._pos=_(this.fd)??g(this.fd,this._pathStr),t}let n=t!=null&&t>=0,r=d(this.fd,this._pathStr);if(n&&!r)throw l(`ESPIPE`,`write`,this._pathStr);let i=n?t:this._pos;r&&h(this.fd,i);let a=y(this.fd,e);return!n&&r&&(this._pos=i+a),a}_assertOpen(e){if(this._closed)throw l(`EBADF`,e,this._pathStr)}_truncateCore(e){if(this._assertOpen(`ftruncate`),!this._spec.writable)throw l(`EINVAL`,`ftruncate`,this._pathStr);v(this.fd,Math.max(0,e),this._pathStr)}_readToEnd(){let e=[],t=0;for(;;){let n=new Uint8Array(64*1024),r=this._readCore(n,0,n.length,null);if(r===0)break;e.push(n.subarray(0,r)),t+=r}let n=new Uint8Array(t),r=0;for(let t of e)n.set(t,r),r+=t.length;return n}_fdTarget(){return c(this.fd)??this._pathStr}fd;static getInstance(e,t=`read`){let n=e instanceof FileHandle?e.fd:e,r=FileHandle.instances[n];if(!r)throw l(`EBADF`,t);return r}async appendFile(e,t){await this.writeFile(e,t)}async chown(e,t){this._assertOpen(`fchown`),C(n(this.options.path),e,t)}async chmod(e){this._assertOpen(`fchmod`),S(this._fdTarget(),e)}createReadStream(e){return new r(this.options.path,{...e,fd:this.fd})}createWriteStream(e){return new o(this.options.path,{...e,fd:this.fd,fdFromHandle:!0})}async datasync(){this._assertOpen(`fdatasync`),u(this.fd)}async sync(){this._assertOpen(`fsync`),u(this.fd)}async read(...e){let t,n,r,i;if(typeof e[0]==`object`&&!(e[0]instanceof Uint8Array)&&!(e[0]instanceof E)){let a=e[0];t=a.buffer,n=a.offset,r=a.length,i=a.position}else t=e[0],n=e[1],r=e[2],i=e[3];let a=t,o=n??0,s=r??(a?a.byteLength-o:65536);return{bytesRead:this._readCore(t,o,s,i??null),buffer:t}}readableWebStream(){let e=globalThis.ReadableStream;if(typeof e!=`function`)throw Error(`readableWebStream() requires a global ReadableStream. Import "node:stream/web" or "@gjsify/web-streams/register" before calling this method.`);return new e}async readFile(n){return e(t(n,`buffer`),this._readToEnd())}readLines(e){return D({input:this.createReadStream(e),crlfDelay:1/0})}async stat(e){this._assertOpen(`fstat`);let t=T.File.new_for_path(this._fdTarget());return x(await new Promise((e,n)=>{t.query_info_async(b,T.FileQueryInfoFlags.NONE,w.PRIORITY_DEFAULT,null,(r,i)=>{try{e(t.query_info_finish(i))}catch(e){n(e)}})}),this._pathStr,`fstat`,e?.bigint)}async truncate(e=0){this._truncateCore(e)}async utimes(e,t){this._assertOpen(`futimes`);let{utimesSync:r}=await import(`./utimes.js`);r(n(this.options.path),e,t)}async writeFile(e,n){let r=t(n),i;i=typeof e==`string`?E.from(e,r||`utf8`):e,this._writeCore(i,null)}async write(e,...n){let r=null,i=null,a=null,o=null;typeof e==`string`?(r=n[0],i=n[1]):(a=n[0],o=n[1],r=n[2]),i=t(i,typeof e==`string`?`utf8`:null);let s;s=typeof e==`string`?new TextEncoder().encode(e):e;let c=a??0,l=o??s.byteLength-c,u=s.subarray(c,c+l);return{bytesWritten:this._writeCore(u,r??null),buffer:e}}async writev(e,t){let n=0;for(let r of e){let e=E.from(r.buffer,r.byteOffset,r.byteLength),i=await this.write(e,0,e.byteLength,t==null?null:t+n);n+=i.bytesWritten}return{bytesWritten:n,buffers:e}}async readv(e,t){let n=0;for(let r of e){let e=await this.read({buffer:E.from(r.buffer,r.byteOffset,r.byteLength),position:t==null?null:t+n});if(n+=e.bytesRead,e.bytesRead<r.byteLength)break}return{bytesRead:n,buffers:e}}_flushSync(){u(this.fd)}_closeSync(){this._teardown()}_readSync(e,t,n,r){return this._readCore(e,t,n,r)}_writeSync(e,t){return this._writeCore(e,t)}_readToEndSync(){return this._readToEnd()}_truncateSync(e){this._truncateCore(e)}_fdStatTarget(){return this._fdTarget()}_teardown(){if(this._closed)return;this._closed=!0,m(this.fd),s(this.fd);let e=FileHandle;delete e.instances[this.fd]}async close(){this._teardown()}async[Symbol.asyncDispose](){await this.close()}pull(...e){throw Error('FileHandle.pull() is not implemented in @gjsify/fs yet — requires `node:stream/iter` (Node 25.9+) which @gjsify/stream has not ported. Track gjsify Open TODO "Node 25 stream/iter integration".')}writer(e){throw Error('FileHandle.writer() is not implemented in @gjsify/fs yet — requires `node:stream/iter` (Node 25.9+) which @gjsify/stream has not ported. Track gjsify Open TODO "Node 25 stream/iter integration".')}};export{O as FileHandle};

package/lib/types/fd-io.d.ts

@@ -5,72 +5,52 @@ export declare function fsError(code: string, syscall: string, path?: string, de
 /**
  * Can this host name an open descriptor as a path?
  *
- * Measured once, and only ONCE it is needed — a module-eval probe would run in
- * every consumer that merely imports `node:fs`. `respond-with-file.ts` carries
- * the scar of assuming procfs exists: the path resolved to nothing on macOS,
- * `statSync` threw, and a swallowed catch meant the check silently never ran.
+ * Lazy, not at module eval: a probe there runs in every consumer that merely
+ * imports `node:fs`. Do not assume procfs exists — in `respond-with-file.ts` the
+ * path resolved to nothing on macOS, `statSync` threw, and a swallowed catch meant
+ * the check silently never ran.
  */
 export declare function hasProcFd(): boolean;
 /**
- * A path that names the DESCRIPTOR rather than the name it was opened from,
- * or `null` where the host cannot express one.
- *
- * This is what makes `fstat`/`fchmod`/`ftruncate` survive a rename or an
- * unlink: `/proc/self/fd/<fd>` resolves to the inode the fd holds, even after
- * the directory entry is gone.
+ * A path naming the DESCRIPTOR rather than the name it was opened from, or `null`
+ * where the host cannot express one. `/proc/self/fd/<fd>` resolves to the inode
+ * the fd holds even after the directory entry is gone, which is what lets
+ * `fstat`/`fchmod`/`ftruncate` survive a rename or unlink.
  */
 export declare function fdPath(fd: number): string | null;
-/**
- * `open(2)`.
- *
- * The mode reaches the kernel, so it is applied ATOMICALLY at creation, masked
- * by the live umask, and it survives a crash — none of which a post-create or
- * close-time `chmod` can offer. `O_EXCL` is likewise the kernel's, so it is
- * atomic and it refuses a symlink whatever the link points at.
- */
+/** `open(2)`. */
 export declare function openFd(path: string, spec: OpenSpec, mode: number): number;
 export declare function closeFd(fd: number): void;
 /**
- * Name the reason `open(2)` refused.
- *
- * GJS cannot read `errno`, so the code is reconstructed from what is observable
- * AFTER the kernel has already refused. That makes this a classification, not a
- * check-then-act: it never decides whether to create anything, so it carries no
- * TOCTOU. The `lstat`-equivalent lookup (`NOFOLLOW_SYMLINKS`) matters — a
- * dangling symlink must read as "the name is taken", which is exactly why
- * `file_test(EXISTS)` was the wrong instrument for the check this replaces.
+ * Name the reason `open(2)` refused, reconstructed from what is observable AFTER
+ * the kernel refused. A classification, not a check-then-act: it decides nothing
+ * about creating anything, so it carries no TOCTOU. The lookup must be
+ * `NOFOLLOW_SYMLINKS` so a dangling symlink reads as "the name is taken".
  */
 export declare function classifyOpenFailure(path: string, spec: OpenSpec): NodeJS.ErrnoException;
 /**
  * Does this `GFileInfo` actually ANSWER, or is it an empty shell?
  *
- * `g_file_query_info()` does NOT fail when the kernel refuses to stat a name.
- * A path under a directory the process cannot search comes back as a non-NULL
- * `GFileInfo` carrying NO attributes at all — measured directly:
- * `list_attributes(null)` is `[]` and `has_attribute('standard::type')` is
- * `false`, where an ordinary lookup returns `['standard::type']`.
- *
- * Two things follow, and this package got both wrong. Reading the type off
- * that shell logs `GFileInfo created without standard::type` plus
- * `g_file_info_get_file_type: should not be reached` — two `GLib-GIO-CRITICAL`
- * lines that `G_DEBUG=fatal-criticals` (standard in GNOME CI, and the exact
- * condition {@link isSeekableFd} below exists to satisfy) turns into a
- * SIGABRT before the caller's `catch` can run. And taking the shell as proof
- * the name EXISTS answered EEXIST — "the name is taken" — for a plain
- * permission denial, which sends an `openSync(lock,'wx')` retry loop round
- * forever and makes the ubiquitous
- * `try { mkdirSync(d) } catch (e) { if (e.code !== 'EEXIST') throw }`
- * swallow a hard EACCES and carry on as if the directory were there.
- *
- * So every read of an attribute in this module is gated on this, and a
- * `false` means "no answer" — never "no".
- *
- * Exported because the stat family needs the identical gate and used to lack
- * it: `statSync` under an unsearchable directory built a `Stats` from the empty
- * shell, which is BOTH of the failures above at once — four CRITICALs (hence a
- * SIGABRT under `G_DEBUG=fatal-criticals`) and then a fabricated `{mode: 0,
- * size: 0, ino: 0}` returned as fact where Node raises EACCES. See
- * `statsFrom()` in `stats.ts`, which is the one place that decision now lives.
+ * `g_file_query_info()` does NOT fail when the kernel refuses to stat a name. A
+ * path under a directory the process cannot search returns a non-NULL `GFileInfo`
+ * with NO attributes at all — measured: `list_attributes(null)` is `[]` and
+ * `has_attribute('standard::type')` is `false`, where an ordinary lookup gives
+ * `['standard::type']`. Every attribute read in this module is therefore gated on
+ * this, and `false` means "no answer", NEVER "no".
+ *
+ * Both ways of skipping the gate are live hazards:
+ *   - reading the type off the shell logs `GFileInfo created without
+ *     standard::type` and `g_file_info_get_file_type: should not be reached`, two
+ *     `GLib-GIO-CRITICAL`s that `G_DEBUG=fatal-criticals` (standard in GNOME CI)
+ *     turns into a SIGABRT before the caller's `catch` can run;
+ *   - taking the shell as proof the name EXISTS answers EEXIST for a plain
+ *     permission denial, so an `openSync(lock,'wx')` retry loop spins forever and
+ *     the ubiquitous `catch (e) { if (e.code !== 'EEXIST') throw }` around
+ *     `mkdirSync` swallows a hard EACCES.
+ *
+ * Exported because the stat family needs the identical gate; without it `statSync`
+ * hits both hazards at once and returns a fabricated `{mode: 0, size: 0, ino: 0}`
+ * as fact where Node raises EACCES. `statsFrom()` in `stats.ts` owns that decision.
  */
 export declare function answered(info: Gio.FileInfo | null): boolean;
 /** The same reconstruction for `mkdir(2)`, which also returns a bare `-1`. */
@@ -78,53 +58,37 @@ export declare function classifyMkdirFailure(path: string): NodeJS.ErrnoExceptio
 /**
  * Can this descriptor be positioned at all?
  *
- * `seekFd` used to be issued before EVERY read and write, unconditionally, so a
- * FIFO / pipe / socket / tty produced one
- * `g_io_channel_seek_position: assertion 'channel->is_seekable' failed`
- * per I/O call — a `GLib-CRITICAL`, which `G_DEBUG=fatal-criticals` (standard
- * in GNOME CI) turns into an abort. The bytes happened to survive because a
- * pipe ignores the offset, so the failed seek was a silent no-op and `_pos`
- * accumulated a number that meant nothing.
- *
- * The answer is therefore ASKED FOR rather than discovered by tripping an
- * assertion. `GIOChannel` decides it with `lseek(fd, 0, SEEK_CUR)`, which GJS
- * cannot reach, and its `is_seekable` field is not introspectable — so the file
- * TYPE is the available instrument.
- *
- * The rule is deliberately narrow: only `S_IFIFO` and `S_IFSOCK` are refused.
- * The tempting "seekable means `S_IFREG` or `S_IFBLK`" is WRONG and would trade
- * this defect for a worse one — a character device usually seeks fine
- * (`noop_llseek`), and Node performs positional I/O on `/dev/null`,
- * `/dev/zero` and `/dev/urandom` without complaint (measured against
- * v24.15.0). Refusing those would have turned a stray log line into an ESPIPE
- * that Node never raises.
- *
- * The type test alone is NOT the whole answer, and a TTY is where it runs out:
- * `/dev/pts/N` is `S_IFCHR` exactly like `/dev/zero`, but it has `no_llseek`.
- * So after the type test the DESCRIPTOR ITSELF is asked, with the same
- * `lseek(fd, 0, SEEK_CUR)` `GIOChannel` uses internally — a pure query that
- * moves nothing. Measured under gjs 1.88.1: it returns `G_IO_STATUS_NORMAL` on
- * a regular file, on `/dev/zero` and on `/dev/null`, and THROWS
- * `GLib.IOChannelError` ("Illegal seek") on a pty slave — cleanly, with no
- * CRITICAL, because a `GIOChannel` over a tty is `is_seekable` and the failure
- * comes from the kernel rather than from an assertion. Order matters: the type
- * test runs FIRST because a FIFO / socket channel is NOT `is_seekable`, and
- * asking one to seek is the `g_io_channel_seek_position: assertion failed`
- * CRITICAL this function exists to avoid.
- *
- * Without the second test, writing to a terminal by path was impossible: the
- * unconditional `seekFd` threw a RAW `Gio.IOErrorEnum` — `code === 8` as a
- * NUMBER, `instanceof Error === false` — straight out of `writeFileSync`,
- * `writeSync` and `createWriteStream`, so `catch (e) { if (e.code === 'ESPIPE') }`
- * could not see it and the classic "write to the terminal even when stdout is
- * redirected" idiom simply failed.
- *
- * The process's own stdin/stdout/stderr — the overwhelmingly common tty case —
- * never reach this code: `isStdFd()` intercepts them first.
- *
- * Cached per fd: the type behind an open file description cannot change under
- * it, and the cache is dropped by {@link releaseFd} so a recycled fd number
- * never inherits the previous holder's answer.
+ * Seeking unconditionally before every read and write emits one
+ * `g_io_channel_seek_position: assertion 'channel->is_seekable' failed` per I/O
+ * call on a FIFO / pipe / socket / tty — a `GLib-CRITICAL`, which
+ * `G_DEBUG=fatal-criticals` (standard in GNOME CI) turns into an abort. The bytes
+ * survive, because a pipe ignores the offset, so `_pos` silently accumulates a
+ * number that means nothing.
+ *
+ * The answer must therefore be ASKED FOR, not discovered by tripping the
+ * assertion, and it takes TWO tests in this order:
+ *
+ * 1. The file TYPE, refusing ONLY `S_IFIFO` and `S_IFSOCK` — the two whose channel
+ *    is not `is_seekable`, so asking them at all is the CRITICAL above. The
+ *    tempting "seekable means `S_IFREG` or `S_IFBLK`" is WRONG: a character device
+ *    usually seeks fine (`noop_llseek`) and Node does positional I/O on
+ *    `/dev/null`, `/dev/zero` and `/dev/urandom` (measured, v24.15.0), so
+ *    refusing those raises an ESPIPE Node never raises.
+ * 2. The DESCRIPTOR itself, via the same `lseek(fd, 0, SEEK_CUR)` `GIOChannel` uses
+ *    internally — a pure query that moves nothing. Needed because a TTY is
+ *    `S_IFCHR` exactly like `/dev/zero` but has `no_llseek`. Measured under gjs
+ *    1.88.1: `G_IO_STATUS_NORMAL` on a regular file, `/dev/zero` and `/dev/null`;
+ *    a clean `GLib.IOChannelError` ("Illegal seek") on a pty slave, with no
+ *    CRITICAL, because that channel IS `is_seekable` and the kernel refuses.
+ *
+ * Skipping test 2 makes writing to a terminal by path impossible: the seek throws
+ * a RAW `Gio.IOErrorEnum` — numeric `code`, `instanceof Error === false` — out of
+ * `writeFileSync`/`writeSync`/`createWriteStream`, invisible to
+ * `catch (e) { if (e.code === 'ESPIPE') }`.
+ *
+ * The process's own stdin/stdout/stderr never arrive here; `isStdFd()` takes them
+ * first. Cached per fd — the type behind an open file description cannot change —
+ * and dropped by {@link releaseFd} so a recycled fd number inherits nothing.
  */
 export declare function isSeekableFd(fd: number, fallbackPath: string): boolean;
 /** Absolute `lseek(2)`. Only valid on a descriptor {@link isSeekableFd} accepts. */
@@ -132,11 +96,9 @@ export declare function seekFd(fd: number, position: number): void;
 /**
  * The descriptor's true offset, or `null` where the host cannot report it.
  *
- * Only needed where the KERNEL moved the offset behind us — an `O_APPEND`
- * write jumps to EOF without telling anyone, and computing the new position
- * from the pre-write value is how the previous attempt let the cursor drift
- * away from the file after the first append. `seek_position()` cannot answer
- * this: it returns a `GIOStatus`, not an offset.
+ * Only needed where the KERNEL moved the offset behind us: an `O_APPEND` write jumps
+ * to EOF silently, and computing the new position from the pre-write value drifts.
+ * `seek_position()` cannot answer this — it returns a `GIOStatus`, not an offset.
  */
 export declare function tellFd(fd: number): number | null;
 /** `read(2)` at the descriptor's current offset. The kernel advances it. */
@@ -145,11 +107,9 @@ export declare function readFd(fd: number, length: number): Uint8Array;
 export declare function writeFd(fd: number, data: Uint8Array): number;
 export declare function fsyncFd(fd: number): void;
 /**
- * Release the cached per-fd views.
- *
- * The streams must go before the descriptor does: a GioUnix stream outliving
- * its fd would answer a later call against whatever the OS handed that number
- * to next.
+ * Release the cached per-fd views. They must go before the descriptor does: a
+ * GioUnix stream outliving its fd answers later calls against whatever the OS
+ * handed that number to next.
  */
 export declare function releaseFd(fd: number): void;
 /** The size of the file behind `fd`, via the descriptor where the host allows. */
@@ -157,32 +117,25 @@ export declare function sizeOfFd(fd: number, fallbackPath: string): number;
 /**
  * `ftruncate(2)`, as closely as GJS can express it.
  *
- * THE PART THAT IS REACHABLE, AND WHERE IT LIVES
- *
- * `ftruncate(2)` checks ONE thing: that the descriptor is open for writing. It
- * never looks at the file's mode. That check is pure bookkeeping we already
- * hold, so it is enforced where the access mode lives — `FileHandle`, next to
- * the identical gates in `_readCore`/`_writeCore` — and NOT here. Without it a
- * handle opened `'r'` could destroy the file, because the re-open below asks
- * the kernel for its own fresh permission and gets it.
- *
- * THE PART THAT IS NOT, MEASURED
- *
- * There is no `g_ftruncate`, and no route from an fd to a `GSeekable`:
- * `GioUnix.OutputStream` does not implement it, and `GBufferedOutputStream` /
- * `GDataOutputStream` wrapped around one both report `can_truncate() == false`
- * (measured under gjs 1.88.1). Truncation therefore needs a second `open(2)`,
- * by the descriptor's procfs name so it lands on the right inode after a rename
- * or an unlink — and a second open is checked against the FILE's mode.
- *
- * So the re-open takes the least privilege that can truncate: `append_to()` is
- * `O_WRONLY`, `open_readwrite()` is `O_RDWR`. That is not a micro-optimisation
- * — it is the difference between working and not on a write-only file: mode
- * 0o200 truncates through the first and is refused by the second (measured).
- * What remains unreachable is a file whose mode denies its own owner write
- * (0o444, 0o400, 0o000): Node truncates those through the descriptor, we cannot.
- * The failure is at least REPORTED now — it used to escape as a bare
- * `Gio.IOErrorEnum` with a numeric `code` and `instanceof Error === false`, so
- * `catch (e) { if (e.code === 'EACCES') }` could not see it.
+ * The access-mode check `ftruncate(2)` performs — descriptor open for writing, mode
+ * never consulted — is bookkeeping we already hold, so it lives in `FileHandle`
+ * beside the identical gates in `_readCore`/`_writeCore`, NOT here. Without it a
+ * handle opened `'r'` destroys the file, because the re-open below asks the kernel
+ * for fresh permission and gets it.
+ *
+ * A re-open is unavoidable: there is no `g_ftruncate` and no route from an fd to a
+ * `GSeekable` — `GioUnix.OutputStream` does not implement it, and
+ * `GBufferedOutputStream` / `GDataOutputStream` around one both report
+ * `can_truncate() == false` (measured, gjs 1.88.1). It goes by the descriptor's
+ * procfs name so it lands on the right inode after a rename or unlink, and being a
+ * second open it IS checked against the file's mode.
+ *
+ * Hence the least privilege that can truncate: `append_to()` is `O_WRONLY`,
+ * `open_readwrite()` is `O_RDWR`. Not an optimisation — on a write-only file, mode
+ * 0o200 truncates through the first and is refused by the second (measured). Still
+ * unreachable: a mode denying its own owner write (0o444, 0o400, 0o000), which Node
+ * truncates through the descriptor. That failure must at least be REPORTED as an
+ * ErrnoException — raw it escapes as a `Gio.IOErrorEnum` with a numeric `code` and
+ * `instanceof Error === false`, invisible to `catch (e) { if (e.code === 'EACCES') }`.
  */
 export declare function truncateFd(fd: number, length: number, fallbackPath: string): void;

package/lib/types/file-handle.d.ts

@@ -19,20 +19,14 @@ export declare class FileHandle implements IFileHandle {
     /** What the caller asked open(2) for — the ORIGINAL flags, nothing flattened. */
     private readonly _spec;
     /**
-     * The one byte position this handle has.
+     * The one byte position this handle has — a descriptor has exactly ONE offset,
+     * shared by reads and writes. `_readCore`/`_writeCore` seek to it absolutely
+     * before every operation, so the kernel's offset is a consequence of this
+     * value and cannot drift from it.
      *
-     * A descriptor has exactly ONE offset, shared by reads and writes, and this
-     * is it: `_readCore`/`_writeCore` seek to it absolutely before every
-     * operation, so the kernel's own offset is a consequence of this value and
-     * can never drift away from it. It replaces four carriers that used to
-     * disagree — a read-only `_readPos`, the IOChannel's buffered offset, a
-     * cached Gio stream's cursor, and a fresh per-call stream that always
-     * started at 0.
-     *
-     * The single exception is an `O_APPEND` write: there the kernel repositions
-     * to EOF without telling us, so the new value is READ BACK rather than
-     * computed from the pre-write one. Computing it is how the previous attempt
-     * let the cursor drift away from the file after the first append.
+     * Exception: an `O_APPEND` write, where the kernel repositions to EOF without
+     * telling us. There the new value must be READ BACK; computing it from the
+     * pre-write value drifts after the very first append.
      */
     private _pos;
     private _closed;
@@ -46,14 +40,11 @@ export declare class FileHandle implements IFileHandle {
     /**
      * Read at `position`, or at the cursor when it is `null`/negative.
      *
-     * SYNCHRONOUS ON PURPOSE. The cursor's read-modify-write — read `_pos`,
-     * seek, transfer, store `_pos` — has no `await` inside it, so it is
-     * indivisible by construction on a single-threaded runtime. The previous
-     * attempt held an async lock around the I/O but computed the offset outside
-     * it, so two concurrent writers captured the same offset and one write was
-     * lost. That class cannot exist here: there is no suspension point for
-     * anything to interleave with, which is why the async lock this replaces is
-     * gone rather than tightened.
+     * SYNCHRONOUS ON PURPOSE: the cursor's read-modify-write — read `_pos`, seek,
+     * transfer, store `_pos` — contains no `await`, so on a single-threaded runtime
+     * it is indivisible by construction. An async lock cannot substitute for that;
+     * one held around the I/O while the offset was computed outside it let two
+     * concurrent writers capture the same offset and lose a write.
      */
     private _readCore;
     /** Write at `position`, or at the cursor when it is `null`/negative. See {@link _readCore}. */
@@ -62,250 +53,93 @@ export declare class FileHandle implements IFileHandle {
     /**
      * `ftruncate(2)` — ONE body for the sync and async halves.
      *
-     * The access-mode gate belongs HERE and not in `truncateFd`, because it is
-     * the descriptor's property and `truncateFd` has to re-open the file to do
-     * its work (see there) — a re-open that asks the kernel for its own fresh
-     * permission and is granted it. Without this line a handle opened `'r'`
-     * truncates the file: `writeFileSync(f,'ABCDEFGH'); ftruncateSync(openSync(f,'r'), 2)`
-     * destroyed six bytes through a READ-ONLY descriptor and returned normally.
-     * Node reports EINVAL, and so does this.
-     *
-     * `_readCore`/`_writeCore` have carried the identical gate since this
-     * redesign began; truncate was the one byte-mover left outside it, which is
-     * exactly the shape of divergence the single-core rule exists to prevent.
+     * The access-mode gate belongs HERE, not in `truncateFd`: it is a property of
+     * the descriptor, and `truncateFd` re-opens the file (see there), so the kernel
+     * grants it fresh permission of its own. Without this line
+     * `ftruncateSync(openSync(f,'r'), 2)` destroys bytes through a READ-ONLY
+     * descriptor and returns normally. Node reports EINVAL, and so does this.
      */
     private _truncateCore;
     /** Read from the cursor to EOF, advancing it — Node's whole-file read on a handle. */
     private _readToEnd;
     /** The path that names this DESCRIPTOR, falling back to the name it was opened from. */
     private _fdTarget;
-    /**
-     * The numeric file descriptor managed by the {FileHandle} object.
-     * @since v10.0.0
-     */
+    /** The numeric file descriptor managed by this object. */
     readonly fd: number;
     /**
      * The handle behind a descriptor number. Not part of Node's API.
      *
-     * TWO things used to go wrong here, both of them at the boundary where a
-     * caller holds a NUMBER and this package holds an object.
-     *
-     * It threw `Error('No instance found for fd!')` — no `code`, not an
-     * `ErrnoException`. But the overwhelmingly common way to reach it is an fd
-     * that WAS valid: `_teardown()` deletes the instance, so every call on a
-     * closed descriptor landed here rather than on `_assertOpen`, which made
-     * that guard dead for every fd-number call site. `catch (e) { if (e.code
-     * === 'EBADF') }` — the idiom for tolerating a racing close — fell through
-     * to the generic branch instead. The syscall is threaded in from the caller
-     * because Node names it in the message, and we know it there and only there.
+     * Must fail as `EBADF`, not a bare Error: the common way to get here is an fd
+     * that WAS valid, since `_teardown()` deletes the instance, so every call on a
+     * closed descriptor lands here instead of on `_assertOpen`. Without the code,
+     * `catch (e) { if (e.code === 'EBADF') }` — the idiom for tolerating a racing
+     * close — falls through. `syscall` comes from the caller because Node names it
+     * in the message and only the caller knows it.
      *
-     * It also indexed `instances` with whatever it was given. `openSync()`
-     * returns a FileHandle rather than Node's number (a pre-existing divergence
-     * this does not attempt to change), so `fs.write(fs.openSync(p,'w'), …)`
-     * stringified the object into a key, missed, and threw out of the callback
-     * machinery. Unwrapping is one line and makes every fd call site accept
-     * both spellings.
+     * A `FileHandle` is accepted as well as a number because `openSync()` returns
+     * the handle where Node returns a number (a divergence this does not change);
+     * without unwrapping, `fs.write(fs.openSync(p,'w'), …)` stringifies the object
+     * into a key and misses.
      */
     static getInstance(fd: number | FileHandle, syscall?: string): FileHandle;
     /**
-     * Alias of `filehandle.writeFile()`.
-     *
-     * When operating on file handles, the mode cannot be changed from what it was set
-     * to with `fsPromises.open()`. Therefore, this is equivalent to `filehandle.writeFile()`.
-     * @since v10.0.0
-     * @return Fulfills with `undefined` upon success.
+     * Alias of `writeFile()`: a handle's mode cannot be changed after
+     * `fsPromises.open()`, so it appends only because the descriptor carries
+     * O_APPEND. It must therefore be a plain CURSOR write — writing at some
+     * separately-tracked offset overwrites from byte 0 on a fresh handle.
      */
     appendFile(data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode) | BufferEncoding | null): Promise<void>;
-    /**
-     * Changes the ownership of the file. A wrapper for [`chown(2)`](http://man7.org/linux/man-pages/man2/chown.2.html).
-     * @since v10.0.0
-     * @param uid The file's new owner's user id.
-     * @param gid The file's new group's group id.
-     * @return Fulfills with `undefined` upon success.
-     */
+    /** [`chown(2)`](http://man7.org/linux/man-pages/man2/chown.2.html). */
     chown(uid: number, gid: number): Promise<void>;
-    /**
-     * Modifies the permissions on the file. See [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html).
-     * @since v10.0.0
-     * @param mode the file mode bit mask.
-     * @return Fulfills with `undefined` upon success.
-     */
+    /** [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html). */
     chmod(mode: Mode): Promise<void>;
     /**
-     * Unlike the 16 kb default `highWaterMark` for a `stream.Readable`, the stream
-     * returned by this method has a default `highWaterMark` of 64 kb.
-     *
-     * `options` can include `start` and `end` values to read a range of bytes from
-     * the file instead of the entire file. Both `start` and `end` are inclusive and
-     * start counting at 0, allowed values are in the
-     * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. If `start` is
-     * omitted or `undefined`, `filehandle.createReadStream()` reads sequentially from
-     * the current file position. The `encoding` can be any one of those accepted by `Buffer`.
-     *
-     * If the `FileHandle` points to a character device that only supports blocking
-     * reads (such as keyboard or sound card), read operations do not finish until data
-     * is available. This can prevent the process from exiting and the stream from
-     * closing naturally.
-     *
-     * By default, the stream will emit a `'close'` event after it has been
-     * destroyed.  Set the `emitClose` option to `false` to change this behavior.
-     *
-     * ```js
-     * import { open } from 'node:fs/promises';
-     *
-     * const fd = await open('/dev/input/event0');
-     * // Create a stream from some character device.
-     * const stream = fd.createReadStream();
-     * setTimeout(() => {
-     *   stream.close(); // This may not close the stream.
-     *   // Artificially marking end-of-stream, as if the underlying resource had
-     *   // indicated end-of-file by itself, allows the stream to close.
-     *   // This does not cancel pending read operations, and if there is such an
-     *   // operation, the process may still not be able to exit successfully
-     *   // until it finishes.
-     *   stream.push(null);
-     *   stream.read(0);
-     * }, 100);
-     * ```
-     *
-     * If `autoClose` is false, then the file descriptor won't be closed, even if
-     * there's an error. It is the application's responsibility to close it and make
-     * sure there's no file descriptor leak. If `autoClose` is set to true (default
-     * behavior), on `'error'` or `'end'` the file descriptor will be closed
-     * automatically.
-     *
-     * An example to read the last 10 bytes of a file which is 100 bytes long:
-     *
-     * ```js
-     * import { open } from 'node:fs/promises';
-     *
-     * const fd = await open('sample.txt');
-     * fd.createReadStream({ start: 90, end: 99 });
-     * ```
-     * @since v16.11.0
+     * `highWaterMark` defaults to 64 kb here rather than a Readable's 16 kb. With
+     * no `start`, reading is sequential from the current file position.
      */
     createReadStream(options?: CreateReadStreamOptions): ReadStream;
     /**
-     * `options` may also include a `start` option to allow writing data at some
-     * position past the beginning of the file, allowed values are in the
-     * \[0, [`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)\] range. Modifying a file rather than
-     * replacing it may require the `flags` `open` option to be set to `r+` rather than
-     * the default `r`. The `encoding` can be any one of those accepted by `Buffer`.
-     *
-     * If `autoClose` is set to true (default behavior) on `'error'` or `'finish'`the file descriptor will be closed automatically. If `autoClose` is false,
-     * then the file descriptor won't be closed, even if there's an error.
-     * It is the application's responsibility to close it and make sure there's no
-     * file descriptor leak.
-     *
-     * By default, the stream will emit a `'close'` event after it has been
-     * destroyed.  Set the `emitClose` option to `false` to change this behavior.
-     * @since v16.11.0
+     * `options.start` writes past the beginning of the file; modifying rather than
+     * replacing may need `flags: 'r+'` instead of the default `'r'`.
      */
     createWriteStream(options?: CreateWriteStreamOptions): WriteStream;
-    /**
-     * Forces all currently queued I/O operations associated with the file to the
-     * operating system's synchronized I/O completion state. Refer to the POSIX [`fdatasync(2)`](http://man7.org/linux/man-pages/man2/fdatasync.2.html) documentation for details.
-     *
-     * Unlike `filehandle.sync` this method does not flush modified metadata.
-     * @since v10.0.0
-     * @return Fulfills with `undefined` upon success.
-     */
+    /** [`fdatasync(2)`](http://man7.org/linux/man-pages/man2/fdatasync.2.html) —
+     *  unlike `sync()` this does not flush modified metadata. */
     datasync(): Promise<void>;
-    /**
-     * Request that all data for the open file descriptor is flushed to the storage
-     * device. The specific implementation is operating system and device specific.
-     * Refer to the POSIX [`fsync(2)`](http://man7.org/linux/man-pages/man2/fsync.2.html) documentation for more detail.
-     * @since v10.0.0
-     * @return Fufills with `undefined` upon success.
-     */
+    /** [`fsync(2)`](http://man7.org/linux/man-pages/man2/fsync.2.html). */
     sync(): Promise<void>;
     /**
-     * Reads data from the file and stores that in the given buffer.
+     * Read into `buffer`. Absent concurrent modification, EOF is `bytesRead === 0`.
      *
-     * If the file is not modified concurrently, the end-of-file is reached when the
-     * number of bytes read is zero.
-     * @since v10.0.0
-     * @param buffer A buffer that will be filled with the file data read.
-     * @param offset The location in the buffer at which to start filling.
-     * @param length The number of bytes to read.
-     * @param position The location where to begin reading data from the file. If `null`, data will be read from the current file position, and the position will be updated. If `position` is an
-     * integer, the current file position will remain unchanged.
-     * @return Fulfills upon success with an object with two properties:
+     * A `null` `position` reads from the current file position AND advances it; an
+     * integer leaves the position unchanged.
      */
     read<T extends NodeJS.ArrayBufferView>(buffer: T, offset?: number | null, length?: number | null, position?: ReadPosition | null): Promise<FileReadResult<T>>;
     read<T extends NodeJS.ArrayBufferView = Buffer>(options?: FileReadOptions<T>): Promise<FileReadResult<T>>;
     /**
-     * Returns a `ReadableStream` that may be used to read the files data.
-     *
-     * An error will be thrown if this method is called more than once or is called after the `FileHandle` is closed
-     * or closing.
-     *
-     * ```js
-     * import { open } from 'node:fs/promises';
-     *
-     * const file = await open('./some/file/to/read');
-     *
-     * for await (const chunk of file.readableWebStream())
-     *   console.log(chunk);
-     *
-     * await file.close();
-     * ```
+     * INCOMPLETE. Node returns a `ReadableStream` over the file's bytes and throws
+     * on a second call or a closed handle; this returns a SOURCELESS stream that
+     * yields nothing, and enforces neither rule. Reading the file needs a source
+     * wired to `_readCore` — until then prefer `createReadStream()`.
      *
-     * While the `ReadableStream` will read the file to completion, it will not close the `FileHandle` automatically. User code must still call the `fileHandle.close()` method.
-     *
-     * @since v17.0.0
-     * @experimental
+     * Node also never closes the handle for you: user code still calls `close()`.
      */
     readableWebStream(): ReadableStream;
     /**
-     * Asynchronously reads the entire contents of a file.
-     *
-     * If `options` is a string, then it specifies the `encoding`.
-     *
-     * The `FileHandle` has to support reading.
-     *
-     * If one or more `filehandle.read()` calls are made on a file handle and then a`filehandle.readFile()` call is made, the data will be read from the current
-     * position till the end of the file. It doesn't always read from the beginning
-     * of the file.
-     * @since v10.0.0
-     * @return Fulfills upon a successful read with the contents of the file. If no encoding is specified (using `options.encoding`), the data is returned as a {Buffer} object. Otherwise, the
-     * data will be a string.
+     * Read from the CURRENT position to EOF — not from the beginning, so earlier
+     * `read()` calls on this handle move the starting point. The handle must have
+     * been opened for reading, and is not closed for you.
      */
     readFile(options?: {
         encoding?: null | undefined;
         flag?: OpenMode | undefined;
     } | null): Promise<Buffer<ArrayBuffer>>;
-    /**
-     * Asynchronously reads the entire contents of a file. The underlying file will _not_ be closed automatically.
-     * The `FileHandle` must have been opened for reading.
-     * @param options An object that may contain an optional flag.
-     * If a flag is not provided, it defaults to `'r'`.
-     */
     readFile(options: {
         encoding: BufferEncoding;
         flag?: OpenMode | undefined;
     } | BufferEncoding): Promise<string>;
-    /**
-     * Convenience method to create a `readline` interface and stream over the file. For example:
-     *
-     * ```js
-     * import { open } from 'node:fs/promises';
-     *
-     * const file = await open('./some/file/to/read');
-     *
-     * for await (const line of file.readLines()) {
-     *   console.log(line);
-     * }
-     * ```
-     *
-     * @since v18.11.0
-     * @param options See `filehandle.createReadStream()` for the options.
-     */
+    /** A `readline` interface over the file; `options` are `createReadStream()`'s. */
     readLines(options?: CreateReadStreamOptions): ReadlineInterface;
-    /**
-     * @since v10.0.0
-     * @return Fulfills with an {fs.Stats} for the file.
-     */
     stat(opts?: StatOptions & {
         bigint?: false | undefined;
     }): Promise<Stats>;
@@ -313,75 +147,25 @@ export declare class FileHandle implements IFileHandle {
         bigint: true;
     }): Promise<BigIntStats>;
     /**
-     * Truncates the file.
-     *
-     * If the file was larger than `len` bytes, only the first `len` bytes will be
-     * retained in the file.
-     *
-     * The following example retains only the first four bytes of the file:
-     *
-     * ```js
-     * import { open } from 'node:fs/promises';
-     *
-     * let filehandle = null;
-     * try {
-     *   filehandle = await open('temp.txt', 'r+');
-     *   await filehandle.truncate(4);
-     * } finally {
-     *   await filehandle?.close();
-     * }
-     * ```
-     *
-     * If the file previously was shorter than `len` bytes, it is extended, and the
-     * extended part is filled with null bytes (`'\0'`):
-     *
-     * If `len` is negative then `0` will be used.
-     * @since v10.0.0
-     * @param [len=0]
-     * @return Fulfills with `undefined` upon success.
+     * Keep only the first `len` bytes, or extend with NUL bytes when the file was
+     * shorter. A negative `len` is treated as 0.
      */
     truncate(len?: number): Promise<void>;
-    /**
-     * Change the file system timestamps of the object referenced by the `FileHandle` then resolves the promise with no arguments upon success.
-     * @since v10.0.0
-     */
+    /** Change the file system timestamps of the referenced object. */
     utimes(atime: string | number | Date, mtime: string | number | Date): Promise<void>;
     /**
-     * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an
-     * [AsyncIterable](https://tc39.github.io/ecma262/#sec-asynciterable-interface) or
-     * [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol) object.
-     * The promise is resolved with no arguments upon success.
-     *
-     * If `options` is a string, then it specifies the `encoding`.
-     *
-     * The `FileHandle` has to support writing.
-     *
-     * It is unsafe to use `filehandle.writeFile()` multiple times on the same file
-     * without waiting for the promise to be resolved (or rejected).
-     *
-     * If one or more `filehandle.write()` calls are made on a file handle and then a`filehandle.writeFile()` call is made, the data will be written from the
-     * current position till the end of the file. It doesn't always write from the
-     * beginning of the file.
-     * @since v10.0.0
+     * Write from the CURRENT position to the end — not from the beginning, so
+     * earlier `write()` calls on this handle move the starting point. Unsafe to
+     * call again before the promise settles.
      */
     writeFile(data: string | Uint8Array, options?: (ObjectEncodingOptions & FlagAndOpenMode & Abortable) | BufferEncoding | null): Promise<void>;
     /**
-     * Write `buffer` to the file.
-     *
-     * The promise is resolved with an object containing two properties:
-     *
-     * It is unsafe to use `filehandle.write()` multiple times on the same file
-     * without waiting for the promise to be resolved (or rejected). For this
-     * scenario, use `filehandle.createWriteStream()`.
+     * Write `buffer` at `position`, or at the current position when `position` is
+     * not a number (POSIX pwrite(2)). Unsafe to call again before the promise
+     * settles — use `createWriteStream()` for that.
      *
-     * On Linux, positional writes do not work when the file is opened in append mode.
-     * The kernel ignores the position argument and always appends the data to
-     * the end of the file.
-     * @since v10.0.0
-     * @param [offset=0] The start position from within `buffer` where the data to write begins.
-     * @param [length=buffer.byteLength - offset] The number of bytes from `buffer` to write.
-     * @param position The offset from the beginning of the file where the data from `buffer` should be written. If `position` is not a `number`, the data will be written at the current position.
-     * See the POSIX pwrite(2) documentation for more detail.
+     * On Linux a positional write is IGNORED on an append-mode file: the kernel
+     * always appends.
      */
     write<TBuffer extends NodeJS.ArrayBufferView>(buffer: TBuffer, offset?: number | null, length?: number | null, position?: number | null): Promise<{
         bytesWritten: number;
@@ -400,27 +184,12 @@ export declare class FileHandle implements IFileHandle {
         buffer: string;
     }>;
     /**
-     * Write an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s to the file.
-     *
-     * The promise is resolved with an object containing a two properties:
-     *
-     * It is unsafe to call `writev()` multiple times on the same file without waiting
-     * for the promise to be resolved (or rejected).
-     *
-     * On Linux, positional writes don't work when the file is opened in append mode.
-     * The kernel ignores the position argument and always appends the data to
-     * the end of the file.
-     * @since v12.9.0
-     * @param position The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current
-     * position.
+     * Write several views in sequence. `position` is where the FIRST one lands, the
+     * current position when it is not a number; unsafe to call again before the
+     * promise settles. As with `write()`, Linux ignores it in append mode.
      */
     writev<TBuffers extends readonly NodeJS.ArrayBufferView[]>(buffers: TBuffers, position?: number): Promise<WriteVResult<TBuffers>>;
-    /**
-     * Read from a file and write to an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s
-     * @since v13.13.0, v12.17.0
-     * @param position The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position.
-     * @return Fulfills upon success an object containing two properties:
-     */
+    /** Fill several views in sequence, from `position` or the current position. */
     readv<TBuffers extends readonly NodeJS.ArrayBufferView[]>(buffers: TBuffers, position?: number): Promise<ReadVResult<TBuffers>>;
     /** @internal */ _flushSync(): void;
     /** @internal */ _closeSync(): void;

package/lib/types/sync.d.ts

@@ -17,19 +17,17 @@ export declare function readdirSync(path: PathLike, options?: {
 /**
  * POSIX `realpath(3)`: resolve EVERY component, not merely a trailing symlink.
  *
- * This used to `query_info` the path once and return it UNCHANGED whenever the
- * LEAF was not a symlink, so a symlinked ANCESTOR survived into the result. On a
- * typical Linux box that is invisible — `/tmp` is a real directory, so the
- * identity answer happens to be the right one. On macOS `/var` is a symlink to
- * `private/var`, so `realpathSync(os.tmpdir())` returned `/var/folders/…` while a
- * child process asked for its own cwd reported `/private/var/folders/…`. That
- * surfaced as six `@gjsify/child_process` cwd failures on main's macOS leg — the
- * only leg that runs it, macOS being off for pull requests. The platform was
- * incidental: reproduced on Linux with nothing but a symlinked parent directory.
+ * Checking only the LEAF lets a symlinked ANCESTOR survive into the result, which is
+ * invisible on a typical Linux box — `/tmp` is a real directory, so the identity
+ * answer is accidentally right. On macOS `/var` is a symlink to `private/var`, so
+ * `realpathSync(os.tmpdir())` answered `/var/folders/…` while the child process
+ * asked for its own cwd reported `/private/var/folders/…`: six
+ * `@gjsify/child_process` cwd failures on main's macOS leg, the only leg that runs
+ * it. The platform was incidental — a symlinked parent directory reproduces it on
+ * Linux.
  *
- * The symlink budget is shared across the whole walk because POSIX counts total
- * resolutions rather than per-component ones, so a cycle reachable through any
- * component still terminates.
+ * The symlink budget is shared across the whole walk because POSIX counts TOTAL
+ * resolutions, not per-component ones, so a cycle through any component terminates.
  */
 export declare function realpathSync(path: PathLike): string;
 export declare function symlinkSync(target: PathLike, path: PathLike, _type?: 'file' | 'dir' | 'junction'): void;
@@ -38,39 +36,21 @@ export declare function readFileSync(path: PathLike | number | FileHandle, optio
     flag?: string;
 } | string | null): string | Buffer<ArrayBuffer>;
 /**
- * Synchronously creates a directory. Returns `undefined`, or if `recursive` is`true`, the first directory path created.
- * This is the synchronous version of {@link mkdir}.
- *
- * See the POSIX [`mkdir(2)`](http://man7.org/linux/man-pages/man2/mkdir.2.html) documentation for more details.
- * @since v0.1.21
+ * [`mkdir(2)`](http://man7.org/linux/man-pages/man2/mkdir.2.html). Returns the FIRST
+ * directory created under `recursive: true`, otherwise `undefined`. A string mode is
+ * parsed as octal; the default is `0o777`.
  */
 export declare function mkdirSync(path: PathLike, options: MakeDirectoryOptions & {
     recursive: true;
 }): string | undefined;
-/**
- * Synchronous mkdir(2) - create a directory.
- * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
- * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders
- * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`.
- */
 export declare function mkdirSync(path: PathLike, options?: Mode | (MakeDirectoryOptions & {
     recursive?: false | undefined;
 }) | null): void;
-/**
- * Synchronous mkdir(2) - create a directory.
- * @param path A path to a file. If a URL is provided, it must use the `file:` protocol.
- * @param options Either the file mode, or an object optionally specifying the file mode and whether parent folders
- * should be created. If a string is passed, it is parsed as an octal integer. If not specified, defaults to `0o777`.
- */
 export declare function mkdirSync(path: PathLike, options?: Mode | MakeDirectoryOptions | null): string | undefined | void;
 /**
- * Synchronous [`rmdir(2)`](http://man7.org/linux/man-pages/man2/rmdir.2.html). Returns `undefined`.
- *
- * Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT` error
- * on Windows and an `ENOTDIR` error on POSIX.
- *
- * To get a behavior similar to the `rm -rf` Unix command, use {@link rmSync} with options `{ recursive: true, force: true }`.
- * @since v0.1.21
+ * [`rmdir(2)`](http://man7.org/linux/man-pages/man2/rmdir.2.html) — empty directories
+ * only; `rm -rf` behaviour is {@link rmSync} with `{ recursive: true, force: true }`.
+ * On a FILE this is ENOTDIR on POSIX but ENOENT on Windows.
  */
 export declare function rmdirSync(path: PathLike, _options?: RmDirOptions): void;
 export declare function unlinkSync(path: PathLike): void;
@@ -99,47 +79,25 @@ export declare function watch(filename: PathLike, options: {
 } | undefined, listener: ((eventType: string, filename: string | null) => void) | undefined): FSWatcher;
 export declare function openSync(path: PathLike, flags?: OpenFlags | number, mode?: Mode): FileHandle;
 /**
- * Returns the created directory path.
- *
- * For detailed information, see the documentation of the asynchronous version of
- * this API: {@link mkdtemp}.
- *
- * The optional `options` argument can be a string specifying an encoding, or an
- * object with an `encoding` property specifying the character encoding to use.
- * @since v5.10.0
+ * Create a unique temporary directory: six random characters appended to `prefix`.
+ * Returns its path, encoded per `options` (default `'utf8'`).
  */
 export declare function mkdtempSync(prefix: string, options?: EncodingOption): string;
-/**
- * Synchronously creates a unique temporary directory.
- * Generates six random characters to be appended behind a required prefix to create a unique temporary directory.
- * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
- */
 export declare function mkdtempSync(prefix: string, options: BufferEncodingOption): Buffer;
-/**
- * Synchronously creates a unique temporary directory.
- * Generates six random characters to be appended behind a required prefix to create a unique temporary directory.
- * @param options The encoding (or an object specifying the encoding), used as the encoding of the result. If not provided, `'utf8'` is used.
- */
 export declare function mkdtempSync(prefix: string, options?: EncodingOption): string | Buffer;
 /**
  * `mkdtemp(3)`: claim a unique name and create it 0700, atomically.
  *
- * TWO defects lived in the four lines this replaces. It asked `mkdirSync` for
- * `mode: 0o777` — inert while `mode` was ignored, and a WORLD-READABLE
- * directory the moment `mode` started working, from the one API whose whole
- * purpose is a private scratch space. And it picked the name with
- * `while (existsSync(path))`, a test-then-create whose `existsSync` was
- * `Gio.File.query_exists()` — true for a dangling symlink, and racy against
- * any other process regardless. `mkdir(2)` decides both questions in one
- * syscall: it fails EEXIST if the name is taken, so the loop retries instead
- * of guessing.
+ * The mode is not negotiable — this is the one API whose whole purpose is a PRIVATE
+ * scratch space, and 0o777 hands it to everyone. Nor is the atomicity: a
+ * `while (existsSync(path))` test-then-create is racy against any other process, and
+ * `existsSync` is `Gio.File.query_exists()`, true even for a dangling symlink.
+ * `mkdir(2)` answers both in one syscall, failing EEXIST on a taken name, so the loop
+ * retries rather than guesses.
  *
- * Both entry points call THIS, so `mkdtempSync` and `promises.mkdtemp` cannot
- * disagree on the mode again — they already did, by 0o077.
+ * Both entry points call THIS so `mkdtempSync` and `promises.mkdtemp` cannot disagree
+ * on the mode — they once did, by 0o077.
  */
 export declare function mkdtempAt(prefix: string): string;
-/**
- * Synchronously removes files and directories (modeled on the standard POSIX `rm`utility). Returns `undefined`.
- * @since v14.14.0
- */
+/** Remove files and directories, modelled on POSIX `rm`. */
 export declare function rmSync(path: PathLike, options?: RmOptions): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/fs",
-    "version": "0.35.0",
+    "version": "0.37.0",
     "description": "Node.js fs module for Gjs",
     "module": "lib/esm/index.js",
     "types": "lib/types/index.d.ts",
@@ -66,8 +66,8 @@
         "fs"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.35.0",
-        "@gjsify/unit": "^0.35.0",
+        "@gjsify/cli": "^0.37.0",
+        "@gjsify/unit": "^0.37.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
@@ -75,11 +75,11 @@
         "@girs/gio-2.0": "^4.1.0",
         "@girs/giounix-2.0": "^4.1.0",
         "@girs/glib-2.0": "^4.1.0",
-        "@gjsify/buffer": "^0.35.0",
-        "@gjsify/events": "^0.35.0",
-        "@gjsify/stream": "^0.35.0",
-        "@gjsify/url": "^0.35.0",
-        "@gjsify/utils": "^0.35.0"
+        "@gjsify/buffer": "^0.37.0",
+        "@gjsify/events": "^0.37.0",
+        "@gjsify/stream": "^0.37.0",
+        "@gjsify/url": "^0.37.0",
+        "@gjsify/utils": "^0.37.0"
     },
     "gjsify": {
         "runtimes": {