feat(fs): undo deprecation of exists and add permission and type check to it

fs/mod.ts

@@ -10,6 +10,9 @@ export * from "./ensure_dir.ts";
 export * from "./ensure_file.ts";
 export * from "./ensure_link.ts";
 export * from "./ensure_symlink.ts";
+export * from "./readable.ts";
+export * from "./readable_dir.ts";
+export * from "./readable_file.ts";
 export * from "./exists.ts";
 export * from "./expand_glob.ts";
 export * from "./move.ts";

fs/readable.ts

@@ -0,0 +1,81 @@
+// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
+
+/**
+ * Test whether or not the given path is readable by checking with the file system. To check simultaneously if the path is either a file or a directory please use `readableFile` or `readableDir` instead.
+ *
+ * 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 { readable } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ *
+ * if (await readable("./foo")) {
+ *   await Deno.remove("./foo");
+ * }
+ * ```
+ *
+ * Good:
+ * ```ts
+ * // Notice no use of readable
+ * try {
+ *   await Deno.remove("./foo", { recursive: true });
+ * } 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
+ */
+export async function readable(path: string | URL): Promise<boolean> {
+  try {
+    await Deno.stat(path);
+    return true;
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Test whether or not the given path is readable by checking with the file system. To check simultaneously if the path is either a file or a directory please use `readableFile` or `readableDir` instead.
+ *
+ * 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 { readable } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ *
+ * if (await readable("./foo")) {
+ *   await Deno.remove("./foo");
+ * }
+ * ```
+ *
+ * Good:
+ * ```ts
+ * // Notice no use of readable
+ * try {
+ *   await Deno.remove("./foo", { recursive: true });
+ * } 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
+ */
+export function readableSync(path: string | URL): boolean {
+  try {
+    Deno.statSync(path);
+    return true;
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) {
+      return false;
+    }
+    throw error;
+  }
+}

fs/readable_dir.ts

@@ -0,0 +1,79 @@
+// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
+
+/**
+ * Test whether or not the given path is readable directory 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 { readableDir } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ *
+ * if (await readableDir("./foo")) {
+ *   await Deno.remove("./foo");
+ * }
+ * ```
+ *
+ * Good:
+ * ```ts
+ * // Notice no use of readableDir
+ * try {
+ *   await Deno.remove("./foo", { recursive: true });
+ * } 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
+ */
+export async function readableDir(dirPath: string | URL): Promise<boolean> {
+  try {
+    return (await Deno.stat(dirPath)).isDirectory;
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Test whether or not the given path is readable directory 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 { readableDir } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ *
+ * if (await readableDir("./foo")) {
+ *   await Deno.remove("./foo");
+ * }
+ * ```
+ *
+ * Good:
+ * ```ts
+ * // Notice no use of readableDir
+ * try {
+ *   await Deno.remove("./foo", { recursive: true });
+ * } 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
+ */
+export function readableDirSync(dirPath: string | URL): boolean {
+  try {
+    return Deno.statSync(dirPath).isDirectory;
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) {
+      return false;
+    }
+    throw error;
+  }
+}

fs/readable_dir_test.ts

@@ -0,0 +1,61 @@
+// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
+import { assertEquals } from "../testing/asserts.ts";
+import * as path from "../path/mod.ts";
+import { readableDir, readableDirSync } from "./readable_dir.ts";
+
+const moduleDir = path.dirname(path.fromFileUrl(import.meta.url));
+const testdataDir = path.resolve(moduleDir, "testdata");
+
+Deno.test("[fs] readableFile", async function () {
+  assertEquals(
+    await readableDir(path.join(testdataDir, "not_exist_file.ts")),
+    false,
+  );
+  assertEquals(await readableDir(path.join(testdataDir, "0.ts")), false);
+});
+
+Deno.test("[fs] readableFileSync", function () {
+  assertEquals(readableDirSync(path.join(testdataDir, "not_exist_file.ts")), false);
+  assertEquals(readableDirSync(path.join(testdataDir, "0.ts")), false);
+});
+
+Deno.test("[fs] readableDir", async function () {
+  assertEquals(
+    await readableDir(path.join(testdataDir, "not_exist_directory")),
+    false,
+  );
+  assertEquals(await readableDir(testdataDir), true);
+});
+
+Deno.test("[fs] readableDirSync", function () {
+  assertEquals(
+    readableDirSync(path.join(testdataDir, "not_exist_directory")),
+    false,
+  );
+  assertEquals(readableDirSync(testdataDir), true);
+});
+
+Deno.test("[fs] readableFileLink", async function () {
+  // TODO(axetroy): generate link file use Deno api instead of set a link file
+  // in repository
+  assertEquals(await readableDir(path.join(testdataDir, "0-link")), false);
+});
+
+Deno.test("[fs] readableFileLinkSync", function () {
+  // TODO(axetroy): generate link file use Deno api instead of set a link file
+  // in repository
+  assertEquals(readableDirSync(path.join(testdataDir, "0-link")), false);
+});
+
+Deno.test("[fs] readableDirLink", async function () {
+  // TODO(axetroy): generate link file use Deno api instead of set a link file
+  // in repository
+  assertEquals(await readableDir(path.join(testdataDir, "testdata-link")), true);
+});
+
+Deno.test("[fs] readableDirLinkSync", function () {
+  // TODO(axetroy): generate link file use Deno api instead of set a link file
+  // in repository
+  assertEquals(readableDirSync(path.join(testdataDir, "testdata-link")), true);
+});
+

fs/readable_file.ts

@@ -0,0 +1,79 @@
+// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
+
+/**
+ * Test whether or not the given path is a readable file 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 { readableFile } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ *
+ * if (await readableFile("./foo.txt")) {
+ *   await Deno.remove("./foo.txt");
+ * }
+ * ```
+ *
+ * Good:
+ * ```ts
+ * // Notice no use of readableFile
+ * 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
+ */
+export async function readableFile(filePath: string | URL): Promise<boolean> {
+  try {
+    return (await Deno.stat(filePath)).isFile;
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Test whether or not the given path is a readable file 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 { readableFile } from "https://deno.land/std@$STD_VERSION/fs/mod.ts";
+ *
+ * if (await readableFile("./foo.txt")) {
+ *   await Deno.remove("./foo.txt");
+ * }
+ * ```
+ *
+ * Good:
+ * ```ts
+ * // Notice no use of readableFile
+ * 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
+ */
+export function readableFileSync(filePath: string | URL): boolean {
+  try {
+    return Deno.statSync(filePath).isFile;
+  } catch (error) {
+    if (error instanceof Deno.errors.NotFound) {
+      return false;
+    }
+    throw error;
+  }
+}

fs/readable_file_test.ts

@@ -0,0 +1,61 @@
+// Copyright 2018-2022 the Deno authors. All rights reserved. MIT license.
+import { assertEquals } from "../testing/asserts.ts";
+import * as path from "../path/mod.ts";
+import { readableFile, readableFileSync } from "./readable_file.ts";
+
+const moduleDir = path.dirname(path.fromFileUrl(import.meta.url));
+const testdataDir = path.resolve(moduleDir, "testdata");
+
+Deno.test("[fs] readableFile", async function () {
+  assertEquals(
+    await readableFile(path.join(testdataDir, "not_exist_file.ts")),
+    false,
+  );
+  assertEquals(await readableFile(path.join(testdataDir, "0.ts")), true);
+});
+
+Deno.test("[fs] readableFileSync", function () {
+  assertEquals(readableFileSync(path.join(testdataDir, "not_exist_file.ts")), false);
+  assertEquals(readableFileSync(path.join(testdataDir, "0.ts")), true);
+});
+
+Deno.test("[fs] readableDir", async function () {
+  assertEquals(
+    await readableFile(path.join(testdataDir, "not_exist_directory")),
+    false,
+  );
+  assertEquals(await readableFile(testdataDir), false);
+});
+
+Deno.test("[fs] readableDirSync", function () {
+  assertEquals(
+    readableFileSync(path.join(testdataDir, "not_exist_directory")),
+    false,
+  );
+  assertEquals(readableFileSync(testdataDir), false);
+});
+
+Deno.test("[fs] readableFileLink", async function () {
+  // TODO(axetroy): generate link file use Deno api instead of set a link file
+  // in repository
+  assertEquals(await readableFile(path.join(testdataDir, "0-link")), true);
+});
+
+Deno.test("[fs] readableFileLinkSync", function () {
+  // TODO(axetroy): generate link file use Deno api instead of set a link file
+  // in repository
+  assertEquals(readableFileSync(path.join(testdataDir, "0-link")), true);
+});
+
+Deno.test("[fs] readableDirLink", async function () {
+  // TODO(axetroy): generate link file use Deno api instead of set a link file
+  // in repository
+  assertEquals(await readableFile(path.join(testdataDir, "testdata-link")), false);
+});
+
+Deno.test("[fs] readableDirLinkSync", function () {
+  // TODO(axetroy): generate link file use Deno api instead of set a link file
+  // in repository
+  assertEquals(readableFileSync(path.join(testdataDir, "testdata-link")), false);
+});
+