@jsenv/filesystem 2.0.0 → 2.3.0

package/src/registerDirectoryLifecycle.js

@@ -1,6 +1,10 @@
 /* eslint-disable import/max-dependencies */
 import { readdirSync } from "fs"
-import { normalizeStructuredMetaMap, urlCanContainsMetaMatching, urlToMeta } from "@jsenv/url-meta"
+import {
+  normalizeStructuredMetaMap,
+  urlCanContainsMetaMatching,
+  urlToMeta,
+} from "@jsenv/url-meta"
 import { replaceBackSlashesWithSlashes } from "./internal/replaceBackSlashesWithSlashes.js"
 import { fileSystemNodeToTypeOrNull } from "./internal/fileSystemNodeToTypeOrNull.js"
 import { createWatcher } from "./internal/createWatcher.js"
@@ -34,13 +38,20 @@ export const registerDirectoryLifecycle = (
     throw new TypeError(`added must be a function or undefined, got ${added}`)
   }
   if (!undefinedOrFunction(updated)) {
-    throw new TypeError(`updated must be a function or undefined, got ${updated}`)
+    throw new TypeError(
+      `updated must be a function or undefined, got ${updated}`,
+    )
   }
   if (!undefinedOrFunction(removed)) {
-    throw new TypeError(`removed must be a function or undefined, got ${removed}`)
+    throw new TypeError(
+      `removed must be a function or undefined, got ${removed}`,
+    )
   }
 
-  const structuredMetaMap = normalizeStructuredMetaMap({ watch: watchDescription }, sourceUrl)
+  const structuredMetaMap = normalizeStructuredMetaMap(
+    { watch: watchDescription },
+    sourceUrl,
+  )
   const entryShouldBeWatched = ({ relativeUrl, type }) => {
     const entryUrl = resolveUrl(relativeUrl, sourceUrl)
 
@@ -65,7 +76,11 @@ export const registerDirectoryLifecycle = (
 
   const contentMap = new Map()
 
-  const handleDirectoryEvent = ({ directoryRelativeUrl, filename, eventType }) => {
+  const handleDirectoryEvent = ({
+    directoryRelativeUrl,
+    filename,
+    eventType,
+  }) => {
     if (filename) {
       if (directoryRelativeUrl) {
         handleChange(`${directoryRelativeUrl}/${filename}`)
@@ -79,29 +94,36 @@ export const registerDirectoryLifecycle = (
       let relativeUrlCandidateArray = Array.from(contentMap.keys())
 
       if (recursive && !fsWatchSupportsRecursive) {
-        relativeUrlCandidateArray = relativeUrlCandidateArray.filter((relativeUrlCandidate) => {
-          if (!directoryRelativeUrl) {
-            // ensure entry is top level
-            if (relativeUrlCandidate.includes("/")) return false
-            return true
-          }
-
-          // entry not inside this directory
-          if (!relativeUrlCandidate.startsWith(directoryRelativeUrl)) return false
-
-          const afterDirectory = relativeUrlCandidate.slice(directoryRelativeUrl.length + 1)
-          // deep inside this directory
-          if (afterDirectory.includes("/")) return false
+        relativeUrlCandidateArray = relativeUrlCandidateArray.filter(
+          (relativeUrlCandidate) => {
+            if (!directoryRelativeUrl) {
+              // ensure entry is top level
+              if (relativeUrlCandidate.includes("/")) return false
+              return true
+            }
+
+            // entry not inside this directory
+            if (!relativeUrlCandidate.startsWith(directoryRelativeUrl))
+              return false
+
+            const afterDirectory = relativeUrlCandidate.slice(
+              directoryRelativeUrl.length + 1,
+            )
+            // deep inside this directory
+            if (afterDirectory.includes("/")) return false
 
-          return true
-        })
+            return true
+          },
+        )
       }
 
-      const removedEntryRelativeUrl = relativeUrlCandidateArray.find((relativeUrlCandidate) => {
-        const entryUrl = resolveUrl(relativeUrlCandidate, sourceUrl)
-        const type = fileSystemNodeToTypeOrNull(entryUrl)
-        return type === null
-      })
+      const removedEntryRelativeUrl = relativeUrlCandidateArray.find(
+        (relativeUrlCandidate) => {
+          const entryUrl = resolveUrl(relativeUrlCandidate, sourceUrl)
+          const type = fileSystemNodeToTypeOrNull(entryUrl)
+          return type === null
+        },
+      )
 
       if (removedEntryRelativeUrl) {
         handleEntryLost({
@@ -201,7 +223,9 @@ export const registerDirectoryLifecycle = (
 
     // we must watch manually every directory we find
     if (!fsWatchSupportsRecursive && type === "directory") {
-      const watcher = createWatcher(urlToFileSystemPath(entryUrl), { persistent: keepProcessAlive })
+      const watcher = createWatcher(urlToFileSystemPath(entryUrl), {
+        persistent: keepProcessAlive,
+      })
       tracker.registerCleanupCallback(() => {
         watcher.close()
       })
@@ -246,7 +270,8 @@ export const registerDirectoryLifecycle = (
   return tracker.cleanup
 }
 
-const undefinedOrFunction = (value) => typeof value === "undefined" || typeof value === "function"
+const undefinedOrFunction = (value) =>
+  typeof value === "undefined" || typeof value === "function"
 
 const visitDirectory = ({ directoryUrl, entryFound }) => {
   const directoryPath = urlToFileSystemPath(directoryUrl)

package/src/registerFileLifecycle.js

@@ -14,10 +14,14 @@ export const registerFileLifecycle = (
     throw new TypeError(`added must be a function or undefined, got ${added}`)
   }
   if (!undefinedOrFunction(updated)) {
-    throw new TypeError(`updated must be a function or undefined, got ${updated}`)
+    throw new TypeError(
+      `updated must be a function or undefined, got ${updated}`,
+    )
   }
   if (!undefinedOrFunction(removed)) {
-    throw new TypeError(`removed must be a function or undefined, got ${removed}`)
+    throw new TypeError(
+      `removed must be a function or undefined, got ${removed}`,
+    )
   }
 
   const tracker = trackRessources()
@@ -34,7 +38,9 @@ export const registerFileLifecycle = (
       },
       keepProcessAlive,
     })
-    const fileMutationStopTracking = tracker.registerCleanupCallback(fileMutationStopWatching)
+    const fileMutationStopTracking = tracker.registerCleanupCallback(
+      fileMutationStopWatching,
+    )
 
     if (added) {
       if (existent) {
@@ -56,7 +62,9 @@ export const registerFileLifecycle = (
       },
       keepProcessAlive,
     )
-    const fileCreationgStopTracking = tracker.registerCleanupCallback(fileCreationStopWatching)
+    const fileCreationgStopTracking = tracker.registerCleanupCallback(
+      fileCreationStopWatching,
+    )
   }
 
   const sourceType = fileSystemNodeToTypeOrNull(sourceUrl)
@@ -64,24 +72,33 @@ export const registerFileLifecycle = (
     if (added) {
       watchFileAdded()
     } else {
-      throw new Error(`${urlToFileSystemPath(sourceUrl)} must lead to a file, found nothing`)
+      throw new Error(
+        `${urlToFileSystemPath(sourceUrl)} must lead to a file, found nothing`,
+      )
     }
   } else if (sourceType === "file") {
     handleFileFound({ existent: true })
   } else {
-    throw new Error(`${urlToFileSystemPath(sourceUrl)} must lead to a file, type found instead`)
+    throw new Error(
+      `${urlToFileSystemPath(
+        sourceUrl,
+      )} must lead to a file, type found instead`,
+    )
   }
 
   return tracker.cleanup
 }
 
-const undefinedOrFunction = (value) => typeof value === "undefined" || typeof value === "function"
+const undefinedOrFunction = (value) =>
+  typeof value === "undefined" || typeof value === "function"
 
 const watchFileCreation = (source, callback, keepProcessAlive) => {
   const sourcePath = urlToFileSystemPath(source)
   const sourceFilename = basename(sourcePath)
   const directoryPath = dirname(sourcePath)
-  let directoryWatcher = createWatcher(directoryPath, { persistent: keepProcessAlive })
+  let directoryWatcher = createWatcher(directoryPath, {
+    persistent: keepProcessAlive,
+  })
   directoryWatcher.on("change", (eventType, filename) => {
     if (filename && filename !== sourceFilename) return
 
@@ -102,8 +119,13 @@ const watchFileCreation = (source, callback, keepProcessAlive) => {
   }
 }
 
-const watchFileMutation = (sourceUrl, { updated, removed, keepProcessAlive }) => {
-  let watcher = createWatcher(urlToFileSystemPath(sourceUrl), { persistent: keepProcessAlive })
+const watchFileMutation = (
+  sourceUrl,
+  { updated, removed, keepProcessAlive },
+) => {
+  let watcher = createWatcher(urlToFileSystemPath(sourceUrl), {
+    persistent: keepProcessAlive,
+  })
 
   watcher.on("change", () => {
     const sourceType = fileSystemNodeToTypeOrNull(sourceUrl)

package/src/removeFileSystemNode.js

@@ -39,10 +39,13 @@ export const removeFileSystemNode = async (
     sourceStats.isCharacterDevice() ||
     sourceStats.isBlockDevice()
   ) {
-    await removeNonDirectory(sourceUrl.endsWith("/") ? sourceUrl.slice(0, -1) : sourceUrl, {
-      maxRetries,
-      retryDelay,
-    })
+    await removeNonDirectory(
+      sourceUrl.endsWith("/") ? sourceUrl.slice(0, -1) : sourceUrl,
+      {
+        maxRetries,
+        retryDelay,
+      },
+    )
   } else if (sourceStats.isDirectory()) {
     await removeDirectory(ensureUrlTrailingSlash(sourceUrl), {
       recursive,
@@ -115,7 +118,11 @@ const removeDirectory = async (
       return
     }
 
-    if (sourceStats.isFile() || sourceStats.isCharacterDevice() || sourceStats.isBlockDevice()) {
+    if (
+      sourceStats.isFile() ||
+      sourceStats.isCharacterDevice() ||
+      sourceStats.isBlockDevice()
+    ) {
       await visitFile(sourceUrl)
     } else if (sourceStats.isSymbolicLink()) {
       await visitSymbolicLink(sourceUrl)
@@ -140,7 +147,9 @@ const removeDirectory = async (
       ...(process.platform === "win32"
         ? {
             handlePermissionError: async (error) => {
-              console.error(`trying to fix windows EPERM after readir on ${directoryPath}`)
+              console.error(
+                `trying to fix windows EPERM after readir on ${directoryPath}`,
+              )
 
               let openOrCloseError
               try {
@@ -160,7 +169,9 @@ const removeDirectory = async (
                 throw error
               }
 
-              await removeDirectoryNaive(directoryPath, { ...optionsFromRecursive })
+              await removeDirectoryNaive(directoryPath, {
+                ...optionsFromRecursive,
+              })
             },
           }
         : {}),

package/src/testFileSystemNodePermissions.js

@@ -12,7 +12,12 @@ const {
 
 export const testFileSystemNodePermissions = async (
   source,
-  { read = false, write = false, execute = false, allowedIfNotFound = false } = {},
+  {
+    read = false,
+    write = false,
+    execute = false,
+    allowedIfNotFound = false,
+  } = {},
 ) => {
   const sourceUrl = assertAndNormalizeFileUrl(source)
   const sourcePath = urlToFileSystemPath(sourceUrl)

package/src/urlToBasename.js

@@ -3,6 +3,7 @@ import { urlToFilename } from "./urlToFilename.js"
 export const urlToBasename = (url) => {
   const filename = urlToFilename(url)
   const dotLastIndex = filename.lastIndexOf(".")
-  const basename = dotLastIndex === -1 ? filename : filename.slice(0, dotLastIndex)
+  const basename =
+    dotLastIndex === -1 ? filename : filename.slice(0, dotLastIndex)
   return basename
 }

package/src/urlToFilename.js

@@ -2,7 +2,9 @@ import { urlToPathname } from "./urlToPathname.js"
 
 export const urlToFilename = (url) => {
   const pathname = urlToPathname(url)
-  const pathnameBeforeLastSlash = pathname.endsWith("/") ? pathname.slice(0, -1) : pathname
+  const pathnameBeforeLastSlash = pathname.endsWith("/")
+    ? pathname.slice(0, -1)
+    : pathname
   const slashLastIndex = pathnameBeforeLastSlash.lastIndexOf("/")
   const filename =
     slashLastIndex === -1

package/src/urlToParentUrl.js

@@ -11,7 +11,10 @@ export const urlToParentUrl = (url) => {
 
   const lastCharacterIndex = ressource.length - 1
   if (slashLastIndex === lastCharacterIndex) {
-    const slashPreviousIndex = ressource.lastIndexOf("/", lastCharacterIndex - 1)
+    const slashPreviousIndex = ressource.lastIndexOf(
+      "/",
+      lastCharacterIndex - 1,
+    )
     if (slashPreviousIndex === -1) {
       const urlAsString = String(url)
       return urlAsString

package/src/urlToPathname.js

@@ -8,5 +8,7 @@ export const urlToPathname = (url) => {
 
 const ressourceToPathname = (ressource) => {
   const searchSeparatorIndex = ressource.indexOf("?")
-  return searchSeparatorIndex === -1 ? ressource : ressource.slice(0, searchSeparatorIndex)
+  return searchSeparatorIndex === -1
+    ? ressource
+    : ressource.slice(0, searchSeparatorIndex)
 }

package/src/urlToRelativeUrl.js

@@ -35,8 +35,12 @@ export const urlToRelativeUrl = (url, baseUrl) => {
   const specificPathname = pathname.slice(commonPathname.length)
   const baseSpecificPathname = basePathname.slice(commonPathname.length)
   if (baseSpecificPathname.includes("/")) {
-    const baseSpecificParentPathname = pathnameToParentPathname(baseSpecificPathname)
-    const relativeDirectoriesNotation = baseSpecificParentPathname.replace(/.*?\//g, "../")
+    const baseSpecificParentPathname =
+      pathnameToParentPathname(baseSpecificPathname)
+    const relativeDirectoriesNotation = baseSpecificParentPathname.replace(
+      /.*?\//g,
+      "../",
+    )
     const relativeUrl = `${relativeDirectoriesNotation}${specificPathname}${search}${hash}`
     return relativeUrl
   }

package/src/writeFileSystemNodeModificationTime.js

@@ -5,7 +5,8 @@ import { urlToFileSystemPath } from "./urlToFileSystemPath.js"
 export const writeFileSystemNodeModificationTime = (source, mtime) => {
   const sourceUrl = assertAndNormalizeFileUrl(source)
   const sourcePath = urlToFileSystemPath(sourceUrl)
-  const mtimeValue = typeof mtime === "number" ? new Date(Math.floor(mtime)) : mtime
+  const mtimeValue =
+    typeof mtime === "number" ? new Date(Math.floor(mtime)) : mtime
   // reading atime mutates its value so there is no use case I can think of
   // where we want to modify it
   const atimeValue = mtimeValue

package/src/writeFileSystemNodePermissions.js

@@ -23,7 +23,11 @@ export const writeFileSystemNodePermissions = async (source, permissions) => {
       others: {
         read: getPermissionOrComputeDefault("read", "others", permissions),
         write: getPermissionOrComputeDefault("write", "others", permissions),
-        execute: getPermissionOrComputeDefault("execute", "others", permissions),
+        execute: getPermissionOrComputeDefault(
+          "execute",
+          "others",
+          permissions,
+        ),
       },
     }
     binaryFlags = permissionsToBinaryFlags(permissions)

package/src/writeSymbolicLink.js

@@ -1,57 +1,113 @@
 import { promises } from "node:fs"
 
 import { assertAndNormalizeFileUrl } from "./assertAndNormalizeFileUrl.js"
+import { fileSystemPathToUrl } from "./fileSystemPathToUrl.js"
 import { urlToFileSystemPath } from "./urlToFileSystemPath.js"
 import { resolveUrl } from "./resolveUrl.js"
 import { isFileSystemPath } from "./isFileSystemPath.js"
 import { ensureParentDirectories } from "./ensureParentDirectories.js"
 import { readFileSystemNodeStat } from "./readFileSystemNodeStat.js"
+import { readSymbolicLink } from "./readSymbolicLink.js"
+import { removeFileSystemNode } from "./removeFileSystemNode.js"
 
 // https://nodejs.org/dist/latest-v13.x/docs/api/fs.html#fs_fspromises_symlink_target_path_type
 const { symlink } = promises
 const isWindows = process.platform === "win32"
 
-export const writeSymbolicLink = async ({ from, to, type }) => {
+/**
+ * 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 writeSymbolicLink = async ({
+  from,
+  to,
+  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 && 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, { nullIfNotFound: true })
+    const toStats = await readFileSystemNodeStat(toInfo.url, {
+      nullIfNotFound: true,
+    })
     type = toStats && toStats.isDirectory() ? "dir" : "file"
   }
 
   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}`,
+  )
+}