@visulima/fs 5.0.0-alpha.12 → 5.0.0-alpha.14

package/dist/index.d.ts

@@ -1,28 +1,334 @@
-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, J as JsonReviver, x as RetryOptions, y as WriteFileOptions, z as WriteJsonOptions } from "./packem_shared/types.d-CYpAhWov.js";
-export { type A as CodeFrameLocation, type C as CodeFrameOptions, B as FIND_UP_STOP, D as F_OK, type E as FindUpNameFnResult, type H as FindUpNameSyncFnResult, type G as GlobOptions, type b as JsonReplacer, K as R_OK, type L as ReadFileEncoding, M as W_OK, X as X_OK } from "./packem_shared/types.d-CYpAhWov.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, c as JsonReviver, x as RetryOptions, y as WriteFileOptions, z as WriteJsonOptions } from "./packem_shared/types.d-BsmmADqx.js";
+export { type A as CodeFrameLocation, type b 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-BsmmADqx.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-BlGjS68e.js";
+export { g as glob, a as globSync } from "./packem_shared/glob-sync.d-p6lOZXnE.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";
 import { JsonValue } from 'type-fest';
-export { isFsCaseSensitive } from 'is-fs-case-sensitive';
+import fs from 'fs';
 import 'tinyglobby';
-import './options';
-import 'picomatch';
+import './lib/picomatch';
+/**
+* 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
+* ```
+*/
 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);
+*   }
+* })();
+* ```
+*/
 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
+* ```
+*/
 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"));
+* ```
+*/
 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"));
+* ```
+*/
 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");
+* ```
+*/
 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");
+* ```
+*/
 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();
+* ```
+*/
 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);
+* ```
+*/
 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();
+* ```
+*/
 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);
+* ```
+*/
 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();
+* ```
+*/
 declare function walk(directory: URL | string, {
   extensions,
   followSymlinks,
@@ -33,6 +339,38 @@ declare function walk(directory: URL | string, {
   maxDepth,
   skip
 }?: 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}`);
+*   }
+* }
+* ```
+*/
 declare function walkSync(directory: URL | string, {
   extensions,
   followSymlinks,
@@ -43,39 +381,478 @@ declare function walkSync(directory: URL | string, {
   maxDepth,
   skip
 }?: 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");
+*   }
+* })();
+* ```
+*/
 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()
+  */
   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
+  */
   readonly directoryMode?: number;
+  /**
+  * 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');
+* ```
+*/
 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');
+* ```
+*/
 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');
+* ```
+*/
 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');
+* ```
+*/
 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();
+* ```
+*/
 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);
+* }
+* ```
+*/
 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();
+* ```
+*/
 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);
+* }
+* ```
+*/
 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();
+* ```
+*/
 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);
+* }
+* ```
+*/
 declare const removeSync: (path: URL | string, options?: RetryOptions) => void;
+/**
+* Supported filesystem types
+*/
 type FileSystemType = "win32" | "unix" | "darwin" | "fat32" | "auto";
+/**
+* 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"
+  */
   filesystem?: FileSystemType;
+  /**
+  * 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.
+*/
 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();
+* ```
+*/
 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();
+* ```
+*/
 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();
+* ```
+*/
 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();
+* ```
+*/
 declare const writeJsonSync: (path: URL | string, data: unknown, options?: WriteJsonOptions) => void;
-export { type ContentType, type FindUpName, type FindUpNameSync, type FindUpOptions, type JsonReviver, type Options as MoveOptions, type ReadFileOptions, type ReadJsonOptions, type SanitizeOptions, type WalkEntry, type WalkOptions, type WriteFileOptions, type WriteJsonOptions, collect, collectSync, emptyDir, emptyDirSync, ensureDir, ensureDirSync, ensureFile, ensureFileSync, ensureLink, ensureLinkSync, ensureSymlink, ensureSymlinkSync, findUp, findUpSync, isAccessible, isAccessibleSync, move, moveSync, readFile, readFileSync, readJson, readJsonSync, remove, removeSync, rename, renameSync, sanitize, walk, walkSync, writeFile, writeFileSync, writeJson, writeJsonSync };
+/**
+ * Subset of Node.js fs module methods required for case-sensitivity detection.
+ * This allows custom fs implementations to be passed for testing purposes.
+ */
+type FsSubset = {
+  existsSync: typeof fs.existsSync;
+  writeFileSync: typeof fs.writeFileSync;
+  unlinkSync: typeof fs.unlinkSync;
+};
+/**
+ * Detects whether the filesystem is case-sensitive.
+ *
+ * Uses a fast, I/O-free primary method that checks if the specified directory
+ * path can be accessed with inverted case. Falls back to writing a temporary
+ * file if the primary method is inconclusive.
+ *
+ * Different mount points can have different case-sensitivity settings, so this
+ * function checks the filesystem where the specified directory resides.
+ *
+ * @param directoryPath - The directory path to check. Defaults to
+ * `process.cwd()`. Different mount points can have different case-sensitivity.
+ * @param fsInstance - Custom filesystem implementation (primarily for
+ * testing). Defaults to Node.js `fs` module.
+ * @param useCache - Whether to cache the result per directory. Defaults to
+ * `true`. When enabled, subsequent calls for the same directory return
+ * instantly without re-checking.
+ * @returns `true` if the filesystem is case-sensitive, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * import { isFsCaseSensitive } from 'is-fs-case-sensitive'
+ *
+ * // Check current working directory's filesystem
+ * if (isFsCaseSensitive()) {
+ *   console.log('Case-sensitive filesystem (likely Linux)')
+ * } else {
+ *   console.log('Case-insensitive filesystem (likely macOS/Windows)')
+ * }
+ *
+ * // Check specific directory
+ * const isHomeCaseSensitive = isFsCaseSensitive('/home/user')
+ * ```
+ */
+declare const isFsCaseSensitive: (directoryPath?: string, fsInstance?: FsSubset, useCache?: boolean) => boolean;
+export { type ContentType, type FindUpName, type FindUpNameSync, type FindUpOptions, type JsonReviver, type Options as MoveOptions, type ReadFileOptions, type ReadJsonOptions, type SanitizeOptions, type WalkEntry, type WalkOptions, type WriteFileOptions, type WriteJsonOptions, collect, collectSync, emptyDir, emptyDirSync, ensureDir, ensureDirSync, ensureFile, ensureFileSync, ensureLink, ensureLinkSync, ensureSymlink, ensureSymlinkSync, findUp, findUpSync, isAccessible, isAccessibleSync, isFsCaseSensitive, move, moveSync, readFile, readFileSync, readJson, readJsonSync, remove, removeSync, rename, renameSync, sanitize, walk, walkSync, writeFile, writeFileSync, writeJson, writeJsonSync };