feat: deprecate Deno.fstat() and Deno.fstatSync() (#22068)

For removal in Deno v2.

cli/tests/unit_node/_fs/_fs_fstat_test.ts

@@ -18,7 +18,7 @@ Deno.test({
     })
       .then(
         (stat) => {
-          assertStats(stat, Deno.fstatSync(file.rid));
+          assertStats(stat, file.statSync());
         },
         () => fail(),
       )
@@ -45,7 +45,7 @@ Deno.test({
       );
     })
       .then(
-        (stat) => assertStatsBigInt(stat, Deno.fstatSync(file.rid)),
+        (stat) => assertStatsBigInt(stat, file.statSync()),
         () => fail(),
       )
       .finally(() => {
@@ -61,7 +61,7 @@ Deno.test({
     using file = Deno.openSync(filePath);
 
     try {
-      assertStats(fstatSync(file.rid), Deno.fstatSync(file.rid));
+      assertStats(fstatSync(file.rid), file.statSync());
     } finally {
       Deno.removeSync(filePath);
     }
@@ -75,10 +75,14 @@ Deno.test({
     using file = Deno.openSync(filePath);
 
     try {
+      // HEAD
+      assertStatsBigInt(fstatSync(file.rid, { bigint: true }), file.statSync());
+      //
       assertStatsBigInt(
         fstatSync(file.rid, { bigint: true }),
         Deno.fstatSync(file.rid),
       );
+      //main
     } finally {
       Deno.removeSync(filePath);
     }

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

@@ -5448,6 +5448,9 @@ declare namespace Deno {
    * assert(fileInfo.isFile);
    * ```
    *
+   * @deprecated Use `file.stat()` instead.
+   * {@linkcode Deno.fstat} will be removed in Deno 2.0.
+   *
    * @category File System
    */
   export function fstat(rid: number): Promise<FileInfo>;
@@ -5464,6 +5467,9 @@ declare namespace Deno {
    * assert(fileInfo.isFile);
    * ```
    *
+   * @deprecated Use `file.statSync()` instead.
+   * {@linkcode Deno.fstatSync} will be removed in Deno 2.0.
+   *
    * @category File System
    */
   export function fstatSync(rid: number): FileInfo;

ext/node/polyfills/_fs/_fs_fstat.ts

@@ -11,6 +11,7 @@ import {
   statOptions,
   Stats,
 } from "ext:deno_node/_fs/_fs_stat.ts";
+import { FsFile } from "ext:deno_fs/30_fs.js";
 
 export function fstat(fd: number, callback: statCallback): void;
 export function fstat(
@@ -40,7 +41,7 @@ export function fstat(
 
   if (!callback) throw new Error("No callback function supplied");
 
-  Deno.fstat(fd).then(
+  new FsFile(fd).stat().then(
     (stat) => callback(null, CFISBIS(stat, options.bigint)),
     (err) => callback(err),
   );
@@ -59,6 +60,6 @@ export function fstatSync(
   fd: number,
   options?: statOptions,
 ): Stats | BigIntStats {
-  const origin = Deno.fstatSync(fd);
+  const origin = new FsFile(fd).statSync();
   return CFISBIS(origin, options?.bigint || false);
 }

runtime/js/90_deno_ns.js

@@ -209,8 +209,22 @@ const denoNs = {
     );
     net.shutdown(rid);
   },
-  fstatSync: fs.fstatSync,
-  fstat: fs.fstat,
+  fstatSync(rid) {
+    internals.warnOnDeprecatedApi(
+      "Deno.fstatSync()",
+      new Error().stack,
+      "Use `Deno.FsFile.statSync()` instead.",
+    );
+    return fs.fstatSync(rid);
+  },
+  fstat(rid) {
+    internals.warnOnDeprecatedApi(
+      "Deno.fstat()",
+      new Error().stack,
+      "Use `Deno.FsFile.stat()` instead.",
+    );
+    return fs.fstat(rid);
+  },
   fsyncSync(rid) {
     internals.warnOnDeprecatedApi(
       "Deno.fsyncSync()",