@jsenv/filesystem 2.0.0 → 2.3.0

package/README.md

@@ -1,18 +1,6 @@
-# Jsenv filesystem
+# Jsenv filesystem [![npm package](https://img.shields.io/npm/v/@jsenv/filesystem.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/filesystem) [![github main](https://github.com/jsenv/filesystem/workflows/main/badge.svg)](https://github.com/jsenv/filesystem/actions?workflow=main) [![codecov coverage](https://codecov.io/gh/jsenv/filesystem/branch/main/graph/badge.svg)](https://codecov.io/gh/jsenv/filesystem)
 
-Collection of functions to interact with filesystem in Node.js.
-
-[![npm package](https://img.shields.io/npm/v/@jsenv/filesystem.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/filesystem)
-[![github main](https://github.com/jsenv/filesystem/workflows/main/badge.svg)](https://github.com/jsenv/filesystem/actions?workflow=main)
-[![codecov coverage](https://codecov.io/gh/jsenv/filesystem/branch/main/graph/badge.svg)](https://codecov.io/gh/jsenv/filesystem)
-
-# Presentation
-
-`@jsenv/filesystem` provides functions needed to work with files. It has no external dependency.
-
-# Examples
-
-The whole list of functions exported by `@jsenv/filesystem` are documented in [./docs/API.md](./docs/API.md). This section demonstrates how `@jsenv/filesystem` can be used in common use cases.
+Collection of functions to interact with filesystem in Node.js
 
 ## Get a relative url
 
@@ -21,30 +9,29 @@ import { urlToRelativeUrl } from "@jsenv/filesystem"
 
 const projectDirectoryUrl = "file:///project/"
 const jsFileUrl = "file:///project/src/file.js"
-const relativeUrl = urlToRelativeUrl(jsFileUrl, projectDirectoryUrl) // "src/file.js"
+const relativeUrl = urlToRelativeUrl(jsFileUrl, projectDirectoryUrl)
+console.log(relativeUrl) // "src/file.js"
 ```
 
-## Collect files using pattern matching
+## List files using pattern matching
 
 ```js
-import { collectFiles } from "@jsenv/filesystem"
-
-const jsAndSourceMapFiles = await collectFiles({
-  directoryUrl: "file:///project/directory/",
-  structuredMetaMap: {
-    isJsFile: {
-      "./**/*.js": true,
-    },
-    isSourceMapFile: {
-      "./**/*.js.map": true,
-    },
-  },
-  predicate: ({ isJsFile, isSourceMapFile }) => isJsFile || isSourceMapFile,
-})
-console.log(jsAndSourceMapFiles.length)
+import { listFilesMatching } from "@jsenv/filesystem"
+
+const jsFiles = await listFilesMatching(
+  "./**/*.js",
+  new URL("./", import.meta.url),
+)
+```
+
+```console
+[
+  'file:///Users/dmail/docs/demo/a.js',
+  'file:///Users/dmail/docs/demo/b.js'
+]
 ```
 
-## Watch a specific file change
+## Watch a specific file changes
 
 ```js
 import { readFileSync } from "node:fs"
@@ -54,10 +41,10 @@ const packageJSONFileUrl = new URL("./package.json", import.meta.url)
 let packageJSON = null
 const unregister = registerFileLifecycle(packageJSONFileUrl, {
   added: () => {
-    packageJSON = JSON.parse(String(readFileSync(filePath)))
+    packageJSON = JSON.parse(String(readFileSync(packageJSONFileUrl)))
   },
   updated: () => {
-    packageJSON = JSON.parse(String(readFileSync(filePath)))
+    packageJSON = JSON.parse(String(readFileSync(packageJSONFileUrl)))
   },
   removed: () => {
     packageJSON = null
@@ -67,27 +54,31 @@ const unregister = registerFileLifecycle(packageJSONFileUrl, {
 unregister() // stop watching the file changes
 ```
 
-## Watch many file change
+## Watch many files changes
 
 ```js
 import { registerDirectoryLifecycle } from "@jsenv/filesystem"
 
-const contentMap = {}
+const directoryContentDescription = {}
 const unregister = registerDirectoryLifecycle("file:///directory/", {
   watchDescription: {
     "./**/*": true,
     "./node_modules/": false,
   },
   added: ({ relativeUrl, type }) => {
-    contentMap[relativeUrl] = type
+    directoryContentDescription[relativeUrl] = type
   },
   removed: ({ relativeUrl }) => {
-    delete contentMap[relativeUrl]
+    delete directoryContentDescription[relativeUrl]
   },
 })
 unregister() // stop watching the directory changes
 ```
 
+# API
+
+[docs/API.md](./docs/API.md)
+
 # Installation
 
 ```console

package/dist/commonjs/jsenv_filesystem.cjs

@@ -785,6 +785,7 @@ const collectFiles = async ({
           })
         });
         matchingFileResultArray.push({
+          url: new URL(relativeUrl, directoryUrl).href,
           relativeUrl,
           meta,
           fileStats: directoryChildNodeStats,
@@ -1040,8 +1041,7 @@ const removeDirectoryNaive = (directoryPath, {
           resolve(handlePermissionError(error));
         } else if (error.code === "ENOENT") {
           resolve();
-        } else if (handleNotEmptyError && ( // linux os
-        error.code === "ENOTEMPTY" || // SunOS
+        } else if (handleNotEmptyError && (error.code === "ENOTEMPTY" || // SunOS
         error.code === "EEXIST")) {
           resolve(handleNotEmptyError(error));
         } else {
@@ -1201,37 +1201,29 @@ const {
   symlink
 } = node_fs.promises;
 const isWindows$1 = 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
+ */
+
 const writeSymbolicLink = async ({
   from,
   to,
-  type
+  type,
+  allowUseless = false,
+  allowOverwrite = false
 }) => {
   const fromUrl = assertAndNormalizeFileUrl(from);
-  let toValue;
-
-  if (typeof to === "string") {
-    // absolute filesystem path
-    if (isFileSystemPath(to)) {
-      toValue = to;
-    } // relative url
-    else if (to.startsWith("./") || to.startsWith("../")) {
-        toValue = to;
-      } // absolute url
-      else {
-          const toUrl = String(new URL(to, fromUrl));
-          toValue = urlToFileSystemPath(toUrl);
-        }
-  } else if (to instanceof URL) {
-    toValue = urlToFileSystemPath(to);
-  } else {
-    throw new TypeError(`symbolic link to must be a string or an url, received ${to}`);
-  }
+  const toInfo = getToInfo(to, fromUrl);
 
   if (isWindows$1 && typeof type === "undefined") {
     // without this if you write a symbolic link without specifying the type on windows
     // you later get EPERM when doing stat on the symlink
-    const toUrl = resolveUrl(toValue, fromUrl);
-    const toStats = await readFileSystemNodeStat(toUrl, {
+    const toStats = await readFileSystemNodeStat(toInfo.url, {
       nullIfNotFound: true
     });
     type = toStats && toStats.isDirectory() ? "dir" : "file";
@@ -1240,18 +1232,77 @@ const writeSymbolicLink = async ({
   const symbolicLinkPath = urlToFileSystemPath(fromUrl);
 
   try {
-    await symlink(toValue, symbolicLinkPath, type);
+    await symlink(toInfo.value, symbolicLinkPath, type);
   } catch (error) {
     if (error.code === "ENOENT") {
       await ensureParentDirectories(fromUrl);
-      await symlink(toValue, symbolicLinkPath, type);
+      await symlink(toInfo.value, symbolicLinkPath, type);
       return;
     }
 
+    if (error.code === "EEXIST") {
+      if (allowUseless) {
+        const existingSymbolicLinkUrl = await readSymbolicLink(fromUrl);
+
+        if (existingSymbolicLinkUrl === toInfo.url) {
+          return;
+        }
+      }
+
+      if (allowOverwrite) {
+        await removeFileSystemNode(fromUrl);
+        await symlink(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}`);
+};
+
 const urlIsInsideOf = (url, otherUrl) => {
   const urlObject = new URL(url);
   const otherUrlObject = new URL(otherUrl);
@@ -1447,6 +1498,72 @@ const copyFileContentNaive = (filePath, fileDestinationPath) => {
   });
 };
 
+const copyDirectoryContent = async ({
+  from,
+  to,
+  overwrite,
+  followLink = true
+} = {}) => {
+  const fromUrl = assertAndNormalizeDirectoryUrl(from);
+  const fromPath = urlToFileSystemPath(fromUrl);
+  let toUrl = assertAndNormalizeDirectoryUrl(to);
+  let toPath = urlToFileSystemPath(toUrl);
+  const sourceStats = await readFileSystemNodeStat(fromUrl, {
+    nullIfNotFound: true,
+    followLink: false
+  });
+
+  if (!sourceStats) {
+    throw new Error(`no directory to copy content from at ${fromPath}`);
+  }
+
+  if (!sourceStats.isDirectory()) {
+    const sourceType = statsToType(sourceStats);
+    throw new Error(`found a ${sourceType} instead of a directory at ${fromPath}`);
+  }
+
+  let destinationStats = await readFileSystemNodeStat(toUrl, {
+    nullIfNotFound: true,
+    // we force false here but in fact we will follow the destination link
+    // to know where we will actually move and detect useless move overrite etc..
+    followLink: false
+  });
+
+  if (followLink && destinationStats && destinationStats.isSymbolicLink()) {
+    const linkTarget = await readSymbolicLink(toUrl);
+    toUrl = resolveUrl(linkTarget, toUrl);
+    toPath = urlToFileSystemPath(toUrl);
+    destinationStats = await readFileSystemNodeStat(toUrl, {
+      nullIfNotFound: true
+    });
+  }
+
+  if (destinationStats === null) {
+    throw new Error(`no directory to copy content into at ${toPath}`);
+  }
+
+  if (!destinationStats.isDirectory()) {
+    const destinationType = statsToType(destinationStats);
+    throw new Error(`destination leads to a ${destinationType} instead of a directory at ${toPath}`);
+  }
+
+  if (urlTargetsSameFileSystemPath(fromUrl, toUrl)) {
+    throw new Error(`cannot copy directory content, source and destination are the same (${fromPath})`);
+  }
+
+  const directoryEntries = await readDirectory(fromUrl);
+  await Promise.all(directoryEntries.map(async directoryEntry => {
+    const from = resolveUrl(directoryEntry, fromUrl);
+    const to = resolveUrl(directoryEntry, toUrl);
+    await copyFileSystemNode({
+      from,
+      to,
+      overwrite,
+      followLink
+    });
+  }));
+};
+
 /*
  * - file modes documentation on Node.js
  *   https://nodejs.org/docs/latest-v13.x/api/fs.html#fs_file_modes
@@ -1492,6 +1609,35 @@ const grantPermissionsOnFileSystemNode = async (source, {
   };
 };
 
+const listFilesMatching = async (patterns, directoryUrl = process.cwd()) => {
+  if (typeof patterns === "string") {
+    patterns = [patterns];
+  } else if (Array.isArray(patterns)) {
+    throw new TypeError(`patterns must be a string or an array of strings, got ${patterns}`);
+  }
+
+  const patternMap = {};
+  patterns.forEach((pattern, index) => {
+    if (typeof pattern !== "string") {
+      throw new TypeError(`every pattern must be a string, found ${pattern} at index ${index}`);
+    }
+
+    patternMap[pattern] = true;
+  });
+  const fileDatas = await collectFiles({
+    directoryUrl,
+    structuredMetaMap: {
+      matches: patternMap
+    },
+    predicate: ({
+      matches
+    }) => matches
+  });
+  return fileDatas.map(({
+    url
+  }) => url);
+};
+
 const memoize = compute => {
   let memoized = false;
   let memoizedValue;
@@ -2464,6 +2610,7 @@ exports.bufferToEtag = bufferToEtag;
 exports.collectDirectoryMatchReport = collectDirectoryMatchReport;
 exports.collectFiles = collectFiles;
 exports.comparePathnames = comparePathnames;
+exports.copyDirectoryContent = copyDirectoryContent;
 exports.copyFileSystemNode = copyFileSystemNode;
 exports.ensureEmptyDirectory = ensureEmptyDirectory;
 exports.ensureParentDirectories = ensureParentDirectories;
@@ -2471,6 +2618,7 @@ exports.ensureWindowsDriveLetter = ensureWindowsDriveLetter;
 exports.fileSystemPathToUrl = fileSystemPathToUrl;
 exports.grantPermissionsOnFileSystemNode = grantPermissionsOnFileSystemNode;
 exports.isFileSystemPath = isFileSystemPath;
+exports.listFilesMatching = listFilesMatching;
 exports.memoize = memoize;
 exports.moveDirectoryContent = moveDirectoryContent;
 exports.moveFileSystemNode = moveFileSystemNode;