@ix-xs/node-comfort 1.0.3 → 1.0.5

package/{core/FS.js → src/fs.js}

@@ -1,39 +1,19 @@
-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");
+const { readdirSync, existsSync, mkdirSync, rmSync, writeFileSync, unlinkSync, copyFileSync, readFileSync, watch } = require("node:fs");
+const { resolve, dirname, sep, isAbsolute, join, relative, basename } = require("node:path");
+
+try {
+  process.loadEnvFile();
+}
+catch {}
 
 /**
- * Normalizes path separators for cross-platform compatibility.
- * @private
- * @param {string} path - Path to normalize.
- * @returns {string} Normalized path.
+ * @param {string} 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.
+ * @returns {string|undefined}
  */
 const _caller = () => {
   const opst = Error.prepareStackTrace;
@@ -47,9 +27,9 @@ const _caller = () => {
       const name = cs.getFileName();
       if (
         name &&
-				!name.startsWith("node:internal") &&
-				!name.includes("node_modules") &&
-				name !== s[0].getFileName()
+      !name.startsWith("node:internal") &&
+      !name.includes("node_modules") &&
+      name !== s[0].getFileName()
       ) {
         return _format(name);
       }
@@ -57,14 +37,11 @@ const _caller = () => {
   }
   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.
+ * @param {string} path
+ * @param {boolean} [recursive=true]
+ * @param {"folder"|"file"} [type="folder"]
+ * @returns {string[]}
  */
 const _walk = (path = process.cwd(), recursive = true, type = "folder") => {
   let result = [];
@@ -87,13 +64,10 @@ const _walk = (path = process.cwd(), recursive = true, type = "folder") => {
     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.
+ * @param {string} path
+ * @param {string} name
+ * @returns {string|undefined}
  */
 const _firstFolder = (path, name) => {
   try {
@@ -112,13 +86,10 @@ const _firstFolder = (path, name) => {
   } 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.
+ * @param {string} path
+ * @param {string} name
+ * @returns {string|undefined}
  */
 const _firstFile = (path, name) => {
   try {
@@ -137,13 +108,10 @@ const _firstFile = (path, name) => {
   } 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.
+ * @param {string} [path=process.cwd()]
+ * @param {"folder"|"file"} [type="folder"]
+ * @returns {string|undefined}
  */
 const _target = (path = process.cwd(), type = "folder") => {
   if (path === process.cwd()) return path;
@@ -153,7 +121,7 @@ const _target = (path = process.cwd(), type = "folder") => {
 
   if (
     _format(path).startsWith(_format("./")) ||
-		_format(path).startsWith(_format("../"))
+  _format(path).startsWith(_format("../"))
   ) {
     absolute = resolve(caller, path);
   } else if (isAbsolute(path)) {
@@ -162,9 +130,9 @@ const _target = (path = process.cwd(), type = "folder") => {
     absolute = resolve(process.cwd(), _format(path));
     if (!existsSync(absolute)) {
       absolute =
-				type === "folder"
-				  ? (_firstFolder(process.cwd(), _format(path)) ?? undefined)
-				  : (_firstFile(process.cwd(), _format(path)) ?? undefined);
+      type === "folder"
+        ? (_firstFolder(process.cwd(), _format(path)) ?? undefined)
+        : (_firstFile(process.cwd(), _format(path)) ?? undefined);
     }
   }
 
@@ -172,58 +140,15 @@ const _target = (path = process.cwd(), type = "folder") => {
   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];
+   * @param {string} value
+   */
+  getEnv(value, envFilePath) {
+    return process.env[value];
   },
   /**
-	 * 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
+	 * @param {string} [path=process.cwd()]
 	 */
   createPath(path = process.cwd()) {
     const target = _target(path);
@@ -235,52 +160,37 @@ module.exports = {
           ? 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.
+	 * @param {string} [path]
+	 * @param {boolean} [recursive]
 	 */
   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.
+	 * @param {string} [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.
+	 * @param {string} [path]
+	 * @param {boolean} [recursive]
 	 */
   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.
+	 * @param {string} 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.
+	 * @param {string} path
+	 * @param {boolean} [force]
 	 */
   createFolder(path, force = false) {
     if (!path) return undefined;
@@ -301,16 +211,10 @@ module.exports = {
       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" });
+	 * @param {string} path
+	 * @param {boolean} [force]
+	 * @param {string|object|null|undefined} [data]
 	 */
   createFile(path, force = false, data) {
     if (!path) return undefined;
@@ -342,12 +246,9 @@ module.exports = {
       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.
+	 * @param {string} [path]
+	 * @param {(folder: string) => boolean} [filter]
 	 */
   deleteFoldersIn(path = process.cwd(), filter = () => true) {
     const target = _target(path);
@@ -363,11 +264,8 @@ module.exports = {
     }
     return deleted;
   },
-
   /**
-	 * Deletes folder and all contents recursively.
-	 * @param {string} path - Folder path.
-	 * @returns {boolean|undefined} Success status.
+	 * @param {string} path
 	 */
   deleteFolder(path) {
     const target = path ? _target(path) : path;
@@ -380,13 +278,10 @@ module.exports = {
       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.
+	 * @param {string} [path=process.cwd()]
+	 * @param {boolean} [recursive=false]
+	 * @param {(file: string) => boolean} [filter]
 	 */
   deleteFilesIn(path = process.cwd(), recursive = false, filter = () => true) {
     const target = _target(path);
@@ -402,11 +297,8 @@ module.exports = {
     }
     return deleted;
   },
-
   /**
-	 * Deletes single file.
-	 * @param {string} path - File path.
-	 * @returns {boolean|undefined} Success status.
+	 * @param {string} path
 	 */
   deleteFile(path) {
     const target = path ? _target(path, "file") : path;
@@ -419,17 +311,14 @@ module.exports = {
       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.
+	 * @param {Object} options
+	 * @param {string} options.dest
+	 * @param {string} [options.path]
+	 * @param {boolean} [options.recursive=true]
+	 * @param {boolean} [options.withFiles=false]
+	 * @param {boolean} [options.force=false]
+	 * @param {(folder: string) => boolean} [options.filter]
 	 */
   copyFoldersIn(options) {
     const target = _target(options.path ?? process.cwd());
@@ -472,16 +361,13 @@ module.exports = {
     }
     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.
+	 * @param {Object} options
+	 * @param {string} options.dest
+	 * @param {string} [options.path]
+	 * @param {boolean} [options.recursive=false]
+	 * @param {boolean} [options.withFiles=false]
+	 * @param {boolean} [options.force=false]
 	 */
   copyFolder(options) {
     const target = _target(options.path ?? process.cwd());
@@ -524,16 +410,13 @@ module.exports = {
     }
     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.
+	 * @param {Object} options
+	 * @param {string} options.dest
+	 * @param {string} [options.path]
+	 * @param {boolean} [options.recursive=true]
+	 * @param {boolean} [options.force=false]
+	 * @param {(file: string) => boolean} [options.filter]
 	 */
   copyFilesIn(options) {
     const target = _target(options.path ?? process.cwd());
@@ -565,14 +448,11 @@ module.exports = {
     }
     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.
+	 * @param {Object} options
+	 * @param {string} options.path
+	 * @param {string} options.dest
+	 * @param {boolean} [options.force=false]
 	 */
   copyFile(options) {
     const target = _target(options.path, "file");
@@ -597,11 +477,14 @@ module.exports = {
     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.
+   * @param {Object} options
+   * @param {string} options.dest
+   * @param {string} [options.path]
+   * @param {boolean} [options.recursive=true]
+   * @param {boolean} [options.withFiles=false]
+   * @param {boolean} [options.force=false]
+   * @param {(folder: string) => boolean} [options.filter]
 	 */
   moveFoldersIn(options) {
     const copied = this.copyFoldersIn(options);
@@ -620,11 +503,13 @@ module.exports = {
     }
     return copied;
   },
-
   /**
-	 * Moves single folder (copy + delete source).
-	 * @param {Object} options - Move options (same as copyFolder).
-	 * @returns {boolean|undefined} Success status.
+   * @param {Object} options
+   * @param {string} options.path
+   * @param {string} options.dest
+   * @param {boolean} [options.recursive=false]
+   * @param {boolean} [options.withFiles=false]
+   * @param {boolean} [options.force=false]
 	 */
   moveFolder(options) {
     const copied = this.copyFolder(options);
@@ -634,11 +519,13 @@ module.exports = {
     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.
+   * @param {Object} options
+   * @param {string} options.dest
+   * @param {string} [options.path]
+   * @param {boolean} [options.recursive=true]
+   * @param {boolean} [options.force=false]
+   * @param {(file: string) => boolean} [options.filter]
 	 */
   moveFilesIn(options) {
     const copied = this.copyFilesIn(options);
@@ -657,11 +544,11 @@ module.exports = {
     }
     return copied;
   },
-
   /**
-	 * Moves single file (copy + delete source).
-	 * @param {Object} options - Move options (same as copyFile).
-	 * @returns {boolean|undefined} Success status.
+   * @param {Object} options
+   * @param {string} options.path
+   * @param {string} options.dest
+   * @param {boolean} [options.force=false]
 	 */
   moveFile(options) {
     const moved = this.copyFile(options);
@@ -671,11 +558,8 @@ module.exports = {
     }
     return moved;
   },
-
   /**
-	 * Reads file content synchronously.
-	 * @param {string} path - File path.
-	 * @returns {string|undefined} File content or undefined.
+	 * @param {string} path
 	 */
   readFile(path) {
     const target = _target(path, "file");
@@ -687,19 +571,11 @@ module.exports = {
       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));
+	 * @param {Object} [options]
+	 * @param {string} [options.path=process.cwd()]
+	 * @param {boolean} [options.recursive=false]
+	 * @param {(event: string, file: string) => boolean} [options.filter]
 	 */
   watch(options = {}) {
     const target = _target(options.path ?? process.cwd());
@@ -708,6 +584,10 @@ module.exports = {
     let paused = false;
     const listeners = {};
 
+    /**
+     * @param {"rename"|"change"|"all"} event
+     * @param {string} file
+     */
     const handler = (event, file) => {
       if (paused) return;
       if (
@@ -740,12 +620,21 @@ module.exports = {
 
     return {
       /**
-			 * Adds event listener.
-			 * @param {"change"|"rename"|"all"} event - Event type.
-			 * @param {function} callback - Callback function.
+       * @typedef { "change" | "rename" | "all" } EventNames
+       * @typedef {{
+       * change: (file: string) => void|Promise<void>,
+       * rename: (file: string) => void|Promise<void>,
+       * all: (event: EventNames, file: string) => void|Promise<void>,
+       * }} EventHandlers
+       */
+      /**
+       * @template {EventNames} E
+			 * @param {E} event
+			 * @param {EventHandlers[E]} callback
 			 */
       on(event, callback) {
         addListener(event, callback);
+        return this;
       },
       stop() {
         if (watcher) {
@@ -756,9 +645,11 @@ module.exports = {
       },
       pause() {
         paused = true;
+        return this;
       },
       resume() {
         paused = false;
+        return this;
       },
     };
   },