Update examples: file exists, folder exists (#1424)

Author: philhawksworth

examples/_data.ts

@@ -658,6 +658,11 @@ export const sidebar = [
         id: "/examples/checking_file_existence",
         type: "example",
       },
+      {
+        label: "Checking for directory existence",
+        id: "/examples/checking_directory_existence",
+        type: "example",
+      },
       {
         label: "Moving/Renaming files",
         id: "/examples/moving_renaming_files",

examples/scripts/checking_directory_existence.ts

@@ -0,0 +1,35 @@
+/**
+ * @title Checking for directory existence
+ * @difficulty beginner
+ * @tags cli, deploy
+ * @run --allow-read --allow-write <url>
+ * @group File System
+ *
+ * When creating directories it can be useful to first ensure that
+ * such a directory doesn't already exist.
+ * There are a number of ways to do this.
+ */
+
+// Use the `exists` utility from the std library to check for existence of a file or folder.
+// Note: Can create a race condition if followed by file operation.
+// Consider the alternative below.
+import { exists } from "jsr:@std/fs/exists";
+await exists("./this_file_or_folder_exists"); // true
+await exists("./this_file_or_folder_does_not_exist"); // false
+
+// We can also use this function to check if the item on a path is a file or a directory
+await exists("./directory", { isDirectory: true }); // true
+await exists("./file", { isDirectory: true }); // false
+
+// Do not use the above function if performing a check directly before another operation on that folder.
+// Doing so creates a race condition. The `exists` function is not recommended for that usecase.
+// Consider this alternative which checks for existence of a folder without doing any other filesystem operations.
+try {
+  await Deno.lstat("./example_directory");
+  console.log("Folder exists");
+} catch (err) {
+  if (!(err instanceof Deno.errors.NotFound)) {
+    throw err;
+  }
+  console.log("Folder does not exist");
+}

examples/scripts/checking_file_existence.ts

@@ -5,38 +5,30 @@
  * @run --allow-read --allow-write <url>
  * @group File System
  *
- * Sometimes we as developers think that we need to check
- * if a file exists or not. More often than not, we are
- * entirely wrong.
+ * When creating files it can be useful to first ensure that
+ * such a file doesn't already exist.
+ * There are a number of ways to do this.
  */
 
-// Let's say we wanted to create a folder if one doesn't
-// already exist. Logically it makes sense to first verify
-// that the folder exists, then try to create it right?
-// Wrong. This will create a race condition where if a folder
-// gets created in between when you check if the folder exists
-// and when you create a folder, your program will crash.
-// Instead, you should just create a folder and try to catch
-// errors like so.
-try {
-  await Deno.mkdir("new_dir");
-} catch (err) {
-  if (!(err instanceof Deno.errors.AlreadyExists)) {
-    throw err;
-  }
-}
+// Use the `exists` utility from the std library to check for existence of a file or folder.
+// Note: Can create a race condition if followed by file operation.
+// Consider the alternative below.
+import { exists } from "jsr:@std/fs/exists";
+await exists("./this_file_or_folder_exists"); // true
+await exists("./this_file_or_folder_does_not_exist"); // false
+
+// We can also use this function to check if the item on a path is a file or a directory
+await exists("./file", { isFile: true }); // true
+await exists("./directory", { isFile: true }); // false
 
-// This applies to almost every usecase. If you have a niche
-// usecase that requires you to check for existence of a file
-// without doing an filesystem operations other than that
-// (which is quite rare), then you can simply lstat the file
-// and catch the error.
+// Do not use the above function if performing a check directly before another operation on that file.
+// Doing so creates a race condition. The `exists` function is not recommended for that usecase.
+// Consider this alternative which checks for existence of a file without doing any other filesystem operations.
 try {
-  await Deno.lstat("example.txt");
-  console.log("exists!");
+  const stats = await Deno.lstat("example.txt");
 } catch (err) {
   if (!(err instanceof Deno.errors.NotFound)) {
     throw err;
   }
-  console.log("not exists!");
+  console.log("File does not exist");
 }