feat: deprecate Deno.FsFile constructor and Deno.FsFile.rid (#22072)

cli/tsc/dts/lib.deno.ns.d.ts

@@ -2299,8 +2299,13 @@ declare namespace Deno {
       SeekerSync,
       Closer,
       Disposable {
-    /** The resource ID associated with the file instance. The resource ID
+    /**
-     * should be considered an opaque reference to resource. */
+     * The resource ID associated with the file instance. The resource ID
+     * should be considered an opaque reference to resource.
+     *
+     * @deprecated Use {@linkcode Deno.FsFile} instance methods instead.
+     * {@linkcode Deno.FsFile.rid} will be removed in Deno 2.0.
+     */
     readonly rid: number;
     /** A {@linkcode ReadableStream} instance representing to the byte contents
      * of the file. This makes it easy to interoperate with other web streams
@@ -2330,9 +2335,15 @@ declare namespace Deno {
      * ```
      */
     readonly writable: WritableStream<Uint8Array>;
-    /** The constructor which takes a resource ID. Generally `FsFile` should
+    /**
+     * The constructor which takes a resource ID. Generally `FsFile` should
      * not be constructed directly. Instead use {@linkcode Deno.open} or
-     * {@linkcode Deno.openSync} to create a new instance of `FsFile`. */
+     * {@linkcode Deno.openSync} to create a new instance of `FsFile`.
+     *
+     * @deprecated Use {@linkcode Deno.open} or {@linkcode Deno.openSync}
+     * instead. {@linkcode Deno.FsFile.constructor} will be removed in Deno
+     * 2.0.
+     */
     constructor(rid: number);
     /** Write the contents of the array buffer (`p`) to the file.
      *

ext/fs/30_fs.js

@@ -670,85 +670,90 @@ class FsFile {
   }
 
   get rid() {
+    internals.warnOnDeprecatedApi(
+      "Deno.FsFile.rid",
+      new Error().stack,
+      "Use `Deno.FsFile` methods directly instead.",
+    );
     return this.#rid;
   }
 
   write(p) {
-    return write(this.rid, p);
+    return write(this.#rid, p);
   }
 
   writeSync(p) {
-    return writeSync(this.rid, p);
+    return writeSync(this.#rid, p);
   }
 
   truncate(len) {
-    return ftruncate(this.rid, len);
+    return ftruncate(this.#rid, len);
   }
 
   truncateSync(len) {
-    return ftruncateSync(this.rid, len);
+    return ftruncateSync(this.#rid, len);
   }
 
   read(p) {
-    return read(this.rid, p);
+    return read(this.#rid, p);
   }
 
   readSync(p) {
-    return readSync(this.rid, p);
+    return readSync(this.#rid, p);
   }
 
   seek(offset, whence) {
-    return seek(this.rid, offset, whence);
+    return seek(this.#rid, offset, whence);
   }
 
   seekSync(offset, whence) {
-    return seekSync(this.rid, offset, whence);
+    return seekSync(this.#rid, offset, whence);
   }
 
   stat() {
-    return fstat(this.rid);
+    return fstat(this.#rid);
   }
 
   statSync() {
-    return fstatSync(this.rid);
+    return fstatSync(this.#rid);
   }
 
   async dataSync() {
-    await op_fs_fdatasync_async(this.rid);
+    await op_fs_fdatasync_async(this.#rid);
   }
 
   dataSyncSync() {
-    op_fs_fdatasync_sync(this.rid);
+    op_fs_fdatasync_sync(this.#rid);
   }
 
   close() {
-    core.close(this.rid);
+    core.close(this.#rid);
   }
 
   get readable() {
     if (this.#readable === undefined) {
-      this.#readable = readableStreamForRid(this.rid);
+      this.#readable = readableStreamForRid(this.#rid);
     }
     return this.#readable;
   }
 
   get writable() {
     if (this.#writable === undefined) {
-      this.#writable = writableStreamForRid(this.rid);
+      this.#writable = writableStreamForRid(this.#rid);
     }
     return this.#writable;
   }
 
   async sync() {
-    await op_fs_fsync_async(this.rid);
+    await op_fs_fsync_async(this.#rid);
   }
 
   syncSync() {
-    op_fs_fsync_sync(this.rid);
+    op_fs_fsync_sync(this.#rid);
   }
 
   [SymbolDispose]() {
-    core.tryClose(this.rid);
+    core.tryClose(this.#rid);
   }
 }
 

ext/node/polyfills/_fs/_fs_readFile.ts

@@ -18,6 +18,7 @@ import {
   Encodings,
   TextEncodings,
 } from "ext:deno_node/_utils.ts";
+import { FsFile } from "ext:deno_fs/30_fs.js";
 
 function maybeDecode(data: Uint8Array, encoding: TextEncodings): string;
 function maybeDecode(
@@ -72,7 +73,7 @@ export function readFile(
 
   let p: Promise<Uint8Array>;
   if (path instanceof FileHandle) {
-    const fsFile = new Deno.FsFile(path.fd);
+    const fsFile = new FsFile(path.fd);
     p = readAll(fsFile);
   } else {
     p = Deno.readFile(path);

ext/node/polyfills/_fs/_fs_writeFile.ts

@@ -24,6 +24,7 @@ import {
   validateStringAfterArrayBufferView,
 } from "ext:deno_node/internal/fs/utils.mjs";
 import { promisify } from "ext:deno_node/internal/util.mjs";
+import { FsFile } from "ext:deno_fs/30_fs.js";
 
 interface Writer {
   write(p: Uint8Array): Promise<number>;
@@ -73,7 +74,7 @@ export function writeFile(
   (async () => {
     try {
       file = isRid
-        ? new Deno.FsFile(pathOrRid as number)
+        ? new FsFile(pathOrRid as number)
         : await Deno.open(pathOrRid as string, openOptions);
 
       // ignore mode because it's not supported on windows
@@ -138,7 +139,7 @@ export function writeFileSync(
   let error: Error | null = null;
   try {
     file = isRid
-      ? new Deno.FsFile(pathOrRid as number)
+      ? new FsFile(pathOrRid as number)
       : Deno.openSync(pathOrRid as string, openOptions);
 
     // ignore mode because it's not supported on windows

runtime/js/90_deno_ns.js

@@ -31,6 +31,17 @@ import * as kv from "ext:deno_kv/01_db.ts";
 import * as cron from "ext:deno_cron/01_cron.ts";
 import * as webgpuSurface from "ext:deno_webgpu/02_surface.js";
 
+class FsFile extends fs.FsFile {
+  constructor(rid) {
+    super(rid);
+    internals.warnOnDeprecatedApi(
+      "Deno.Fs",
+      new Error().stack,
+      "Use `Deno.open()` or `Deno.openSync()` instead.",
+    );
+  }
+}
+
 const denoNs = {
   metrics: core.metrics,
   Process: process.Process,
@@ -115,7 +126,7 @@ const denoNs = {
   write: io.write,
   writeSync: io.writeSync,
   File: fs.File,
-  FsFile: fs.FsFile,
+  FsFile,
   open: fs.open,
   openSync: fs.openSync,
   create: fs.create,