@jsenv/filesystem 4.10.13 → 4.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/filesystem",
-  "version": "4.10.13",
+  "version": "4.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/lifecycle/call_once_idle.js

@@ -0,0 +1,32 @@
+export const callOnceIdle = (callback, idleMs) => {
+  let timeoutId;
+  return (...args) => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      callback(...args);
+    }, idleMs);
+    if (timeoutId.unref) {
+      timeoutId.unref();
+    }
+  };
+};
+
+export const callOnceIdlePerFile = (callback, idleMs) => {
+  const timeoutIdMap = new Map();
+  return (fileEvent) => {
+    const { relativeUrl } = fileEvent;
+    let timeoutId = timeoutIdMap.get(relativeUrl);
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      callback(fileEvent);
+    }, idleMs);
+    if (timeoutId.unref) {
+      timeoutId.unref();
+    }
+    timeoutIdMap.set(relativeUrl, timeoutId);
+  };
+};

package/src/lifecycle/register_directory_lifecycle.js

@@ -4,6 +4,7 @@ import { readdirSync } from "node:fs";
 import { assertAndNormalizeDirectoryUrl } from "../path_and_url/directory_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 { callOnceIdlePerFile } from "./call_once_idle.js";
 import { createWatcher } from "./create_watcher.js";
 import { guardTooFastSecondCallPerFile } from "./guard_second_call.js";
 import { trackResources } from "./track_resources.js";
@@ -30,6 +31,7 @@ export const registerDirectoryLifecycle = (
     // For this reason"cooldownBetweenFileEvents" should be reserved to scenarios
     // like unit tests
     cooldownBetweenFileEvents = 0,
+    idleMs = 50,
   },
 ) => {
   const sourceUrl = assertAndNormalizeDirectoryUrl(source);
@@ -46,6 +48,11 @@ export const registerDirectoryLifecycle = (
       `removed must be a function or undefined, got ${removed}`,
     );
   }
+  if (idleMs) {
+    if (updated) {
+      updated = callOnceIdlePerFile(updated, idleMs);
+    }
+  }
   if (cooldownBetweenFileEvents) {
     if (added) {
       added = guardTooFastSecondCallPerFile(added, cooldownBetweenFileEvents);

package/src/lifecycle/register_file_lifecycle.js

@@ -3,6 +3,7 @@ import { basename, dirname } from "node:path";
 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 { callOnceIdle } from "./call_once_idle.js";
 import { createWatcher } from "./create_watcher.js";
 import { guardTooFastSecondCall } from "./guard_second_call.js";
 import { trackResources } from "./track_resources.js";
@@ -16,6 +17,7 @@ export const registerFileLifecycle = (
     notifyExistent = false,
     keepProcessAlive = true,
     cooldownBetweenFileEvents = 0,
+    idleMs = 50,
   },
 ) => {
   const sourceUrl = assertAndNormalizeFileUrl(source);
@@ -32,6 +34,11 @@ export const registerFileLifecycle = (
       `removed must be a function or undefined, got ${removed}`,
     );
   }
+  if (idleMs) {
+    if (updated) {
+      updated = callOnceIdle(updated, idleMs);
+    }
+  }
   if (cooldownBetweenFileEvents) {
     if (added) {
       added = guardTooFastSecondCall(added, cooldownBetweenFileEvents);

package/src/main.js

@@ -17,6 +17,8 @@ export {
 } from "./path_and_url/file_url_validation.js";
 export { comparePathnames } from "./path_and_url/compare_pathnames.js";
 export { ensureWindowsDriveLetter } from "./path_and_url/ensure_windows_drive_letter.js";
+export { getParentDirectoryUrl } from "./path_and_url/get_parent_directory_url.js";
+export { findAncestorDirectoryUrl } from "./path_and_url/find_ancestor_directory_url.js";
 
 // list
 export { collectDirectoryMatchReport } from "./list/collect_directory_match_report.js";

package/src/path_and_url/find_ancestor_directory_url.js

@@ -0,0 +1,12 @@
+import { getParentDirectoryUrl } from "./get_parent_directory_url.js";
+
+export const findAncestorDirectoryUrl = (url, callback) => {
+  url = String(url);
+  while (url !== "file:///") {
+    if (callback(url)) {
+      return url;
+    }
+    url = getParentDirectoryUrl(url);
+  }
+  return null;
+};

package/src/path_and_url/get_parent_directory_url.js

@@ -0,0 +1,24 @@
+export const getParentDirectoryUrl = (url) => {
+  if (url.startsWith("file://")) {
+    // With node.js new URL('../', 'file:///C:/').href
+    // returns "file:///C:/" instead of "file:///"
+    const resource = url.slice("file://".length);
+    const slashLastIndex = resource.lastIndexOf("/");
+    if (slashLastIndex === -1) {
+      return url;
+    }
+    const lastCharIndex = resource.length - 1;
+    if (slashLastIndex === lastCharIndex) {
+      const slashBeforeLastIndex = resource.lastIndexOf(
+        "/",
+        slashLastIndex - 1,
+      );
+      if (slashBeforeLastIndex === -1) {
+        return url;
+      }
+      return `file://${resource.slice(0, slashBeforeLastIndex + 1)}`;
+    }
+    return `file://${resource.slice(0, slashLastIndex + 1)}`;
+  }
+  return new URL(url.endsWith("/") ? "../" : "./", url).href;
+};

package/src/read_write/write_directory_sync.js

@@ -1,21 +1,59 @@
 import { urlToFileSystemPath } from "@jsenv/urls";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, statSync, unlinkSync } from "node:fs";
 
 import { assertAndNormalizeDirectoryUrl } from "../path_and_url/directory_url_validation.js";
+import { findAncestorDirectoryUrl } from "../path_and_url/find_ancestor_directory_url.js";
 import { readEntryStatSync } from "./stat/read_entry_stat_sync.js";
 import { statsToType } from "./stat/stats_to_type.js";
 
 export const writeDirectorySync = (
   destination,
-  { recursive = true, allowUseless = false } = {},
+  { recursive = true, allowUseless = false, force } = {},
 ) => {
   const destinationUrl = assertAndNormalizeDirectoryUrl(destination);
   const destinationPath = urlToFileSystemPath(destinationUrl);
 
-  const destinationStats = readEntryStatSync(destinationUrl, {
-    nullIfNotFound: true,
-    followLink: false,
-  });
+  let destinationStats;
+  try {
+    destinationStats = readEntryStatSync(destinationUrl, {
+      nullIfNotFound: true,
+      followLink: false,
+    });
+  } catch (e) {
+    if (e.code === "ENOTDIR") {
+      let previousNonDirUrl = destinationUrl;
+      // we must try all parent directories as long as it fails with ENOTDIR
+      findAncestorDirectoryUrl(destinationUrl, (ancestorUrl) => {
+        try {
+          statSync(new URL(ancestorUrl));
+          return true;
+        } catch (e) {
+          if (e.code === "ENOTDIR") {
+            previousNonDirUrl = ancestorUrl;
+            return false;
+          }
+          throw e;
+        }
+      });
+      if (force) {
+        unlinkSync(
+          new URL(
+            previousNonDirUrl
+              // remove trailing slash
+              .slice(0, -1),
+          ),
+        );
+      } else {
+        throw new Error(
+          `cannot write directory at ${destinationPath} because there is a file at ${urlToFileSystemPath(
+            previousNonDirUrl,
+          )}`,
+        );
+      }
+    } else {
+      throw e;
+    }
+  }
 
   if (destinationStats) {
     if (destinationStats.isDirectory()) {
@@ -24,7 +62,6 @@ export const writeDirectorySync = (
       }
       throw new Error(`directory already exists at ${destinationPath}`);
     }
-
     const destinationType = statsToType(destinationStats);
     throw new Error(
       `cannot write directory at ${destinationPath} because there is a ${destinationType}`,

package/src/read_write/write_file_sync.js

@@ -1,12 +1,10 @@
-import {
-  mkdirSync,
-  readFileSync,
-  writeFileSync as writeFileSyncNode,
-} from "node:fs";
+import { readFileSync, writeFileSync as writeFileSyncNode } from "node:fs";
 
 import { assertAndNormalizeFileUrl } from "../path_and_url/file_url_validation.js";
+import { removeDirectorySync } from "../remove/remove_directory_sync.js";
+import { writeDirectorySync } from "./write_directory_sync.js";
 
-export const writeFileSync = (destination, content = "") => {
+export const writeFileSync = (destination, content = "", { force } = {}) => {
   const destinationUrl = assertAndNormalizeFileUrl(destination);
   const destinationUrlObject = new URL(destinationUrl);
   if (content && content instanceof URL) {
@@ -15,8 +13,18 @@ export const writeFileSync = (destination, content = "") => {
   try {
     writeFileSyncNode(destinationUrlObject, content);
   } catch (error) {
-    if (error.code === "ENOENT") {
-      mkdirSync(new URL("./", destinationUrlObject), {
+    if (error.code === "EISDIR") {
+      // happens when directory existed but got deleted and now it's a file
+      if (force) {
+        removeDirectorySync(destinationUrlObject);
+        writeFileSyncNode(destinationUrlObject, content);
+      } else {
+        throw error;
+      }
+    }
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") {
+      writeDirectorySync(new URL("./", destinationUrlObject), {
+        force,
         recursive: true,
       });
       writeFileSyncNode(destinationUrlObject, content);