chore(fs): document the deprecation of exists and existsSync

fs/README.md

@@ -95,7 +95,65 @@ format(CRLFinput, EOL.LF); // output "deno\nis not\nnode"
 
 ### exists
 
-This function is now deprecated.
+Test whether or not the given path exists by checking with the file system.
+
+```ts
+import {
+  exists,
+  existsSync,
+} from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+
+exists("./foo.txt"); // resolves a boolean
+existsSync("./foo.txt"); // returns a boolean
+```
+
+**Note: do not use this function if performing a check before another operation
+on that file. Doing so causes a race condition. Instead, perform the actual file
+operation directly.**
+
+Bad:
+
+```ts
+import {
+  exists,
+  existsSync,
+} from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+
+if (await exists("./foo.txt")) {
+  await Deno.remove("./foo.txt");
+}
+
+// OR
+
+if (existsSync("./foo.txt")) {
+  Deno.removeSync("./foo.txt");
+}
+```
+
+Good:
+
+```ts
+// Notice no use of exists or existsSync
+try {
+  await Deno.remove("./foo.txt");
+} catch (error) {
+  if (!(error instanceof Deno.errors.NotFound)) {
+    throw error;
+  }
+  // Do nothing...
+}
+
+// OR
+
+try {
+  Deno.removeSync("./foo.txt");
+} catch (error) {
+  if (!(error instanceof Deno.errors.NotFound)) {
+    throw error;
+  }
+  // Do nothing...
+}
+```
 
 ### move
 

fs/exists.ts

@@ -1,35 +1,83 @@
 // Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
+
 /**
- * Test whether or not the given path exists by checking with the file system
- * @deprecated (will be removed after 0.157.0) Checking the state of a file before using it causes a race condition. Perform the actual operation directly instead.
+ * Test whether or not the given path exists by checking with the file system.
+ *
+ * Note: do not use this function if performing a check before another operation on that file. Doing so creates a race condition. Instead, perform the actual file operation directly.
+ *
+ * Bad:
+ * ```ts
+ * import { exists } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ *
+ * if (await exists("./foo.txt")) {
+ *   await Deno.remove("./foo.txt");
+ * }
+ * ```
+ *
+ * Good:
+ * ```ts
+ * // Notice no use of exists
+ * try {
+ *   await Deno.remove("./foo.txt");
+ * } catch (error) {
+ *   if (!(error instanceof Deno.errors.NotFound)) {
+ *     throw error;
+ *   }
+ *   // Do nothing...
+ * }
+ * ```
  * @see https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use
+ * @deprecated (will be removed after 0.157.0) Checking the state of a file before using it causes a race condition. Perform the actual operation directly instead.
  */
-export async function exists(filePath: string): Promise<boolean> {
+export async function exists(filePath: string | URL): Promise<boolean> {
   try {
     await Deno.lstat(filePath);
     return true;
-  } catch (err) {
-    if (err instanceof Deno.errors.NotFound) {
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) {
       return false;
     }
-
-    throw err;
+    throw error;
   }
 }
 
 /**
- * Test whether or not the given path exists by checking with the file system
- * @deprecated (will be removed after 0.157.0) Checking the state of a file before using it causes a race condition. Perform the actual operation directly instead.
+ * Test whether or not the given path exists by checking with the file system.
+ *
+ * Note: do not use this function if performing a check before another operation on that file. Doing so creates a race condition. Instead, perform the actual file operation directly.
+ *
+ * Bad:
+ * ```ts
+ * import { existsSync } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ *
+ * if (existsSync("./foo.txt")) {
+ *   Deno.removeSync("./foo.txt");
+ * }
+ * ```
+ *
+ * Good:
+ * ```ts
+ * // Notice no use of existsSync
+ * try {
+ *   Deno.removeSync("./foo.txt");
+ * } catch (error) {
+ *   if (!(error instanceof Deno.errors.NotFound)) {
+ *     throw error;
+ *   }
+ *   // Do nothing...
+ * }
+ * ```
  * @see https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use
+ * @deprecated (will be removed after 0.157.0) Checking the state of a file before using it causes a race condition. Perform the actual operation directly instead.
  */
-export function existsSync(filePath: string): boolean {
+export function existsSync(filePath: string | URL): boolean {
   try {
     Deno.lstatSync(filePath);
     return true;
-  } catch (err) {
-    if (err instanceof Deno.errors.NotFound) {
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) {
       return false;
     }
-    throw err;
+    throw error;
   }
 }

log/handlers.ts

@@ -189,8 +189,12 @@ export class RotatingFileHandler extends FileHandler {
       // Remove old backups too as it doesn't make sense to start with a clean
       // log file, but old backups
       for (let i = 1; i <= this.#maxBackupCount; i++) {
-        if (await exists(this._filename + "." + i)) {
+        try {
           await Deno.remove(this._filename + "." + i);
+        } catch (error) {
+          if (!(error instanceof Deno.errors.NotFound)) {
+            throw error;
+          }
         }
       }
     } else if (this._mode === "x") {