@ooneex/fs 0.0.4

package/dist/index.d.ts

@@ -0,0 +1,1659 @@
+import { Dirent as Dirent2, Stats as Stats2 } from "node:fs";
+import { Dirent, Stats } from "node:fs";
+/**
+* Interface for file operations.
+*
+* Provides methods for reading, writing, and managing files using Bun's optimized file I/O APIs.
+*
+* @example
+* ```typescript
+* import { File, type IFile } from "@ooneex/fs";
+*
+* function processFile(file: IFile): Promise<string> {
+*   return file.text();
+* }
+*
+* const file = new File("/path/to/file.txt");
+* const content = await processFile(file);
+* ```
+*/
+interface IFile {
+	/**
+	* Returns the file path.
+	*
+	* @returns The absolute or relative path of the file
+	*
+	* @example
+	* ```typescript
+	* const path = file.getPath(); // "/path/to/file.txt"
+	* ```
+	*/
+	getPath: () => string;
+	/**
+	* Returns the file name including extension.
+	*
+	* @returns The base name of the file
+	*
+	* @example
+	* ```typescript
+	* const name = file.getName(); // "document.pdf"
+	* ```
+	*/
+	getName: () => string;
+	/**
+	* Returns the file extension without the leading dot.
+	*
+	* @returns The file extension or empty string if none
+	*
+	* @example
+	* ```typescript
+	* const ext = file.getExtension(); // "pdf"
+	* ```
+	*/
+	getExtension: () => string;
+	/**
+	* Returns the directory containing the file.
+	*
+	* @returns The parent directory as an IDirectory instance
+	*
+	* @example
+	* ```typescript
+	* const dir = file.getDirectory();
+	* console.log(dir.getPath()); // "/path/to"
+	* ```
+	*/
+	getDirectory: () => IDirectory;
+	/**
+	* Returns the file size in bytes.
+	*
+	* @returns The size of the file in bytes, or 0 if file doesn't exist
+	*
+	* @example
+	* ```typescript
+	* const size = file.getSize(); // 1024
+	* ```
+	*/
+	getSize: () => number;
+	/**
+	* Returns the MIME type of the file.
+	*
+	* @returns The MIME type string (e.g., "text/plain", "application/json")
+	*
+	* @example
+	* ```typescript
+	* const type = file.getType(); // "application/json;charset=utf-8"
+	* ```
+	*/
+	getType: () => string;
+	/**
+	* Checks if the file exists on disk.
+	*
+	* @returns A promise that resolves to true if the file exists
+	*
+	* @example
+	* ```typescript
+	* if (await file.exists()) {
+	*   console.log("File found");
+	* }
+	* ```
+	*/
+	exists: () => Promise<boolean>;
+	/**
+	* Reads the file content as a string.
+	*
+	* @returns A promise that resolves to the file content as a string
+	*
+	* @example
+	* ```typescript
+	* const content = await file.text();
+	* ```
+	*/
+	text: () => Promise<string>;
+	/**
+	* Reads and parses the file content as JSON.
+	*
+	* @typeParam T - The expected type of the parsed JSON
+	* @returns A promise that resolves to the parsed JSON object
+	*
+	* @example
+	* ```typescript
+	* const config = await file.json<{ name: string }>();
+	* ```
+	*/
+	json: <T = unknown>() => Promise<T>;
+	/**
+	* Reads the file content as an ArrayBuffer.
+	*
+	* @returns A promise that resolves to the file content as an ArrayBuffer
+	*
+	* @example
+	* ```typescript
+	* const buffer = await file.arrayBuffer();
+	* ```
+	*/
+	arrayBuffer: () => Promise<ArrayBuffer>;
+	/**
+	* Reads the file content as a Uint8Array.
+	*
+	* @returns A promise that resolves to the file content as a Uint8Array
+	*
+	* @example
+	* ```typescript
+	* const bytes = await file.bytes();
+	* ```
+	*/
+	bytes: () => Promise<Uint8Array>;
+	/**
+	* Returns a ReadableStream for incremental file reading.
+	*
+	* @returns A ReadableStream of Uint8Array chunks
+	*
+	* @example
+	* ```typescript
+	* const stream = file.stream();
+	* for await (const chunk of stream) {
+	*   console.log(chunk);
+	* }
+	* ```
+	*/
+	stream: () => ReadableStream<Uint8Array>;
+	/**
+	* Returns a ReadableStream for incremental file reading as text.
+	*
+	* @returns A ReadableStream of string chunks
+	*
+	* @example
+	* ```typescript
+	* const stream = file.streamAsText();
+	* for await (const chunk of stream) {
+	*   console.log(chunk);
+	* }
+	* ```
+	*/
+	streamAsText: () => ReadableStream<string>;
+	/**
+	* Returns a ReadableStream for incremental JSON parsing from a JSON array file.
+	*
+	* @typeParam T - The expected type of each JSON element
+	* @returns A ReadableStream of parsed JSON elements
+	*
+	* @example
+	* ```typescript
+	* const stream = file.streamAsJson<{ id: number }>();
+	* for await (const item of stream) {
+	*   console.log(item.id);
+	* }
+	* ```
+	*/
+	streamAsJson: <T = unknown>() => ReadableStream<T>;
+	/**
+	* Writes data to the file, overwriting existing content.
+	*
+	* @param data - The data to write
+	* @returns A promise that resolves to the number of bytes written
+	*
+	* @example
+	* ```typescript
+	* await file.write("Hello, World!");
+	* ```
+	*/
+	write: (data: FileWriteDataType) => Promise<number>;
+	/**
+	* Appends data to the end of the file.
+	*
+	* @param data - The data to append (string or Uint8Array)
+	* @returns A promise that resolves to the total number of bytes in the file
+	*
+	* @example
+	* ```typescript
+	* await file.append("New line\n");
+	* ```
+	*/
+	append: (data: string | Uint8Array) => Promise<number>;
+	/**
+	* Copies the file to a destination path.
+	*
+	* @param destination - The destination file path
+	* @returns A promise that resolves to a new File instance for the copied file
+	*
+	* @example
+	* ```typescript
+	* const copiedFile = await file.copy("/path/to/backup.txt");
+	* ```
+	*/
+	copy: (destination: string) => Promise<IFile>;
+	/**
+	* Deletes the file from disk.
+	*
+	* @example
+	* ```typescript
+	* await file.delete();
+	* ```
+	*/
+	delete: () => Promise<void>;
+	/**
+	* Downloads a file from a URL and saves it to this file's path.
+	*
+	* @param url - The URL to download the file from
+	* @returns A promise that resolves to the number of bytes written
+	*
+	* @example
+	* ```typescript
+	* const bytes = await file.download("https://example.com/image.png");
+	* ```
+	*/
+	download: (url: string | URL) => Promise<number>;
+	/**
+	* Returns a FileSink for incremental writing.
+	*
+	* @param options - Optional configuration for the writer
+	* @returns A FileSink instance for buffered writing
+	*
+	* @example
+	* ```typescript
+	* const writer = file.writer();
+	* writer.write("Line 1\n");
+	* writer.end();
+	* ```
+	*/
+	writer: (options?: FileWriterOptionsType) => BunFileSinkType;
+}
+/**
+* Interface for directory operations.
+*
+* Provides methods for creating, listing, copying, and managing directories.
+*
+* @example
+* ```typescript
+* import { Directory, type IDirectory } from "@ooneex/fs";
+*
+* function cleanupDir(dir: IDirectory): Promise<void> {
+*   return dir.rm({ recursive: true });
+* }
+*
+* const dir = new Directory("/tmp/cache");
+* await cleanupDir(dir);
+* ```
+*/
+interface IDirectory {
+	/**
+	* Returns the directory path.
+	*
+	* @returns The absolute or relative path of the directory
+	*
+	* @example
+	* ```typescript
+	* const path = dir.getPath(); // "/path/to/directory"
+	* ```
+	*/
+	getPath: () => string;
+	/**
+	* Returns the directory name.
+	*
+	* @returns The base name of the directory
+	*
+	* @example
+	* ```typescript
+	* const name = dir.getName(); // "mydir"
+	* ```
+	*/
+	getName: () => string;
+	/**
+	* Returns the parent directory path.
+	*
+	* @returns The path of the parent directory
+	*
+	* @example
+	* ```typescript
+	* const parent = dir.getParent(); // "/path/to"
+	* ```
+	*/
+	getParent: () => string;
+	/**
+	* Checks if the directory exists.
+	*
+	* @returns A promise that resolves to true if the directory exists
+	*
+	* @example
+	* ```typescript
+	* if (await dir.exists()) {
+	*   console.log("Directory found");
+	* }
+	* ```
+	*/
+	exists: () => Promise<boolean>;
+	/**
+	* Creates the directory on disk.
+	*
+	* @param options - Optional configuration for directory creation
+	* @returns A promise that resolves when the directory is created
+	*
+	* @example
+	* ```typescript
+	* await dir.mkdir({ recursive: true });
+	* ```
+	*/
+	mkdir: (options?: DirectoryCreateOptionsType) => Promise<void>;
+	/**
+	* Deletes the directory from disk.
+	*
+	* @param options - Optional configuration for directory deletion
+	* @returns A promise that resolves when the directory is deleted
+	*
+	* @example
+	* ```typescript
+	* await dir.rm({ recursive: true, force: true });
+	* ```
+	*/
+	rm: (options?: DirectoryDeleteOptionsType) => Promise<void>;
+	/**
+	* Lists the contents of the directory.
+	*
+	* @param options - Optional configuration for listing
+	* @returns A promise that resolves to an array of file/directory names
+	*
+	* @example
+	* ```typescript
+	* const files = await dir.ls(); // ["file1.txt", "subdir"]
+	* ```
+	*/
+	ls: (options?: DirectoryListOptionsType) => Promise<string[]>;
+	/**
+	* Lists the contents of the directory with type information.
+	*
+	* @param options - Optional configuration for listing
+	* @returns A promise that resolves to an array of Dirent objects
+	*
+	* @example
+	* ```typescript
+	* const entries = await dir.lsWithTypes();
+	* entries.filter(e => e.isFile());
+	* ```
+	*/
+	lsWithTypes: (options?: DirectoryListOptionsType) => Promise<Dirent[]>;
+	/**
+	* Copies the directory to a destination path.
+	*
+	* @param destination - The destination directory path
+	* @param options - Optional configuration for copying
+	* @returns A promise that resolves when the directory is copied
+	*
+	* @example
+	* ```typescript
+	* await dir.cp("/path/to/backup");
+	* ```
+	*/
+	cp: (destination: string, options?: DirectoryCopyOptionsType) => Promise<void>;
+	/**
+	* Moves (renames) the directory to a new location.
+	*
+	* @param destination - The new directory path
+	* @returns A promise that resolves when the directory is moved
+	*
+	* @example
+	* ```typescript
+	* await dir.mv("/path/to/newname");
+	* ```
+	*/
+	mv: (destination: string) => Promise<void>;
+	/**
+	* Returns the directory statistics.
+	*
+	* @returns A promise that resolves to a Stats object
+	*
+	* @example
+	* ```typescript
+	* const stats = await dir.stat();
+	* console.log(stats.mtime);
+	* ```
+	*/
+	stat: () => Promise<Stats>;
+	/**
+	* Watches the directory for changes.
+	*
+	* @param callback - Function called when changes are detected
+	* @param options - Optional configuration for watching
+	* @returns A FSWatcher that can be closed to stop watching
+	*
+	* @example
+	* ```typescript
+	* const watcher = dir.watch((event, filename) => {
+	*   console.log(event, filename);
+	* });
+	* ```
+	*/
+	watch: (callback: DirectoryWatchCallbackType, options?: DirectoryWatchOptionsType) => DirectoryWatcherType;
+	/**
+	* Checks if the directory is empty.
+	*
+	* @returns A promise that resolves to true if the directory has no contents
+	*
+	* @example
+	* ```typescript
+	* if (await dir.isEmpty()) {
+	*   await dir.rm();
+	* }
+	* ```
+	*/
+	isEmpty: () => Promise<boolean>;
+	/**
+	* Calculates the total size of all contents in the directory.
+	*
+	* @returns A promise that resolves to the total size in bytes
+	*
+	* @example
+	* ```typescript
+	* const size = await dir.getSize();
+	* console.log(`${size} bytes`);
+	* ```
+	*/
+	getSize: () => Promise<number>;
+	/**
+	* Gets a list of files (not directories) in the directory.
+	*
+	* @param options - Optional configuration for getting files
+	* @returns A promise that resolves to an array of File instances
+	*
+	* @example
+	* ```typescript
+	* // Get immediate files
+	* const files = await dir.getFiles();
+	*
+	* // Get all files recursively
+	* const allFiles = await dir.getFiles({ recursive: true });
+	*
+	* // Get only TypeScript files
+	* const tsFiles = await dir.getFiles({ pattern: /\.ts$/ });
+	* ```
+	*/
+	getFiles: (options?: DirectoryGetFilesOptionsType) => Promise<IFile[]>;
+	/**
+	* Gets a list of subdirectories (not files) in the directory.
+	*
+	* @param options - Optional configuration for getting directories
+	* @returns A promise that resolves to an array of Directory instances
+	*
+	* @example
+	* ```typescript
+	* // Get immediate subdirectories
+	* const dirs = await dir.getDirectories();
+	*
+	* // Get all subdirectories recursively
+	* const allDirs = await dir.getDirectories({ recursive: true });
+	*
+	* // Get only directories starting with "test"
+	* const testDirs = await dir.getDirectories({ pattern: /^test/ });
+	* ```
+	*/
+	getDirectories: (options?: DirectoryGetDirectoriesOptionsType) => Promise<IDirectory[]>;
+	/**
+	* Changes to a subdirectory and returns a new Directory instance.
+	*
+	* @param paths - The relative path segments to the subdirectory
+	* @returns A new Directory instance pointing to the subdirectory
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/project");
+	*
+	* // Navigate to subdirectory
+	* const srcDir = dir.cd("src");
+	*
+	* // Navigate multiple levels with multiple args
+	* const componentsDir = dir.cd("src", "components", "ui");
+	*
+	* // Navigate to parent
+	* const parentDir = dir.cd("..");
+	* ```
+	*/
+	cd: (...paths: string[]) => IDirectory;
+}
+/**
+* Types of data that can be written to a file.
+*
+* Supports strings, binary data (Blob, ArrayBuffer, TypedArrays), and Response objects.
+*
+* @example
+* ```typescript
+* // String
+* await file.write("Hello, World!");
+*
+* // Uint8Array
+* await file.write(new Uint8Array([72, 101, 108, 108, 111]));
+*
+* // Response from fetch
+* const response = await fetch("https://example.com/data");
+* await file.write(response);
+* ```
+*/
+type FileWriteDataType = string | Blob | ArrayBuffer | SharedArrayBuffer | Uint8Array | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array | Response;
+/**
+* Options for configuring the FileSink writer.
+*
+* @example
+* ```typescript
+* const writer = file.writer({
+*   highWaterMark: 1024 * 1024 // 1MB buffer
+* });
+* ```
+*/
+type FileWriterOptionsType = {
+	/**
+	* The buffer size in bytes before auto-flushing.
+	* When the internal buffer reaches this size, it will automatically flush to disk.
+	*
+	* @default undefined (uses Bun's default)
+	*
+	* @example
+	* ```typescript
+	* { highWaterMark: 1024 * 1024 } // 1MB buffer
+	* ```
+	*/
+	highWaterMark?: number;
+};
+/**
+* Options for configuring file creation.
+*
+* @example
+* ```typescript
+* const file = new File("/path/to/file.txt", {
+*   type: "text/plain"
+* });
+* ```
+*/
+type FileOptionsType = {
+	/**
+	* The MIME type to use for the file.
+	* Overrides automatic MIME type detection.
+	*
+	* @example
+	* ```typescript
+	* { type: "application/json" }
+	* { type: "text/html;charset=utf-8" }
+	* ```
+	*/
+	type?: string;
+};
+/**
+* Type representing Bun's FileSink for incremental file writing.
+*
+* FileSink provides buffered writing with manual flush control.
+*
+* @example
+* ```typescript
+* const writer: BunFileSinkType = file.writer();
+* writer.write("chunk 1");
+* writer.write("chunk 2");
+* writer.flush(); // Write buffer to disk
+* writer.end();   // Flush and close
+* ```
+*/
+type BunFileSinkType = ReturnType<ReturnType<typeof Bun.file>["writer"]>;
+/**
+* Options for creating a directory.
+*
+* @example
+* ```typescript
+* await dir.create({
+*   recursive: true,
+*   mode: 0o755
+* });
+* ```
+*/
+type DirectoryCreateOptionsType = {
+	/**
+	* Whether to create parent directories if they don't exist.
+	*
+	* @default true
+	*
+	* @example
+	* ```typescript
+	* // Creates /path/to/nested/directory and all parents
+	* await dir.create({ recursive: true });
+	* ```
+	*/
+	recursive?: boolean;
+	/**
+	* The file mode (permissions) for the directory.
+	* Uses octal notation (e.g., 0o755 for rwxr-xr-x).
+	*
+	* @example
+	* ```typescript
+	* { mode: 0o700 }  // rwx------
+	* { mode: 0o755 }  // rwxr-xr-x
+	* ```
+	*/
+	mode?: number;
+};
+/**
+* Options for deleting a directory.
+*
+* @example
+* ```typescript
+* await dir.delete({
+*   recursive: true,
+*   force: true
+* });
+* ```
+*/
+type DirectoryDeleteOptionsType = {
+	/**
+	* Whether to delete contents recursively.
+	* Required for non-empty directories.
+	*
+	* @default true
+	*
+	* @example
+	* ```typescript
+	* // Delete directory and all contents
+	* await dir.delete({ recursive: true });
+	* ```
+	*/
+	recursive?: boolean;
+	/**
+	* Whether to ignore errors if directory doesn't exist.
+	*
+	* @default false
+	*
+	* @example
+	* ```typescript
+	* // Won't throw if directory doesn't exist
+	* await dir.delete({ force: true });
+	* ```
+	*/
+	force?: boolean;
+};
+/**
+* Options for listing directory contents.
+*
+* @example
+* ```typescript
+* const files = await dir.ls({ recursive: true });
+* ```
+*/
+type DirectoryListOptionsType = {
+	/**
+	* Whether to list contents recursively including subdirectories.
+	*
+	* @default false
+	*
+	* @example
+	* ```typescript
+	* // List all files in directory tree
+	* const allFiles = await dir.ls({ recursive: true });
+	* ```
+	*/
+	recursive?: boolean;
+};
+/**
+* Options for getting files from a directory.
+*
+* @example
+* ```typescript
+* const tsFiles = await dir.getFiles({ recursive: true, pattern: /\.ts$/ });
+* ```
+*/
+type DirectoryGetFilesOptionsType = {
+	/**
+	* Whether to get files recursively from subdirectories.
+	*
+	* @default false
+	*
+	* @example
+	* ```typescript
+	* // Get all files in directory tree
+	* const allFiles = await dir.getFiles({ recursive: true });
+	* ```
+	*/
+	recursive?: boolean;
+	/**
+	* Regular expression pattern to filter files by name.
+	* Only files matching the pattern will be returned.
+	*
+	* @example
+	* ```typescript
+	* // Get only TypeScript files
+	* const tsFiles = await dir.getFiles({ pattern: /\.ts$/ });
+	*
+	* // Get files starting with "test"
+	* const testFiles = await dir.getFiles({ pattern: /^test/ });
+	* ```
+	*/
+	pattern?: RegExp;
+};
+/**
+* Options for getting subdirectories from a directory.
+*
+* @example
+* ```typescript
+* const srcDirs = await dir.getDirectories({ recursive: true, pattern: /^src/ });
+* ```
+*/
+type DirectoryGetDirectoriesOptionsType = {
+	/**
+	* Whether to get directories recursively from subdirectories.
+	*
+	* @default false
+	*
+	* @example
+	* ```typescript
+	* // Get all directories in directory tree
+	* const allDirs = await dir.getDirectories({ recursive: true });
+	* ```
+	*/
+	recursive?: boolean;
+	/**
+	* Regular expression pattern to filter directories by name.
+	* Only directories matching the pattern will be returned.
+	*
+	* @example
+	* ```typescript
+	* // Get only directories starting with "test"
+	* const testDirs = await dir.getDirectories({ pattern: /^test/ });
+	*
+	* // Get directories ending with "-config"
+	* const configDirs = await dir.getDirectories({ pattern: /-config$/ });
+	* ```
+	*/
+	pattern?: RegExp;
+};
+/**
+* Options for copying a directory.
+*
+* @example
+* ```typescript
+* await dir.copy("/path/to/destination", {
+*   recursive: true,
+*   overwrite: true
+* });
+* ```
+*/
+type DirectoryCopyOptionsType = {
+	/**
+	* Whether to copy contents recursively.
+	*
+	* @default true
+	*
+	* @example
+	* ```typescript
+	* // Copy directory and all contents
+	* await dir.copy(dest, { recursive: true });
+	* ```
+	*/
+	recursive?: boolean;
+	/**
+	* Whether to overwrite existing files at destination.
+	*
+	* @default false
+	*
+	* @example
+	* ```typescript
+	* // Overwrite existing files
+	* await dir.copy(dest, { overwrite: true });
+	* ```
+	*/
+	overwrite?: boolean;
+};
+/**
+* Options for watching a directory.
+*
+* @example
+* ```typescript
+* const watcher = dir.watch(callback, { recursive: true });
+* ```
+*/
+type DirectoryWatchOptionsType = {
+	/**
+	* Whether to watch subdirectories recursively.
+	*
+	* @default false
+	*
+	* @example
+	* ```typescript
+	* // Watch all subdirectories
+	* dir.watch(callback, { recursive: true });
+	* ```
+	*/
+	recursive?: boolean;
+};
+/**
+* Types of events emitted by the directory watcher.
+*
+* - `"rename"`: A file or directory was created, deleted, or renamed
+* - `"change"`: A file's contents were modified
+*
+* @example
+* ```typescript
+* dir.watch((event: DirectoryWatchEventType, filename) => {
+*   if (event === "rename") {
+*     console.log("File created/deleted:", filename);
+*   } else if (event === "change") {
+*     console.log("File modified:", filename);
+*   }
+* });
+* ```
+*/
+type DirectoryWatchEventType = "rename" | "change";
+/**
+* Callback function for directory watch events.
+*
+* @param event - The type of change that occurred ("rename" or "change")
+* @param filename - The name of the file that changed, or null if unavailable
+*
+* @example
+* ```typescript
+* const callback: DirectoryWatchCallbackType = (event, filename) => {
+*   console.log(`${event}: ${filename}`);
+* };
+*
+* dir.watch(callback);
+* ```
+*/
+type DirectoryWatchCallbackType = (event: DirectoryWatchEventType, filename: string | null) => void;
+/**
+* Type representing Node.js FSWatcher returned by the watch method.
+*
+* Use the `.close()` method to stop watching.
+*
+* @example
+* ```typescript
+* const watcher: DirectoryWatcherType = dir.watch((event, filename) => {
+*   console.log(event, filename);
+* });
+*
+* // Stop watching
+* watcher.close();
+*
+* // Or close on SIGINT
+* process.on("SIGINT", () => {
+*   watcher.close();
+*   process.exit(0);
+* });
+* ```
+*/
+type DirectoryWatcherType = ReturnType<typeof import("node:fs").watch>;
+/**
+* A class for performing directory operations using Bun's optimized fs APIs.
+*
+* @example
+* ```typescript
+* import { Directory } from "@ooneex/fs";
+*
+* const dir = new Directory("/path/to/directory");
+*
+* // Create directory
+* await dir.mkdir();
+*
+* // List contents
+* const files = await dir.ls();
+*
+* // Check if empty
+* if (await dir.isEmpty()) {
+*   await dir.rm();
+* }
+* ```
+*/
+declare class Directory implements IDirectory {
+	private readonly path;
+	/**
+	* Creates a new Directory instance.
+	*
+	* @param path - The directory path as a string
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	* const homeDir = new Directory("~/Documents");
+	* const relativeDir = new Directory("./src");
+	* ```
+	*/
+	constructor(path: string);
+	/**
+	* Returns the directory path.
+	*
+	* @returns The absolute or relative path of the directory
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/mydir");
+	* console.log(dir.getPath()); // "/path/to/mydir"
+	* ```
+	*/
+	getPath(): string;
+	/**
+	* Returns the directory name.
+	*
+	* @returns The base name of the directory
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/mydir");
+	* console.log(dir.getName()); // "mydir"
+	* ```
+	*/
+	getName(): string;
+	/**
+	* Returns the parent directory path.
+	*
+	* @returns The path of the parent directory
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/mydir");
+	* console.log(dir.getParent()); // "/path/to"
+	* ```
+	*/
+	getParent(): string;
+	/**
+	* Checks if the directory exists.
+	*
+	* @returns A promise that resolves to true if the directory exists
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	*
+	* if (await dir.exists()) {
+	*   console.log("Directory exists!");
+	* } else {
+	*   await dir.mkdir();
+	* }
+	* ```
+	*/
+	exists(): Promise<boolean>;
+	/**
+	* Creates the directory on disk.
+	*
+	* @param options - Optional configuration for directory creation
+	* @param options.recursive - Create parent directories if needed (default: true)
+	* @param options.mode - Directory permissions (e.g., 0o755)
+	* @throws {DirectoryException} If the directory cannot be created
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/new/nested/directory");
+	*
+	* // Create with all parent directories (default behavior)
+	* await dir.mkdir();
+	*
+	* // Create with specific permissions
+	* await dir.mkdir({ mode: 0o700 });
+	*
+	* // Create without recursive (fails if parent doesn't exist)
+	* await dir.mkdir({ recursive: false });
+	* ```
+	*/
+	mkdir(options?: DirectoryCreateOptionsType): Promise<void>;
+	/**
+	* Deletes the directory from disk.
+	*
+	* @param options - Optional configuration for directory deletion
+	* @param options.recursive - Delete contents recursively (default: true)
+	* @param options.force - Ignore errors if directory doesn't exist (default: false)
+	* @throws {DirectoryException} If the directory cannot be deleted
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	*
+	* // Delete directory and all contents
+	* await dir.rm();
+	*
+	* // Delete only if empty
+	* await dir.rm({ recursive: false });
+	*
+	* // Delete without throwing if doesn't exist
+	* await dir.rm({ force: true });
+	* ```
+	*/
+	rm(options?: DirectoryDeleteOptionsType): Promise<void>;
+	/**
+	* Lists the contents of the directory.
+	*
+	* @param options - Optional configuration for listing
+	* @param options.recursive - List contents recursively (default: false)
+	* @returns A promise that resolves to an array of file/directory names
+	* @throws {DirectoryException} If the directory cannot be listed
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	*
+	* // List immediate contents
+	* const files = await dir.ls();
+	* console.log(files); // ["file1.txt", "file2.txt", "subdir"]
+	*
+	* // List all contents recursively
+	* const allFiles = await dir.ls({ recursive: true });
+	* console.log(allFiles); // ["file1.txt", "file2.txt", "subdir", "subdir/nested.txt"]
+	* ```
+	*/
+	ls(options?: DirectoryListOptionsType): Promise<string[]>;
+	/**
+	* Lists the contents of the directory with type information.
+	*
+	* @param options - Optional configuration for listing
+	* @param options.recursive - List contents recursively (default: false)
+	* @returns A promise that resolves to an array of Dirent objects
+	* @throws {DirectoryException} If the directory cannot be listed
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	* const entries = await dir.lsWithTypes();
+	*
+	* for (const entry of entries) {
+	*   if (entry.isFile()) {
+	*     console.log(`File: ${entry.name}`);
+	*   } else if (entry.isDirectory()) {
+	*     console.log(`Directory: ${entry.name}`);
+	*   } else if (entry.isSymbolicLink()) {
+	*     console.log(`Symlink: ${entry.name}`);
+	*   }
+	* }
+	* ```
+	*/
+	lsWithTypes(options?: DirectoryListOptionsType): Promise<Dirent2[]>;
+	/**
+	* Copies the directory to a destination path.
+	*
+	* @param destination - The destination directory path
+	* @param options - Optional configuration for copying
+	* @param options.recursive - Copy contents recursively (default: true)
+	* @param options.overwrite - Overwrite existing files (default: false)
+	* @throws {DirectoryException} If the directory cannot be copied
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/source");
+	*
+	* // Copy directory and all contents
+	* await dir.cp("/path/to/destination");
+	*
+	* // Copy with overwrite
+	* await dir.cp("/path/to/destination", { overwrite: true });
+	*
+	* // Copy only the directory structure (no files)
+	* await dir.cp("/path/to/destination", { recursive: false });
+	* ```
+	*/
+	cp(destination: string, options?: DirectoryCopyOptionsType): Promise<void>;
+	/**
+	* Moves (renames) the directory to a new location.
+	*
+	* @param destination - The new directory path
+	* @throws {DirectoryException} If the directory cannot be moved
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/oldname");
+	*
+	* // Rename directory
+	* await dir.mv("/path/to/newname");
+	*
+	* // Move to different location
+	* await dir.mv("/different/path/dirname");
+	* ```
+	*/
+	mv(destination: string): Promise<void>;
+	/**
+	* Returns the directory statistics.
+	*
+	* @returns A promise that resolves to a Stats object
+	* @throws {DirectoryException} If stats cannot be retrieved
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	* const stats = await dir.stat();
+	*
+	* console.log(stats.isDirectory()); // true
+	* console.log(stats.mode);          // 16877 (permissions)
+	* console.log(stats.mtime);         // Date object (modification time)
+	* console.log(stats.birthtime);     // Date object (creation time)
+	* ```
+	*/
+	stat(): Promise<Stats2>;
+	/**
+	* Watches the directory for changes.
+	*
+	* @param callback - Function called when changes are detected
+	* @param options - Optional configuration for watching
+	* @param options.recursive - Watch subdirectories recursively (default: false)
+	* @returns A FSWatcher that can be closed to stop watching
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	*
+	* // Watch for changes
+	* const watcher = dir.watch((event, filename) => {
+	*   console.log(`${event}: ${filename}`);
+	* });
+	*
+	* // Watch recursively
+	* const recursiveWatcher = dir.watch(
+	*   (event, filename) => console.log(event, filename),
+	*   { recursive: true }
+	* );
+	*
+	* // Stop watching
+	* watcher.close();
+	*
+	* // Handle close with SIGINT
+	* process.on("SIGINT", () => {
+	*   watcher.close();
+	*   process.exit(0);
+	* });
+	* ```
+	*/
+	watch(callback: DirectoryWatchCallbackType, options?: DirectoryWatchOptionsType): DirectoryWatcherType;
+	/**
+	* Checks if the directory is empty.
+	*
+	* @returns A promise that resolves to true if the directory has no contents
+	* @throws {DirectoryException} If the directory cannot be checked
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	*
+	* if (await dir.isEmpty()) {
+	*   console.log("Directory is empty");
+	*   await dir.rm();
+	* } else {
+	*   console.log("Directory has contents");
+	* }
+	* ```
+	*/
+	isEmpty(): Promise<boolean>;
+	/**
+	* Calculates the total size of all contents in the directory.
+	*
+	* @returns A promise that resolves to the total size in bytes
+	* @throws {DirectoryException} If the size cannot be calculated
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	* const sizeBytes = await dir.getSize();
+	*
+	* // Format as human-readable
+	* const sizeMB = (sizeBytes / (1024 * 1024)).toFixed(2);
+	* console.log(`Directory size: ${sizeMB} MB`);
+	* ```
+	*/
+	getSize(): Promise<number>;
+	/**
+	* Gets a list of files (not directories) in the directory.
+	*
+	* @param options - Optional configuration for getting files
+	* @param options.recursive - Get files recursively from subdirectories (default: false)
+	* @param options.pattern - Regular expression to filter files by name
+	* @returns A promise that resolves to an array of File instances
+	* @throws {DirectoryException} If the files cannot be listed
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	*
+	* // Get immediate files only
+	* const files = await dir.getFiles();
+	* for (const file of files) {
+	*   console.log(file.getName());
+	* }
+	*
+	* // Get all files recursively
+	* const allFiles = await dir.getFiles({ recursive: true });
+	*
+	* // Get only TypeScript files
+	* const tsFiles = await dir.getFiles({ pattern: /\.ts$/ });
+	*
+	* // Get TypeScript files recursively
+	* const allTsFiles = await dir.getFiles({ recursive: true, pattern: /\.tsx?$/ });
+	* ```
+	*/
+	getFiles(options?: DirectoryGetFilesOptionsType): Promise<IFile[]>;
+	/**
+	* Gets a list of subdirectories (not files) in the directory.
+	*
+	* @param options - Optional configuration for getting directories
+	* @param options.recursive - Get directories recursively from subdirectories (default: false)
+	* @param options.pattern - Regular expression to filter directories by name
+	* @returns A promise that resolves to an array of Directory instances
+	* @throws {DirectoryException} If the directories cannot be listed
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/directory");
+	*
+	* // Get immediate subdirectories only
+	* const dirs = await dir.getDirectories();
+	* for (const subdir of dirs) {
+	*   console.log(subdir.getName());
+	* }
+	*
+	* // Get all subdirectories recursively
+	* const allDirs = await dir.getDirectories({ recursive: true });
+	*
+	* // Get only directories starting with "test"
+	* const testDirs = await dir.getDirectories({ pattern: /^test/ });
+	*
+	* // Get directories recursively matching pattern
+	* const srcDirs = await dir.getDirectories({ recursive: true, pattern: /^src/ });
+	* ```
+	*/
+	getDirectories(options?: DirectoryGetDirectoriesOptionsType): Promise<IDirectory[]>;
+	/**
+	* Changes to a subdirectory and returns a new Directory instance.
+	*
+	* @param paths - The relative path segments to the subdirectory
+	* @returns A new Directory instance pointing to the subdirectory
+	*
+	* @example
+	* ```typescript
+	* const dir = new Directory("/path/to/project");
+	*
+	* // Navigate to subdirectory
+	* const srcDir = dir.cd("src");
+	* console.log(srcDir.getPath()); // "/path/to/project/src"
+	*
+	* // Navigate multiple levels with multiple args
+	* const componentsDir = dir.cd("src", "components", "ui");
+	* console.log(componentsDir.getPath()); // "/path/to/project/src/components/ui"
+	*
+	* // Navigate to parent
+	* const parentDir = dir.cd("..");
+	* console.log(parentDir.getPath()); // "/path/to"
+	*
+	* // Chain navigation
+	* const deepDir = dir.cd("src").cd("components").cd("ui");
+	* ```
+	*/
+	cd(...paths: string[]): IDirectory;
+	private calculateSize;
+}
+import { Exception } from "@ooneex/exception";
+declare class DirectoryException extends Exception {
+	constructor(message: string, data?: Record<string, unknown>);
+}
+/**
+* A class for performing file operations using Bun's optimized file I/O APIs.
+*
+* @example
+* ```typescript
+* import { File } from "@ooneex/fs";
+*
+* const file = new File("/path/to/file.txt");
+*
+* // Read file content
+* const content = await file.text();
+*
+* // Write to file
+* await file.write("Hello, World!");
+*
+* // Check if file exists
+* if (await file.exists()) {
+*   console.log("File exists!");
+* }
+* ```
+*/
+declare class File implements IFile {
+	private readonly path;
+	private readonly options;
+	/**
+	* Creates a new File instance.
+	*
+	* @param path - The file path as a string or URL
+	* @param options - Optional configuration options
+	*
+	* @example
+	* ```typescript
+	* // Using string path
+	* const file = new File("/path/to/file.txt");
+	*
+	* // Using URL
+	* const file = new File(new URL("file:///path/to/file.txt"));
+	*
+	* // With custom MIME type
+	* const file = new File("/path/to/file", { type: "application/json" });
+	* ```
+	*/
+	constructor(path: string | URL, options?: FileOptionsType);
+	private getBunFile;
+	/**
+	* Returns the file path.
+	*
+	* @returns The absolute or relative path of the file
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/document.pdf");
+	* console.log(file.getPath()); // "/path/to/document.pdf"
+	* ```
+	*/
+	getPath(): string;
+	/**
+	* Returns the file name including extension.
+	*
+	* @returns The base name of the file
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/document.pdf");
+	* console.log(file.getName()); // "document.pdf"
+	* ```
+	*/
+	getName(): string;
+	/**
+	* Returns the file extension without the leading dot.
+	*
+	* @returns The file extension or empty string if none
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/document.pdf");
+	* console.log(file.getExtension()); // "pdf"
+	*
+	* const noExt = new File("/path/to/README");
+	* console.log(noExt.getExtension()); // ""
+	* ```
+	*/
+	getExtension(): string;
+	/**
+	* Returns the directory containing the file.
+	*
+	* @returns The parent directory as an IDirectory instance
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/document.pdf");
+	* const dir = file.getDirectory();
+	* console.log(dir.getPath()); // "/path/to"
+	* ```
+	*/
+	getDirectory(): IDirectory;
+	/**
+	* Returns the file size in bytes.
+	*
+	* @returns The size of the file in bytes, or 0 if file doesn't exist
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/document.pdf");
+	* console.log(file.getSize()); // 1024
+	* ```
+	*/
+	getSize(): number;
+	/**
+	* Returns the MIME type of the file.
+	*
+	* @returns The MIME type string (e.g., "text/plain", "application/json")
+	*
+	* @example
+	* ```typescript
+	* const txtFile = new File("/path/to/file.txt");
+	* console.log(txtFile.getType()); // "text/plain;charset=utf-8"
+	*
+	* const jsonFile = new File("/path/to/data.json");
+	* console.log(jsonFile.getType()); // "application/json;charset=utf-8"
+	* ```
+	*/
+	getType(): string;
+	/**
+	* Checks if the file exists on disk.
+	*
+	* @returns A promise that resolves to true if the file exists
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/file.txt");
+	*
+	* if (await file.exists()) {
+	*   console.log("File exists!");
+	* } else {
+	*   console.log("File not found");
+	* }
+	* ```
+	*/
+	exists(): Promise<boolean>;
+	/**
+	* Reads the file content as a string.
+	*
+	* @returns A promise that resolves to the file content as a string
+	* @throws {FileException} If the file cannot be read
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/file.txt");
+	* const content = await file.text();
+	* console.log(content); // "Hello, World!"
+	* ```
+	*/
+	text(): Promise<string>;
+	/**
+	* Reads and parses the file content as JSON.
+	*
+	* @typeParam T - The expected type of the parsed JSON
+	* @returns A promise that resolves to the parsed JSON object
+	* @throws {FileException} If the file cannot be read or parsed
+	*
+	* @example
+	* ```typescript
+	* interface Config {
+	*   name: string;
+	*   version: number;
+	* }
+	*
+	* const file = new File("/path/to/config.json");
+	* const config = await file.json<Config>();
+	* console.log(config.name); // "my-app"
+	* ```
+	*/
+	json<T = unknown>(): Promise<T>;
+	/**
+	* Reads the file content as an ArrayBuffer.
+	*
+	* @returns A promise that resolves to the file content as an ArrayBuffer
+	* @throws {FileException} If the file cannot be read
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/binary.bin");
+	* const buffer = await file.arrayBuffer();
+	* const view = new DataView(buffer);
+	* console.log(view.getInt32(0)); // First 4 bytes as int32
+	* ```
+	*/
+	arrayBuffer(): Promise<ArrayBuffer>;
+	/**
+	* Reads the file content as a Uint8Array.
+	*
+	* @returns A promise that resolves to the file content as a Uint8Array
+	* @throws {FileException} If the file cannot be read
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/binary.bin");
+	* const bytes = await file.bytes();
+	* console.log(bytes[0]); // First byte
+	* console.log(bytes.length); // Total bytes
+	* ```
+	*/
+	bytes(): Promise<Uint8Array>;
+	/**
+	* Returns a ReadableStream for incremental file reading.
+	*
+	* @returns A ReadableStream of Uint8Array chunks
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/large-file.txt");
+	* const stream = file.stream();
+	*
+	* for await (const chunk of stream) {
+	*   console.log(`Received ${chunk.length} bytes`);
+	* }
+	* ```
+	*/
+	stream(): ReadableStream<Uint8Array>;
+	/**
+	* Returns a ReadableStream for incremental file reading as text.
+	*
+	* @returns A ReadableStream of string chunks
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/large-file.txt");
+	* const stream = file.streamAsText();
+	*
+	* for await (const chunk of stream) {
+	*   console.log(`Received text: ${chunk}`);
+	* }
+	* ```
+	*/
+	streamAsText(): ReadableStream<string>;
+	/**
+	* Returns a ReadableStream for incremental JSON parsing from a JSON array file.
+	*
+	* Reads a file containing a JSON array and streams each parsed element individually.
+	* This is useful for processing large JSON array files without loading everything into memory.
+	*
+	* @typeParam T - The expected type of each JSON element
+	* @returns A ReadableStream of parsed JSON elements
+	*
+	* @example
+	* ```typescript
+	* // For a file containing: [{"id": 1}, {"id": 2}, {"id": 3}]
+	* const file = new File("/path/to/data.json");
+	* const stream = file.streamAsJson<{ id: number }>();
+	*
+	* for await (const item of stream) {
+	*   console.log(item.id); // 1, 2, 3
+	* }
+	* ```
+	*/
+	streamAsJson<T = unknown>(): ReadableStream<T>;
+	/**
+	* Writes data to the file, overwriting existing content.
+	*
+	* @param data - The data to write (string, Blob, ArrayBuffer, TypedArray, or Response)
+	* @returns A promise that resolves to the number of bytes written
+	* @throws {FileException} If the file cannot be written
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/file.txt");
+	*
+	* // Write string
+	* await file.write("Hello, World!");
+	*
+	* // Write Uint8Array
+	* await file.write(new Uint8Array([72, 101, 108, 108, 111]));
+	*
+	* // Write from Response
+	* const response = await fetch("https://example.com/data");
+	* await file.write(response);
+	* ```
+	*/
+	write(data: FileWriteDataType): Promise<number>;
+	/**
+	* Appends data to the end of the file.
+	*
+	* @param data - The data to append (string or Uint8Array)
+	* @returns A promise that resolves to the total number of bytes in the file
+	* @throws {FileException} If the file cannot be appended to
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/log.txt");
+	*
+	* // Append string
+	* await file.append("New log entry\n");
+	*
+	* // Append binary data
+	* await file.append(new Uint8Array([10, 20, 30]));
+	* ```
+	*/
+	append(data: string | Uint8Array): Promise<number>;
+	/**
+	* Copies the file to a destination path.
+	*
+	* @param destination - The destination file path
+	* @returns A promise that resolves to a new File instance for the copied file
+	* @throws {FileException} If the file cannot be copied
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/original.txt");
+	* const copiedFile = await file.copy("/path/to/backup.txt");
+	*
+	* // The original file is preserved
+	* console.log(await file.exists()); // true
+	* // Access the copied file
+	* console.log(await copiedFile.text()); // same content as original
+	* ```
+	*/
+	copy(destination: string): Promise<IFile>;
+	/**
+	* Deletes the file from disk.
+	*
+	* @throws {FileException} If the file cannot be deleted
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/temp.txt");
+	*
+	* if (await file.exists()) {
+	*   await file.delete();
+	*   console.log("File deleted");
+	* }
+	* ```
+	*/
+	delete(): Promise<void>;
+	/**
+	* Downloads a file from a URL and saves it to this file's path.
+	*
+	* @param url - The URL to download the file from
+	* @returns A promise that resolves to the number of bytes written
+	* @throws {FileException} If the download or write operation fails
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/image.png");
+	*
+	* // Download from URL
+	* const bytes = await file.download("https://example.com/image.png");
+	* console.log(`Downloaded ${bytes} bytes`);
+	*
+	* // Download with URL object
+	* await file.download(new URL("https://example.com/data.json"));
+	* ```
+	*/
+	download(url: string | URL): Promise<number>;
+	/**
+	* Returns a FileSink for incremental writing.
+	*
+	* @param options - Optional configuration for the writer
+	* @returns A FileSink instance for buffered writing
+	*
+	* @example
+	* ```typescript
+	* const file = new File("/path/to/output.txt");
+	* const writer = file.writer({ highWaterMark: 1024 * 1024 }); // 1MB buffer
+	*
+	* writer.write("Line 1\n");
+	* writer.write("Line 2\n");
+	* writer.flush(); // Flush buffer to disk
+	*
+	* writer.write("Line 3\n");
+	* writer.end(); // Flush and close
+	* ```
+	*/
+	writer(options?: FileWriterOptionsType): BunFileSinkType;
+}
+import { Exception as Exception2 } from "@ooneex/exception";
+declare class FileException extends Exception2 {
+	constructor(message: string, data?: Record<string, unknown>);
+}
+export { IFile, IDirectory, FileWriterOptionsType, FileWriteDataType, FileOptionsType, FileException, File, DirectoryWatcherType, DirectoryWatchOptionsType, DirectoryWatchEventType, DirectoryWatchCallbackType, DirectoryListOptionsType, DirectoryGetFilesOptionsType, DirectoryGetDirectoriesOptionsType, DirectoryException, DirectoryDeleteOptionsType, DirectoryCreateOptionsType, DirectoryCopyOptionsType, Directory, BunFileSinkType };