feat(fs/unstable): add fs.lstat (#6276)

_tools/node_test_runner/run_test.mjs

@@ -50,6 +50,7 @@ import "../../collections/unzip_test.ts";
 import "../../collections/without_all_test.ts";
 import "../../collections/zip_test.ts";
 import "../../fs/unstable_stat_test.ts";
+import "../../fs/unstable_lstat_test.ts";
 
 for (const testDef of testDefinitions) {
   test(testDef.name, testDef.fn);

fs/deno.json

@@ -14,6 +14,7 @@
     "./expand-glob": "./expand_glob.ts",
     "./move": "./move.ts",
     "./unstable-stat": "./unstable_stat.ts",
+    "./unstable-lstat": "./unstable_lstat.ts",
     "./walk": "./walk.ts"
   }
 }

fs/unstable_lstat.ts

@@ -0,0 +1,34 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+import { getNodeFsPromises, isDeno } from "./_utils.ts";
+import { mapError } from "./_map_error.ts";
+import { toFileInfo } from "./_to_file_info.ts";
+import type { FileInfo } from "./unstable_types.ts";
+
+/** Resolves to a {@linkcode FileInfo} for the specified `path`. If `path` is a symlink, information for the symlink will be returned instead of what it points to.
+ *
+ * ```ts
+ * import { assert } from "@std/assert";
+ * import { lstat } from "@std/fs/unstable-lstat";
+ * const fileInfo = await lstat("README.md");
+ * assert(fileInfo.isFile);
+ * ```
+ *
+ * Requires `allow-read` permission.
+ *
+ * @tags allow-read
+ * @category File System
+ */
+export async function lstat(path: string | URL): Promise<FileInfo> {
+  if (isDeno) {
+    return Deno.lstat(path);
+  } else {
+    const fsPromises = getNodeFsPromises();
+    try {
+      const stat = await fsPromises.lstat(path);
+      return toFileInfo(stat);
+    } catch (error) {
+      throw mapError(error);
+    }
+  }
+}

fs/unstable_lstat_test.ts

@@ -0,0 +1,30 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+
+import { assert, assertRejects } from "@std/assert";
+import { lstat } from "./unstable_lstat.ts";
+import { NotFound } from "./unstable_errors.js";
+
+Deno.test("lstat() returns FileInfo for a file", async () => {
+  const fileInfo = await lstat("README.md");
+
+  assert(fileInfo.isFile);
+});
+
+Deno.test("lstat() does not follow symlinks", async () => {
+  const linkFile = `${import.meta.dirname}/testdata/0-link`;
+  const fileInfo = await lstat(linkFile);
+
+  assert(fileInfo.isSymlink);
+});
+
+Deno.test("lstat() returns FileInfo for a directory", async () => {
+  const fileInfo = await lstat("fs");
+
+  assert(fileInfo.isDirectory);
+});
+
+Deno.test("lstat() rejects with NotFound for a non-existent file", async () => {
+  await assertRejects(async () => {
+    await lstat("non_existent_file");
+  }, NotFound);
+});