@ix-xs/node-comfort 1.0.0

package/core/FS.js

@@ -0,0 +1,765 @@
+const dotenv = require("@dotenvx/dotenvx");
+const {
+  readdirSync,
+  existsSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  unlinkSync,
+  copyFileSync,
+  readFileSync,
+  watch,
+} = require("node:fs");
+const {
+  resolve,
+  dirname,
+  sep,
+  isAbsolute,
+  join,
+  relative,
+  basename,
+} = require("node:path");
+
+/**
+ * Normalizes path separators for cross-platform compatibility.
+ * @private
+ * @param {string} path - Path to normalize.
+ * @returns {string} Normalized path.
+ */
+const _format = (path) => {
+  return path.replace(/\//g, sep).replace(/\\/g, sep);
+};
+
+/**
+ * Detects the caller's file path from stack trace (excludes node_modules/internal).
+ * @private
+ * @returns {string|undefined} Caller file path or undefined.
+ */
+const _caller = () => {
+  const opst = Error.prepareStackTrace;
+  Error.prepareStackTrace = (_, stack) => stack;
+  const e = new Error();
+  const s = e.stack;
+  Error.prepareStackTrace = opst;
+
+  if (s) {
+    for (const cs of s) {
+      const name = cs.getFileName();
+      if (
+        name &&
+				!name.startsWith("node:internal") &&
+				!name.includes("node_modules") &&
+				name !== s[0].getFileName()
+      ) {
+        return _format(name);
+      }
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Recursively walks directory returning files or folders.
+ * @private
+ * @param {string} path - Directory path.
+ * @param {boolean} [recursive=true] - Include subdirectories.
+ * @param {"folder"|"file"} [type="folder"] - Filter type.
+ * @returns {string[]} Array of matching paths.
+ */
+const _walk = (path = process.cwd(), recursive = true, type = "folder") => {
+  let result = [];
+  try {
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+      if (entry.name.includes("node_modules")) continue;
+      const _ = resolve(path, entry.name);
+
+      if (type === "folder" && entry.isDirectory()) {
+        result.push(_);
+        if (recursive) result = result.concat(_walk(_, recursive, type));
+      } else if (type === "file" && entry.isFile()) {
+        result.push(_);
+      } else if (type === "file" && entry.isDirectory() && recursive) {
+        result = result.concat(_walk(_, recursive, type));
+      }
+    }
+    return result;
+  } catch (error) {
+    return result;
+  }
+};
+
+/**
+ * Finds first matching folder recursively from root.
+ * @private
+ * @param {string} path - Starting path.
+ * @param {string} name - Folder name to find.
+ * @returns {string|undefined} First matching folder path.
+ */
+const _firstFolder = (path, name) => {
+  try {
+    const entries = readdirSync(path, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === name && entry.isDirectory()) {
+        return resolve(path, name);
+      }
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && !entry.name.includes("node_modules")) {
+        const result = _firstFolder(resolve(path, entry.name), name);
+        if (result) return result;
+      }
+    }
+  } catch {}
+  return undefined;
+};
+
+/**
+ * Finds first matching file recursively from root.
+ * @private
+ * @param {string} path - Starting path.
+ * @param {string} name - File name to find.
+ * @returns {string|undefined} First matching file path.
+ */
+const _firstFile = (path, name) => {
+  try {
+    const entries = readdirSync(path, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === name && entry.isFile()) {
+        return resolve(path, name);
+      }
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && !entry.name.includes("node_modules")) {
+        const result = _firstFile(resolve(path, entry.name), name);
+        if (result) return result;
+      }
+    }
+  } catch {}
+  return undefined;
+};
+
+/**
+ * Resolves target path with smart relative/absolute/caller context detection.
+ * @private
+ * @param {string} [path=process.cwd()] - Path to resolve.
+ * @param {"folder"|"file"} [type="folder"] - Resolution type.
+ * @returns {string|undefined} Resolved absolute path or undefined.
+ */
+const _target = (path = process.cwd(), type = "folder") => {
+  if (path === process.cwd()) return path;
+
+  let absolute;
+  const caller = dirname(_caller() || process.cwd());
+
+  if (
+    _format(path).startsWith(_format("./")) ||
+		_format(path).startsWith(_format("../"))
+  ) {
+    absolute = resolve(caller, path);
+  } else if (isAbsolute(path)) {
+    absolute = _format(path);
+  } else {
+    absolute = resolve(process.cwd(), _format(path));
+    if (!existsSync(absolute)) {
+      absolute =
+				type === "folder"
+				  ? (_firstFolder(process.cwd(), _format(path)) ?? undefined)
+				  : (_firstFile(process.cwd(), _format(path)) ?? undefined);
+    }
+  }
+
+  if (absolute && existsSync(absolute)) return _format(absolute);
+  return undefined;
+};
+
+/**
+ * @module FS
+ * @description
+ * Comprehensive synchronous file system utilities with intelligent path resolution,
+ * caller context awareness, and cross-platform support.
+ *
+ * Handles relative/absolute paths relative to caller file, recursive operations,
+ * file/folder watching, and bulk copy/move operations. Automatically skips `node_modules`.
+ *
+ * @example
+ * const nodeComfort = require("@ix-xs/node-comfort");
+ *
+ * // Create folder structure
+ * nodeComfort.createFolder("./data/users");
+ *
+ * // Write JSON file
+ * nodeComfort.createFile("./data/users.json", false, { users: [] });
+ *
+ * // List all files recursively
+ * console.log(nodeComfort.getFilesIn("./data"));
+ *
+ * // Watch for changes
+ * const watcher = nodeComfort.watch({ path: "./data", recursive: true });
+ * watcher.on("change", (file) => console.log("File changed:", file));
+ */
+module.exports = {
+  /**
+	 * Safely read an environment variable.
+	 *
+	 * Loads variables from the default `.env` file (if present) and then
+	 * returns the value for the given key. When `options.envFile` is provided,
+	 * the function expects `process.env[options.envFile]` to be an object
+	 * containing namespaced environment variables (e.g. per environment).
+	 *
+	 * @param {string} env - Environment variable name (e.g. "PORT").
+	 * @param {object} [options] - Optional configuration object.
+	 * @param {string} [options.envFile] - Name of a namespaced env container under `process.env`.
+	 * @returns {string|undefined} The environment variable value, or `undefined` if not found.
+	 */
+  getEnv(env, options) {
+    dotenv.config({ quiet: true });
+    return options?.envFile
+      ? process.env[options?.envFile][env]
+      : process.env[env];
+  },
+  /**
+	 * Resolves path relative to caller file or current directory.
+	 * Supports `./`, `../`, absolute paths, and searches for existing paths.
+	 * @param {string} [path=process.cwd()] - Path to resolve.
+	 * @returns {string} Resolved absolute path.
+	 * @example
+	 * nodeComfort.createPath("./data/users"); // Resolves from caller file
+	 */
+  createPath(path = process.cwd()) {
+    const target = _target(path);
+    return target
+      ? target
+      : isAbsolute(path)
+        ? path
+        : path.startsWith("./") || path.startsWith("../")
+          ? resolve(dirname(_caller()), path)
+          : resolve(process.cwd(), path);
+  },
+
+  /**
+	 * Returns all folders in path (recursive option).
+	 * @param {string} [path=process.cwd()] - Starting directory.
+	 * @param {boolean} [recursive=true] - Include subfolders.
+	 * @returns {string[]|undefined} Array of folder paths.
+	 */
+  getFoldersIn(path = process.cwd(), recursive = true) {
+    const target = _target(path ?? process.cwd());
+    return target ? _walk(target, recursive) : undefined;
+  },
+
+  /**
+	 * Resolves and returns existing folder path.
+	 * @param {string} [path=process.cwd()] - Folder path.
+	 * @returns {string|undefined} Absolute folder path.
+	 */
+  getFolder(path = process.cwd()) {
+    return _target(path ?? process.cwd());
+  },
+
+  /**
+	 * Returns all files in path (recursive option).
+	 * @param {string} [path=process.cwd()] - Starting directory.
+	 * @param {boolean} [recursive=true] - Include subdirectories.
+	 * @returns {string[]|undefined} Array of file paths.
+	 */
+  getFilesIn(path = process.cwd(), recursive = true) {
+    const target = _target(path ?? process.cwd());
+    return target ? _walk(target, recursive, "file") : undefined;
+  },
+
+  /**
+	 * Resolves and returns existing file path.
+	 * @param {string} path - File path.
+	 * @returns {string|undefined} Absolute file path.
+	 */
+  getFile(path) {
+    return path ? _target(path, "file") : path;
+  },
+
+  /**
+	 * Creates folder (recursive) with force overwrite option.
+	 * @param {string} path - Folder path to create.
+	 * @param {boolean} [force=false] - Overwrite if exists.
+	 * @returns {boolean|undefined} Success status.
+	 */
+  createFolder(path, force = false) {
+    if (!path) return undefined;
+    const target = this.createPath(path);
+
+    try {
+      if (this.getFolder(target)) {
+        if (force) {
+          this.deleteFolder(target);
+          mkdirSync(target, { recursive: true });
+          return true;
+        }
+        return false;
+      }
+      mkdirSync(target, { recursive: true });
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+	 * Creates file with auto-directory creation and content serialization.
+	 * Supports string, object (→ JSON), null/undefined (→ empty).
+	 * @param {string} path - File path.
+	 * @param {boolean} [force=false] - Overwrite if exists.
+	 * @param {string|object|null|undefined} [data] - File content.
+	 * @returns {boolean|undefined} Success status.
+	 * @example
+	 * nodeComfort.createFile("config.json", false, { apiKey: "secret" });
+	 */
+  createFile(path, force = false, data) {
+    if (!path) return undefined;
+    const target = this.createPath(path);
+    const content =
+			data === null || typeof data === "undefined"
+			  ? ""
+			  : typeof data === "string"
+			    ? data
+			    : JSON.stringify(data, null, 2);
+
+    try {
+      if (this.getFile(target)) {
+        if (force) {
+          this.deleteFile(target);
+          writeFileSync(target, content, "utf8");
+          return true;
+        }
+        return false;
+      }
+
+      if (!this.getFolder(dirname(target))) {
+        this.createFolder(dirname(target));
+      }
+
+      writeFileSync(target, content, "utf8");
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+	 * Deletes multiple folders matching filter.
+	 * @param {string} [path=process.cwd()] - Starting directory.
+	 * @param {(folder: string) => boolean} [filter] - Folder filter function.
+	 * @returns {number|undefined} Count of deleted folders.
+	 */
+  deleteFoldersIn(path = process.cwd(), filter = () => true) {
+    const target = _target(path);
+    if (!target) return undefined;
+
+    const folders = this.getFoldersIn(target);
+    let deleted = 0;
+
+    for (const folder of folders.map(_format)) {
+      if (!filter(folder)) continue;
+      this.deleteFolder(folder);
+      deleted++;
+    }
+    return deleted;
+  },
+
+  /**
+	 * Deletes folder and all contents recursively.
+	 * @param {string} path - Folder path.
+	 * @returns {boolean|undefined} Success status.
+	 */
+  deleteFolder(path) {
+    const target = path ? _target(path) : path;
+    if (!target || !this.getFolder(target)) return undefined;
+
+    try {
+      rmSync(target, { recursive: true, force: true });
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+	 * Deletes multiple files matching filter.
+	 * @param {string} [path=process.cwd()] - Starting directory.
+	 * @param {boolean} [recursive=false] - Search subdirectories.
+	 * @param {(file: string) => boolean} [filter] - File filter function.
+	 * @returns {number|undefined} Count of deleted files.
+	 */
+  deleteFilesIn(path = process.cwd(), recursive = false, filter = () => true) {
+    const target = _target(path);
+    if (!target) return undefined;
+
+    const files = this.getFilesIn(target, recursive);
+    let deleted = 0;
+
+    for (const file of files.map(_format)) {
+      if (!filter(file)) continue;
+      this.deleteFile(file);
+      deleted++;
+    }
+    return deleted;
+  },
+
+  /**
+	 * Deletes single file.
+	 * @param {string} path - File path.
+	 * @returns {boolean|undefined} Success status.
+	 */
+  deleteFile(path) {
+    const target = path ? _target(path, "file") : path;
+    if (!target || !this.getFile(target)) return undefined;
+
+    try {
+      unlinkSync(target);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+	 * Copies multiple folders with optional files and recursive support.
+	 * @param {Object} options - Copy options.
+	 * @param {string} options.dest - Destination base path.
+	 * @param {string} [options.path] - Source path.
+	 * @param {boolean} [options.recursive=true] - Copy subfolders.
+	 * @param {boolean} [options.withFiles=false] - Include files.
+	 * @param {boolean} [options.force=false] - Overwrite existing.
+	 * @param {(folder: string) => boolean} [options.filter] - Folder filter.
+	 * @returns {number|undefined} Count of copied folders.
+	 */
+  copyFoldersIn(options) {
+    const target = _target(options.path ?? process.cwd());
+    if (!target || !options.dest) return undefined;
+
+    const folders = this.getFoldersIn(target, options.recursive ?? true) ?? [];
+    options.filter =
+			typeof options.filter === "function" ? options.filter : () => true;
+    let copied = 0;
+
+    for (const folder of folders.map(_format)) {
+      if (!options.filter(folder)) continue;
+
+      const destFolder = join(
+        this.createPath(options.dest),
+        relative(target, folder),
+      );
+
+      if (options.force && this.getFolder(destFolder)) {
+        this.deleteFolder(destFolder);
+      }
+
+      this.createFolder(destFolder);
+      copied++;
+
+      if (options.withFiles) {
+        if (options.recursive) {
+          for (const file of this.getFilesIn(folder, true) ?? []) {
+            const destFile = join(destFolder, relative(folder, file));
+            this.createFolder(dirname(destFile));
+            copyFileSync(file, destFile);
+          }
+        } else {
+          for (const file of this.getFilesIn(folder, false) ?? []) {
+            const destFile = join(destFolder, basename(file));
+            copyFileSync(file, destFile);
+          }
+        }
+      }
+    }
+    return copied;
+  },
+
+  /**
+	 * Copies single folder with optional contents.
+	 * @param {Object} options - Copy options.
+	 * @param {string} options.dest - Destination path.
+	 * @param {string} [options.path] - Source path.
+	 * @param {boolean} [options.recursive=false] - Copy subfolders.
+	 * @param {boolean} [options.withFiles=false] - Include files.
+	 * @param {boolean} [options.force=false] - Overwrite existing.
+	 * @returns {boolean|undefined} Success status.
+	 */
+  copyFolder(options) {
+    const target = _target(options.path ?? process.cwd());
+    const dest = this.createPath(options.dest);
+
+    if (!target || !dest) return undefined;
+
+    if (options.force && this.getFolder(dest)) {
+      this.deleteFolder(dest);
+    }
+
+    this.createFolder(dest);
+
+    if (options.recursive) {
+      for (const folder of this.getFoldersIn(target, true) ?? []) {
+        const destFolder = join(dest, relative(target, folder));
+        this.createFolder(destFolder);
+
+        if (options.withFiles) {
+          for (const file of this.getFilesIn(folder, false) ?? []) {
+            const destFile = join(destFolder, basename(file));
+            copyFileSync(file, destFile);
+          }
+        }
+      }
+
+      if (options.withFiles) {
+        for (const file of this.getFilesIn(target, false) ?? []) {
+          const destFile = join(dest, basename(file));
+          copyFileSync(file, destFile);
+        }
+      }
+    } else {
+      if (options.withFiles) {
+        for (const file of this.getFilesIn(target, false) ?? []) {
+          const destFile = join(dest, basename(file));
+          copyFileSync(file, destFile);
+        }
+      }
+    }
+    return true;
+  },
+
+  /**
+	 * Copies multiple files with optional recursive structure preservation.
+	 * @param {Object} options - Copy options.
+	 * @param {string} options.dest - Destination base path.
+	 * @param {string} [options.path] - Source path.
+	 * @param {boolean} [options.recursive=true] - Preserve directory structure.
+	 * @param {boolean} [options.force=false] - Overwrite existing.
+	 * @param {(file: string) => boolean} [options.filter] - File filter.
+	 * @returns {number|undefined} Count of copied files.
+	 */
+  copyFilesIn(options) {
+    const target = _target(options.path ?? process.cwd());
+    const destBase = this.createPath(options.dest);
+
+    if (!target || !options.dest) return undefined;
+
+    const recursive = options.recursive ?? true;
+    const files = this.getFilesIn(target, recursive) ?? [];
+    const filter =
+			typeof options.filter === "function" ? options.filter : () => true;
+    let copied = 0;
+
+    for (const file of files.map(_format)) {
+      if (!filter(file)) continue;
+
+      const destFile = join(
+        destBase,
+        recursive ? relative(target, file) : basename(file),
+      );
+
+      if (options.force && this.getFile(destFile)) {
+        this.deleteFile(destFile);
+      }
+
+      this.createFolder(dirname(destFile));
+      copyFileSync(file, destFile);
+      copied++;
+    }
+    return copied;
+  },
+
+  /**
+	 * Copies single file to destination (auto-creates parent folders).
+	 * @param {Object} options - Copy options.
+	 * @param {string} options.path - Source file path.
+	 * @param {string} options.dest - Destination path or folder.
+	 * @param {boolean} [options.force=false] - Overwrite existing.
+	 * @returns {boolean|undefined} Success status.
+	 */
+  copyFile(options) {
+    const target = _target(options.path, "file");
+    if (!target || !options.dest) return undefined;
+
+    let destFile;
+    if (
+      !basename(options.dest) ||
+			options.dest.endsWith("/") ||
+			options.dest.endsWith("\\")
+    ) {
+      destFile = join(this.createPath(options.dest), basename(target));
+    } else {
+      destFile = this.createPath(options.dest);
+    }
+
+    if (options.force && this.getFile(destFile)) {
+      this.deleteFile(destFile);
+    }
+
+    this.createFolder(dirname(destFile));
+    copyFileSync(target, destFile);
+    return true;
+  },
+
+  /**
+	 * Moves multiple folders (copy + delete source).
+	 * @param {Object} options - Move options (same as copyFoldersIn).
+	 * @returns {number|undefined} Count of moved folders.
+	 */
+  moveFoldersIn(options) {
+    const copied = this.copyFoldersIn(options);
+    if (copied === undefined || !options.path) return copied;
+
+    const target = _target(options.path);
+    if (!target) return copied;
+
+    const folders = this.getFoldersIn(target, options.recursive ?? true) ?? [];
+    options.filter =
+			typeof options.filter === "function" ? options.filter : () => true;
+
+    for (const folder of folders.map(_format)) {
+      if (!options.filter(folder)) continue;
+      this.deleteFolder(folder);
+    }
+    return copied;
+  },
+
+  /**
+	 * Moves single folder (copy + delete source).
+	 * @param {Object} options - Move options (same as copyFolder).
+	 * @returns {boolean|undefined} Success status.
+	 */
+  moveFolder(options) {
+    const copied = this.copyFolder(options);
+    const target = _target(options.path);
+    if (!target) return copied;
+
+    this.deleteFolder(target);
+    return copied;
+  },
+
+  /**
+	 * Moves multiple files (copy + delete source).
+	 * @param {Object} options - Move options (same as copyFilesIn).
+	 * @returns {number|undefined} Count of moved files.
+	 */
+  moveFilesIn(options) {
+    const copied = this.copyFilesIn(options);
+    if (copied === undefined || !options.path) return copied;
+
+    const target = _target(options.path ?? process.cwd());
+    if (!target) return copied;
+
+    const files = this.getFilesIn(target, options.recursive ?? true) ?? [];
+    const filter =
+			typeof options.filter === "function" ? options.filter : () => true;
+
+    for (const file of files.map(_format)) {
+      if (!filter(file)) continue;
+      this.deleteFile(file);
+    }
+    return copied;
+  },
+
+  /**
+	 * Moves single file (copy + delete source).
+	 * @param {Object} options - Move options (same as copyFile).
+	 * @returns {boolean|undefined} Success status.
+	 */
+  moveFile(options) {
+    const moved = this.copyFile(options);
+    if (moved) {
+      const target = _target(options.path, "file");
+      if (target) this.deleteFile(target);
+    }
+    return moved;
+  },
+
+  /**
+	 * Reads file content synchronously.
+	 * @param {string} path - File path.
+	 * @returns {string|undefined} File content or undefined.
+	 */
+  readFile(path) {
+    const target = _target(path, "file");
+    if (!target) return undefined;
+
+    try {
+      return readFileSync(target, "utf8");
+    } catch {
+      return undefined;
+    }
+  },
+
+  /**
+	 * Creates file system watcher with event filtering and pause/resume.
+	 * @param {Object} [options] - Watcher options.
+	 * @param {string} [options.path=process.cwd()] - Watch path.
+	 * @param {boolean} [options.recursive=false] - Watch subdirectories.
+	 * @param {(event: string, file: string) => boolean} [options.filter] - Event filter.
+	 * @returns {Object|undefined} Watcher API.
+	 * @example
+	 * const watcher = nodeComfort.watch({ path: "./src", recursive: true });
+	 * watcher.on("change", (file) => console.log("Changed:", file));
+	 * watcher.on("rename", (file) => console.log("Renamed:", file));
+	 * watcher.on("all", (event, file) => console.log(event, file));
+	 */
+  watch(options = {}) {
+    const target = _target(options.path ?? process.cwd());
+    if (!target) return undefined;
+
+    let paused = false;
+    const listeners = {};
+
+    const handler = (event, file) => {
+      if (paused) return;
+      if (
+        typeof options.filter === "function" &&
+				!options.filter(event, file)
+      ) {
+        return;
+      }
+
+      if (listeners[event]) {
+        for (const cb of listeners[event]) cb(file);
+      }
+      if (listeners["all"]) {
+        for (const cb of listeners["all"]) cb(event, file);
+      }
+    };
+
+    const addListener = (type, callback) => {
+      listeners[type] = listeners[type] ?? [];
+      listeners[type].push(callback);
+    };
+
+    const watcher = watch(
+      target,
+      { recursive: options.recursive ?? false },
+      (eventType, fileName) => {
+        handler(eventType, fileName ? join(target, fileName) : target);
+      },
+    );
+
+    return {
+      /**
+			 * Adds event listener.
+			 * @param {"change"|"rename"|"all"} event - Event type.
+			 * @param {function} callback - Callback function.
+			 */
+      on(event, callback) {
+        addListener(event, callback);
+      },
+      stop() {
+        if (watcher) {
+          try {
+            watcher.close();
+          } catch {}
+        }
+      },
+      pause() {
+        paused = true;
+      },
+      resume() {
+        paused = false;
+      },
+    };
+  },
+};