@gjsify/fs 0.1.15 → 0.2.0

package/src/file-handle.ts

@@ -1,13 +1,16 @@
 // Reference: Node.js lib/internal/fs/promises.js (FileHandle)
 // Reimplemented for GJS using Gio.File
 
-import { warnNotImplemented, notImplemented } from '@gjsify/utils';
+import { warnNotImplemented, notImplemented, createGLibFileError } from '@gjsify/utils';
 import { ReadStream } from "./read-stream.js";
 import { WriteStream } from "./write-stream.js";
-import { Stats } from "./stats.js";
+import { Stats, BigIntStats, STAT_ATTRIBUTES } from "./stats.js";
 import { getEncodingFromOptions, encodeUint8Array } from './encoding.js';
+import { normalizePath } from './utils.js';
+import { chmodSync, chownSync } from './sync.js';
 import GLib from '@girs/glib-2.0';
 import Gio from '@girs/gio-2.0';
+import { createInterface } from 'node:readline';
 // Type-only import for ReadableStream — the runtime constructor is resolved
 // via globalThis inside readableWebStream() to avoid bundling the entire
 // WHATWG streams implementation for apps that never call this method.
@@ -28,51 +31,69 @@ import type {
     OpenMode,
     PathLike,
     StatOptions,
-    BigIntStats,
     WriteVResult,
     ReadVResult,
     ReadPosition,
 } from 'node:fs';
 import type { Interface as ReadlineInterface } from 'node:readline';
 
+// POSIX numeric open(2) flags (values on Linux x86-64).
+const O_WRONLY = 1;
+const O_RDWR   = 2;
+const O_CREAT  = 64;
+const O_TRUNC  = 512;
+const O_APPEND = 1024;
+
+type IOMode = 'r' | 'r+' | 'w' | 'w+' | 'a' | 'a+';
+
 /**
- * GLib.FileError enum numeric values → Node.js error code strings.
- * GLib.IOChannel.new_file() throws GLib.FileError (different from Gio.IOErrorEnum).
+ * Convert open flags (Node.js string or POSIX numeric) to a GLib.IOChannel mode.
+ * IOChannel.new_file() takes fopen(3) modes: 'r', 'r+', 'w', 'w+', 'a', 'a+'.
  */
-const GLIB_FILE_ERROR_TO_NODE: Record<number, string> = {
-    0:  'EEXIST',
-    1:  'EISDIR',
-    2:  'EACCES',
-    3:  'ENAMETOOLONG',
-    4:  'ENOENT',
-    5:  'ENOTDIR',
-    6:  'ENXIO',
-    7:  'ENODEV',
-    8:  'EROFS',
-    11: 'ELOOP',
-    12: 'ENOSPC',
-    13: 'ENOMEM',
-    14: 'EMFILE',
-    15: 'ENFILE',
-    16: 'EBADF',
-    17: 'EINVAL',
-    18: 'EPIPE',
-    21: 'EIO',
-    22: 'EPERM',
-    24: 'EIO',
-};
+function resolveIOMode(flags: OpenFlags | number | undefined): IOMode {
+    if (flags === undefined || flags === null) return 'r';
+    if (typeof flags === 'number') {
+        const rdwr   = (flags & O_RDWR)   !== 0;
+        const wronly = (flags & O_WRONLY) !== 0;
+        const append = (flags & O_APPEND) !== 0;
+        const trunc  = (flags & O_TRUNC)  !== 0;
+        if (rdwr)   return trunc ? 'w+' : 'r+';
+        if (wronly) return append ? 'a' : 'w';
+        return 'r';
+    }
+    // Node.js string flags — map extras to IOChannel equivalents.
+    switch (flags) {
+        case 'ax': case 'wx':   return 'w';
+        case 'ax+': case 'wx+': return 'w+';
+        case 'as': case 'rs+':  return 'r+';
+        case 'as+':             return 'a+';
+        default:                return flags as IOMode;
+    }
+}
+
+/**
+ * Open the file with the given IOChannel mode. When the flags request
+ * create-if-missing + read/write without truncation (numeric O_CREAT | O_RDWR,
+ * which maps to IOChannel 'r+' — a mode that requires the file to exist), we
+ * catch the ENOENT and create an empty file, then retry. This avoids a TOCTOU
+ * existence check and keeps the common "file exists" path to a single syscall.
+ */
+function openIOChannel(path: string, mode: IOMode, creat: boolean): GLib.IOChannel {
+    try {
+        return GLib.IOChannel.new_file(path, mode);
+    } catch (err) {
+        const gErr = err as { code?: number } | null | undefined;
+        if (creat && mode === 'r+' && gErr?.code === GLib.FileError.NOENT) {
+            GLib.file_set_contents(path, new Uint8Array(0));
+            return GLib.IOChannel.new_file(path, mode);
+        }
+        throw err;
+    }
+}
 
 function mapOpenError(err: unknown, path: string): NodeJS.ErrnoException {
-    const gErr = err as { code?: number; message?: string } | null | undefined;
-    const msg = gErr?.message ?? '';
     // GLib.IOChannel.new_file() always throws GLib.FileError (not Gio.IOErrorEnum).
-    // GLIB_FILE_ERROR_TO_NODE maps GLib.FileError numeric values to Node.js codes.
-    const code = GLIB_FILE_ERROR_TO_NODE[gErr?.code ?? -1] ?? 'EIO';
-    const error = new Error(`${code}: ${msg || 'unknown error'}, open '${path}'`) as NodeJS.ErrnoException;
-    error.code = code;
-    error.syscall = 'open';
-    error.path = path;
-    return error;
+    return createGLibFileError(err, 'open', { path }) as NodeJS.ErrnoException;
 }
 
 export class FileHandle implements IFileHandle {
@@ -80,29 +101,104 @@ export class FileHandle implements IFileHandle {
     /** Not part of the default implementation, used internal by gjsify */
     private _file: GLib.IOChannel;
 
+    /**
+     * Lazily-opened Gio streams for positional read() / write() so each call does
+     * not re-load the entire file via Gio.File.load_contents(). The IOStream is
+     * used when the handle was opened with write capability (r+, w, w+, a, a+) —
+     * it shares seek state between input and output so writes are visible to
+     * subsequent reads without a flush. For read-only handles we only open a
+     * FileInputStream; trying to open_readwrite on a read-only file can fall
+     * back to create_readwrite(REPLACE_DESTINATION) which would truncate it.
+     */
+    private _ioStream: Gio.FileIOStream | null = null;
+    private _readStream: Gio.FileInputStream | null = null;
+    private readonly _gFile: Gio.File;
+    private readonly _ioMode: IOMode;
+    // Serialize async I/O on the shared FileIOStream. Concurrent write_bytes_async
+    // calls hit Gio.IOErrorEnum.PENDING ("Datenstrom hat noch einen ausstehenden
+    // Vorgang"); overlapping seek()s on the shared cursor also corrupt positions.
+    // random-access-file (used by fs-chunk-store / webtorrent) issues many
+    // concurrent positional writes, so every async op on this handle chains
+    // through _ioLock.
+    private _ioLock: Promise<unknown> = Promise.resolve();
+
     /** Not part of the default implementation, used internal by gjsify */
     private static instances: {[fd: number]: FileHandle} = {};
 
     constructor(readonly options: {
         path: PathLike,
-        flags?: OpenFlags,
+        flags?: OpenFlags | number,
         mode?: Mode
     }) {
         this.options.flags ||= "r";
         this.options.mode ||= 0o666;
+        const pathStr = normalizePath(options.path);
+        const creat = typeof options.flags === 'number' && (options.flags & O_CREAT) !== 0;
+        const ioMode = resolveIOMode(options.flags);
         try {
-            this._file = GLib.IOChannel.new_file(options.path.toString(), this.options.flags);
+            this._file = openIOChannel(pathStr, ioMode, creat);
         } catch (err: unknown) {
-            throw mapOpenError(err, options.path.toString());
+            throw mapOpenError(err, pathStr);
         }
         // Binary mode: prevent GLib from doing any character set conversion.
         this._file.set_encoding(null as unknown as string);
         this.fd = this._file.unix_get_fd();
+        this._gFile = Gio.File.new_for_path(pathStr);
+        this._ioMode = ioMode;
 
         FileHandle.instances[this.fd] = this;
         return FileHandle.getInstance(this.fd);
     }
 
+    /**
+     * Lazy-open the read-capable stream and return both the input stream and
+     * its seekable view. Both FileInputStream (read-only handle) and
+     * FileIOStream (read/write handle) implement Gio.Seekable, but we return
+     * both to avoid callers needing to know which concrete type they got.
+     */
+    private _getReadStream(): { input: Gio.InputStream; seekable: Gio.Seekable } {
+        if (this._ioStream) {
+            return {
+                input: this._ioStream.get_input_stream(),
+                seekable: this._ioStream as unknown as Gio.Seekable,
+            };
+        }
+        if (this._ioMode === 'r') {
+            if (!this._readStream) this._readStream = this._gFile.read(null);
+            return {
+                input: this._readStream,
+                seekable: this._readStream as unknown as Gio.Seekable,
+            };
+        }
+        // open_readwrite requires the file to exist. For modes that imply
+        // create-if-missing (w, w+, a, a+) the IOChannel already created it
+        // above; for 'r+' openIOChannel() catches ENOENT and pre-creates it.
+        this._ioStream = this._gFile.open_readwrite(null);
+        return {
+            input: this._ioStream.get_input_stream(),
+            seekable: this._ioStream as unknown as Gio.Seekable,
+        };
+    }
+
+    /** Lazy-open the write-capable stream (IOStream) for this handle. Only valid
+     *  when the handle was opened with a write-capable mode. */
+    private _getWriteStream(): Gio.FileIOStream {
+        if (this._ioStream) return this._ioStream;
+        if (this._ioMode === 'r') {
+            throw new Error('FileHandle opened read-only; cannot write');
+        }
+        this._ioStream = this._gFile.open_readwrite(null);
+        return this._ioStream;
+    }
+
+    /** Serialize an async operation on the shared FileIOStream. */
+    private _serialize<T>(op: () => Promise<T>): Promise<T> {
+        const prev = this._ioLock;
+        const next = prev.catch(() => {}).then(op);
+        this._ioLock = next;
+        return next;
+    }
+
 
     /**
      * The numeric file descriptor managed by the {FileHandle} object.
@@ -150,7 +246,7 @@ export class FileHandle implements IFileHandle {
      * @return Fulfills with `undefined` upon success.
      */
     async chown(uid: number, gid: number): Promise<void> {
-        warnNotImplemented('fs.FileHandle.chown');
+        chownSync(normalizePath(this.options.path), uid, gid);
     }
     /**
      * Modifies the permissions on the file. See [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html).
@@ -159,7 +255,7 @@ export class FileHandle implements IFileHandle {
      * @return Fulfills with `undefined` upon success.
      */
     async chmod(mode: Mode): Promise<void> {
-        warnNotImplemented('fs.FileHandle.chmod');
+        chmodSync(normalizePath(this.options.path), mode);
     }
     /**
      * Unlike the 16 kb default `highWaterMark` for a `stream.Readable`, the stream
@@ -245,7 +341,7 @@ export class FileHandle implements IFileHandle {
      * @return Fulfills with `undefined` upon success.
      */
     async datasync(): Promise<void> {
-        warnNotImplemented('fs.FileHandle.datasync');
+        this._file.flush();
     }
     /**
      * Request that all data for the open file descriptor is flushed to the storage
@@ -255,7 +351,7 @@ export class FileHandle implements IFileHandle {
      * @return Fufills with `undefined` upon success.
      */
     async sync(): Promise<void> {
-        warnNotImplemented('fs.FileHandle.sync');
+        this._file.flush();
     }
     /**
      * Reads data from the file and stores that in the given buffer.
@@ -295,24 +391,25 @@ export class FileHandle implements IFileHandle {
         const bufView = buffer as unknown as Uint8Array;
         const bufOffset = offset ?? 0;
         const readLength = length ?? bufView?.byteLength ?? 65536;
-
-        // Use Gio.File.load_contents for reliable position-based reads.
-        // GLib.IOChannel.read_chars() is not introspectable in GJS (caller-allocated buffer),
-        // and read_to_end() has stdio-buffer visibility issues after mixed write/read.
-        const gFile = Gio.File.new_for_path(this.options.path.toString());
-        const [, fileContents] = gFile.load_contents(null);
-        const fileData = fileContents as Uint8Array;
         const startPos = (position as number | null) ?? 0;
-        const readData = fileData.slice(startPos, startPos + readLength);
-        const bytesRead = readData.length;
-        if (bufView && bytesRead > 0) {
-            bufView.set(readData, bufOffset);
-        }
 
-        return {
-            bytesRead,
-            buffer: buffer as T,
-        };
+        // Positional read — seek + read_bytes on the appropriate Gio stream,
+        // touching only the requested region. Replaces the old load_contents()
+        // path that read the entire file on every call (O(N²) over streamed
+        // workloads like WebTorrent piece hashing or random-access-file).
+        // Serialized with writes: seek() on the shared FileIOStream cursor must
+        // not interleave with a pending write_bytes_async.
+        return this._serialize(async () => {
+            const { input, seekable } = this._getReadStream();
+            seekable.seek(BigInt(startPos), GLib.SeekType.SET, null);
+            const bytes = input.read_bytes(readLength, null);
+            const data = bytes.get_data() as Uint8Array | null;
+            const bytesRead = data?.length ?? 0;
+            if (bufView && data && bytesRead > 0) {
+                bufView.set(data, bufOffset);
+            }
+            return { bytesRead, buffer: buffer as T };
+        });
     }
     /**
      * Returns a `ReadableStream` that may be used to read the files data.
@@ -426,7 +523,7 @@ export class FileHandle implements IFileHandle {
      * @param options See `filehandle.createReadStream()` for the options.
      */
     readLines(options?: CreateReadStreamOptions): ReadlineInterface {
-        notImplemented('fs.FileHandle.readLines');
+        return createInterface({ input: this.createReadStream(options), crlfDelay: Infinity });
     }
     /**
      * @since v10.0.0
@@ -443,8 +540,15 @@ export class FileHandle implements IFileHandle {
         }
     ): Promise<BigIntStats>
     async stat(opts?: StatOptions): Promise<Stats | BigIntStats> {
-        warnNotImplemented('fs.FileHandle.stat');
-        return new Stats(this.options.path.toString());
+        const info = await new Promise<Gio.FileInfo>((resolve, reject) => {
+            this._gFile.query_info_async(STAT_ATTRIBUTES, Gio.FileQueryInfoFlags.NONE, GLib.PRIORITY_DEFAULT, null, (_s: unknown, res: Gio.AsyncResult) => {
+                try { resolve(this._gFile.query_info_finish(res)); } catch (e) { reject(e); }
+            });
+        });
+        const pathStr = normalizePath(this.options.path);
+        return opts?.bigint
+            ? new BigIntStats(info, pathStr)
+            : new Stats(info, pathStr);
     }
     /**
      * Truncates the file.
@@ -477,18 +581,18 @@ export class FileHandle implements IFileHandle {
     async truncate(len: number = 0): Promise<void> {
         const effectiveLen = Math.max(0, len);
         this._file.flush();
-        const gFile = Gio.File.new_for_path(this.options.path.toString());
-        const [, currentContent] = gFile.load_contents(null);
-        const newContent = new Uint8Array(effectiveLen);
-        newContent.set(currentContent.slice(0, Math.min(effectiveLen, currentContent.length)));
-        gFile.replace_contents(newContent, null, false, Gio.FileCreateFlags.NONE, null);
+        // Gio.FileOutputStream implements Seekable.truncate — extends with zeros
+        // when growing, matches POSIX ftruncate(2).
+        const out = this._getWriteStream().get_output_stream() as Gio.FileOutputStream;
+        out.truncate(effectiveLen, null);
     }
     /**
      * 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
      */
     async utimes(atime: string | number | Date, mtime: string | number | Date): Promise<void> {
-        warnNotImplemented('fs.FileHandle.utimes');
+        const { utimesSync } = await import('./utimes.js');
+        utimesSync(normalizePath(this.options.path), atime, mtime);
     }
     /**
      * Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an
@@ -600,25 +704,32 @@ export class FileHandle implements IFileHandle {
         const writeSlice = writeBuf.slice(bufOffset, bufOffset + writeLength);
         const writePos = position ?? 0;
 
-        // Use Gio.File for reliable position-based writes.
-        // GLib.IOChannel write_chars + flush does not guarantee data is visible to
-        // subsequent Gio.File or g_file_get_contents readers (stdio-buffer flushing issue).
-        const gFile = Gio.File.new_for_path(this.options.path.toString());
-        let existingData: Uint8Array;
-        try {
-            const [, existing] = gFile.load_contents(null);
-            existingData = existing as Uint8Array;
-        } catch {
-            existingData = new Uint8Array(0);
-        }
-        const newSize = Math.max(existingData.length, writePos + writeSlice.length);
-        const newContent = new Uint8Array(newSize);
-        newContent.set(existingData);
-        newContent.set(writeSlice, writePos);
-        gFile.replace_contents(newContent, null, false, Gio.FileCreateFlags.NONE, null);
+        // Positional write — seek + write_bytes_async on the IOStream, touches
+        // only the requested region. Uses async Gio I/O so the GLib main loop
+        // (and GTK events) are not blocked during the write. Serialized via
+        // _serialize() so concurrent callers (e.g. random-access-file) don't
+        // trigger GIO_ERROR_PENDING or corrupt the shared seek cursor.
+        const bytesWritten = await this._serialize(async () => {
+            const stream = this._getWriteStream();
+            stream.seek(BigInt(writePos), GLib.SeekType.SET, null);
+            const output = stream.get_output_stream();
+            const written = await new Promise<number>((resolve, reject) => {
+                output.write_bytes_async(new GLib.Bytes(writeSlice), GLib.PRIORITY_DEFAULT, null, (_source, asyncResult) => {
+                    try { resolve(output.write_bytes_finish(asyncResult)); }
+                    catch (err) { reject(err); }
+                });
+            });
+            await new Promise<void>((resolve, reject) => {
+                output.flush_async(GLib.PRIORITY_DEFAULT, null, (_source, asyncResult) => {
+                    try { output.flush_finish(asyncResult); resolve(); }
+                    catch (err) { reject(err); }
+                });
+            });
+            return written;
+        });
 
         return {
-            bytesWritten: writeSlice.length,
+            bytesWritten,
             buffer: data
         }
     }
@@ -640,11 +751,16 @@ export class FileHandle implements IFileHandle {
      * position.
      */
     async writev<TBuffers extends readonly NodeJS.ArrayBufferView[]>(buffers: TBuffers, position?: number): Promise<WriteVResult<TBuffers>> {
-        warnNotImplemented('fs.FileHandle.writev');
-        return {
-            bytesWritten: 0,
-            buffers: buffers as unknown as TBuffers,
+        let bytesWritten = 0;
+        for (const buf of buffers) {
+            const b = Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength);
+            const res = await this.write(
+                b, 0, b.byteLength,
+                position != null ? position + bytesWritten : null,
+            );
+            bytesWritten += res.bytesWritten;
         }
+        return { bytesWritten, buffers: buffers as unknown as TBuffers };
     }
     /**
      * Read from a file and write to an array of [ArrayBufferView](https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView) s
@@ -653,12 +769,57 @@ export class FileHandle implements IFileHandle {
      * @return Fulfills upon success an object containing two properties:
      */
     async readv<TBuffers extends readonly NodeJS.ArrayBufferView[]>(buffers: TBuffers, position?: number): Promise<ReadVResult<TBuffers>> {
-        warnNotImplemented('fs.FileHandle.readv');
-        return {
-            bytesRead: 0,
-            buffers: buffers as unknown as TBuffers,
+        let bytesRead = 0;
+        for (const buf of buffers) {
+            const res = await this.read({
+                buffer: Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength),
+                position: position != null ? position + bytesRead : null,
+            });
+            bytesRead += res.bytesRead;
+            if (res.bytesRead < buf.byteLength) break;
         }
+        return { bytesRead, buffers: buffers as unknown as TBuffers };
     }
+    /** @internal */ _flushSync(): void {
+        this._file.flush();
+    }
+
+    /** @internal */ _closeSync(): void {
+        try { this._ioStream?.close(null); } catch { /* best-effort */ }
+        try { this._readStream?.close(null); } catch { /* best-effort */ }
+        this._ioStream = null;
+        this._readStream = null;
+        try { this._file.shutdown(true); } catch { /* best-effort */ }
+        delete (FileHandle as any).instances[this.fd];
+    }
+
+    /** @internal */ _readSync(buffer: NodeJS.ArrayBufferView, offset: number, length: number, position: number | null): number {
+        const stream = this._gFile.read(null);
+        try {
+            if (position !== null && position >= 0) {
+                (stream as unknown as Gio.Seekable).seek(position, GLib.SeekType.SET, null);
+            }
+            const bytes = stream.read_bytes(length, null);
+            const arr = bytes.get_data()!;
+            new Uint8Array((buffer as any).buffer, (buffer as any).byteOffset + offset).set(arr.subarray(0, arr.length));
+            return arr.length;
+        } finally {
+            stream.close(null);
+        }
+    }
+
+    /** @internal */ _writeSync(data: Uint8Array, position: number | null): number {
+        const stream = this._gFile.open_readwrite(null);
+        try {
+            if (position !== null && position >= 0) {
+                (stream as unknown as Gio.Seekable).seek(position, GLib.SeekType.SET, null);
+            }
+            return stream.get_output_stream().write_bytes(GLib.Bytes.new(data), null);
+        } finally {
+            stream.close(null);
+        }
+    }
+
     /**
      * Closes the file handle after waiting for any pending operation on the handle to
      * complete.
@@ -677,7 +838,16 @@ export class FileHandle implements IFileHandle {
      * @return Fulfills with `undefined` upon success.
      */
     async close(): Promise<void> {
-        this._file.shutdown(true);
+        // Close the Gio streams first; they own an fd wrapping the same file
+        // as the IOChannel. IOChannel.shutdown(true) flushes + closes its own
+        // fd — safe to call even if the Gio streams already released theirs,
+        // but guarded here so a throw from shutdown doesn't strand the stream
+        // references in a "closed but still pinned" state.
+        try { this._ioStream?.close(null); } catch { /* best-effort */ }
+        try { this._readStream?.close(null); } catch { /* best-effort */ }
+        this._ioStream = null;
+        this._readStream = null;
+        try { this._file.shutdown(true); } catch { /* best-effort */ }
     }
 
     async [Symbol.asyncDispose](): Promise<void> {

package/src/fs-watcher.ts

@@ -4,20 +4,22 @@
 import GLib from '@girs/glib-2.0';
 import Gio from '@girs/gio-2.0';
 import { EventEmitter } from 'node:events';
+import { normalizePath } from './utils.js';
 const privates = new WeakMap;
 
-import type { FSWatcher as IFSWatcher } from 'node:fs';
+import type { FSWatcher as IFSWatcher, PathLike, WatchOptions } from 'node:fs';
 
 export class FSWatcher extends EventEmitter implements IFSWatcher {
 
-  constructor(filename: string, options, listener) {
+  constructor(filename: PathLike, options, listener) {
     super();
     if (!options || typeof options !== 'object')
       options = {persistent: true};
 
     const persistent = options.persistent !== false;
     const cancellable = Gio.Cancellable.new();
-    const file = Gio.File.new_for_path(filename);
+    const pathStr = normalizePath(filename);
+    const file = Gio.File.new_for_path(pathStr);
     const watcher = file.monitor(Gio.FileMonitorFlags.NONE, cancellable);
     watcher.connect('changed', changed.bind(this));
 
@@ -28,7 +30,11 @@ export class FSWatcher extends EventEmitter implements IFSWatcher {
     if (persistent) {
       // Add a never-firing timeout source to keep the mainloop alive.
       // This is a lightweight way to hold a ref on the main context.
-      sourceId = GLib.timeout_add(GLib.PRIORITY_LOW, 2147483647, () => GLib.SOURCE_CONTINUE);
+      sourceId = (GLib.timeout_add as unknown as (priority: number, interval: number, fn: () => boolean) => number)(
+        GLib.PRIORITY_LOW,
+        2147483647,
+        () => GLib.SOURCE_CONTINUE,
+      );
     }
 
     privates.set(this, {
@@ -62,7 +68,11 @@ export class FSWatcher extends EventEmitter implements IFSWatcher {
     const priv = privates.get(this);
     if (!priv.persistent && !priv.cancellable.is_cancelled()) {
       priv.persistent = true;
-      priv.sourceId = GLib.timeout_add(GLib.PRIORITY_LOW, 2147483647, () => GLib.SOURCE_CONTINUE);
+      priv.sourceId = (GLib.timeout_add as unknown as (priority: number, interval: number, fn: () => boolean) => number)(
+        GLib.PRIORITY_LOW,
+        2147483647,
+        () => GLib.SOURCE_CONTINUE,
+      );
     }
     return this;
   }
@@ -100,4 +110,89 @@ function changed(watcher, file, otherFile, eventType) {
   }
 }
 
-export default FSWatcher;
+export default FSWatcher;
+
+// ─── fs.promises.watch ────────────────────────────────────────────────────────
+
+type WatchEvent = { eventType: string; filename: string | null };
+
+function gioEventToNodeType(eventType: Gio.FileMonitorEvent): string | null {
+  switch (eventType) {
+    case Gio.FileMonitorEvent.CHANGES_DONE_HINT: return 'change';
+    case Gio.FileMonitorEvent.DELETED:
+    case Gio.FileMonitorEvent.CREATED:
+    case Gio.FileMonitorEvent.RENAMED:
+    case Gio.FileMonitorEvent.MOVED_IN:
+    case Gio.FileMonitorEvent.MOVED_OUT: return 'rename';
+    default: return null;
+  }
+}
+
+export async function* watchAsync(
+  filename: PathLike,
+  options?: WatchOptions & { signal?: AbortSignal },
+): AsyncIterableIterator<WatchEvent> {
+  const signal = (options as any)?.signal as AbortSignal | undefined;
+
+  if (signal?.aborted) return;
+
+  const pathStr = normalizePath(filename);
+  const file = Gio.File.new_for_path(pathStr);
+  const cancellable = Gio.Cancellable.new();
+
+  let watcher: Gio.FileMonitor;
+  try {
+    watcher = file.monitor(Gio.FileMonitorFlags.NONE, cancellable);
+  } catch {
+    return;
+  }
+
+  const eventQueue: WatchEvent[] = [];
+  const waiterQueue: Array<{ resolve: (r: IteratorResult<WatchEvent>) => void }> = [];
+  let finished = false;
+
+  function enqueue(event: WatchEvent): void {
+    if (finished) return;
+    if (waiterQueue.length > 0) {
+      waiterQueue.shift()!.resolve({ value: event, done: false });
+    } else {
+      eventQueue.push(event);
+    }
+  }
+
+  function terminate(): void {
+    if (finished) return;
+    finished = true;
+    if (!cancellable.is_cancelled()) cancellable.cancel();
+    while (waiterQueue.length > 0) {
+      waiterQueue.shift()!.resolve({ value: undefined as any, done: true });
+    }
+  }
+
+  const signalId = watcher.connect('changed', (_mon: Gio.FileMonitor, changedFile: Gio.File, _otherFile: Gio.File | null, eventType: Gio.FileMonitorEvent) => {
+    const type = gioEventToNodeType(eventType);
+    if (type === null) return;
+    enqueue({ eventType: type, filename: changedFile?.get_basename() ?? null });
+  });
+
+  const abortHandler = () => terminate();
+  signal?.addEventListener('abort', abortHandler);
+
+  try {
+    while (!finished) {
+      if (eventQueue.length > 0) {
+        yield eventQueue.shift()!;
+        continue;
+      }
+      const result = await new Promise<IteratorResult<WatchEvent>>(resolve => {
+        waiterQueue.push({ resolve });
+      });
+      if (result.done) break;
+      yield result.value;
+    }
+  } finally {
+    signal?.removeEventListener('abort', abortHandler);
+    try { watcher.disconnect(signalId); } catch {}
+    if (!cancellable.is_cancelled()) cancellable.cancel();
+  }
+}