feat(fs/unstable): add open, openSync, and FsFile class

_tools/node_test_runner/run_test.mjs

@@ -48,12 +48,14 @@ import "../../collections/union_test.ts";
 import "../../collections/unzip_test.ts";
 import "../../collections/without_all_test.ts";
 import "../../collections/zip_test.ts";
+import "../../fs/_node_fs_file_test.ts";
 import "../../fs/unstable_chown_test.ts";
 import "../../fs/unstable_copy_file_test.ts";
 import "../../fs/unstable_link_test.ts";
 import "../../fs/unstable_make_temp_dir_test.ts";
 import "../../fs/unstable_make_temp_file_test.ts";
 import "../../fs/unstable_mkdir_test.ts";
+import "../../fs/unstable_open_test.ts";
 import "../../fs/unstable_read_dir_test.ts";
 import "../../fs/unstable_read_file_test.ts";
 import "../../fs/unstable_read_link_test.ts";

fs/_get_fs_flag.ts

@@ -2,12 +2,18 @@
 
 import { getNodeFs } from "./_utils.ts";
 import type { WriteFileOptions } from "./unstable_types.ts";
+import type { OpenOptions } from "./unstable_open.ts";
 
 type WriteBooleanOptions = Pick<
   WriteFileOptions,
   "append" | "create" | "createNew"
 >;
 
+type OpenBooleanOptions = Pick<
+  OpenOptions,
+  "read" | "write" | "append" | "truncate" | "create" | "createNew"
+>;
+
 /**
  * Uses the boolean options specified in {@linkcode WriteFileOptions} to
  * construct the composite flag value to pass to the `flag` option in the
@@ -31,3 +37,74 @@
   }
   return flag;
 }
+
+/**
+ * Uses the boolean options specified in {@linkcode OpenOptions} to construct the
+ * composite flag value to pass to the `flag` option in the Node.js `open`
+ * function.
+ */
+export function getOpenFsFlag(opt: OpenBooleanOptions): number {
+  const { O_APPEND, O_CREAT, O_EXCL, O_WRONLY, O_RDONLY, O_RDWR, O_TRUNC } =
+    getNodeFs().constants;
+
+  if (
+    !opt.read && !opt.write && !opt.append && !opt.truncate && !opt.create &&
+    !opt.createNew
+  ) {
+    throw new Error("'options' requires at least one option to be true");
+  }
+
+  if (!opt.write && opt.truncate) {
+    throw new Error("'truncate' option requires 'write' to be true");
+  }
+
+  if ((opt.create || opt.createNew) && !(opt.write || opt.append)) {
+    throw new Error(
+      "'create' or 'createNew' options require 'write' or 'append' to be true",
+    );
+  }
+
+  // This error is added to match the Deno runtime. Deno throws a `TypeError`
+  // (os error 22) for this OpenOption combo. Under Node.js, the bitmask
+  // combinations of (O_RDWR | O_TRUNC | O_APPEND) and
+  // (O_WRONLY | O_TRUNC | O_APPEND) to open files are valid.
+  if (opt.write && opt.append && opt.truncate) {
+    throw new TypeError("Invalid argument.");
+  }
+
+  let flag = O_RDONLY;
+  if (opt.read && !opt.write) {
+    flag |= O_RDONLY;
+  }
+
+  if (opt.read && opt.write) {
+    flag |= O_RDWR;
+  }
+
+  if (!opt.read && opt.write) {
+    flag |= O_WRONLY;
+  }
+
+  if (opt.create || opt.createNew) {
+    flag |= O_CREAT;
+  }
+
+  if (opt.createNew) {
+    flag |= O_EXCL;
+  }
+
+  if (opt.append) {
+    flag |= O_APPEND;
+    if (!opt.read) {
+      flag |= O_WRONLY;
+    } else {
+      flag |= O_RDWR;
+    }
+  }
+
+  if (opt.truncate) {
+    flag |= O_TRUNC;
+  }
+
+  return flag;
+}

fs/_node_fs_file.ts

@@ -0,0 +1,217 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+
+import { getNodeFs, getNodeStream, getNodeTty, getNodeUtil } from "./_utils.ts";
+import { mapError } from "./_map_error.ts";
+import type { FileInfo, FsFile, SetRawOptions } from "./unstable_types.ts";
+import { toFileInfo } from "./_to_file_info.ts";
+
+/**
+ * The internal class to convert a Node file descriptor into a FsFile object.
+ */
+export class NodeFsFile implements FsFile {
+  #nodeFs = getNodeFs();
+  #nodeStream = getNodeStream();
+  #nodeTty = getNodeTty();
+  #nodeUtil = getNodeUtil();
+  #nodeReadFd = this.#nodeUtil.promisify(this.#nodeFs.read);
+  #nodeWriteFd = this.#nodeUtil.promisify(this.#nodeFs.write);
+
+  #closed: boolean;
+  #rid: number;
+  #readableStream?: ReadableStream<Uint8Array>;
+  #writableStream?: WritableStream<Uint8Array>;
+
+  constructor(fd: number) {
+    this.#rid = fd;
+    this.#closed = false;
+  }
+
+  get readable(): ReadableStream<Uint8Array> {
+    if (this.#readableStream == null) {
+      const readStream = this.#nodeFs.createReadStream(null as unknown, {
+        fd: this.#rid,
+        autoClose: false,
+      });
+      this.#readableStream = this.#nodeStream.Readable.toWeb(readStream);
+    }
+    return this.#readableStream as ReadableStream;
+  }
+
+  get writable(): WritableStream<Uint8Array> {
+    if (this.#writableStream == null) {
+      const writeStream = this.#nodeFs.createWriteStream(null as unknown, {
+        fd: this.#rid,
+        autoClose: false,
+      });
+      this.#writableStream = this.#nodeStream.Writable.toWeb(writeStream);
+    }
+    return this.#writableStream as WritableStream;
+  }
+
+  [Symbol.dispose](): void {
+    if (!this.#closed) {
+      this.close();
+    }
+  }
+
+  close(): void {
+    this.#closed = true;
+    this.#nodeFs.closeSync(this.#rid);
+  }
+
+  isTerminal(): boolean {
+    return this.#nodeTty.isatty(this.#rid);
+  }
+
+  // deno-lint-ignore require-await no-unused-vars
+  async lock(exclusive?: boolean): Promise<void> {
+    throw new Error("Method not implemented.");
+  }
+
+  // deno-lint-ignore no-unused-vars
+  lockSync(exclusive?: boolean): void {
+    throw new Error("Method not implemented.");
+  }
+
+  async read(p: Uint8Array): Promise<number | null> {
+    try {
+      const { bytesRead } = await this.#nodeReadFd(
+        this.#rid,
+        p,
+        0,
+        p.length,
+        null,
+      );
+      return bytesRead === 0 ? null : bytesRead;
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  readSync(p: Uint8Array): number | null {
+    try {
+      const bytesRead = this.#nodeFs.readSync(this.#rid, p);
+      return bytesRead === 0 ? null : bytesRead;
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  //deno-lint-ignore no-unused-vars
+  setRaw(mode: boolean, options?: SetRawOptions): void {
+    throw new Error("Method not implemented.");
+  }
+
+  async stat(): Promise<FileInfo> {
+    const nodeStatFd = this.#nodeUtil.promisify(this.#nodeFs.fstat);
+    try {
+      const fdStat = await nodeStatFd(this.#rid);
+      return toFileInfo(fdStat);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  statSync(): FileInfo {
+    try {
+      const fdStat = this.#nodeFs.fstatSync(this.#rid);
+      return toFileInfo(fdStat);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  async sync(): Promise<void> {
+    const nodeFsyncFd = this.#nodeUtil.promisify(this.#nodeFs.fsync);
+    try {
+      await nodeFsyncFd(this.#rid);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  syncSync(): void {
+    try {
+      this.#nodeFs.fsyncSync(this.#rid);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  async syncData(): Promise<void> {
+    const nodeFdatasyncFd = this.#nodeUtil.promisify(this.#nodeFs.fdatasync);
+    try {
+      await nodeFdatasyncFd(this.#rid);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  syncDataSync(): void {
+    try {
+      this.#nodeFs.fdatasyncSync(this.#rid);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  async truncate(len?: number): Promise<void> {
+    const nodeTruncateFd = this.#nodeUtil.promisify(this.#nodeFs.ftruncate);
+    try {
+      await nodeTruncateFd(this.#rid, len);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  truncateSync(len?: number): void {
+    try {
+      this.#nodeFs.ftruncateSync(this.#rid, len);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  // deno-lint-ignore require-await
+  async unlock(): Promise<void> {
+    throw new Error("Method not implemented.");
+  }
+
+  unlockSync(): void {
+    throw new Error("Method not implemented.");
+  }
+
+  async utime(atime: number | Date, mtime: number | Date): Promise<void> {
+    const nodeUtimeFd = this.#nodeUtil.promisify(this.#nodeFs.futimes);
+    try {
+      await nodeUtimeFd(this.#rid, atime, mtime);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  utimeSync(atime: number | Date, mtime: number | Date): void {
+    try {
+      this.#nodeFs.futimesSync(this.#rid, atime, mtime);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  async write(p: Uint8Array): Promise<number> {
+    try {
+      const { bytesWritten } = await this.#nodeWriteFd(this.#rid, p);
+      return bytesWritten;
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+
+  writeSync(p: Uint8Array): number {
+    try {
+      return this.#nodeFs.writeSync(this.#rid, p);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+}