chore: use `FsFile[Symbol.dispose]()` (#22007)

This change takes advantage of explicit resources management for
`FsFile` instances and tweaks documentation to encourage the use of it.

---------

Signed-off-by: Asher Gomez <ashersaupingomez@gmail.com>

1 files changed, 25 insertions, 52 deletions

diff --git a/cli/tests/unit/files_test.ts b/cli/tests/unit/files_test.ts
index 0b9a104a8..977d6463d 100644
--- a/cli/tests/unit/files_test.ts
+++ b/cli/tests/unit/files_test.ts
@@ -18,17 +18,16 @@ Deno.test(function filesStdioFileDescriptors() {
 
 Deno.test({ permissions: { read: true } }, async function filesCopyToStdout() {
   const filename = "cli/tests/testdata/assets/fixture.json";
-  const file = await Deno.open(filename);
+  using file = await Deno.open(filename);
   assert(file.rid > 2);
   const bytesWritten = await copy(file, Deno.stdout);
   const fileSize = Deno.statSync(filename).size;
   assertEquals(bytesWritten, fileSize);
-  file.close();
 });
 
 Deno.test({ permissions: { read: true } }, async function filesIter() {
   const filename = "cli/tests/testdata/assets/hello.txt";
-  const file = await Deno.open(filename);
+  using file = await Deno.open(filename);
 
   let totalSize = 0;
   for await (const buf of Deno.iter(file)) {
@@ -36,14 +35,13 @@ Deno.test({ permissions: { read: true } }, async function filesIter() {
   }
 
   assertEquals(totalSize, 12);
-  file.close();
 });
 
 Deno.test(
   { permissions: { read: true } },
   async function filesIterCustomBufSize() {
     const filename = "cli/tests/testdata/assets/hello.txt";
-    const file = await Deno.open(filename);
+    using file = await Deno.open(filename);
 
     let totalSize = 0;
     let iterations = 0;
@@ -54,13 +52,12 @@ Deno.test(
 
     assertEquals(totalSize, 12);
     assertEquals(iterations, 2);
-    file.close();
   },
 );
 
 Deno.test({ permissions: { read: true } }, function filesIterSync() {
   const filename = "cli/tests/testdata/assets/hello.txt";
-  const file = Deno.openSync(filename);
+  using file = Deno.openSync(filename);
 
   let totalSize = 0;
   for (const buf of Deno.iterSync(file)) {
@@ -68,14 +65,13 @@ Deno.test({ permissions: { read: true } }, function filesIterSync() {
   }
 
   assertEquals(totalSize, 12);
-  file.close();
 });
 
 Deno.test(
   { permissions: { read: true } },
   function filesIterSyncCustomBufSize() {
     const filename = "cli/tests/testdata/assets/hello.txt";
-    const file = Deno.openSync(filename);
+    using file = Deno.openSync(filename);
 
     let totalSize = 0;
     let iterations = 0;
@@ -86,7 +82,6 @@ Deno.test(
 
     assertEquals(totalSize, 12);
     assertEquals(iterations, 2);
-    file.close();
   },
 );
 
@@ -166,12 +161,11 @@ Deno.test(
   },
   function openSyncMode() {
     const path = Deno.makeTempDirSync() + "/test_openSync.txt";
-    const file = Deno.openSync(path, {
+    using _file = Deno.openSync(path, {
       write: true,
       createNew: true,
       mode: 0o626,
     });
-    file.close();
     const pathInfo = Deno.statSync(path);
     if (Deno.build.os !== "windows") {
       assertEquals(pathInfo.mode! & 0o777, 0o626 & ~Deno.umask());
@@ -185,12 +179,11 @@ Deno.test(
   },
   async function openMode() {
     const path = (await Deno.makeTempDir()) + "/test_open.txt";
-    const file = await Deno.open(path, {
+    using _file = await Deno.open(path, {
       write: true,
       createNew: true,
       mode: 0o626,
     });
-    file.close();
     const pathInfo = Deno.statSync(path);
     if (Deno.build.os !== "windows") {
       assertEquals(pathInfo.mode! & 0o777, 0o626 & ~Deno.umask());
@@ -209,12 +202,11 @@ Deno.test(
         Deno.build.os === "windows" ? "/" : ""
       }${tempDir}/test_open.txt`,
     );
-    const file = Deno.openSync(fileUrl, {
+    using _file = Deno.openSync(fileUrl, {
       write: true,
       createNew: true,
       mode: 0o626,
     });
-    file.close();
     const pathInfo = Deno.statSync(fileUrl);
     if (Deno.build.os !== "windows") {
       assertEquals(pathInfo.mode! & 0o777, 0o626 & ~Deno.umask());
@@ -235,12 +227,11 @@ Deno.test(
         Deno.build.os === "windows" ? "/" : ""
       }${tempDir}/test_open.txt`,
     );
-    const file = await Deno.open(fileUrl, {
+    using _file = await Deno.open(fileUrl, {
       write: true,
       createNew: true,
       mode: 0o626,
     });
-    file.close();
     const pathInfo = Deno.statSync(fileUrl);
     if (Deno.build.os !== "windows") {
       assertEquals(pathInfo.mode! & 0o777, 0o626 & ~Deno.umask());
@@ -314,7 +305,7 @@ Deno.test(
       truncate: true,
       create: true,
     };
-    const file = await Deno.open(filename, w);
+    using file = await Deno.open(filename, w);
 
     // writing null should throw an error
     await assertRejects(
@@ -323,7 +314,6 @@ Deno.test(
         await file.write(null as any);
       },
     ); // TODO(bartlomieju): Check error kind when dispatch_minimal pipes errors properly
-    file.close();
     await Deno.remove(tempDir, { recursive: true });
   },
 );
@@ -333,7 +323,7 @@ Deno.test(
   async function readNullBufferFailure() {
     const tempDir = Deno.makeTempDirSync();
     const filename = tempDir + "hello.txt";
-    const file = await Deno.open(filename, {
+    using file = await Deno.open(filename, {
       read: true,
       write: true,
       truncate: true,
@@ -351,7 +341,6 @@ Deno.test(
     }, TypeError);
     // TODO(bartlomieju): Check error kind when dispatch_minimal pipes errors properly
 
-    file.close();
     await Deno.remove(tempDir, { recursive: true });
   },
 );
@@ -529,7 +518,7 @@ Deno.test(
     const filename = tempDir + "hello.txt";
     const data = encoder.encode("Hello world!\n");
 
-    const file = await Deno.open(filename, {
+    using file = await Deno.open(filename, {
       write: true,
       truncate: true,
       create: true,
@@ -551,7 +540,6 @@ Deno.test(
     assertEquals(seekPosition, cursorPosition);
     const result = await file.read(buf);
     assertEquals(result, 13);
-    file.close();
 
     await Deno.remove(tempDir, { recursive: true });
   },
@@ -559,7 +547,7 @@ Deno.test(
 
 Deno.test({ permissions: { read: true } }, async function seekStart() {
   const filename = "cli/tests/testdata/assets/hello.txt";
-  const file = await Deno.open(filename);
+  using file = await Deno.open(filename);
   const seekPosition = 6;
   // Deliberately move 1 step forward
   await file.read(new Uint8Array(1)); // "H"
@@ -571,12 +559,11 @@ Deno.test({ permissions: { read: true } }, async function seekStart() {
   await file.read(buf);
   const decoded = new TextDecoder().decode(buf);
   assertEquals(decoded, "world!");
-  file.close();
 });
 
 Deno.test({ permissions: { read: true } }, async function seekStartBigInt() {
   const filename = "cli/tests/testdata/assets/hello.txt";
-  const file = await Deno.open(filename);
+  using file = await Deno.open(filename);
   const seekPosition = 6n;
   // Deliberately move 1 step forward
   await file.read(new Uint8Array(1)); // "H"
@@ -588,12 +575,11 @@ Deno.test({ permissions: { read: true } }, async function seekStartBigInt() {
   await file.read(buf);
   const decoded = new TextDecoder().decode(buf);
   assertEquals(decoded, "world!");
-  file.close();
 });
 
 Deno.test({ permissions: { read: true } }, function seekSyncStart() {
   const filename = "cli/tests/testdata/assets/hello.txt";
-  const file = Deno.openSync(filename);
+  using file = Deno.openSync(filename);
   const seekPosition = 6;
   // Deliberately move 1 step forward
   file.readSync(new Uint8Array(1)); // "H"
@@ -605,12 +591,11 @@ Deno.test({ permissions: { read: true } }, function seekSyncStart() {
   file.readSync(buf);
   const decoded = new TextDecoder().decode(buf);
   assertEquals(decoded, "world!");
-  file.close();
 });
 
 Deno.test({ permissions: { read: true } }, async function seekCurrent() {
   const filename = "cli/tests/testdata/assets/hello.txt";
-  const file = await Deno.open(filename);
+  using file = await Deno.open(filename);
   // Deliberately move 1 step forward
   await file.read(new Uint8Array(1)); // "H"
   // Skipping "ello "
@@ -622,12 +607,11 @@ Deno.test({ permissions: { read: true } }, async function seekCurrent() {
   await file.read(buf);
   const decoded = new TextDecoder().decode(buf);
   assertEquals(decoded, "world!");
-  file.close();
 });
 
 Deno.test({ permissions: { read: true } }, function seekSyncCurrent() {
   const filename = "cli/tests/testdata/assets/hello.txt";
-  const file = Deno.openSync(filename);
+  using file = Deno.openSync(filename);
   // Deliberately move 1 step forward
   file.readSync(new Uint8Array(1)); // "H"
   // Skipping "ello "
@@ -639,12 +623,11 @@ Deno.test({ permissions: { read: true } }, function seekSyncCurrent() {
   file.readSync(buf);
   const decoded = new TextDecoder().decode(buf);
   assertEquals(decoded, "world!");
-  file.close();
 });
 
 Deno.test({ permissions: { read: true } }, async function seekEnd() {
   const filename = "cli/tests/testdata/assets/hello.txt";
-  const file = await Deno.open(filename);
+  using file = await Deno.open(filename);
   const seekPosition = -6;
   // seek from end of file that has 12 chars, 12 - 6  = 6
   const cursorPosition = await file.seek(seekPosition, Deno.SeekMode.End);
@@ -653,12 +636,11 @@ Deno.test({ permissions: { read: true } }, async function seekEnd() {
   await file.read(buf);
   const decoded = new TextDecoder().decode(buf);
   assertEquals(decoded, "world!");
-  file.close();
 });
 
 Deno.test({ permissions: { read: true } }, function seekSyncEnd() {
   const filename = "cli/tests/testdata/assets/hello.txt";
-  const file = Deno.openSync(filename);
+  using file = Deno.openSync(filename);
   const seekPosition = -6;
   // seek from end of file that has 12 chars, 12 - 6  = 6
   const cursorPosition = file.seekSync(seekPosition, Deno.SeekMode.End);
@@ -667,12 +649,11 @@ Deno.test({ permissions: { read: true } }, function seekSyncEnd() {
   file.readSync(buf);
   const decoded = new TextDecoder().decode(buf);
   assertEquals(decoded, "world!");
-  file.close();
 });
 
 Deno.test({ permissions: { read: true } }, async function seekMode() {
   const filename = "cli/tests/testdata/assets/hello.txt";
-  const file = await Deno.open(filename);
+  using file = await Deno.open(filename);
   await assertRejects(
     async () => {
       await file.seek(1, -1 as unknown as Deno.SeekMode);
@@ -686,14 +667,13 @@ Deno.test({ permissions: { read: true } }, async function seekMode() {
   const buf = new Uint8Array(1);
   await file.read(buf); // "H"
   assertEquals(new TextDecoder().decode(buf), "H");
-  file.close();
 });
 
 Deno.test(
   { permissions: { read: true, write: true } },
   function fileTruncateSyncSuccess() {
     const filename = Deno.makeTempDirSync() + "/test_fileTruncateSync.txt";
-    const file = Deno.openSync(filename, {
+    using file = Deno.openSync(filename, {
       create: true,
       read: true,
       write: true,
@@ -706,7 +686,6 @@ Deno.test(
     file.truncateSync(-5);
     assertEquals(Deno.readFileSync(filename).byteLength, 0);
 
-    file.close();
     Deno.removeSync(filename);
   },
 );
@@ -715,7 +694,7 @@ Deno.test(
   { permissions: { read: true, write: true } },
   async function fileTruncateSuccess() {
     const filename = Deno.makeTempDirSync() + "/test_fileTruncate.txt";
-    const file = await Deno.open(filename, {
+    using file = await Deno.open(filename, {
       create: true,
       read: true,
       write: true,
@@ -728,13 +707,12 @@ Deno.test(
     await file.truncate(-5);
     assertEquals((await Deno.readFile(filename)).byteLength, 0);
 
-    file.close();
     await Deno.remove(filename);
   },
 );
 
 Deno.test({ permissions: { read: true } }, function fileStatSyncSuccess() {
-  const file = Deno.openSync("README.md");
+  using file = Deno.openSync("README.md");
   const fileInfo = file.statSync();
   assert(fileInfo.isFile);
   assert(!fileInfo.isSymlink);
@@ -744,12 +722,10 @@ Deno.test({ permissions: { read: true } }, function fileStatSyncSuccess() {
   assert(fileInfo.mtime);
   // The `birthtime` field is not available on Linux before kernel version 4.11.
   assert(fileInfo.birthtime || Deno.build.os === "linux");
-
-  file.close();
 });
 
 Deno.test(async function fileStatSuccess() {
-  const file = await Deno.open("README.md");
+  using file = await Deno.open("README.md");
   const fileInfo = await file.stat();
   assert(fileInfo.isFile);
   assert(!fileInfo.isSymlink);
@@ -759,8 +735,6 @@ Deno.test(async function fileStatSuccess() {
   assert(fileInfo.mtime);
   // The `birthtime` field is not available on Linux before kernel version 4.11.
   assert(fileInfo.birthtime || Deno.build.os === "linux");
-
-  file.close();
 });
 
 Deno.test({ permissions: { read: true } }, async function readableStream() {
@@ -813,10 +787,9 @@ Deno.test(
   { permissions: { read: true, write: true } },
   async function readTextFileNonUtf8() {
     const path = await Deno.makeTempFile();
-    const file = await Deno.open(path, { write: true });
+    using file = await Deno.open(path, { write: true });
     await file.write(new TextEncoder().encode("hello "));
     await file.write(new Uint8Array([0xC0]));
-    file.close();
 
     const res = await Deno.readTextFile(path);
     const resSync = Deno.readTextFileSync(path);