@gjsify/fs 0.30.0 → 0.32.0

package/lib/types/sync.d.ts

@@ -33,7 +33,7 @@ export declare function readdirSync(path: PathLike, options?: {
  */
 export declare function realpathSync(path: PathLike): string;
 export declare function symlinkSync(target: PathLike, path: PathLike, _type?: 'file' | 'dir' | 'junction'): void;
-export declare function readFileSync(path: PathLike | number, options?: {
+export declare function readFileSync(path: PathLike | number | FileHandle, options?: {
     encoding?: string | null;
     flag?: string;
 } | string | null): string | Buffer<ArrayBuffer>;
@@ -74,15 +74,17 @@ export declare function mkdirSync(path: PathLike, options?: Mode | MakeDirectory
  */
 export declare function rmdirSync(path: PathLike, _options?: RmDirOptions): void;
 export declare function unlinkSync(path: PathLike): void;
-export declare function writeFileSync(path: PathLike, data: string | Uint8Array): void;
+/** The `{ encoding, mode, flag }` bag `writeFileSync` / `appendFileSync` accept. */
+type WriteFileOptions = {
+    encoding?: string | null;
+    mode?: Mode;
+    flag?: OpenFlags | string;
+} | string | null;
+export declare function writeFileSync(path: PathLike | number | FileHandle, data: string | Uint8Array, options?: WriteFileOptions): void;
 export declare function renameSync(oldPath: PathLike, newPath: PathLike): void;
 export declare function copyFileSync(src: PathLike, dest: PathLike, mode?: number): void;
 export declare function accessSync(path: PathLike, mode?: number): void;
-export declare function appendFileSync(path: PathLike, data: string | Uint8Array, _options?: {
-    encoding?: string;
-    mode?: number;
-    flag?: string;
-} | string): void;
+export declare function appendFileSync(path: PathLike | number | FileHandle, data: string | Uint8Array, options?: WriteFileOptions): void;
 export declare function readlinkSync(path: PathLike, options?: {
     encoding?: string;
 } | string): string | Buffer;
@@ -119,6 +121,23 @@ export declare function mkdtempSync(prefix: string, options: BufferEncodingOptio
  * @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.
+ *
+ * Both entry points call THIS, so `mkdtempSync` and `promises.mkdtemp` cannot
+ * disagree on the mode again — they already 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

package/lib/types/utils.d.ts

@@ -1,4 +1,3 @@
 import type { PathLike } from 'node:fs';
 export declare function normalizePath(path: PathLike): string;
 export declare function randomName(): string;
-export declare function tempDirPath(prefix: string): string;

package/lib/types/utimes.d.ts

@@ -8,6 +8,10 @@ export declare function lutimesAsync(path: PathLike, atime: TimeLike, mtime: Tim
 export declare function lchownSync(path: PathLike, uid: number, gid: number): void;
 export declare function lchown(path: PathLike, uid: number, gid: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
 export declare function lchownAsync(path: PathLike, uid: number, gid: number): Promise<void>;
-export declare function lchmodSync(_path: PathLike, _mode: number): void;
-export declare function lchmod(_path: PathLike, _mode: number, callback: (err: NodeJS.ErrnoException | null) => void): void;
+export declare const lchmodSync: ((path: PathLike, mode: number) => void) | undefined;
+export declare const lchmod: ((path: PathLike, mode: number, callback: (err: NodeJS.ErrnoException | null) => void) => void) | undefined;
+/**
+ * The one spelling Node defines on every platform — and it throws there too, so
+ * this is the only lchmod surface that keeps a body.
+ */
 export declare function lchmodAsync(_path: PathLike, _mode: number): Promise<void>;

package/lib/types/write-stream.d.ts

@@ -1,7 +1,36 @@
 import { Writable } from 'node:stream';
 import type { OpenFlags } from './types/index.js';
-import type { PathLike, WriteStream as IWriteStream } from 'node:fs';
+import type { Mode, PathLike, WriteStream as IWriteStream } from 'node:fs';
 import type { CreateWriteStreamOptions } from 'node:fs/promises';
+/**
+ * What `fs.createWriteStream()` accepts, as opposed to
+ * `filehandle.createWriteStream()`.
+ *
+ * `CreateWriteStreamOptions` is the fs/promises shape and carries only
+ * `encoding`/`autoClose`/`emitClose`/`start`/`highWaterMark` — which is
+ * precisely why `flags`, `mode` and `fd` were never read here: they are not in
+ * the type the constructor was written against.
+ */
+export type WriteStreamOptions = CreateWriteStreamOptions & {
+    flags?: OpenFlags | string;
+    mode?: Mode;
+    fd?: number | null;
+    /**
+     * @internal Set only by {@link FileHandle.createWriteStream}.
+     *
+     * A descriptor that came from a `FileHandle` is closed through the HANDLE
+     * in Node, and a handle's close is IDEMPOTENT — so a stream that finishes
+     * after the caller already closed the handle reports nothing (measured
+     * against v24.15.0: `errs=[]`). A raw `fd` handed to
+     * `createWriteStream(p, {fd})` is a real `close(2)`, and Node DOES surface
+     * its EBADF as an `'error'`. The two look identical from inside this class,
+     * which is why they are told apart here rather than both swallowed — or, as
+     * before this flag existed, both reported: that turned the ordinary
+     * `fh.createWriteStream(); …; await fh.close()` sequence into an
+     * `'error'` nobody listens for.
+     */
+    fdFromHandle?: boolean;
+};
 declare const kIsPerformingIO: unique symbol;
 export declare function toPathIfFileURL(fileURLOrPath: string | Buffer | URL): string;
 export declare class WriteStream extends Writable implements IWriteStream {
@@ -33,12 +62,24 @@ export declare class WriteStream extends Writable implements IWriteStream {
     fd: number | null;
     flags: OpenFlags;
     mode: number;
-    pos: number;
+    /**
+     * The offset the next chunk is written at, or `undefined` to ride the
+     * descriptor's own cursor — which is what Node does unless `start` is given.
+     *
+     * This was `pos = 0`, i.e. ALWAYS defined, so every chunk carried an
+     * explicit position. That is why a `{flags: 'a'}` stream could only ever
+     * rewrite the file from byte 0, and why `{start: n}` was silently ignored.
+     */
+    pos: number | undefined;
+    /** Whether this stream owns the descriptor and must close it. */
+    private _autoClose;
+    /** Whether the descriptor came from a FileHandle — see `fdFromHandle`. */
+    private _fdFromHandle;
     [kIsPerformingIO]: boolean;
-    constructor(path: PathLike, opts?: CreateWriteStreamOptions);
+    constructor(path: PathLike, opts?: WriteStreamOptions);
     _construct(callback: (err?: Error) => void): void;
     _write(data: Buffer, _encoding: string, cb: (err?: Error | null) => void): void;
     _destroy(err: Error, cb: (err?: Error | null) => void): void;
 }
-export declare function createWriteStream(path: string | Buffer, opts: CreateWriteStreamOptions): WriteStream;
+export declare function createWriteStream(path: string | Buffer, opts: WriteStreamOptions): WriteStream;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/fs",
-    "version": "0.30.0",
+    "version": "0.32.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.30.0",
-        "@gjsify/unit": "^0.30.0",
+        "@gjsify/cli": "^0.32.0",
+        "@gjsify/unit": "^0.32.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.30.0",
-        "@gjsify/events": "^0.30.0",
-        "@gjsify/stream": "^0.30.0",
-        "@gjsify/url": "^0.30.0",
-        "@gjsify/utils": "^0.30.0"
+        "@gjsify/buffer": "^0.32.0",
+        "@gjsify/events": "^0.32.0",
+        "@gjsify/stream": "^0.32.0",
+        "@gjsify/url": "^0.32.0",
+        "@gjsify/utils": "^0.32.0"
     },
     "gjsify": {
         "runtimes": {
@@ -88,6 +88,15 @@
             "browser": "partial",
             "nativescript": "none"
         },
+        "os": {
+            "linux": "supported",
+            "darwin": "partial",
+            "win32": "none"
+        },
+        "osNotes": {
+            "darwin": "The descriptor path is measured on Linux only. fstat/fchmod/ftruncate and the cursor read-back go through /proc/self/fd and /proc/self/fdinfo, which darwin does not have; fd-io.ts falls back to acting on the PATH there, and tellFd() to sizeOfFd(). Both fallbacks are gated on the measured CAN_PROC_FD capability rather than assumed, but no darwin host has run them — shipping an unmeasured darwin path is how the first cut of this work shipped a broken umask probe. The O_* table in posix-flags.ts carries darwin values (O_CREAT 0x200 collides with Linux O_TRUNC, which is why it is host-keyed at all) and those are equally unexercised: prebuilds.yml runs no darwin leg for this package.",
+            "win32": "Not attempted. The implementation is POSIX open(2)/mkdir(2) semantics with real O_CREAT|O_EXCL, an fd-owned cursor and mode-at-creation; win32 has no procfs, no POSIX mode bits and different open flags. The WIN32 branch in posix-flags.ts exists so the table is total, not because the package works there — the fs specs already carry `it.failing({ when: isWin32() })` rows saying the same."
+        },
         "tier": 1
     },
     "license": "MIT",

package/lib/esm/file-handle-open.js

@@ -1 +0,0 @@
-import"./_virtual/_rolldown/runtime.js";import e from"@girs/glib-2.0";import{createGLibFileError as t}from"@gjsify/utils/core";function resolveIOMode(e){if(e==null)return`r`;if(typeof e==`number`){let t=(e&2)!=0,n=(e&1)!=0,r=(e&1024)!=0,i=(e&512)!=0;return t?i?`w+`:`r+`:n?r?`a`:`w`:`r`}switch(e){case`ax`:case`wx`:return`w`;case`ax+`:case`wx+`:return`w+`;case`as`:case`rs+`:return`r+`;case`as+`:return`a+`;default:return e}}function shouldCreate(e){return typeof e==`number`?(e&64)!=0:typeof e==`string`?e===`w`||e===`w+`||e===`wx`||e===`wx+`||e===`a`||e===`a+`||e===`ax`||e===`ax+`||e===`as`||e===`as+`:!1}function openIOChannel(t,n,r){try{return e.IOChannel.new_file(t,n)}catch(i){if(r&&n===`r+`&&i?.code===e.FileError.NOENT)return e.file_set_contents(t,new Uint8Array),e.IOChannel.new_file(t,n);throw i}}function mapOpenError(e,n){return t(e,`open`,{path:n})}export{mapOpenError,openIOChannel,resolveIOMode,shouldCreate};

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

@@ -1,25 +0,0 @@
-import GLib from '@girs/glib-2.0';
-import type { OpenFlags } from './types/index.js';
-/** fopen(3)-style IOChannel mode. */
-export type IOMode = 'r' | 'r+' | 'w' | 'w+' | 'a' | 'a+';
-/**
- * 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+'.
- */
-export declare function resolveIOMode(flags: OpenFlags | number | undefined): IOMode;
-/** Whether the open flags include `O_CREAT` (create-if-missing semantics). */
-export declare function shouldCreate(flags: OpenFlags | number | undefined): boolean;
-/**
- * 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.
- */
-export declare function openIOChannel(path: string, mode: IOMode, creat: boolean): GLib.IOChannel;
-/**
- * Wrap a `GLib.IOChannel.new_file()` failure as a Node `ErrnoException`.
- * GLib's IOChannel throws GLib.FileError (not Gio.IOErrorEnum) on this path,
- * so we route through `createGLibFileError` to get the right errno + code.
- */
-export declare function mapOpenError(err: unknown, path: string): NodeJS.ErrnoException;