Create a facade for node:fs (#2224)

Localize the import surface with `node:fs` with an explicit facade.
Currently the facade API is 1-1 the (used part of) original API with the
exception of some simplifications.

In the future, this facade can help simplify migration as the original
API changes or (perhaps more likely in the case of a built-in library)
aid in writing code that supports both older and newer version of the
API when multiple runtime versions are supported.

Author: ericcornelissen

src/internal/fs.js

@@ -0,0 +1,29 @@
+/**
+ * @overview Provides an interface for interacting with the file system.
+ * @license MPL-2.0
+ */
+
+import * as fs from "node:fs";
+
+/**
+ * Synchronously look up if the `path` exists.
+ *
+ * @param {string} path The path to look up.
+ * @param {object} [deps] Node.js' fs module.
+ * @returns {boolean} `true` if the path exists, `false` otherwise.
+ */
+export function existsSync(path, deps = fs) {
+  return deps.existsSync(path);
+}
+
+/**
+ * Synchronously look up the (target) location of a symbolic link.
+ *
+ * @param {string} path The path to look up.
+ * @param {object} [deps] Node.js' fs module.
+ * @returns {string} The contents of `path`.
+ * @throws {Error} If `path` is not a symbolic link.
+ */
+export function readlinkSync(path, deps = fs) {
+  return deps.readlinkSync(path);
+}

src/internal/unix.js

@@ -3,11 +3,11 @@
  * @license MPL-2.0
  */
 
-import * as fs from "node:fs";
 import * as path from "node:path";
 
 import which from "which";
 
+import * as fs from "./fs.js";
 import { noShell } from "./options.js";
 import * as bash from "./unix/bash.js";
 import * as busybox from "./unix/busybox.js";

src/internal/win.js

@@ -3,11 +3,11 @@
  * @license MPL-2.0
  */
 
-import * as fs from "node:fs";
 import * as path from "node:path";
 
 import which from "which";
 
+import * as fs from "./fs.js";
 import { noShell } from "./options.js";
 import { hasOwn } from "./reflection.js";
 import * as cmd from "./win/cmd.js";

test/unit/fs/exists.test.js

@@ -0,0 +1,41 @@
+/**
+ * @overview Contains unit tests for the functionality to check if a file
+ * exists.
+ * @license MIT
+ */
+
+import { testProp } from "@fast-check/ava";
+import test from "ava";
+import * as fc from "fast-check";
+import * as sinon from "sinon";
+
+import { existsSync } from "../../../src/internal/fs.js";
+
+test.before((t) => {
+  const existsSync = sinon.mock();
+
+  t.context = {
+    deps: { existsSync },
+  };
+});
+
+testProp(
+  "return value",
+  [fc.string(), fc.boolean()],
+  (t, path, returnValue) => {
+    t.context.deps.existsSync.resetHistory();
+    t.context.deps.existsSync.returns(returnValue);
+
+    const result = existsSync(path, t.context.deps);
+    t.is(result, returnValue);
+  },
+);
+
+testProp("fs usage", [fc.string(), fc.boolean()], (t, path, returnValue) => {
+  t.context.deps.existsSync.resetHistory();
+  t.context.deps.existsSync.returns(returnValue);
+
+  existsSync(path, t.context.deps);
+  t.is(t.context.deps.existsSync.callCount, 1);
+  t.true(t.context.deps.existsSync.calledWithExactly(path));
+});

test/unit/fs/readlink.test.js

@@ -0,0 +1,48 @@
+/**
+ * @overview Contains unit tests for the functionality to read a file system
+ * link.
+ * @license MIT
+ */
+
+import { testProp } from "@fast-check/ava";
+import test from "ava";
+import * as fc from "fast-check";
+import * as sinon from "sinon";
+
+import { readlinkSync } from "../../../src/internal/fs.js";
+
+test.before((t) => {
+  const readlinkSync = sinon.mock();
+
+  t.context = {
+    deps: { readlinkSync },
+  };
+});
+
+testProp("return value", [fc.string(), fc.string()], (t, path, returnValue) => {
+  t.context.deps.readlinkSync.resetHistory();
+  t.context.deps.readlinkSync.returns(returnValue);
+
+  const result = readlinkSync(path, t.context.deps);
+  t.is(result, returnValue);
+});
+
+testProp(
+  "error",
+  [fc.string(), fc.string().map((message) => new Error(message))],
+  (t, path, error) => {
+    t.context.deps.readlinkSync.resetHistory();
+    t.context.deps.readlinkSync.throws(error);
+
+    t.throws(() => readlinkSync(path, t.context.deps), { is: error });
+  },
+);
+
+testProp("fs usage", [fc.string(), fc.string()], (t, path, returnValue) => {
+  t.context.deps.readlinkSync.resetHistory();
+  t.context.deps.readlinkSync.returns(returnValue);
+
+  readlinkSync(path, t.context.deps);
+  t.is(t.context.deps.readlinkSync.callCount, 1);
+  t.true(t.context.deps.readlinkSync.calledWithExactly(path));
+});