@ix-xs/node-comfort 1.2.0 → 2.1.0

package/types/src/FS.d.ts

@@ -1,303 +1,782 @@
 /**
- * Reads an environment variable from process.env.
- * @param {string} value - The environment variable name.
- * @param {string} [envFilePath] - Reserved for future use.
- * @returns {string|undefined} The environment value, or undefined if not set.
+ * Options for `copyFoldersIn()` and `moveFoldersIn()`.
  */
-export function getEnv(value: string, envFilePath?: string): string | undefined;
+export type CopyFoldersOptions = {
+    /**
+     * Destination folder.
+     */
+    dest: string;
+    /**
+     * Source folder. Defaults to the working directory.
+     */
+    path?: string | undefined;
+    /**
+     * Include nested folders. Defaults to `true`.
+     */
+    recursive?: boolean | undefined;
+    /**
+     * Copy the files in each folder too.
+     */
+    withFiles?: boolean | undefined;
+    /**
+     * Delete an existing destination folder first.
+     */
+    force?: boolean | undefined;
+    /**
+     * Keep a folder when it returns `true`. Gets absolute paths.
+     */
+    filter?: ((folder: string) => boolean) | undefined;
+};
 /**
- * Resolves a path even when it does not already exist.
- * @param {string} [path=process.cwd()] - The path to resolve.
- * @returns {string} The resolved path.
+ * Options for `copyFolder()` and `moveFolder()`.
  */
-export function createPath(path?: string): string;
+export type CopyFolderOptions = {
+    /**
+     * Destination folder.
+     */
+    dest: string;
+    /**
+     * Source folder. Defaults to the working directory.
+     */
+    path?: string | undefined;
+    /**
+     * Copy nested folders too.
+     */
+    recursive?: boolean | undefined;
+    /**
+     * Copy files too. `copy()` does all of this in one call.
+     */
+    withFiles?: boolean | undefined;
+    /**
+     * Delete an existing destination first.
+     */
+    force?: boolean | undefined;
+};
 /**
- * Returns folders found inside a path.
- * @param {string} [path=process.cwd()] - The base path to inspect.
- * @param {boolean} [recursive=true] - Whether to scan recursively.
- * @returns {string[]|undefined} Matching folders, or undefined if the path cannot be resolved.
+ * Options for `copyFilesIn()` and `moveFilesIn()`.
  */
-export function getFoldersIn(path?: string, recursive?: boolean): string[] | undefined;
+export type CopyFilesOptions = {
+    /**
+     * Destination folder.
+     */
+    dest: string;
+    /**
+     * Source folder. Defaults to the working directory.
+     */
+    path?: string | undefined;
+    /**
+     * Include files from nested folders, keeping the tree. Defaults to `true`.
+     */
+    recursive?: boolean | undefined;
+    /**
+     * Delete existing destination files first.
+     */
+    force?: boolean | undefined;
+    /**
+     * Keep a file when it returns `true`. Gets absolute paths.
+     */
+    filter?: ((file: string) => boolean) | undefined;
+};
 /**
- * Returns the resolved folder path.
- * @param {string} [path=process.cwd()] - The folder path to resolve.
- * @returns {string|undefined} The resolved folder path, or undefined if not found.
+ * Options for `copyFile()` and `moveFile()`.
  */
-export function getFolder(path?: string): string | undefined;
+export type CopyFileOptions = {
+    /**
+     * Source file.
+     */
+    path: string;
+    /**
+     * Destination file, or a folder if it ends with `/`.
+     */
+    dest: string;
+    /**
+     * Delete the destination first.
+     */
+    force?: boolean | undefined;
+};
+/**
+ * Options for `copy()`.
+ */
+export type CopyOptions = {
+    /**
+     * Replace existing files. Defaults to `true`.
+     */
+    overwrite?: boolean | undefined;
+    /**
+     * Return `false` to skip a file or folder.
+     */
+    filter?: ((source: string, destination: string) => boolean) | undefined;
+    /**
+     * Keep modification times.
+     */
+    preserveTimestamps?: boolean | undefined;
+};
+/**
+ * Options for `writeFile()`.
+ */
+export type WriteFileOptions = {
+    /**
+     * Write to a temporary file and rename it, so nobody reads a half-written file and a crash can't corrupt it. Defaults to `true`.
+     */
+    atomic?: boolean | undefined;
+    /**
+     * Defaults to `"utf8"`.
+     */
+    encoding?: BufferEncoding | undefined;
+    /**
+     * Permissions, like `0o600` for secrets. A file that already exists keeps the ones it has.
+     */
+    mode?: number | undefined;
+    /**
+     * Wait until the data is on the disk before returning. Slower, for files that must survive a power cut.
+     */
+    fsync?: boolean | undefined;
+    /**
+     * Indentation when writing an object as JSON. Defaults to `2`.
+     */
+    spaces?: number | undefined;
+};
+/**
+ * Options for `writeJSON()`.
+ */
+export type WriteJSONOptions = {
+    /**
+     * Defaults to `2`.
+     */
+    spaces?: number | undefined;
+    /**
+     * Defaults to `true`.
+     */
+    atomic?: boolean | undefined;
+    /**
+     * Passed to `JSON.stringify`.
+     */
+    replacer?: ((key: string, value: unknown) => unknown) | undefined;
+    /**
+     * Permissions, like `0o600` for secrets. A file that already exists keeps the ones it has.
+     */
+    mode?: number | undefined;
+    /**
+     * Wait until the data is on the disk before returning.
+     */
+    fsync?: boolean | undefined;
+};
+/**
+ * Options for `readJSON()`.
+ */
+export type ReadJSONOptions = {
+    /**
+     * Allow comments and trailing commas, like in `tsconfig.json`.
+     */
+    comments?: boolean | undefined;
+    /**
+     * Passed to `JSON.parse`.
+     */
+    reviver?: ((key: string, value: any) => any) | undefined;
+};
+/**
+ * Options for `getFilesIn()` and `getFoldersIn()`.
+ */
+export type ListOptions = {
+    /**
+     * Go into nested folders. Defaults to `true`.
+     */
+    recursive?: boolean | undefined;
+    /**
+     * Include names starting with a dot. Defaults to `true`.
+     */
+    hidden?: boolean | undefined;
+    /**
+     * Folder names to skip. Defaults to `["node_modules"]`.
+     */
+    ignore?: string[] | undefined;
+};
+/**
+ * Options for `glob()`.
+ */
+export type GlobOptions = {
+    /**
+     * Where the pattern starts. Defaults to the working directory.
+     */
+    cwd?: string | undefined;
+    /**
+     * Return absolute paths.
+     */
+    absolute?: boolean | undefined;
+    /**
+     * Let `*` and `**` match names starting with a dot.
+     */
+    dot?: boolean | undefined;
+    /**
+     * Patterns to leave out. Defaults to `node_modules` and `.git`.
+     */
+    ignore?: string[] | undefined;
+    /**
+     * Defaults to `"files"`.
+     */
+    type?: "files" | "folders" | "all" | undefined;
+};
+/**
+ * Options for `find()`.
+ */
+export type FindOptions = {
+    /**
+     * Where to start. Defaults to the working directory.
+     */
+    cwd?: string | undefined;
+    /**
+     * Defaults to `"file"`.
+     */
+    type?: "file" | "folder" | "any" | undefined;
+    /**
+     * Folder names to skip. Defaults to `node_modules` and `.git`.
+     */
+    ignore?: string[] | undefined;
+};
+/**
+ * Options for `watch()`.
+ */
+export type WatchOptions = {
+    /**
+     * What to watch. Defaults to the working directory.
+     */
+    path?: string | undefined;
+    /**
+     * Watch nested folders too.
+     */
+    recursive?: boolean | undefined;
+    /**
+     * Return `false` to ignore an event.
+     */
+    filter?: ((event: "rename" | "change", file: string) => boolean) | undefined;
+    /**
+     * Merge events on the same file within this long, in ms or like `"100ms"`. Editors often save in several steps.
+     */
+    debounce?: string | number | undefined;
+};
+/**
+ * Returned by `watch()`.
+ */
+export type Watcher = {
+    /**
+     * Listens for changes. `"all"` also gets the event name. `"error"` tells you the watch broke, for instance because the folder was deleted.
+     */
+    on: <E extends "change" | "rename" | "all" | "error">(event: E, callback: E extends "all" ? (event: "change" | "rename", file: string) => void : E extends "error" ? (error: Error) => void : (file: string) => void) => Watcher;
+    /**
+     * Stops watching.
+     */
+    stop: () => void;
+    /**
+     * Ignores events until `resume()`.
+     */
+    pause: () => Watcher;
+    resume: () => Watcher;
+};
 /**
- * Returns files found inside a path.
- * @param {string} [path=process.cwd()] - The base path to inspect.
- * @param {boolean} [recursive=true] - Whether to scan recursively.
- * @returns {string[]|undefined} Matching files, or undefined if the path cannot be resolved.
+ * Reads an environment variable. For typed and checked values, see `nc.env`.
+ *
+ * @example
+ * nc.getEnv("REGION", "eu-west-1");
+ *
+ * @param {string} name
+ * @param {string} [fallback]
+ * @returns {string | undefined}
  */
-export function getFilesIn(path?: string, recursive?: boolean): string[] | undefined;
+export function getEnv(name: string, fallback?: string): string | undefined;
 /**
- * Returns the resolved file path.
- * @param {string} path - The file path to resolve.
- * @returns {string|undefined} The resolved file path, or undefined if not found.
+ * The absolute version of a path, whether it exists or not.
+ *
+ * @example
+ * nc.createPath("./config/app.json"); // next to the calling file
+ * nc.createPath("logs/app.log");      // from the working directory
+ *
+ * @param {string} [path] Defaults to the working directory.
+ * @returns {string}
+ */
+export function createPath(path?: string): string;
+/**
+ * The absolute path of a folder, or `undefined` if it doesn't exist.
+ *
+ * @example
+ * if (!nc.getFolder("./uploads")) nc.createFolder("./uploads");
+ *
+ * @param {string} [path] Defaults to the working directory.
+ * @returns {string | undefined}
+ */
+export function getFolder(path?: string): string | undefined;
+/**
+ * The absolute path of a file, or `undefined` if it doesn't exist.
+ *
+ * @param {string} path
+ * @returns {string | undefined}
  */
 export function getFile(path: string): string | undefined;
 /**
- * Creates a folder.
- * @param {string} path - The folder path to create.
- * @param {boolean} [force=false] - Whether to recreate the folder if it already exists.
- * @returns {boolean|undefined} True on success, false on failure, undefined if no path was provided.
+ * The folders inside a folder, nested ones included by default.
+ * `node_modules` is skipped.
+ *
+ * @example
+ * nc.getFoldersIn("./src");        // everything
+ * nc.getFoldersIn("./src", false); // direct children only
+ *
+ * @param {string} [path] Defaults to the working directory.
+ * @param {boolean | ListOptions} [recursive=true]
+ * @returns {string[] | undefined} Absolute paths, or `undefined` if the folder doesn't exist.
+ */
+export function getFoldersIn(path?: string, recursive?: boolean | ListOptions): string[] | undefined;
+/**
+ * The files inside a folder, nested ones included by default.
+ * `node_modules` is skipped.
+ *
+ * @example
+ * nc.getFilesIn("./src").filter((file) => file.endsWith(".js"));
+ *
+ * @param {string} [path] Defaults to the working directory.
+ * @param {boolean | ListOptions} [recursive=true]
+ * @returns {string[] | undefined} Absolute paths, or `undefined` if the folder doesn't exist.
+ */
+export function getFilesIn(path?: string, recursive?: boolean | ListOptions): string[] | undefined;
+/**
+ * Finds paths matching a glob pattern: `*` (anything but `/`), `**` (any
+ * depth), `?`, `[abc]` and `{js,ts}`.
+ *
+ * A pattern starting from the root of the disk searches there, and its
+ * results are absolute.
+ *
+ * @example
+ * nc.glob("src/**\/*.js");                           // ["src/index.js", "src/lib/a.js"]
+ * nc.glob("**\/*.{png,jpg}", { cwd: "./assets", absolute: true });
+ * nc.glob("packages/*", { type: "folders" });
+ * nc.glob(`${folder}/**\/*.json`);                   // absolute pattern, absolute results
+ *
+ * @param {string | string[]} pattern One or more patterns.
+ * @param {GlobOptions} [options]
+ * @returns {string[]} Sorted, relative to `cwd` with `/` separators, unless the pattern is absolute or `absolute` is set.
+ */
+export function glob(pattern: string | string[], options?: GlobOptions): string[];
+/**
+ * Searches a folder tree for the first file or folder with this name,
+ * closest first.
+ *
+ * @example
+ * nc.find("config.json");
+ * nc.find("fixtures", { type: "folder", cwd: "./test" });
+ *
+ * @param {string} name
+ * @param {FindOptions} [options]
+ * @returns {string | undefined} The absolute path.
+ */
+export function find(name: string, options?: FindOptions): string | undefined;
+/**
+ * Looks for a file or folder in a folder, then in its parent, and so on up
+ * to the root. It's how you find the `package.json` or the `.git` a file
+ * belongs to.
+ *
+ * @example
+ * nc.findUp("package.json");                         // the closest one above the working directory
+ * nc.findUp(".git", { type: "folder", cwd: __dirname });
+ * nc.findUp(["pnpm-lock.yaml", "yarn.lock", "package-lock.json"]);
+ *
+ * @param {string | string[]} name One name, or several to try in each folder, in this order.
+ * @param {{ cwd?: string, type?: "file" | "folder" | "any", stopAt?: string }} [options] Where to start (the working directory by default), what to look for (`"any"` by default), and a folder not to go above.
+ * @returns {string | undefined} The absolute path.
+ */
+export function findUp(name: string | string[], options?: {
+    cwd?: string;
+    type?: "file" | "folder" | "any";
+    stopAt?: string;
+}): string | undefined;
+/**
+ * Reads a file as text, or as a Buffer with `"buffer"`.
+ *
+ * @example
+ * const text = nc.readFile("./README.md");
+ * const bytes = nc.readFile("./logo.png", "buffer");
+ *
+ * @overload
+ * @param {string} path
+ * @param {"buffer"} encoding
+ * @returns {Buffer | undefined} `undefined` if it can't be read.
+ */
+export function readFile(path: string, encoding: "buffer"): Buffer | undefined;
+/**
+ * Reads a file as text.
+ *
+ * @overload
+ * @param {string} path
+ * @param {BufferEncoding} [encoding="utf8"]
+ * @returns {string | undefined} `undefined` if it can't be read.
+ */
+export function readFile(path: string, encoding?: BufferEncoding | undefined): string | undefined;
+/**
+ * Reads a text file as lines. A final newline doesn't add an empty line.
+ *
+ * @example
+ * for (const url of nc.readLines("./urls.txt") ?? []) await check(url);
+ *
+ * @param {string} path
+ * @returns {string[] | undefined} `undefined` if it can't be read.
+ */
+export function readLines(path: string): string[] | undefined;
+/**
+ * Reads a JSON file. If it's missing or invalid you get `fallback`, never
+ * an error.
+ *
+ * @example
+ * const settings = nc.readJSON("./settings.json", { theme: "light" });
+ * const tsconfig = nc.readJSON("./tsconfig.json", {}, { comments: true });
+ *
+ * @template [T=any]
+ * @param {string} path
+ * @param {T} [fallback]
+ * @param {ReadJSONOptions} [options]
+ * @returns {T}
+ */
+export function readJSON<T = any>(path: string, fallback?: T, options?: ReadJSONOptions): T;
+/**
+ * Writes a file atomically, creating its folders. Objects are written as
+ * JSON.
+ *
+ * @example
+ * nc.writeFile("./dist/index.html", html);
+ * nc.writeFile("./.secrets/token", token, { mode: 0o600 });
+ *
+ * @param {string} path
+ * @param {string | Buffer | Uint8Array | object} data
+ * @param {WriteFileOptions} [options]
+ * @returns {boolean} `false` if it failed.
+ */
+export function writeFile(path: string, data: string | Buffer | Uint8Array | object, options?: WriteFileOptions): boolean;
+/**
+ * Writes a value as JSON, atomically, creating folders.
+ *
+ * @example
+ * nc.writeJSON("./data/users.json", users);
+ *
+ * @param {string} path
+ * @param {unknown} data
+ * @param {WriteJSONOptions} [options]
+ * @returns {boolean} `false` if it failed, for example on a circular structure.
+ */
+export function writeJSON(path: string, data: unknown, options?: WriteJSONOptions): boolean;
+/**
+ * Appends to a file, creating it and its folders if needed.
+ *
+ * @example
+ * nc.appendFile("./logs/audit.log", `${new Date().toISOString()} login ${user}\n`);
+ *
+ * @param {string} path
+ * @param {string | Buffer} data
+ * @returns {boolean}
+ */
+export function appendFile(path: string, data: string | Buffer): boolean;
+/**
+ * Creates a file and its folders.
+ *
+ * @example
+ * nc.createFile("./notes.txt", false, "hello");    // only if it doesn't exist
+ * nc.createFile("./data.json", true, { ok: true }); // replace it
+ *
+ * @param {string} path
+ * @param {boolean} [force=false] Replace the file if it exists.
+ * @param {string | Buffer | object | null} [data] Objects are written as JSON.
+ * @returns {boolean | undefined} `false` if it already existed or failed.
+ */
+export function createFile(path: string, force?: boolean, data?: string | Buffer | object | null): boolean | undefined;
+/**
+ * Creates a folder and its parents.
+ *
+ * @example
+ * nc.createFolder("./uploads");
+ * nc.createFolder("./cache", true); // start from an empty folder
+ *
+ * @param {string} path
+ * @param {boolean} [force=false] Delete and recreate it if it exists.
+ * @returns {boolean | undefined} `false` if it already existed or failed.
  */
 export function createFolder(path: string, force?: boolean): boolean | undefined;
 /**
- * Creates a file.
- * @param {string} path - The file path to create.
- * @param {boolean} [force=false] - Whether to recreate the file if it already exists.
- * @param {string|object|null|undefined} [data] - File content to write.
- * @returns {boolean|undefined} True on success, false on failure, undefined if no path was provided.
+ * Makes sure a folder exists and returns its absolute path.
+ *
+ * @example
+ * const dir = nc.ensureFolder("./storage/uploads");
+ *
+ * @param {string} path
+ * @returns {string}
+ * @throws {Error} If it can't be created.
  */
-export function createFile(path: string, force?: boolean, data?: string | object | null | undefined): boolean | undefined;
+export function ensureFolder(path: string): string;
 /**
- * Deletes folders found inside a path.
- * @param {string} [path=process.cwd()] - The base path to inspect.
- * @param {(folder: string) => boolean} [filter=() => true] - Filter applied to each folder path.
- * @returns {number|undefined} Number of deleted folders, or undefined if the path cannot be resolved.
+ * Makes sure a file exists (an empty one if needed) and returns its
+ * absolute path. An existing file is left as is.
+ *
+ * @param {string} path
+ * @returns {string}
+ * @throws {Error} If it can't be created.
  */
-export function deleteFoldersIn(path?: string, filter?: (folder: string) => boolean): number | undefined;
+export function ensureFile(path: string): string;
 /**
- * Deletes a folder.
- * @param {string} path - The folder path to delete.
- * @returns {boolean|undefined} True on success, false on failure, undefined if the path is invalid.
+ * Updates a file's modification time, creating the file if needed, like
+ * the Unix `touch` command.
+ *
+ * @param {string} path
+ * @returns {boolean}
  */
-export function deleteFolder(path: string): boolean | undefined;
+export function touch(path: string): boolean;
 /**
- * Deletes files found inside a path.
- * @param {string} [path=process.cwd()] - The base path to inspect.
- * @param {boolean} [recursive=false] - Whether to scan recursively.
- * @param {(file: string) => boolean} [filter=() => true] - Filter applied to each file path.
- * @returns {number|undefined} Number of deleted files, or undefined if the path cannot be resolved.
+ * Deletes a folder and everything in it.
+ *
+ * @param {string} path
+ * @returns {boolean | undefined} `undefined` if it doesn't exist.
  */
-export function deleteFilesIn(path?: string, recursive?: boolean, filter?: (file: string) => boolean): number | undefined;
+export function deleteFolder(path: string): boolean | undefined;
 /**
  * Deletes a file.
- * @param {string} path - The file path to delete.
- * @returns {boolean|undefined} True on success, false on failure, undefined if the path is invalid.
+ *
+ * @param {string} path
+ * @returns {boolean | undefined} `undefined` if it doesn't exist.
  */
 export function deleteFile(path: string): boolean | undefined;
 /**
- * Copies folders from a source path into a destination folder.
- * @param {Object} options - Copy options.
- * @param {string} options.dest - Destination path.
- * @param {string} [options.path] - Source path.
- * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
- * @param {boolean} [options.withFiles=false] - Whether to copy files as well.
- * @param {boolean} [options.force=false] - Whether to overwrite existing folders.
- * @param {(folder: string) => boolean} [options.filter=() => true] - Filter applied to each folder.
- * @returns {number|undefined} Number of copied folders, or undefined if invalid input.
- */
-export function copyFoldersIn(options: {
-    dest: string;
-    path?: string | undefined;
-    recursive?: boolean | undefined;
-    withFiles?: boolean | undefined;
-    force?: boolean | undefined;
-    filter?: ((folder: string) => boolean) | undefined;
-}): number | undefined;
-/**
- * Copies a folder to a destination path.
- * @param {Object} options - Copy options.
- * @param {string} options.dest - Destination path.
- * @param {string} [options.path] - Source path.
- * @param {boolean} [options.recursive=false] - Whether to copy subfolders.
- * @param {boolean} [options.withFiles=false] - Whether to copy files.
- * @param {boolean} [options.force=false] - Whether to overwrite the destination.
- * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
- */
-export function copyFolder(options: {
-    dest: string;
-    path?: string | undefined;
-    recursive?: boolean | undefined;
-    withFiles?: boolean | undefined;
-    force?: boolean | undefined;
-}): boolean | undefined;
+ * Deletes a file or a folder, whichever it is. Nothing happens if the path
+ * doesn't exist.
+ *
+ * @example
+ * nc.remove("./dist");
+ *
+ * @param {string} path
+ * @returns {boolean} `true` if something was deleted.
+ */
+export function remove(path: string): boolean;
 /**
- * Copies files from a source path into a destination folder.
- * @param {Object} options - Copy options.
- * @param {string} options.dest - Destination path.
- * @param {string} [options.path] - Source path.
- * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
- * @param {boolean} [options.force=false] - Whether to overwrite existing files.
- * @param {(file: string) => boolean} [options.filter=() => true] - Filter applied to each file.
- * @returns {number|undefined} Number of copied files, or undefined if invalid input.
+ * Deletes the folders inside a folder that pass a test.
+ *
+ * @example
+ * nc.deleteFoldersIn("./packages", (folder) => folder.endsWith("dist"));
+ *
+ * @param {string} [path] Defaults to the working directory.
+ * @param {(folder: string) => boolean} [filter] Gets absolute paths. Defaults to every folder.
+ * @returns {number | undefined} How many were deleted.
  */
-export function copyFilesIn(options: {
-    dest: string;
-    path?: string | undefined;
-    recursive?: boolean | undefined;
-    force?: boolean | undefined;
-    filter?: ((file: string) => boolean) | undefined;
-}): number | undefined;
+export function deleteFoldersIn(path?: string, filter?: (folder: string) => boolean): number | undefined;
 /**
- * Copies a file to a destination path.
- * @param {Object} options - Copy options.
- * @param {string} options.path - Source file path.
- * @param {string} options.dest - Destination path.
- * @param {boolean} [options.force=false] - Whether to overwrite the destination file.
- * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
+ * Deletes the files inside a folder that pass a test.
+ *
+ * @example
+ * nc.deleteFilesIn("./logs", false, (file) => file.endsWith(".log"));
+ *
+ * @param {string} [path] Defaults to the working directory.
+ * @param {boolean} [recursive=false]
+ * @param {(file: string) => boolean} [filter] Gets absolute paths. Defaults to every file.
+ * @returns {number | undefined} How many were deleted.
  */
-export function copyFile(options: {
-    path: string;
-    dest: string;
-    force?: boolean | undefined;
-}): boolean | undefined;
+export function deleteFilesIn(path?: string, recursive?: boolean, filter?: (file: string) => boolean): number | undefined;
 /**
- * Moves folders from a source path into a destination folder.
- * @param {Object} options - Move options.
- * @param {string} options.dest - Destination path.
- * @param {string} [options.path] - Source path.
- * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
- * @param {boolean} [options.withFiles=false] - Whether to move files as well.
- * @param {boolean} [options.force=false] - Whether to overwrite existing folders.
- * @param {(folder: string) => boolean} [options.filter=() => true] - Filter applied to each folder.
- * @returns {number|undefined} Number of copied folders, or undefined if invalid input.
- */
-export function moveFoldersIn(options: {
-    dest: string;
-    path?: string | undefined;
-    recursive?: boolean | undefined;
-    withFiles?: boolean | undefined;
-    force?: boolean | undefined;
-    filter?: ((folder: string) => boolean) | undefined;
-}): number | undefined;
-/**
- * Moves a folder to a destination path.
- * @param {Object} options - Move options.
- * @param {string} options.path - Source folder path.
- * @param {string} options.dest - Destination path.
- * @param {boolean} [options.recursive=false] - Whether to move subfolders.
- * @param {boolean} [options.withFiles=false] - Whether to move files.
- * @param {boolean} [options.force=false] - Whether to overwrite the destination.
- * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
- */
-export function moveFolder(options: {
-    path: string;
-    dest: string;
-    recursive?: boolean | undefined;
-    withFiles?: boolean | undefined;
-    force?: boolean | undefined;
-}): boolean | undefined;
+ * Deletes everything inside a folder, keeping the folder.
+ *
+ * @param {string} path
+ * @returns {boolean | undefined} `undefined` if it doesn't exist.
+ */
+export function emptyFolder(path: string): boolean | undefined;
 /**
- * Moves files from a source path into a destination folder.
- * @param {Object} options - Move options.
- * @param {string} options.dest - Destination path.
- * @param {string} [options.path] - Source path.
- * @param {boolean} [options.recursive=true] - Whether to recurse into subfolders.
- * @param {boolean} [options.force=false] - Whether to overwrite existing files.
- * @param {(file: string) => boolean} [options.filter=() => true] - Filter applied to each file.
- * @returns {number|undefined} Number of copied files, or undefined if invalid input.
+ * Copies a file or a whole folder, like `cp -r`.
+ *
+ * @example
+ * nc.copy("./templates", "./dist/templates");
+ * nc.copy("./.env.example", "./.env", { overwrite: false });
+ *
+ * @param {string} source
+ * @param {string} destination
+ * @param {CopyOptions} [options]
+ * @returns {boolean} `false` if the source is missing or the copy failed.
  */
-export function moveFilesIn(options: {
-    dest: string;
-    path?: string | undefined;
-    recursive?: boolean | undefined;
-    force?: boolean | undefined;
-    filter?: ((file: string) => boolean) | undefined;
-}): number | undefined;
+export function copy(source: string, destination: string, options?: CopyOptions): boolean;
+/**
+ * Moves or renames a file or folder, across drives too.
+ *
+ * @example
+ * nc.move("./report.pdf", "./archive/2024/report.pdf");
+ *
+ * @param {string} source
+ * @param {string} destination
+ * @param {{ overwrite?: boolean }} [options] Replace an existing destination. Defaults to `true`.
+ * @returns {boolean}
+ */
+export function move(source: string, destination: string, options?: {
+    overwrite?: boolean;
+}): boolean;
+/**
+ * Copies the folders inside a folder into another one. `copy()` is simpler
+ * for most cases.
+ *
+ * @param {CopyFoldersOptions} options
+ * @returns {number | undefined} How many were copied.
+ */
+export function copyFoldersIn(options: CopyFoldersOptions): number | undefined;
+/**
+ * Copies a folder. Without `recursive` or `withFiles`, only the empty
+ * folder is created; `copy()` copies everything in one call.
+ *
+ * @param {CopyFolderOptions} options
+ * @returns {boolean | undefined}
+ */
+export function copyFolder(options: CopyFolderOptions): boolean | undefined;
+/**
+ * Copies the files inside a folder into another one, keeping the tree.
+ *
+ * @example
+ * nc.copyFilesIn({ path: "./src", dest: "./dist", filter: (file) => file.endsWith(".css") });
+ *
+ * @param {CopyFilesOptions} options
+ * @returns {number | undefined} How many were copied.
+ */
+export function copyFilesIn(options: CopyFilesOptions): number | undefined;
 /**
- * Moves a file to a destination path.
- * @param {Object} options - Move options.
- * @param {string} options.path - Source file path.
- * @param {string} options.dest - Destination path.
- * @param {boolean} [options.force=false] - Whether to overwrite the destination file.
- * @returns {boolean|undefined} True on success, false on failure, undefined if invalid input.
+ * Copies one file. If `dest` ends with `/`, the file keeps its name inside
+ * that folder.
+ *
+ * @example
+ * nc.copyFile({ path: "./src/index.js", dest: "./dist/" });
+ *
+ * @param {CopyFileOptions} options
+ * @returns {boolean | undefined}
  */
-export function moveFile(options: {
+export function copyFile(options: CopyFileOptions): boolean | undefined;
+/**
+ * Moves the folders inside a folder.
+ *
+ * @param {CopyFoldersOptions} options
+ * @returns {number | undefined} How many were moved.
+ */
+export function moveFoldersIn(options: CopyFoldersOptions): number | undefined;
+/**
+ * Moves a folder.
+ *
+ * @param {CopyFolderOptions & { path: string }} options
+ * @returns {boolean | undefined}
+ */
+export function moveFolder(options: CopyFolderOptions & {
     path: string;
-    dest: string;
-    force?: boolean | undefined;
 }): boolean | undefined;
 /**
- * Reads a file as UTF-8 text.
- * @param {string} path - The file path to read.
- * @returns {string|undefined} File content, or undefined if the file cannot be read.
+ * Moves the files inside a folder.
+ *
+ * @param {CopyFilesOptions} options
+ * @returns {number | undefined} How many were moved.
  */
-export function readFile(path: string): string | undefined;
+export function moveFilesIn(options: CopyFilesOptions): number | undefined;
 /**
- * Reads and parses a JSON file.
- * @template T
- * @param {string} path - The JSON file path.
- * @param {T} [fallback] - Value returned when the file is missing or invalid.
- * @returns {T|any|undefined} The parsed value, or the fallback.
+ * Moves one file.
+ *
+ * @example
+ * nc.moveFile({ path: "./logs/app.log", dest: "./logs/archive/" });
+ *
+ * @param {CopyFileOptions} options
+ * @returns {boolean | undefined}
  */
-export function readJSON<T>(path: string, fallback?: T): T | any | undefined;
+export function moveFile(options: CopyFileOptions): boolean | undefined;
 /**
- * Serializes a value to JSON and writes it to a file (creating folders as needed).
- * @param {string} path - The destination file path.
- * @param {*} data - The value to serialize.
- * @param {{ spaces?: number, force?: boolean }} [options] - Formatting options (`spaces` default 2).
- * @returns {boolean} True on success, false on failure.
+ * Does a file or folder exist at this path?
+ *
+ * @param {string} path
+ * @returns {boolean}
  */
-export function writeJSON(path: string, data: any, options?: {
-    spaces?: number;
-    force?: boolean;
-}): boolean;
+export function exists(path: string): boolean;
 /**
- * Appends text to a file, creating it (and its folders) if necessary.
- * @param {string} path - The file path.
- * @param {string} data - The text to append.
- * @returns {boolean} True on success, false on failure.
+ * Is it an existing file?
+ *
+ * @param {string} path
+ * @returns {boolean}
  */
-export function appendFile(path: string, data: string): boolean;
+export function isFile(path: string): boolean;
 /**
- * Checks whether a path (file or folder) exists.
- * @param {string} path - The path to check.
- * @returns {boolean} True if the path exists.
+ * Is it an existing folder?
+ *
+ * @param {string} path
+ * @returns {boolean}
  */
-export function exists(path: string): boolean;
+export function isFolder(path: string): boolean;
 /**
- * Returns filesystem stats for a path, or undefined if it does not exist.
- * @param {string} path - The path to stat.
- * @returns {import("node:fs").Stats|undefined} The stats object, or undefined.
+ * Size, dates and type of a path.
+ *
+ * @example
+ * nc.stat("./video.mp4")?.mtime;
+ *
+ * @param {string} path
+ * @returns {fs.Stats | undefined} `undefined` if it doesn't exist.
  */
-export function stat(path: string): any | undefined;
+export function stat(path: string): fs.Stats | undefined;
 /**
- * Returns the size of a file in bytes.
- * @param {string} path - The file path.
- * @returns {number|undefined} Size in bytes, or undefined if not found.
+ * A file's size in bytes.
+ *
+ * @example
+ * nc.num.formatBytes(nc.fileSize("./backup.zip") ?? 0); // "1.2 GB"
+ *
+ * @param {string} path
+ * @returns {number | undefined} `undefined` if it doesn't exist.
  */
 export function fileSize(path: string): number | undefined;
 /**
- * Computes a hash digest of a file's contents.
- * @param {string} path - The file path.
- * @param {{ algorithm?: string, encoding?: "hex"|"base64"|"base64url" }} [options] - Hash options.
- * @returns {string|undefined} The digest, or undefined if the file cannot be read.
+ * The total size of every file in a folder.
+ *
+ * @param {string} path
+ * @returns {number | undefined} `undefined` if it doesn't exist.
+ */
+export function folderSize(path: string): number | undefined;
+/**
+ * Hashes a file in chunks, so huge files are fine.
+ *
+ * @example
+ * nc.hashFile("./release.zip");                     // sha256, hex
+ * nc.hashFile("./release.zip", { algorithm: "md5" });
+ *
+ * @param {string} path
+ * @param {{ algorithm?: string, encoding?: "hex" | "base64" | "base64url" }} [options] Defaults to sha256 in hex.
+ * @returns {string | undefined} `undefined` if it can't be read.
  */
 export function hashFile(path: string, options?: {
     algorithm?: string;
     encoding?: "hex" | "base64" | "base64url";
 }): string | undefined;
 /**
- * Empties a folder's contents while keeping the folder itself.
- * @param {string} path - The folder to empty.
- * @returns {boolean|undefined} True on success, false on failure, undefined if not found.
+ * Creates a new, unique folder in the system's temp directory.
+ *
+ * @example
+ * const dir = nc.tempFolder("export-");
+ * try { await exportTo(dir); } finally { nc.remove(dir); }
+ *
+ * @param {string} [prefix="nc-"]
+ * @returns {string}
  */
-export function emptyFolder(path: string): boolean | undefined;
+export function tempFolder(prefix?: string): string;
 /**
- * Watches a path and exposes event listeners.
- * @param {Object} [options] - Watch options.
- * @param {string} [options.path=process.cwd()] - Path to watch.
- * @param {boolean} [options.recursive=false] - Whether to watch recursively.
- * @param {(event: "rename"|"change", file: string) => boolean} [options.filter] - Filter applied before dispatch.
- * @returns {{
- *   on: <E extends "change"|"rename"|"all">(event: E, callback: E extends "all" ? (event: "change"|"rename", file: string) => void|Promise<void> : (file: string) => void|Promise<void>) => any,
- *   stop: () => void,
- *   pause: () => any,
- *   resume: () => any,
- * }|undefined} Watch controller, or undefined if the path cannot be resolved.
- */
-export function watch(options?: {
-    path?: string | undefined;
-    recursive?: boolean | undefined;
-    filter?: ((event: "rename" | "change", file: string) => boolean) | undefined;
-}): {
-    on: <E extends "change" | "rename" | "all">(event: E, callback: E extends "all" ? (event: "change" | "rename", file: string) => void | Promise<void> : (file: string) => void | Promise<void>) => any;
-    stop: () => void;
-    pause: () => any;
-    resume: () => any;
-} | undefined;
+ * Turns any text into a file name that works on Windows, macOS and Linux:
+ * forbidden characters are replaced, reserved names like `CON` are
+ * prefixed, and the length is capped.
+ *
+ * @example
+ * nc.sanitizeFilename('Report: Q1/Q2 "final"?.pdf'); // "Report_ Q1_Q2 _final__.pdf"
+ * nc.sanitizeFilename("CON.txt");                    // "_CON.txt"
+ *
+ * @param {string} name
+ * @param {{ replacement?: string }} [options] Defaults to `"_"`.
+ * @returns {string}
+ */
+export function sanitizeFilename(name: string, options?: {
+    replacement?: string;
+}): string;
+/**
+ * Watches a file or folder for changes.
+ *
+ * @example
+ * const watcher = nc.watch({ path: "./src", recursive: true, debounce: 100 })
+ *   .on("change", (file) => nc.info(`Changed: ${file}`))
+ *   .on("rename", (file) => nc.info(`Added or removed: ${file}`));
+ * watcher.stop();
+ *
+ * @param {WatchOptions} [options]
+ * @returns {Watcher | undefined} `undefined` if the path doesn't exist.
+ */
+export function watch(options?: WatchOptions): Watcher | undefined;
+import fs = require("node:fs");
 //# sourceMappingURL=FS.d.ts.map