@visulima/fs 5.0.9 → 5.0.11

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { q as WalkOptions, F as FindUpName, r as FindUpOptions, s as FindUpNameSync, t as WalkEntry, u as ReadFileOptions, v as ContentType, w as ReadJsonOptions, l as JsonReviver, x as RetryOptions, y as WriteFileOptions, z as WriteJsonOptions } from "./packem_shared/types.d-BMdL_ygj.js";
-export { type A as CodeFrameLocation, type k as CodeFrameOptions, B as FIND_UP_STOP, D as F_OK, type E as FindUpNameFnResult, type H as FindUpNameSyncFnResult, type G as GlobOptions, type o as JsonReplacer, K as R_OK, type L as ReadFileEncoding, M as W_OK, X as X_OK } from "./packem_shared/types.d-BMdL_ygj.js";
+import { q as WalkOptions, F as FindUpName, r as FindUpOptions, s as FindUpNameSync, t as WalkEntry, u as ReadFileOptions, v as ContentType, w as ReadJsonOptions, l as JsonReviver, x as RetryOptions, y as WriteFileOptions, z as WriteJsonOptions } from "./packem_shared/types.d-D3Jo_iA-.js";
+export { type A as CodeFrameLocation, type k as CodeFrameOptions, B as FIND_UP_STOP, D as F_OK, type E as FindUpNameFnResult, type H as FindUpNameSyncFnResult, type G as GlobOptions, type o as JsonReplacer, K as R_OK, type L as ReadFileEncoding, M as W_OK, X as X_OK } from "./packem_shared/types.d-D3Jo_iA-.js";
 import { symlink } from 'node:fs';
 export { CRLF, EOL, LF, detect, format } from "./eol.js";
-export { g as glob, a as globSync } from "./packem_shared/glob-sync.d-hXe38TnZ.js";
+export { g as glob, a as globSync } from "./packem_shared/glob-sync.d-DaAZHTsv.js";
 export { type GlobParentOptions, default as globParent } from "./glob-parent.js";
 export { type IsGlobOptions, default as isGlob } from "./is-glob.js";
 export { type MatchOptions, match, matcher } from "./match.js";
@@ -10,878 +10,878 @@ import { JsonValue } from 'type-fest';
 import fs from 'fs';
 import 'fdir';
 /**
-* Options for `copy` and `copySync`.
-*/
+ * Options for `copy` and `copySync`.
+ */
 type CopyOptions = {
   /**
-  * Dereference symlinks, copying the files they point to instead of the
-  * links themselves.
-  * @default false
-  */
+   * Dereference symlinks, copying the files they point to instead of the
+   * links themselves.
+   * @default false
+   */
   dereference?: boolean;
   /**
-  * When `true`, throw an error if the destination already exists and
-  * {@link CopyOptions.overwrite} is `false`. When `false`, existing files
-  * are silently skipped.
-  * @default true
-  */
+   * When `true`, throw an error if the destination already exists and
+   * {@link CopyOptions.overwrite} is `false`. When `false`, existing files
+   * are silently skipped.
+   * @default true
+   */
   errorOnExist?: boolean;
   /**
-  * Function to filter which files/directories are copied. Return `true` to
-  * copy the item, `false` to skip it (and, for directories, their contents).
-  * @param source The source path being considered.
-  * @param destination The destination path it would be copied to.
-  * @returns Whether to copy the item.
-  */
+   * Function to filter which files/directories are copied. Return `true` to
+   * copy the item, `false` to skip it (and, for directories, their contents).
+   * @param source The source path being considered.
+   * @param destination The destination path it would be copied to.
+   * @returns Whether to copy the item.
+   */
   filter?: (source: string, destination: string) => boolean | Promise<boolean>;
   /**
-  * Overwrite existing files/directories at the destination.
-  * @default true
-  */
+   * Overwrite existing files/directories at the destination.
+   * @default true
+   */
   overwrite?: boolean;
   /**
-  * Preserve timestamps (`atime`/`mtime`) from the source.
-  * @default false
-  */
+   * Preserve timestamps (`atime`/`mtime`) from the source.
+   * @default false
+   */
   preserveTimestamps?: boolean;
   /**
-  * When `true`, copy directories recursively.
-  * @default true
-  */
+   * When `true`, copy directories recursively.
+   * @default true
+   */
   recursive?: boolean;
   /**
-  * When `overwrite` is `false`, this controls whether copying over an
-  * existing file throws. Mirrors `node:fs.cp`'s `verbatimSymlinks`.
-  * @default false
-  */
+   * When `overwrite` is `false`, this controls whether copying over an
+   * existing file throws. Mirrors `node:fs.cp`'s `verbatimSymlinks`.
+   * @default false
+   */
   verbatimSymlinks?: boolean;
 };
 /**
-* Synchronous variant of {@link CopyOptions.filter}.
-*/
+ * Synchronous variant of {@link CopyOptions.filter}.
+ */
 type CopyFilterSync = (source: string, destination: string) => boolean;
 /**
-* Asynchronously copies a file or directory (recursively) from `source` to `destination`.
-*
-* Built on `node:fs.cp`, this completes the fs-extra parity story alongside
-* `move`, `remove` and `emptyDir`.
-* @param source The file or directory to copy. Can be a file URL or a string path.
-* @param destination The target path. Can be a file URL or a string path.
-* @param options Optional configuration. See {@link CopyOptions}.
-* @returns A promise that resolves when the copy completes.
-* @throws {AlreadyExistsError} When `overwrite` is `false`, `errorOnExist` is `true`, and the destination exists.
-* @example
-* ```javascript
-* import { copy } from "@visulima/fs";
-*
-* // Copy a template directory, skipping node_modules and overwriting existing files
-* await copy("templates/app", "out/app", {
-*   filter: (src) => !src.includes("node_modules"),
-* });
-* ```
-*/
+ * Asynchronously copies a file or directory (recursively) from `source` to `destination`.
+ *
+ * Built on `node:fs.cp`, this completes the fs-extra parity story alongside
+ * `move`, `remove` and `emptyDir`.
+ * @param source The file or directory to copy. Can be a file URL or a string path.
+ * @param destination The target path. Can be a file URL or a string path.
+ * @param options Optional configuration. See {@link CopyOptions}.
+ * @returns A promise that resolves when the copy completes.
+ * @throws {AlreadyExistsError} When `overwrite` is `false`, `errorOnExist` is `true`, and the destination exists.
+ * @example
+ * ```javascript
+ * import { copy } from "@visulima/fs";
+ *
+ * // Copy a template directory, skipping node_modules and overwriting existing files
+ * await copy("templates/app", "out/app", {
+ *   filter: (src) => !src.includes("node_modules"),
+ * });
+ * ```
+ */
 declare const copy: (source: URL | string, destination: URL | string, options?: CopyOptions) => Promise<void>;
 /**
-* Synchronously copies a file or directory (recursively) from `source` to `destination`.
-*
-* The synchronous counterpart of `copy`. Note that `cpSync` only accepts a
-* synchronous `filter`.
-* @param source The file or directory to copy. Can be a file URL or a string path.
-* @param destination The target path. Can be a file URL or a string path.
-* @param options Optional configuration. See {@link CopyOptions} (the `filter` must be synchronous).
-* @throws {AlreadyExistsError} When `overwrite` is `false`, `errorOnExist` is `true`, and the destination exists.
-* @example
-* ```javascript
-* import { copySync } from "@visulima/fs";
-*
-* copySync("templates/app", "out/app", { overwrite: false, errorOnExist: false });
-* ```
-*/
+ * Synchronously copies a file or directory (recursively) from `source` to `destination`.
+ *
+ * The synchronous counterpart of `copy`. Note that `cpSync` only accepts a
+ * synchronous `filter`.
+ * @param source The file or directory to copy. Can be a file URL or a string path.
+ * @param destination The target path. Can be a file URL or a string path.
+ * @param options Optional configuration. See {@link CopyOptions} (the `filter` must be synchronous).
+ * @throws {AlreadyExistsError} When `overwrite` is `false`, `errorOnExist` is `true`, and the destination exists.
+ * @example
+ * ```javascript
+ * import { copySync } from "@visulima/fs";
+ *
+ * copySync("templates/app", "out/app", { overwrite: false, errorOnExist: false });
+ * ```
+ */
 declare const copySync: (source: URL | string, destination: URL | string, options?: Omit<CopyOptions, "filter"> & {
   filter?: CopyFilterSync;
 }) => void;
 /**
-* Ensures that the directory exists.
-* If the directory structure does not exist, it is created. Like mkdir -p.
-* @param directory The path to the directory to ensure exists.
-* @example
-* ```javascript
-* import ensureDir from "@visulima/fs/ensure/ensure-dir";
-*
-* await ensureDir("/tmp/foo/bar/baz");
-* // Creates the directory structure /tmp/foo/bar/baz if it doesn't exist
-* ```
-*/
+ * Ensures that the directory exists.
+ * If the directory structure does not exist, it is created. Like mkdir -p.
+ * @param directory The path to the directory to ensure exists.
+ * @example
+ * ```javascript
+ * import ensureDir from "@visulima/fs/ensure/ensure-dir";
+ *
+ * await ensureDir("/tmp/foo/bar/baz");
+ * // Creates the directory structure /tmp/foo/bar/baz if it doesn't exist
+ * ```
+ */
 declare const ensureDir: (directory: URL | string) => Promise<void>;
 /**
-* Ensures that the directory exists.
-* If the directory structure does not exist, it is created. Like mkdir -p.
-* @param directory The path to the directory to ensure exists.
-* @example
-* ```javascript
-* import ensureDirSync from "@visulima/fs/ensure/ensure-dir-sync";
-*
-* ensureDirSync("/tmp/foo/bar/baz");
-* // Creates the directory structure /tmp/foo/bar/baz if it doesn't exist
-* ```
-*/
+ * Ensures that the directory exists.
+ * If the directory structure does not exist, it is created. Like mkdir -p.
+ * @param directory The path to the directory to ensure exists.
+ * @example
+ * ```javascript
+ * import ensureDirSync from "@visulima/fs/ensure/ensure-dir-sync";
+ *
+ * ensureDirSync("/tmp/foo/bar/baz");
+ * // Creates the directory structure /tmp/foo/bar/baz if it doesn't exist
+ * ```
+ */
 declare const ensureDirSync: (directory: URL | string) => void;
 /**
-* Asynchronously ensures that a file exists.
-* If the directory structure for the file does not exist, it is created.
-* If the file already exists, it is not modified.
-* @param filePath The path to the file. Can be a string or a URL object.
-* @returns A Promise that resolves when the file has been created or confirmed to exist.
-* @throws Will throw an error if the path exists and is not a file.
-* @throws Will throw an error if directory or file creation fails for reasons other than the path not existing initially.
-* @example
-* ```typescript
-* import { ensureFile } from "@visulima/fs";
-*
-* (async () => {
-*   try {
-*     await ensureFile("path/to/my/file.txt");
-*     console.log("File ensured!");
-*
-*     await ensureFile(new URL("file:///path/to/another/file.log"));
-*     console.log("Another file ensured!");
-*   } catch (error) {
-*     console.error("Failed to ensure file:", error);
-*   }
-* })();
-* ```
-*/
+ * Asynchronously ensures that a file exists.
+ * If the directory structure for the file does not exist, it is created.
+ * If the file already exists, it is not modified.
+ * @param filePath The path to the file. Can be a string or a URL object.
+ * @returns A Promise that resolves when the file has been created or confirmed to exist.
+ * @throws Will throw an error if the path exists and is not a file.
+ * @throws Will throw an error if directory or file creation fails for reasons other than the path not existing initially.
+ * @example
+ * ```typescript
+ * import { ensureFile } from "@visulima/fs";
+ *
+ * (async () => {
+ *   try {
+ *     await ensureFile("path/to/my/file.txt");
+ *     console.log("File ensured!");
+ *
+ *     await ensureFile(new URL("file:///path/to/another/file.log"));
+ *     console.log("Another file ensured!");
+ *   } catch (error) {
+ *     console.error("Failed to ensure file:", error);
+ *   }
+ * })();
+ * ```
+ */
 declare const ensureFile: (filePath: URL | string) => Promise<void>;
 /**
-* Ensures that the file exists.
-* If the file that is requested to be created is in directories that do not exist,
-* these directories are created. If the file already exists, it is NOT MODIFIED.
-* @param filePath The path to the file to ensure exists.
-* @example
-* ```javascript
-* import { ensureFileSync } from "@visulima/fs";
-*
-* ensureFileSync("/tmp/foo/bar/baz.txt");
-* // Creates the file /tmp/foo/bar/baz.txt and any missing parent directories if they don't exist
-* ```
-*/
+ * Ensures that the file exists.
+ * If the file that is requested to be created is in directories that do not exist,
+ * these directories are created. If the file already exists, it is NOT MODIFIED.
+ * @param filePath The path to the file to ensure exists.
+ * @example
+ * ```javascript
+ * import { ensureFileSync } from "@visulima/fs";
+ *
+ * ensureFileSync("/tmp/foo/bar/baz.txt");
+ * // Creates the file /tmp/foo/bar/baz.txt and any missing parent directories if they don't exist
+ * ```
+ */
 declare const ensureFileSync: (filePath: URL | string) => void;
 /**
-* Ensures that the hard link exists.
-* If the directory structure does not exist, it is created.
-* @param source The path to the source file or directory.
-* @param destination The path to the destination link.
-* @example
-* ```javascript
-* import { ensureLink } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* // ensure the link /tmp/foo/bar-link.txt points to /tmp/foo/bar.txt
-* await ensureLink(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "bar-link.txt"));
-* ```
-*/
+ * Ensures that the hard link exists.
+ * If the directory structure does not exist, it is created.
+ * @param source The path to the source file or directory.
+ * @param destination The path to the destination link.
+ * @example
+ * ```javascript
+ * import { ensureLink } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // ensure the link /tmp/foo/bar-link.txt points to /tmp/foo/bar.txt
+ * await ensureLink(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "bar-link.txt"));
+ * ```
+ */
 declare const ensureLink: (source: URL | string, destination: URL | string) => Promise<void>;
 /**
-* Ensures that the hard link exists.
-* If the directory structure does not exist, it is created.
-* @param source The path to the source file or directory.
-* @param destination The path to the destination link.
-* @example
-* ```javascript
-* import { ensureLinkSync } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* // ensure the link /tmp/foo/bar-link.txt points to /tmp/foo/bar.txt
-* ensureLinkSync(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "bar-link.txt"));
-* ```
-*/
+ * Ensures that the hard link exists.
+ * If the directory structure does not exist, it is created.
+ * @param source The path to the source file or directory.
+ * @param destination The path to the destination link.
+ * @example
+ * ```javascript
+ * import { ensureLinkSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // ensure the link /tmp/foo/bar-link.txt points to /tmp/foo/bar.txt
+ * ensureLinkSync(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "bar-link.txt"));
+ * ```
+ */
 declare const ensureLinkSync: (source: URL | string, destination: URL | string) => void;
 /**
-* Ensures that the link exists, and points to a valid file.
-* If the directory structure does not exist, it is created.
-* If the link already exists, it is not modified but error is thrown if it is not point to the given target.
-* @param target the source file path
-* @param linkName the destination link path
-* @param type the type of the symlink, or null to use automatic detection
-* @returns A void promise that resolves once the link exists.
-* @example
-* ```javascript
-* import { ensureSymlink } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* // Ensure a symlink /tmp/foo/link-to-bar.txt points to /tmp/foo/bar.txt
-* await ensureSymlink(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "link-to-bar.txt"));
-*
-* // Ensure a directory symlink /tmp/foo/link-to-baz-dir points to /tmp/foo/baz-dir
-* await ensureSymlink(join("/tmp", "foo", "baz-dir"), join("/tmp", "foo", "link-to-baz-dir"), "dir");
-* ```
-*/
+ * Ensures that the link exists, and points to a valid file.
+ * If the directory structure does not exist, it is created.
+ * If the link already exists, it is not modified but error is thrown if it is not point to the given target.
+ * @param target the source file path
+ * @param linkName the destination link path
+ * @param type the type of the symlink, or null to use automatic detection
+ * @returns A void promise that resolves once the link exists.
+ * @example
+ * ```javascript
+ * import { ensureSymlink } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // Ensure a symlink /tmp/foo/link-to-bar.txt points to /tmp/foo/bar.txt
+ * await ensureSymlink(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "link-to-bar.txt"));
+ *
+ * // Ensure a directory symlink /tmp/foo/link-to-baz-dir points to /tmp/foo/baz-dir
+ * await ensureSymlink(join("/tmp", "foo", "baz-dir"), join("/tmp", "foo", "link-to-baz-dir"), "dir");
+ * ```
+ */
 declare const ensureSymlink: (target: URL | string, linkName: URL | string, type?: symlink.Type) => Promise<void>;
 /**
-* Ensures that the link exists, and points to a valid file.
-* If the directory structure does not exist, it is created.
-* If the link already exists, it is not modified but error is thrown if it is not point to the given target.
-* @param target the source file path
-* @param linkName the destination link path
-* @param type the type of the symlink, or null to use automatic detection
-* @returns A void.
-* @example
-* ```javascript
-* import { ensureSymlinkSync } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* // Ensure a symlink /tmp/foo/link-to-bar.txt points to /tmp/foo/bar.txt
-* ensureSymlinkSync(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "link-to-bar.txt"));
-*
-* // Ensure a directory symlink /tmp/foo/link-to-baz-dir points to /tmp/foo/baz-dir
-* ensureSymlinkSync(join("/tmp", "foo", "baz-dir"), join("/tmp", "foo", "link-to-baz-dir"), "dir");
-* ```
-*/
+ * Ensures that the link exists, and points to a valid file.
+ * If the directory structure does not exist, it is created.
+ * If the link already exists, it is not modified but error is thrown if it is not point to the given target.
+ * @param target the source file path
+ * @param linkName the destination link path
+ * @param type the type of the symlink, or null to use automatic detection
+ * @returns A void.
+ * @example
+ * ```javascript
+ * import { ensureSymlinkSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // Ensure a symlink /tmp/foo/link-to-bar.txt points to /tmp/foo/bar.txt
+ * ensureSymlinkSync(join("/tmp", "foo", "bar.txt"), join("/tmp", "foo", "link-to-bar.txt"));
+ *
+ * // Ensure a directory symlink /tmp/foo/link-to-baz-dir points to /tmp/foo/baz-dir
+ * ensureSymlinkSync(join("/tmp", "foo", "baz-dir"), join("/tmp", "foo", "link-to-baz-dir"), "dir");
+ * ```
+ */
 declare const ensureSymlinkSync: (target: URL | string, linkName: URL | string, type?: symlink.Type) => void;
 /**
-* Asynchronously collects all file paths within a directory that match the specified criteria.
-* By default, it searches for JavaScript and TypeScript file extensions.
-* @param directory The root directory to start collecting files from.
-* @param options Optional configuration to control the collection process. See {@link WalkOptions}.
-* @returns A promise that resolves to an array of absolute file paths.
-* @example
-* ```javascript
-* import { collect } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* const collectFiles = async () => {
-*   // Collect all .txt and .md files in /tmp/docs, up to 2 levels deep
-*   const files = await collect(join("/tmp", "docs"), {
-*     extensions: ["txt", "md"],
-*     maxDepth: 2,
-*     includeDirs: false, // Only collect files
-*   });
-*   console.log(files);
-*   // Example output: ['/tmp/docs/file1.txt', '/tmp/docs/subdir/report.md']
-*
-*   // Collect all .js files, excluding anything in node_modules
-*   const jsFiles = await collect(join("/tmp", "project"), {
-*     extensions: ["js"],
-*     skip: [/node_modules/],
-*   });
-*   console.log(jsFiles);
-* };
-*
-* collectFiles();
-* ```
-*/
+ * Asynchronously collects all file paths within a directory that match the specified criteria.
+ * By default, it searches for JavaScript and TypeScript file extensions.
+ * @param directory The root directory to start collecting files from.
+ * @param options Optional configuration to control the collection process. See {@link WalkOptions}.
+ * @returns A promise that resolves to an array of absolute file paths.
+ * @example
+ * ```javascript
+ * import { collect } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * const collectFiles = async () => {
+ *   // Collect all .txt and .md files in /tmp/docs, up to 2 levels deep
+ *   const files = await collect(join("/tmp", "docs"), {
+ *     extensions: ["txt", "md"],
+ *     maxDepth: 2,
+ *     includeDirs: false, // Only collect files
+ *   });
+ *   console.log(files);
+ *   // Example output: ['/tmp/docs/file1.txt', '/tmp/docs/subdir/report.md']
+ *
+ *   // Collect all .js files, excluding anything in node_modules
+ *   const jsFiles = await collect(join("/tmp", "project"), {
+ *     extensions: ["js"],
+ *     skip: [/node_modules/],
+ *   });
+ *   console.log(jsFiles);
+ * };
+ *
+ * collectFiles();
+ * ```
+ */
 declare const collect: (directory: string, options?: WalkOptions) => Promise<string[]>;
 /**
-* Synchronously collects all file paths within a directory that match the specified criteria.
-* By default, it searches for JavaScript and TypeScript file extensions.
-* @param directory The root directory to start collecting files from.
-* @param options Optional configuration to control the collection process. See {@link WalkOptions}.
-* @returns An array of absolute file paths.
-* @example
-* ```javascript
-* import { collectSync } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* // Collect all .txt and .md files in /tmp/docs, up to 2 levels deep
-* const files = collectSync(join("/tmp", "docs"), {
-*   extensions: ["txt", "md"],
-*   maxDepth: 2,
-*   includeDirs: false, // Only collect files
-* });
-* console.log(files);
-* // Example output: ['/tmp/docs/file1.txt', '/tmp/docs/subdir/report.md']
-*
-* // Collect all .js files, excluding anything in node_modules
-* const jsFiles = collectSync(join("/tmp", "project"), {
-*   extensions: ["js"],
-*   skip: [/node_modules/],
-* });
-* console.log(jsFiles);
-* ```
-*/
+ * Synchronously collects all file paths within a directory that match the specified criteria.
+ * By default, it searches for JavaScript and TypeScript file extensions.
+ * @param directory The root directory to start collecting files from.
+ * @param options Optional configuration to control the collection process. See {@link WalkOptions}.
+ * @returns An array of absolute file paths.
+ * @example
+ * ```javascript
+ * import { collectSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // Collect all .txt and .md files in /tmp/docs, up to 2 levels deep
+ * const files = collectSync(join("/tmp", "docs"), {
+ *   extensions: ["txt", "md"],
+ *   maxDepth: 2,
+ *   includeDirs: false, // Only collect files
+ * });
+ * console.log(files);
+ * // Example output: ['/tmp/docs/file1.txt', '/tmp/docs/subdir/report.md']
+ *
+ * // Collect all .js files, excluding anything in node_modules
+ * const jsFiles = collectSync(join("/tmp", "project"), {
+ *   extensions: ["js"],
+ *   skip: [/node_modules/],
+ * });
+ * console.log(jsFiles);
+ * ```
+ */
 declare const collectSync: (directory: string, options?: WalkOptions) => string[];
 /**
-* Asynchronously finds a file or directory by walking up parent directories.
-* @param name The name(s) of the file or directory to find. Can be a string, an array of strings, or a function that returns a name or `FIND_UP_STOP`.
-* @param options Optional configuration for the search. See {@link FindUpOptions}.
-* @returns A promise that resolves to the absolute path of the first found file/directory, or `undefined` if not found.
-* @example
-* ```javascript
-* import { findUp } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* const findProjectRoot = async () => {
-*   // Find the closest package.json, starting from /tmp/foo/bar/baz
-*   const projectRoot = await findUp("package.json", {
-*     cwd: join("/tmp", "foo", "bar", "baz"),
-*     type: "file",
-*   });
-*   console.log(projectRoot); // e.g., /tmp/foo/package.json or undefined
-*
-*   // Find the closest .git directory or a README.md file
-*   const gitDirOrReadme = await findUp([".git", "README.md"], {
-*     cwd: join("/tmp", "foo", "bar"),
-*   });
-*   console.log(gitDirOrReadme);
-*
-*   // Find using a custom function, stopping at /tmp
-*   const customFound = await findUp(
-*     (directory) => {
-*       if (directory === join("/tmp", "foo")) {
-*         return "found-it-here.txt"; // Pretend this file exists in /tmp/foo
-*       }
-*       return undefined;
-*     },
-*     {
-*       cwd: join("/tmp", "foo", "bar", "baz"),
-*       stopAt: join("/tmp"),
-*     }
-*   );
-*   console.log(customFound);
-* };
-*
-* findProjectRoot();
-* ```
-*/
+ * Asynchronously finds a file or directory by walking up parent directories.
+ * @param name The name(s) of the file or directory to find. Can be a string, an array of strings, or a function that returns a name or `FIND_UP_STOP`.
+ * @param options Optional configuration for the search. See {@link FindUpOptions}.
+ * @returns A promise that resolves to the absolute path of the first found file/directory, or `undefined` if not found.
+ * @example
+ * ```javascript
+ * import { findUp } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * const findProjectRoot = async () => {
+ *   // Find the closest package.json, starting from /tmp/foo/bar/baz
+ *   const projectRoot = await findUp("package.json", {
+ *     cwd: join("/tmp", "foo", "bar", "baz"),
+ *     type: "file",
+ *   });
+ *   console.log(projectRoot); // e.g., /tmp/foo/package.json or undefined
+ *
+ *   // Find the closest .git directory or a README.md file
+ *   const gitDirOrReadme = await findUp([".git", "README.md"], {
+ *     cwd: join("/tmp", "foo", "bar"),
+ *   });
+ *   console.log(gitDirOrReadme);
+ *
+ *   // Find using a custom function, stopping at /tmp
+ *   const customFound = await findUp(
+ *     (directory) => {
+ *       if (directory === join("/tmp", "foo")) {
+ *         return "found-it-here.txt"; // Pretend this file exists in /tmp/foo
+ *       }
+ *       return undefined;
+ *     },
+ *     {
+ *       cwd: join("/tmp", "foo", "bar", "baz"),
+ *       stopAt: join("/tmp"),
+ *     }
+ *   );
+ *   console.log(customFound);
+ * };
+ *
+ * findProjectRoot();
+ * ```
+ */
 declare const findUp: (name: FindUpName, options?: FindUpOptions) => Promise<string | undefined>;
 /**
-* Synchronously finds a file or directory by walking up parent directories.
-* @param name The name(s) of the file or directory to find. Can be a string, an array of strings, or a function that returns a name or `FIND_UP_STOP`.
-* @param options Optional configuration for the search. See {@link FindUpOptions}.
-* @returns The absolute path of the first found file/directory, or `undefined` if not found.
-* @example
-* ```javascript
-* import { findUpSync } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* // Find the closest package.json, starting from /tmp/foo/bar/baz
-* const projectRoot = findUpSync("package.json", {
-*   cwd: join("/tmp", "foo", "bar", "baz"),
-*   type: "file",
-* });
-* console.log(projectRoot); // e.g., /tmp/foo/package.json or undefined
-*
-* // Find the closest .git directory or a README.md file
-* const gitDirOrReadme = findUpSync([".git", "README.md"], {
-*   cwd: join("/tmp", "foo", "bar"),
-* });
-* console.log(gitDirOrReadme);
-*
-* // Find using a custom function, stopping at /tmp
-* const customFound = findUpSync(
-*   (directory) => {
-*     if (directory === join("/tmp", "foo")) {
-*       return "found-it-here.txt"; // Pretend this file exists in /tmp/foo
-*     }
-*     return undefined;
-*   },
-*   {
-*     cwd: join("/tmp", "foo", "bar", "baz"),
-*     stopAt: join("/tmp"),
-*   }
-* );
-* console.log(customFound);
-* ```
-*/
+ * Synchronously finds a file or directory by walking up parent directories.
+ * @param name The name(s) of the file or directory to find. Can be a string, an array of strings, or a function that returns a name or `FIND_UP_STOP`.
+ * @param options Optional configuration for the search. See {@link FindUpOptions}.
+ * @returns The absolute path of the first found file/directory, or `undefined` if not found.
+ * @example
+ * ```javascript
+ * import { findUpSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // Find the closest package.json, starting from /tmp/foo/bar/baz
+ * const projectRoot = findUpSync("package.json", {
+ *   cwd: join("/tmp", "foo", "bar", "baz"),
+ *   type: "file",
+ * });
+ * console.log(projectRoot); // e.g., /tmp/foo/package.json or undefined
+ *
+ * // Find the closest .git directory or a README.md file
+ * const gitDirOrReadme = findUpSync([".git", "README.md"], {
+ *   cwd: join("/tmp", "foo", "bar"),
+ * });
+ * console.log(gitDirOrReadme);
+ *
+ * // Find using a custom function, stopping at /tmp
+ * const customFound = findUpSync(
+ *   (directory) => {
+ *     if (directory === join("/tmp", "foo")) {
+ *       return "found-it-here.txt"; // Pretend this file exists in /tmp/foo
+ *     }
+ *     return undefined;
+ *   },
+ *   {
+ *     cwd: join("/tmp", "foo", "bar", "baz"),
+ *     stopAt: join("/tmp"),
+ *   }
+ * );
+ * console.log(customFound);
+ * ```
+ */
 declare const findUpSync: (name: FindUpNameSync, options?: FindUpOptions) => string | undefined;
 /**
-* Asynchronously walks the file tree rooted at `directory`, yielding each file or directory that matches the criteria specified in `options`.
-* @param directory The root directory to start walking from.
-* @param options Optional configuration to control the walking process. See {@link WalkOptions}.
-* @param options.extensions List of file extensions used to filter entries.
-* @param options.followSymlinks Indicates whether symlinks should be resolved or not.
-* @param options.includeDirs Indicates whether directory entries should be included or not.
-* @param options.includeFiles Indicates whether file entries should be included or not.
-* @param options.includeSymlinks Indicates whether symlink entries should be included or not.
-* @param options.match List of regular expression or glob patterns used to filter entries.
-* @param options.maxDepth Maximum depth to walk. Defaults to infinity.
-* @param options.skip List of regular expression or glob patterns used to skip entries.
-* @returns An async iterable iterator yielding {@link WalkEntry} objects for each matching file or directory.
-* @example
-* ```javascript
-* import { walk } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* const printEntries = async () => {
-*   // Walk through /tmp/my-project, looking for .ts files, max depth 2
-*   for await (const entry of walk(join("/tmp", "my-project"), { extensions: ["ts"], maxDepth: 2 })) {
-*     console.log(`Found: ${entry.path} (Type: ${entry.isFile() ? 'file' : 'directory'})`);
-*   }
-*
-*   // Walk, including only directories, and skip any node_modules folders
-*   for await (const entry of walk(join("/tmp", "another-project"), { includeFiles: false, skip: [/node_modules/] })) {
-*     if (entry.isDirectory()) {
-*        console.log(`Directory: ${entry.path}`);
-*     }
-*   }
-* };
-*
-* printEntries();
-* ```
-*/
+ * Asynchronously walks the file tree rooted at `directory`, yielding each file or directory that matches the criteria specified in `options`.
+ * @param directory The root directory to start walking from.
+ * @param options Optional configuration to control the walking process. See {@link WalkOptions}.
+ * @param options.extensions List of file extensions used to filter entries.
+ * @param options.followSymlinks Indicates whether symlinks should be resolved or not.
+ * @param options.includeDirs Indicates whether directory entries should be included or not.
+ * @param options.includeFiles Indicates whether file entries should be included or not.
+ * @param options.includeSymlinks Indicates whether symlink entries should be included or not.
+ * @param options.match List of regular expression or glob patterns used to filter entries.
+ * @param options.maxDepth Maximum depth to walk. Defaults to infinity.
+ * @param options.skip List of regular expression or glob patterns used to skip entries.
+ * @returns An async iterable iterator yielding {@link WalkEntry} objects for each matching file or directory.
+ * @example
+ * ```javascript
+ * import { walk } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * const printEntries = async () => {
+ *   // Walk through /tmp/my-project, looking for .ts files, max depth 2
+ *   for await (const entry of walk(join("/tmp", "my-project"), { extensions: ["ts"], maxDepth: 2 })) {
+ *     console.log(`Found: ${entry.path} (Type: ${entry.isFile() ? 'file' : 'directory'})`);
+ *   }
+ *
+ *   // Walk, including only directories, and skip any node_modules folders
+ *   for await (const entry of walk(join("/tmp", "another-project"), { includeFiles: false, skip: [/node_modules/] })) {
+ *     if (entry.isDirectory()) {
+ *        console.log(`Directory: ${entry.path}`);
+ *     }
+ *   }
+ * };
+ *
+ * printEntries();
+ * ```
+ */
 declare function walk(directory: URL | string, options?: WalkOptions): AsyncIterableIterator<WalkEntry>;
 /**
-* Synchronously walks the file tree rooted at `directory`, yielding each file or directory that matches the criteria specified in `options`.
-* This is the synchronous version of the async walk function.
-* @param directory The root directory to start walking from.
-* @param options Optional configuration to control the walking process. See {@link WalkOptions}.
-* @param options.extensions List of file extensions used to filter entries.
-* @param options.followSymlinks Indicates whether symlinks should be resolved or not.
-* @param options.includeDirs Indicates whether directory entries should be included or not.
-* @param options.includeFiles Indicates whether file entries should be included or not.
-* @param options.includeSymlinks Indicates whether symlink entries should be included or not.
-* @param options.match List of regular expression or glob patterns used to filter entries.
-* @param options.maxDepth Maximum depth to walk. Defaults to infinity.
-* @param options.skip List of regular expression or glob patterns used to skip entries.
-* @returns An iterable iterator yielding {@link WalkEntry} objects for each matching file or directory.
-* @example
-* ```javascript
-* import { walkSync } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* // Walk through /tmp/my-project, looking for .ts files, max depth 2
-* for (const entry of walkSync(join("/tmp", "my-project"), { extensions: ["ts"], maxDepth: 2 })) {
-*   console.log(`Found: ${entry.path} (Type: ${entry.isFile() ? 'file' : 'directory'})`);
-* }
-*
-* // Walk, including only directories, and skip any node_modules folders
-* for (const entry of walkSync(join("/tmp", "another-project"), { includeFiles: false, skip: [/node_modules/] })) {
-*   if (entry.isDirectory()) {
-*      console.log(`Directory: ${entry.path}`);
-*   }
-* }
-* ```
-*/
+ * Synchronously walks the file tree rooted at `directory`, yielding each file or directory that matches the criteria specified in `options`.
+ * This is the synchronous version of the async walk function.
+ * @param directory The root directory to start walking from.
+ * @param options Optional configuration to control the walking process. See {@link WalkOptions}.
+ * @param options.extensions List of file extensions used to filter entries.
+ * @param options.followSymlinks Indicates whether symlinks should be resolved or not.
+ * @param options.includeDirs Indicates whether directory entries should be included or not.
+ * @param options.includeFiles Indicates whether file entries should be included or not.
+ * @param options.includeSymlinks Indicates whether symlink entries should be included or not.
+ * @param options.match List of regular expression or glob patterns used to filter entries.
+ * @param options.maxDepth Maximum depth to walk. Defaults to infinity.
+ * @param options.skip List of regular expression or glob patterns used to skip entries.
+ * @returns An iterable iterator yielding {@link WalkEntry} objects for each matching file or directory.
+ * @example
+ * ```javascript
+ * import { walkSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * // Walk through /tmp/my-project, looking for .ts files, max depth 2
+ * for (const entry of walkSync(join("/tmp", "my-project"), { extensions: ["ts"], maxDepth: 2 })) {
+ *   console.log(`Found: ${entry.path} (Type: ${entry.isFile() ? 'file' : 'directory'})`);
+ * }
+ *
+ * // Walk, including only directories, and skip any node_modules folders
+ * for (const entry of walkSync(join("/tmp", "another-project"), { includeFiles: false, skip: [/node_modules/] })) {
+ *   if (entry.isDirectory()) {
+ *      console.log(`Directory: ${entry.path}`);
+ *   }
+ * }
+ * ```
+ */
 declare function walkSync(directory: URL | string, options?: WalkOptions): IterableIterator<WalkEntry>;
 /**
-* Asynchronously tests a user's permissions for the file or directory specified by path.
-* Returns a Promise that resolves to `true` if the accessibility check is successful, `false` otherwise.
-* @param path The path to the file or directory. Can be a string or a URL object.
-* @param mode The accessibility checks to perform. Defaults to `F_OK` (check for existence).
-* Other possible values include `R_OK` (check for read access), `W_OK` (check for write access),
-* and `X_OK` (check for execute/search access). Multiple modes can be combined using bitwise OR.
-* @returns A Promise that resolves to a boolean indicating if the path is accessible with the specified mode.
-* @example
-* ```typescript
-* import { isAccessible, F_OK, R_OK } from "@visulima/fs";
-*
-* (async () => {
-*   if (await isAccessible("myFile.txt")) {
-*     console.log("myFile.txt exists");
-*   }
-*
-*   if (await isAccessible("myFile.txt", R_OK)) {
-*     console.log("myFile.txt is readable");
-*   }
-*
-*   if (await isAccessible("myDirectory", F_OK | R_OK | W_OK)) {
-*     console.log("myDirectory exists, is readable and writable");
-*   }
-* })();
-* ```
-*/
+ * Asynchronously tests a user's permissions for the file or directory specified by path.
+ * Returns a Promise that resolves to `true` if the accessibility check is successful, `false` otherwise.
+ * @param path The path to the file or directory. Can be a string or a URL object.
+ * @param mode The accessibility checks to perform. Defaults to `F_OK` (check for existence).
+ * Other possible values include `R_OK` (check for read access), `W_OK` (check for write access),
+ * and `X_OK` (check for execute/search access). Multiple modes can be combined using bitwise OR.
+ * @returns A Promise that resolves to a boolean indicating if the path is accessible with the specified mode.
+ * @example
+ * ```typescript
+ * import { isAccessible, F_OK, R_OK } from "@visulima/fs";
+ *
+ * (async () => {
+ *   if (await isAccessible("myFile.txt")) {
+ *     console.log("myFile.txt exists");
+ *   }
+ *
+ *   if (await isAccessible("myFile.txt", R_OK)) {
+ *     console.log("myFile.txt is readable");
+ *   }
+ *
+ *   if (await isAccessible("myDirectory", F_OK | R_OK | W_OK)) {
+ *     console.log("myDirectory exists, is readable and writable");
+ *   }
+ * })();
+ * ```
+ */
 declare function isAccessible(path: URL | string, mode?: number): Promise<boolean>;
 /** Returns a boolean indicating if the path is accessible or not. */
 declare function isAccessibleSync(path: URL | string, mode?: number): boolean;
 type Options = {
   /**
-  * The working directory to find source files.
-  * The source and destination path are relative to this.
-  * @default process.cwd()
-  */
+   * The working directory to find source files.
+   * The source and destination path are relative to this.
+   * @default process.cwd()
+   */
   cwd?: URL | string;
   /**
-  * [Permissions](https://en.wikipedia.org/wiki/File-system_permissions#Numeric_notation) for created directories.
-  *
-  * It has no effect on Windows.
-  * @default 0o777
-  */
+   * [Permissions](https://en.wikipedia.org/wiki/File-system_permissions#Numeric_notation) for created directories.
+   *
+   * It has no effect on Windows.
+   * @default 0o777
+   */
   readonly directoryMode?: number;
   /**
-  * Overwrite existing destination file.
-  * @default true
-  */
+   * Overwrite existing destination file.
+   * @default true
+   */
   readonly overwrite?: boolean;
 };
 /**
-* Move a file asynchronously.
-* @param sourcePath The file you want to move.
-* @param destinationPath Where you want the file moved.
-* @param options Configuration options.
-* @returns A `Promise` that resolves when the file has been moved.
-* @example
-* ```
-* import { move } from '@visulima/fs';
-*
-* await move('source/test.png', 'destination/test.png');
-* console.log('The file has been moved');
-* ```
-*/
+ * Move a file asynchronously.
+ * @param sourcePath The file you want to move.
+ * @param destinationPath Where you want the file moved.
+ * @param options Configuration options.
+ * @returns A `Promise` that resolves when the file has been moved.
+ * @example
+ * ```
+ * import { move } from '@visulima/fs';
+ *
+ * await move('source/test.png', 'destination/test.png');
+ * console.log('The file has been moved');
+ * ```
+ */
 declare const move: (sourcePath: string, destinationPath: string, options?: Options) => Promise<void>;
 /**
-* Move a file synchronously.
-* @param sourcePath The file you want to move.
-* @param destinationPath Where you want the file moved.
-* @param options Configuration options.
-* @example
-* ```
-* import { moveSync } from '@visulima/fs';
-*
-* moveSync('source/test.png', 'destination/test.png');
-* console.log('The file has been moved');
-* ```
-*/
+ * Move a file synchronously.
+ * @param sourcePath The file you want to move.
+ * @param destinationPath Where you want the file moved.
+ * @param options Configuration options.
+ * @example
+ * ```
+ * import { moveSync } from '@visulima/fs';
+ *
+ * moveSync('source/test.png', 'destination/test.png');
+ * console.log('The file has been moved');
+ * ```
+ */
 declare const moveSync: (sourcePath: string, destinationPath: string, options?: Options) => void;
 /**
-* Rename a file asynchronously.
-* @param source The file you want to rename.
-* @param destination The name of the renamed file.
-* @param options Configuration options.
-* @returns A `Promise` that resolves when the file has been renamed.
-* @example
-* ```
-* import { rename } from '@visulima/fs';
-*
-* await rename('test.png', 'tests.png', {cwd: 'source'});
-* console.log('The file has been renamed');
-* ```
-*/
+ * Rename a file asynchronously.
+ * @param source The file you want to rename.
+ * @param destination The name of the renamed file.
+ * @param options Configuration options.
+ * @returns A `Promise` that resolves when the file has been renamed.
+ * @example
+ * ```
+ * import { rename } from '@visulima/fs';
+ *
+ * await rename('test.png', 'tests.png', {cwd: 'source'});
+ * console.log('The file has been renamed');
+ * ```
+ */
 declare const rename: (source: string, destination: string, options?: Options) => Promise<void>;
 /**
-* Rename a file synchronously.
-* @param source The file you want to rename.
-* @param destination The name of the renamed file.
-* @param options Configuration options.
-* @example
-* ```
-* import { renameSync } from '@visulima/fs';
-*
-* renameSync('test.png', 'tests.png', {cwd: 'source'});
-* console.log('The file has been renamed');
-* ```
-*/
+ * Rename a file synchronously.
+ * @param source The file you want to rename.
+ * @param destination The name of the renamed file.
+ * @param options Configuration options.
+ * @example
+ * ```
+ * import { renameSync } from '@visulima/fs';
+ *
+ * renameSync('test.png', 'tests.png', {cwd: 'source'});
+ * console.log('The file has been renamed');
+ * ```
+ */
 declare const renameSync: (source: string, destination: string, options?: Options) => void;
 type DecompressionMethod$1 = (buffer: Buffer, callback: (error: Error | null, result: Buffer) => void) => void;
 declare const decompressionMethods$1: Record<string, DecompressionMethod$1>;
 /**
-* Asynchronously reads the entire contents of a file.
-* It can also decompress the file content if a `compression` option is provided.
-* @template O - The type of the options object, extending {@link ReadFileOptions}.
-* @param path The path to the file to read. Can be a file URL or a string path.
-* @param options Optional configuration for reading the file. See {@link ReadFileOptions}.
-* Available `compression` methods: "brotli", "gzip", "none" (default).
-* @returns A promise that resolves with the file content. The type of the content (string or Buffer)
-* depends on the `buffer` option (defaults to string if `buffer` is false or not set).
-* @example
-* ```javascript
-* import { readFile } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* const readMyFile = async () => {
-*   try {
-*     // Read a regular text file
-*     const content = await readFile(join("path", "to", "my-file.txt"));
-*     console.log("File content:", content);
-*
-*     // Read a file as a Buffer
-*     const bufferContent = await readFile(join("path", "to", "another-file.bin"), { buffer: true });
-*     console.log("Buffer length:", bufferContent.length);
-*
-*     // Read and decompress a gzipped file
-*     // Assume my-archive.txt.gz exists
-*     // const decompressedContent = await readFile(join("path", "to", "my-archive.txt.gz"), { compression: "gzip", encoding: "utf8" });
-*     // console.log("Decompressed content:", decompressedContent);
-*   } catch (error) {
-*     console.error("Failed to read file:", error);
-*   }
-* };
-*
-* readMyFile();
-* ```
-*/
+ * Asynchronously reads the entire contents of a file.
+ * It can also decompress the file content if a `compression` option is provided.
+ * @template O - The type of the options object, extending {@link ReadFileOptions}.
+ * @param path The path to the file to read. Can be a file URL or a string path.
+ * @param options Optional configuration for reading the file. See {@link ReadFileOptions}.
+ * Available `compression` methods: "brotli", "gzip", "none" (default).
+ * @returns A promise that resolves with the file content. The type of the content (string or Buffer)
+ * depends on the `buffer` option (defaults to string if `buffer` is false or not set).
+ * @example
+ * ```javascript
+ * import { readFile } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * const readMyFile = async () => {
+ *   try {
+ *     // Read a regular text file
+ *     const content = await readFile(join("path", "to", "my-file.txt"));
+ *     console.log("File content:", content);
+ *
+ *     // Read a file as a Buffer
+ *     const bufferContent = await readFile(join("path", "to", "another-file.bin"), { buffer: true });
+ *     console.log("Buffer length:", bufferContent.length);
+ *
+ *     // Read and decompress a gzipped file
+ *     // Assume my-archive.txt.gz exists
+ *     // const decompressedContent = await readFile(join("path", "to", "my-archive.txt.gz"), { compression: "gzip", encoding: "utf8" });
+ *     // console.log("Decompressed content:", decompressedContent);
+ *   } catch (error) {
+ *     console.error("Failed to read file:", error);
+ *   }
+ * };
+ *
+ * readMyFile();
+ * ```
+ */
 declare const readFile: <O extends ReadFileOptions<keyof typeof decompressionMethods$1> | undefined = undefined>(path: URL | string, options?: O) => Promise<ContentType<O>>;
 type DecompressionMethod = (buffer: Buffer) => Buffer;
 declare const decompressionMethods: Record<string, DecompressionMethod>;
 /**
-* Synchronously reads the entire contents of a file.
-* It can also decompress the file content if a `compression` option is provided.
-* @template O - The type of the options object, extending {@link ReadFileOptions}.
-* @param path The path to the file to read. Can be a file URL or a string path.
-* @param options Optional configuration for reading the file. See {@link ReadFileOptions}.
-* Available `compression` methods: "brotli", "gzip", "none" (default).
-* @returns The file content. The type of the content (string or Buffer)
-* depends on the `buffer` option (defaults to string if `buffer` is false or not set).
-* @example
-* ```javascript
-* import { readFileSync } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* try {
-*   // Read a regular text file
-*   const content = readFileSync(join("path", "to", "my-file.txt"));
-*   console.log("File content:", content);
-*
-*   // Read a file as a Buffer
-*   const bufferContent = readFileSync(join("path", "to", "another-file.bin"), { buffer: true });
-*   console.log("Buffer length:", bufferContent.length);
-*
-*   // Read and decompress a gzipped file
-*   // Assume my-archive.txt.gz exists
-*   // const decompressedContent = readFileSync(join("path", "to", "my-archive.txt.gz"), { compression: "gzip", encoding: "utf8" });
-*   // console.log("Decompressed content:", decompressedContent);
-* } catch (error) {
-*   console.error("Failed to read file:", error);
-* }
-* ```
-*/
+ * Synchronously reads the entire contents of a file.
+ * It can also decompress the file content if a `compression` option is provided.
+ * @template O - The type of the options object, extending {@link ReadFileOptions}.
+ * @param path The path to the file to read. Can be a file URL or a string path.
+ * @param options Optional configuration for reading the file. See {@link ReadFileOptions}.
+ * Available `compression` methods: "brotli", "gzip", "none" (default).
+ * @returns The file content. The type of the content (string or Buffer)
+ * depends on the `buffer` option (defaults to string if `buffer` is false or not set).
+ * @example
+ * ```javascript
+ * import { readFileSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * try {
+ *   // Read a regular text file
+ *   const content = readFileSync(join("path", "to", "my-file.txt"));
+ *   console.log("File content:", content);
+ *
+ *   // Read a file as a Buffer
+ *   const bufferContent = readFileSync(join("path", "to", "another-file.bin"), { buffer: true });
+ *   console.log("Buffer length:", bufferContent.length);
+ *
+ *   // Read and decompress a gzipped file
+ *   // Assume my-archive.txt.gz exists
+ *   // const decompressedContent = readFileSync(join("path", "to", "my-archive.txt.gz"), { compression: "gzip", encoding: "utf8" });
+ *   // console.log("Decompressed content:", decompressedContent);
+ * } catch (error) {
+ *   console.error("Failed to read file:", error);
+ * }
+ * ```
+ */
 declare const readFileSync: <O extends ReadFileOptions<keyof typeof decompressionMethods> | undefined = undefined>(path: URL | string, options?: O) => ContentType<O>;
 declare function readJson<T extends JsonValue>(path: URL | string, options?: ReadJsonOptions): Promise<T>;
 declare function readJson<T extends JsonValue>(path: URL | string, reviver: JsonReviver, options?: ReadJsonOptions): Promise<T>;
 declare function readJsonSync(path: URL | string, options?: ReadJsonOptions): JsonValue;
 declare function readJsonSync(path: URL | string, reviver: JsonReviver, options?: ReadJsonOptions): JsonValue;
 /**
-* Ensures that a directory is empty.
-* Deletes directory contents if the directory is not empty.
-* If the directory does not exist, it is created.
-* The directory itself is not deleted.
-* @param dir The path to the directory to empty.
-* @param options Optional configuration for the operation. See {@link RetryOptions}.
-* @returns A promise that resolves when the directory is empty.
-* @example
-* ```javascript
-* import { emptyDir } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* const clearTempDir = async () => {
-*   try {
-*     await emptyDir(join("/tmp", "my-app-temp"));
-*     console.log("Temporary directory emptied or created.");
-*   } catch (error) {
-*     console.error("Failed to empty directory:", error);
-*   }
-* };
-*
-* clearTempDir();
-* ```
-*/
+ * Ensures that a directory is empty.
+ * Deletes directory contents if the directory is not empty.
+ * If the directory does not exist, it is created.
+ * The directory itself is not deleted.
+ * @param dir The path to the directory to empty.
+ * @param options Optional configuration for the operation. See {@link RetryOptions}.
+ * @returns A promise that resolves when the directory is empty.
+ * @example
+ * ```javascript
+ * import { emptyDir } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * const clearTempDir = async () => {
+ *   try {
+ *     await emptyDir(join("/tmp", "my-app-temp"));
+ *     console.log("Temporary directory emptied or created.");
+ *   } catch (error) {
+ *     console.error("Failed to empty directory:", error);
+ *   }
+ * };
+ *
+ * clearTempDir();
+ * ```
+ */
 declare const emptyDir: (dir: URL | string, options?: RetryOptions) => Promise<void>;
 /**
-* Ensures that a directory is empty.
-* Deletes directory contents if the directory is not empty.
-* If the directory does not exist, it is created.
-* The directory itself is not deleted.
-* @param dir The path to the directory to empty.
-* @param options Optional configuration for the operation. See {@link RetryOptions}.
-* @example
-* ```javascript
-* import { emptyDirSync } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* try {
-*   emptyDirSync(join("/tmp", "my-app-temp"));
-*   console.log("Temporary directory emptied or created.");
-* } catch (error) {
-*   console.error("Failed to empty directory:", error);
-* }
-* ```
-*/
+ * Ensures that a directory is empty.
+ * Deletes directory contents if the directory is not empty.
+ * If the directory does not exist, it is created.
+ * The directory itself is not deleted.
+ * @param dir The path to the directory to empty.
+ * @param options Optional configuration for the operation. See {@link RetryOptions}.
+ * @example
+ * ```javascript
+ * import { emptyDirSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * try {
+ *   emptyDirSync(join("/tmp", "my-app-temp"));
+ *   console.log("Temporary directory emptied or created.");
+ * } catch (error) {
+ *   console.error("Failed to empty directory:", error);
+ * }
+ * ```
+ */
 declare const emptyDirSync: (dir: URL | string, options?: RetryOptions) => void;
 /**
-* Asynchronously removes a file or directory (recursively).
-* If the path does not exist, it does nothing.
-* @param path The path to the file or directory to remove.
-* @param options Optional configuration for the operation. See {@link RetryOptions}.
-* @returns A promise that resolves when the path has been removed.
-* @example
-* ```javascript
-* import { remove } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* const deleteFileOrDir = async () => {
-*   try {
-*     await remove(join("/tmp", "my-file.txt"));
-*     console.log("File /tmp/my-file.txt removed.");
-*
-*     await remove(join("/tmp", "my-empty-dir"));
-*     console.log("Directory /tmp/my-empty-dir removed.");
-*
-*     await remove(join("/tmp", "my-dir-with-contents"));
-*     console.log("Directory /tmp/my-dir-with-contents and its contents removed.");
-*   } catch (error) {
-*     console.error("Failed to remove path:", error);
-*   }
-* };
-*
-* deleteFileOrDir();
-* ```
-*/
+ * Asynchronously removes a file or directory (recursively).
+ * If the path does not exist, it does nothing.
+ * @param path The path to the file or directory to remove.
+ * @param options Optional configuration for the operation. See {@link RetryOptions}.
+ * @returns A promise that resolves when the path has been removed.
+ * @example
+ * ```javascript
+ * import { remove } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * const deleteFileOrDir = async () => {
+ *   try {
+ *     await remove(join("/tmp", "my-file.txt"));
+ *     console.log("File /tmp/my-file.txt removed.");
+ *
+ *     await remove(join("/tmp", "my-empty-dir"));
+ *     console.log("Directory /tmp/my-empty-dir removed.");
+ *
+ *     await remove(join("/tmp", "my-dir-with-contents"));
+ *     console.log("Directory /tmp/my-dir-with-contents and its contents removed.");
+ *   } catch (error) {
+ *     console.error("Failed to remove path:", error);
+ *   }
+ * };
+ *
+ * deleteFileOrDir();
+ * ```
+ */
 declare const remove: (path: URL | string, options?: RetryOptions) => Promise<void>;
 /**
-* Synchronously removes a file or directory (recursively).
-* If the path does not exist, it does nothing.
-* @param path The path to the file or directory to remove.
-* @param options Optional configuration for the operation. See {@link RetryOptions}.
-* @example
-* ```javascript
-* import { removeSync } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* try {
-*   removeSync(join("/tmp", "my-file.txt"));
-*   console.log("File /tmp/my-file.txt removed.");
-*
-*   removeSync(join("/tmp", "my-empty-dir"));
-*   console.log("Directory /tmp/my-empty-dir removed.");
-*
-*   removeSync(join("/tmp", "my-dir-with-contents"));
-*   console.log("Directory /tmp/my-dir-with-contents and its contents removed.");
-* } catch (error) {
-*   console.error("Failed to remove path:", error);
-* }
-* ```
-*/
+ * Synchronously removes a file or directory (recursively).
+ * If the path does not exist, it does nothing.
+ * @param path The path to the file or directory to remove.
+ * @param options Optional configuration for the operation. See {@link RetryOptions}.
+ * @example
+ * ```javascript
+ * import { removeSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * try {
+ *   removeSync(join("/tmp", "my-file.txt"));
+ *   console.log("File /tmp/my-file.txt removed.");
+ *
+ *   removeSync(join("/tmp", "my-empty-dir"));
+ *   console.log("Directory /tmp/my-empty-dir removed.");
+ *
+ *   removeSync(join("/tmp", "my-dir-with-contents"));
+ *   console.log("Directory /tmp/my-dir-with-contents and its contents removed.");
+ * } catch (error) {
+ *   console.error("Failed to remove path:", error);
+ * }
+ * ```
+ */
 declare const removeSync: (path: URL | string, options?: RetryOptions) => void;
 /**
-* Supported filesystem types
-*/
+ * Supported filesystem types
+ */
 type FileSystemType = "win32" | "unix" | "darwin" | "fat32" | "auto";
 /**
-* Options for the sanitize function
-*/
+ * Options for the sanitize function
+ */
 interface SanitizeOptions {
   /**
-  * Target filesystem type for sanitization rules
-  * - "win32": Windows filesystem rules (reserved names, Windows forbidden chars, no trailing periods/spaces)
-  * - "unix": Unix/Linux filesystem rules (only / and null forbidden)
-  * - "darwin": macOS filesystem rules (same as unix)
-  * - "fat32": FAT32 filesystem rules (Windows rules + no leading/trailing spaces/periods in name part)
-  * - "auto": Automatically detect from process.platform
-  * @default "auto"
-  */
+   * Target filesystem type for sanitization rules
+   * - "win32": Windows filesystem rules (reserved names, Windows forbidden chars, no trailing periods/spaces)
+   * - "unix": Unix/Linux filesystem rules (only / and null forbidden)
+   * - "darwin": macOS filesystem rules (same as unix)
+   * - "fat32": FAT32 filesystem rules (Windows rules + no leading/trailing spaces/periods in name part)
+   * - "auto": Automatically detect from process.platform
+   * @default "auto"
+   */
   filesystem?: FileSystemType;
   /**
-  * Maximum length of the sanitized name
-  * @default 128
-  */
+   * Maximum length of the sanitized name
+   * @default 128
+   */
   maxLength?: number;
 }
 /**
-* Sanitizes a filename by removing or replacing forbidden characters.
-* @param name The filename to sanitize.
-* @param options Optional configuration.
-* @returns The sanitized filename, or "unnamed" if the result would be empty.
-*/
+ * Sanitizes a filename by removing or replacing forbidden characters.
+ * @param name The filename to sanitize.
+ * @param options Optional configuration.
+ * @returns The sanitized filename, or "unnamed" if the result would be empty.
+ */
 declare const sanitize: (name: string, options?: Partial<SanitizeOptions>) => string;
 /**
-* Asynchronously writes data to a file, replacing the file if it already exists.
-* This function includes safeguards like writing to a temporary file first and then renaming, and handling permissions.
-* @param path The path to the file to write. Can be a file URL or a string path.
-* @param content The data to write. Can be a string, Buffer, ArrayBuffer, or ArrayBufferView.
-* @param options Optional configuration for writing the file. See {@link WriteFileOptions}.
-* @returns A promise that resolves when the file has been written.
-* @example
-* ```javascript
-* import { writeFile } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* const writeMyFile = async () => {
-*   try {
-*     await writeFile(join("/tmp", "my-new-file.txt"), "Hello World!");
-*     console.log("File written successfully.");
-*
-*     await writeFile(join("/tmp", "another-file.txt"), "Some other content", { encoding: 'utf16le', mode: 0o600 });
-*     console.log("Another file written with specific options.");
-*   } catch (error) {
-*     console.error("Failed to write file:", error);
-*   }
-* };
-*
-* writeMyFile();
-* ```
-*/
+ * Asynchronously writes data to a file, replacing the file if it already exists.
+ * This function includes safeguards like writing to a temporary file first and then renaming, and handling permissions.
+ * @param path The path to the file to write. Can be a file URL or a string path.
+ * @param content The data to write. Can be a string, Buffer, ArrayBuffer, or ArrayBufferView.
+ * @param options Optional configuration for writing the file. See {@link WriteFileOptions}.
+ * @returns A promise that resolves when the file has been written.
+ * @example
+ * ```javascript
+ * import { writeFile } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * const writeMyFile = async () => {
+ *   try {
+ *     await writeFile(join("/tmp", "my-new-file.txt"), "Hello World!");
+ *     console.log("File written successfully.");
+ *
+ *     await writeFile(join("/tmp", "another-file.txt"), "Some other content", { encoding: 'utf16le', mode: 0o600 });
+ *     console.log("Another file written with specific options.");
+ *   } catch (error) {
+ *     console.error("Failed to write file:", error);
+ *   }
+ * };
+ *
+ * writeMyFile();
+ * ```
+ */
 declare const writeFile: (path: URL | string, content: ArrayBuffer | ArrayBufferView | string, options?: WriteFileOptions) => Promise<void>;
 /**
-* Synchronously writes data to a file, replacing the file if it already exists.
-* This function includes safeguards like writing to a temporary file first and then renaming, and handling permissions.
-* @param path The path to the file to write. Can be a file URL or a string path.
-* @param content The data to write. Can be a string, Buffer, ArrayBuffer, or ArrayBufferView.
-* @param options Optional configuration for writing the file. See {@link WriteFileOptions}.
-* @returns void
-* @example
-* ```javascript
-* import { writeFileSync } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* const writeMyFileSync = () => {
-*   try {
-*     writeFileSync(join("/tmp", "my-new-file-sync.txt"), "Hello World Synchronously!");
-*     console.log("File written successfully (sync).");
-*
-*     writeFileSync(join("/tmp", "another-file-sync.txt"), "Some other sync content", { encoding: 'utf16le', mode: 0o600 });
-*     console.log("Another file written with specific options (sync).");
-*   } catch (error) {
-*     console.error("Failed to write file (sync):", error);
-*   }
-* };
-*
-* writeMyFileSync();
-* ```
-*/
+ * Synchronously writes data to a file, replacing the file if it already exists.
+ * This function includes safeguards like writing to a temporary file first and then renaming, and handling permissions.
+ * @param path The path to the file to write. Can be a file URL or a string path.
+ * @param content The data to write. Can be a string, Buffer, ArrayBuffer, or ArrayBufferView.
+ * @param options Optional configuration for writing the file. See {@link WriteFileOptions}.
+ * @returns void
+ * @example
+ * ```javascript
+ * import { writeFileSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * const writeMyFileSync = () => {
+ *   try {
+ *     writeFileSync(join("/tmp", "my-new-file-sync.txt"), "Hello World Synchronously!");
+ *     console.log("File written successfully (sync).");
+ *
+ *     writeFileSync(join("/tmp", "another-file-sync.txt"), "Some other sync content", { encoding: 'utf16le', mode: 0o600 });
+ *     console.log("Another file written with specific options (sync).");
+ *   } catch (error) {
+ *     console.error("Failed to write file (sync):", error);
+ *   }
+ * };
+ *
+ * writeMyFileSync();
+ * ```
+ */
 declare const writeFileSync: (path: URL | string, content: ArrayBuffer | ArrayBufferView | string, options?: WriteFileOptions) => void;
 /**
-* Asynchronously writes an object to a JSON file.
-* Handles indentation detection, custom stringifiers, and gracefully manages existing files.
-* @param path The path to the JSON file to write. Can be a file URL or a string path.
-* @param data The data to serialize and write. Can be any JavaScript value that can be stringified by `JSON.stringify` or a custom stringifier.
-* @param options Optional configuration for writing the JSON file. See {@link WriteJsonOptions}.
-* @returns A promise that resolves when the JSON file has been written.
-* @example
-* ```javascript
-* import { writeJson } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* const writeMyJson = async () => {
-*   try {
-*     await writeJson(join("/tmp", "my-config.json"), { setting: "enabled", value: 123 });
-*     console.log("JSON file written successfully.");
-*
-*     await writeJson(join("/tmp", "another-config.json"), { user: "test", id: "abc" }, { indent: 2, replacer: ["user"] });
-*     console.log("Another JSON file written with specific options (indent 2, only 'user' key).");
-*   } catch (error) {
-*     console.error("Failed to write JSON file:", error);
-*   }
-* };
-*
-* writeMyJson();
-* ```
-*/
+ * Asynchronously writes an object to a JSON file.
+ * Handles indentation detection, custom stringifiers, and gracefully manages existing files.
+ * @param path The path to the JSON file to write. Can be a file URL or a string path.
+ * @param data The data to serialize and write. Can be any JavaScript value that can be stringified by `JSON.stringify` or a custom stringifier.
+ * @param options Optional configuration for writing the JSON file. See {@link WriteJsonOptions}.
+ * @returns A promise that resolves when the JSON file has been written.
+ * @example
+ * ```javascript
+ * import { writeJson } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * const writeMyJson = async () => {
+ *   try {
+ *     await writeJson(join("/tmp", "my-config.json"), { setting: "enabled", value: 123 });
+ *     console.log("JSON file written successfully.");
+ *
+ *     await writeJson(join("/tmp", "another-config.json"), { user: "test", id: "abc" }, { indent: 2, replacer: ["user"] });
+ *     console.log("Another JSON file written with specific options (indent 2, only 'user' key).");
+ *   } catch (error) {
+ *     console.error("Failed to write JSON file:", error);
+ *   }
+ * };
+ *
+ * writeMyJson();
+ * ```
+ */
 declare const writeJson: (path: URL | string, data: unknown, options?: WriteJsonOptions) => Promise<void>;
 /**
-* Synchronously writes an object to a JSON file.
-* Handles indentation detection, custom stringifiers, and gracefully manages existing files.
-* @param path The path to the JSON file to write. Can be a file URL or a string path.
-* @param data The data to serialize and write. Can be any JavaScript value that can be stringified by `JSON.stringify` or a custom stringifier.
-* @param options Optional configuration for writing the JSON file. See {@link WriteJsonOptions}.
-* @example
-* ```javascript
-* import { writeJsonSync } from "@visulima/fs";
-* import { join } from "node:path";
-*
-* const writeMyJsonSync = () => {
-*   try {
-*     writeJsonSync(join("/tmp", "my-config-sync.json"), { setting: "enabled", value: 456 });
-*     console.log("JSON file written successfully (sync).");
-*
-*     writeJsonSync(join("/tmp", "another-config-sync.json"), { user: "testSync", id: "def" }, { indent: 4, replacer: ["id"] });
-*     console.log("Another JSON file written with specific options (sync, indent 4, only 'id' key).");
-*   } catch (error) {
-*     console.error("Failed to write JSON file (sync):", error);
-*   }
-* };
-*
-* writeMyJsonSync();
-* ```
-*/
+ * Synchronously writes an object to a JSON file.
+ * Handles indentation detection, custom stringifiers, and gracefully manages existing files.
+ * @param path The path to the JSON file to write. Can be a file URL or a string path.
+ * @param data The data to serialize and write. Can be any JavaScript value that can be stringified by `JSON.stringify` or a custom stringifier.
+ * @param options Optional configuration for writing the JSON file. See {@link WriteJsonOptions}.
+ * @example
+ * ```javascript
+ * import { writeJsonSync } from "@visulima/fs";
+ * import { join } from "node:path";
+ *
+ * const writeMyJsonSync = () => {
+ *   try {
+ *     writeJsonSync(join("/tmp", "my-config-sync.json"), { setting: "enabled", value: 456 });
+ *     console.log("JSON file written successfully (sync).");
+ *
+ *     writeJsonSync(join("/tmp", "another-config-sync.json"), { user: "testSync", id: "def" }, { indent: 4, replacer: ["id"] });
+ *     console.log("Another JSON file written with specific options (sync, indent 4, only 'id' key).");
+ *   } catch (error) {
+ *     console.error("Failed to write JSON file (sync):", error);
+ *   }
+ * };
+ *
+ * writeMyJsonSync();
+ * ```
+ */
 declare const writeJsonSync: (path: URL | string, data: unknown, options?: WriteJsonOptions) => void;
 /**
  * Subset of Node.js fs module methods required for case-sensitivity detection.