@jsenv/filesystem 4.3.2 → 4.4.0

package/src/read_write/write_symbolic_link_sync.js

@@ -0,0 +1,115 @@
+import { symlinkSync } from "node:fs";
+import {
+  fileSystemPathToUrl,
+  urlToFileSystemPath,
+  resolveUrl,
+  isFileSystemPath,
+} from "@jsenv/urls";
+
+import { assertAndNormalizeFileUrl } from "../path_and_url/file_url_validation.js";
+import { removeEntrySync } from "../remove/remove_entry_sync.js";
+import { readEntryStatSync } from "./stat/read_entry_stat_sync.js";
+import { readSymbolicLinkSync } from "./read_symbolic_link_sync.js";
+import { ensureParentDirectoriesSync } from "./ensure_parent_directories_sync.js";
+
+const isWindows = process.platform === "win32";
+
+/**
+ * Writes a symbolic link pointing from a filesystem node to an other
+ * @param {string} from Where symlink is written
+ * @param {string} to The symlink target
+ * @param {"file" | "dir"} [type] Symlink type if you know it before hand
+ * @param {boolean} [allowUseless=false] Prevent error when symlink already exists with the same target
+ * @param {boolean} [allowOverwrite=false] Will replace any existing symlink
+ */
+export const writeSymbolicLinkSync = ({
+  from,
+  to,
+  type,
+  allowUseless = false,
+  allowOverwrite = false,
+}) => {
+  const fromUrl = assertAndNormalizeFileUrl(from);
+  const toInfo = getToInfo(to, fromUrl);
+  // Node.js doc at https://nodejs.org/api/fs.html#fssymlinktarget-path-type-callback
+  // states the following:
+  // "If the type argument is not set, Node.js will autodetect
+  // target type and use 'file' or 'dir'"
+  // In practice, if code don't specify "type" on windows, you later get EPERM errors
+  // when doing operation on the symlink such as "fs.stat"
+  if (isWindows && typeof type === "undefined") {
+    const toStats = readEntryStatSync(toInfo.url, {
+      nullIfNotFound: true,
+    });
+    type = toStats && toStats.isDirectory() ? "dir" : "file";
+  }
+  const symbolicLinkPath = urlToFileSystemPath(fromUrl);
+  try {
+    symlinkSync(toInfo.value, symbolicLinkPath, type);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      ensureParentDirectoriesSync(fromUrl);
+      symlinkSync(toInfo.value, symbolicLinkPath, type);
+      return;
+    }
+    if (error.code === "EEXIST") {
+      if (allowUseless) {
+        const existingSymbolicLinkUrl = readSymbolicLinkSync(fromUrl);
+        if (existingSymbolicLinkUrl === toInfo.url) {
+          return;
+        }
+      }
+      if (allowOverwrite) {
+        removeEntrySync(fromUrl);
+        symlinkSync(toInfo.value, symbolicLinkPath, type);
+        return;
+      }
+    }
+    throw error;
+  }
+};
+
+const getToInfo = (to, fromUrl) => {
+  if (typeof to === "string") {
+    // absolute filesystem path
+    if (isFileSystemPath(to)) {
+      const url = fileSystemPathToUrl(to);
+      const value = to;
+      return {
+        url,
+        value,
+      };
+    }
+
+    // relative url
+    if (to.startsWith("./") || to.startsWith("../")) {
+      const url = resolveUrl(to, fromUrl);
+      const value = to;
+      return {
+        url,
+        value,
+      };
+    }
+
+    // absolute url
+    const url = resolveUrl(to, fromUrl);
+    const value = urlToFileSystemPath(url);
+    return {
+      url,
+      value,
+    };
+  }
+
+  if (to instanceof URL) {
+    const url = String(to);
+    const value = urlToFileSystemPath(url);
+    return {
+      url,
+      value,
+    };
+  }
+
+  throw new TypeError(
+    `symbolic link to must be a string or an url, received ${to}`,
+  );
+};

package/src/remove/clear_directory_sync.js

@@ -0,0 +1,68 @@
+import { readdirSync, statSync } from "node:fs";
+import { URL_META } from "@jsenv/url-meta";
+
+import { removeEntrySync } from "./remove_entry_sync.js";
+
+export const clearDirectorySync = (initialDirectoryUrl, pattern = "**/*") => {
+  const associations = URL_META.resolveAssociations(
+    {
+      clear: {
+        [pattern]: true,
+        "**/.*": false,
+        "**/.*/": false,
+        "**/node_modules/": false,
+      },
+    },
+    initialDirectoryUrl,
+  );
+  const visitDirectory = (directoryUrl) => {
+    const entryNames = readdirSync(new URL(directoryUrl));
+    for (const entryName of entryNames) {
+      const entryUrl = new URL(entryName, directoryUrl);
+      let entryStat;
+      try {
+        entryStat = statSync(entryUrl);
+      } catch (e) {
+        if (e && e.code === "ENOENT") {
+          continue;
+        }
+        throw e;
+      }
+
+      if (entryStat.isDirectory()) {
+        const subDirectoryUrl = new URL(`${entryName}/`, directoryUrl);
+        const meta = URL_META.applyAssociations({
+          url: subDirectoryUrl,
+          associations,
+        });
+        if (meta.clear) {
+          removeEntrySync(subDirectoryUrl, {
+            recursive: true,
+            allowUseless: true,
+          });
+          continue;
+        }
+        if (
+          !URL_META.urlChildMayMatch({
+            url: subDirectoryUrl,
+            associations,
+            predicate: ({ clear }) => clear,
+          })
+        ) {
+          continue;
+        }
+        visitDirectory(subDirectoryUrl);
+      }
+
+      const meta = URL_META.applyAssociations({
+        url: entryUrl,
+        associations,
+      });
+      if (meta.clear) {
+        removeEntrySync(entryUrl, { allowUseless: true });
+        continue;
+      }
+    }
+  };
+  visitDirectory(initialDirectoryUrl);
+};

package/src/{ensureEmptyDirectory.js → remove/ensure_empty_directory.js}

@@ -1,10 +1,10 @@
 import { urlToFileSystemPath } from "@jsenv/urls";
 
-import { assertAndNormalizeFileUrl } from "./file_url_validation.js";
-import { statsToType } from "./internal/statsToType.js";
-import { writeDirectory } from "./writeDirectory.js";
-import { readEntryStat } from "./readEntryStat.js";
-import { removeEntry } from "./removeEntry.js";
+import { assertAndNormalizeFileUrl } from "../path_and_url/file_url_validation.js";
+import { statsToType } from "../read_write/stat/stats_to_type.js";
+import { readEntryStat } from "../read_write/stat/read_entry_stat.js";
+import { writeDirectory } from "../read_write/write_directory.js";
+import { removeEntry } from "./remove_entry.js";
 
 export const ensureEmptyDirectory = async (source) => {
   const stats = await readEntryStat(source, {
@@ -13,15 +13,17 @@ export const ensureEmptyDirectory = async (source) => {
   });
   if (stats === null) {
     // if there is nothing, create a directory
-    return writeDirectory(source, { allowUseless: true });
+    await writeDirectory(source, { allowUseless: true });
+    return;
   }
   if (stats.isDirectory()) {
     // if there is a directory remove its content and done
-    return removeEntry(source, {
+    await removeEntry(source, {
       allowUseless: true,
       recursive: true,
       onlyContent: true,
     });
+    return;
   }
 
   const sourceType = statsToType(stats);

package/src/remove/ensure_empty_directory_sync.js

@@ -0,0 +1,34 @@
+import { urlToFileSystemPath } from "@jsenv/urls";
+
+import { assertAndNormalizeFileUrl } from "../path_and_url/file_url_validation.js";
+import { readEntryStatSync } from "../read_write/stat/read_entry_stat_sync.js";
+import { statsToType } from "../read_write/stat/stats_to_type.js";
+import { writeDirectorySync } from "../read_write/write_directory_sync.js";
+import { removeEntrySync } from "./remove_entry_sync.js";
+
+export const ensureEmptyDirectorySync = (source) => {
+  const stat = readEntryStatSync(source, {
+    nullIfNotFound: true,
+    followLink: false,
+  });
+
+  if (stat === null) {
+    // if there is nothing, create a directory
+    writeDirectorySync(source, { allowUseless: true });
+    return;
+  }
+  if (stat.isDirectory()) {
+    removeEntrySync(source, {
+      recursive: true,
+      onlyContent: true,
+      allowUseless: true,
+    });
+    return;
+  }
+
+  const sourceType = statsToType(stat);
+  const sourcePath = urlToFileSystemPath(assertAndNormalizeFileUrl(source));
+  throw new Error(
+    `ensureEmptyDirectorySync expect directory at ${sourcePath}, found ${sourceType} instead`,
+  );
+};

package/src/remove/remove_directory.js

@@ -0,0 +1,8 @@
+import { removeEntry } from "./remove_entry.js";
+
+export const removeDirectory = (url, options = {}) => {
+  return removeEntry(url, {
+    ...options,
+    recursive: true,
+  });
+};

package/src/remove/remove_directory_sync.js

@@ -0,0 +1,8 @@
+import { removeEntrySync } from "./remove_entry_sync.js";
+
+export const removeDirectorySync = (url, options = {}) => {
+  return removeEntrySync(url, {
+    ...options,
+    recursive: true,
+  });
+};

package/src/{removeEntry.js → remove/remove_entry.js}

@@ -6,9 +6,9 @@ import {
   resolveUrl,
 } from "@jsenv/urls";
 
-import { assertAndNormalizeFileUrl } from "./file_url_validation.js";
-import { readEntryStat } from "./readEntryStat.js";
-import { readDirectory } from "./readDirectory.js";
+import { assertAndNormalizeFileUrl } from "../path_and_url/file_url_validation.js";
+import { readEntryStat } from "../read_write/stat/read_entry_stat.js";
+import { readDirectory } from "../read_write/read_directory.js";
 
 export const removeEntry = async (
   source,

package/src/remove/remove_entry_sync.js

@@ -0,0 +1,240 @@
+import {
+  unlinkSync,
+  rmdirSync,
+  readdirSync,
+  openSync,
+  closeSync,
+} from "node:fs";
+import { Abort } from "@jsenv/abort";
+import {
+  ensurePathnameTrailingSlash,
+  urlToFileSystemPath,
+  resolveUrl,
+} from "@jsenv/urls";
+
+import { assertAndNormalizeFileUrl } from "../path_and_url/file_url_validation.js";
+import { readEntryStatSync } from "../read_write/stat/read_entry_stat_sync.js";
+
+export const removeEntrySync = (
+  source,
+  {
+    signal = new AbortController().signal,
+    allowUseless = false,
+    recursive = false,
+    maxRetries = 3,
+    retryDelay = 100,
+    onlyContent = false,
+  } = {},
+) => {
+  const sourceUrl = assertAndNormalizeFileUrl(source);
+
+  const removeOperation = Abort.startOperation();
+  removeOperation.addAbortSignal(signal);
+
+  try {
+    removeOperation.throwIfAborted();
+    const sourceStats = readEntryStatSync(sourceUrl, {
+      nullIfNotFound: true,
+      followLink: false,
+    });
+    if (!sourceStats) {
+      if (allowUseless) {
+        return;
+      }
+      throw new Error(`nothing to remove at ${urlToFileSystemPath(sourceUrl)}`);
+    }
+
+    // https://nodejs.org/dist/latest-v13.x/docs/api/fs.html#fs_class_fs_stats
+    // FIFO and socket are ignored, not sure what they are exactly and what to do with them
+    // other libraries ignore them, let's do the same.
+    if (
+      sourceStats.isFile() ||
+      sourceStats.isSymbolicLink() ||
+      sourceStats.isCharacterDevice() ||
+      sourceStats.isBlockDevice()
+    ) {
+      removeNonDirectory(
+        sourceUrl.endsWith("/") ? sourceUrl.slice(0, -1) : sourceUrl,
+        {
+          maxRetries,
+          retryDelay,
+        },
+      );
+    } else if (sourceStats.isDirectory()) {
+      const directoryUrl = ensurePathnameTrailingSlash(sourceUrl);
+      removeDirectorySync(directoryUrl, {
+        signal: removeOperation.signal,
+        recursive,
+        maxRetries,
+        retryDelay,
+        onlyContent,
+      });
+    }
+  } finally {
+    removeOperation.end();
+  }
+};
+
+const removeNonDirectory = (sourceUrl) => {
+  const sourcePath = urlToFileSystemPath(sourceUrl);
+  const attempt = () => {
+    unlinkSyncNaive(sourcePath);
+  };
+  attempt();
+};
+
+const unlinkSyncNaive = (sourcePath, { handleTemporaryError = null } = {}) => {
+  try {
+    unlinkSync(sourcePath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return;
+    }
+    if (
+      handleTemporaryError &&
+      (error.code === "EBUSY" ||
+        error.code === "EMFILE" ||
+        error.code === "ENFILE" ||
+        error.code === "ENOENT")
+    ) {
+      handleTemporaryError(error);
+      return;
+    }
+    throw error;
+  }
+};
+
+const removeDirectorySync = (
+  rootDirectoryUrl,
+  { signal, maxRetries, retryDelay, recursive, onlyContent },
+) => {
+  const removeDirectoryOperation = Abort.startOperation();
+  removeDirectoryOperation.addAbortSignal(signal);
+
+  const visit = (sourceUrl) => {
+    removeDirectoryOperation.throwIfAborted();
+    const sourceStats = readEntryStatSync(sourceUrl, {
+      nullIfNotFound: true,
+      followLink: false,
+    });
+
+    // file/directory not found
+    if (sourceStats === null) {
+      return;
+    }
+
+    if (
+      sourceStats.isFile() ||
+      sourceStats.isCharacterDevice() ||
+      sourceStats.isBlockDevice()
+    ) {
+      visitFile(sourceUrl);
+    } else if (sourceStats.isSymbolicLink()) {
+      visitSymbolicLink(sourceUrl);
+    } else if (sourceStats.isDirectory()) {
+      visitDirectory(`${sourceUrl}/`);
+    }
+  };
+
+  const visitDirectory = (directoryUrl) => {
+    const directoryPath = urlToFileSystemPath(directoryUrl);
+    const optionsFromRecursive = recursive
+      ? {
+          handleNotEmptyError: () => {
+            removeDirectoryContent(directoryUrl);
+            visitDirectory(directoryUrl);
+          },
+        }
+      : {};
+    removeDirectoryOperation.throwIfAborted();
+    removeDirectorySyncNaive(directoryPath, {
+      ...optionsFromRecursive,
+      // Workaround for https://github.com/joyent/node/issues/4337
+      ...(process.platform === "win32"
+        ? {
+            handlePermissionError: (error) => {
+              console.error(
+                `trying to fix windows EPERM after readir on ${directoryPath}`,
+              );
+
+              let openOrCloseError;
+              try {
+                const fd = openSync(directoryPath);
+                closeSync(fd);
+              } catch (e) {
+                openOrCloseError = e;
+              }
+
+              if (openOrCloseError) {
+                if (openOrCloseError.code === "ENOENT") {
+                  return;
+                }
+                console.error(
+                  `error while trying to fix windows EPERM after readir on ${directoryPath}: ${openOrCloseError.stack}`,
+                );
+                throw error;
+              }
+              removeDirectorySyncNaive(directoryPath, {
+                ...optionsFromRecursive,
+              });
+            },
+          }
+        : {}),
+    });
+  };
+
+  const removeDirectoryContent = (directoryUrl) => {
+    removeDirectoryOperation.throwIfAborted();
+    const entryNames = readdirSync(new URL(directoryUrl));
+    for (const entryName of entryNames) {
+      const url = resolveUrl(entryName, directoryUrl);
+      visit(url);
+    }
+  };
+
+  const visitFile = (fileUrl) => {
+    removeNonDirectory(fileUrl, { maxRetries, retryDelay });
+  };
+
+  const visitSymbolicLink = (symbolicLinkUrl) => {
+    removeNonDirectory(symbolicLinkUrl, { maxRetries, retryDelay });
+  };
+
+  try {
+    if (onlyContent) {
+      removeDirectoryContent(rootDirectoryUrl);
+    } else {
+      visitDirectory(rootDirectoryUrl);
+    }
+  } finally {
+    removeDirectoryOperation.end();
+  }
+};
+
+const removeDirectorySyncNaive = (
+  directoryPath,
+  { handleNotEmptyError = null, handlePermissionError = null } = {},
+) => {
+  try {
+    rmdirSync(directoryPath);
+  } catch (error) {
+    if (handlePermissionError && error.code === "EPERM") {
+      handlePermissionError(error);
+      return;
+    }
+    if (error.code === "ENOENT") {
+      return;
+    }
+    if (
+      handleNotEmptyError &&
+      // linux os
+      (error.code === "ENOTEMPTY" ||
+        // SunOS
+        error.code === "EEXIST")
+    ) {
+      handleNotEmptyError(error);
+      return;
+    }
+    throw error;
+  }
+};

package/src/remove/remove_file.js

@@ -0,0 +1,5 @@
+import { removeEntry } from "./remove_entry.js";
+
+export const removeFile = (url, options) => {
+  return removeEntry(url, options);
+};

package/src/remove/remove_file_sync.js

@@ -0,0 +1,5 @@
+import { removeEntrySync } from "./remove_entry_sync.js";
+
+export const removeFileSync = (url, options) => {
+  return removeEntrySync(url, options);
+};

package/src/internal/getCommandArgument.js

@@ -1,27 +0,0 @@
-export const getCommandArgument = (argv, name) => {
-  let i = 0;
-
-  while (i < argv.length) {
-    const arg = argv[i];
-
-    if (arg === name) {
-      return {
-        name,
-        index: i,
-        value: "",
-      };
-    }
-
-    if (arg.startsWith(`${name}=`)) {
-      return {
-        name,
-        index: i,
-        value: arg.slice(`${name}=`.length),
-      };
-    }
-
-    i++;
-  }
-
-  return null;
-};