/**
 * @file File-content readers — UTF-8 / binary / safe variants (sync + async).
 *   The `safe*` versions trap errors and return `undefined` (or a
 *   caller-supplied `defaultValue`) so they fit the non-throwing-fallback shape
 *   used elsewhere in the lib. The encoding `null` overload returns a `Buffer`;
 *   the default and any string encoding return a string. The runtime fast-path
 *   normalizes encoding once and forwards untouched options to `node:fs`.
 */
import type { PathLike } from 'node:fs';
import type { ReadFileOptions, SafeReadOptions } from './types';
/**
 * Read a file as binary data asynchronously. Returns a Buffer without encoding
 * the contents. Useful for reading images, archives, or other binary formats.
 *
 * @example
 *   ;```ts
 *   // Read an image file
 *   const imageBuffer = await readFileBinary('./image.png')
 *
 *   // Read with abort signal
 *   const buffer = await readFileBinary('./data.bin', { signal: abortSignal })
 *   ```
 *
 * @param filepath - Path to file.
 * @param options - Read options (encoding is forced to null for binary)
 *
 * @returns Promise resolving to Buffer containing file contents
 */
export declare function readFileBinary(filepath: PathLike, options?: ReadFileOptions | undefined): Promise<NonSharedBuffer>;
/**
 * Read a file as binary data synchronously. Returns a Buffer without encoding
 * the contents. Useful for reading images, archives, or other binary formats.
 *
 * @example
 *   ;```ts
 *   // Read an image file
 *   const imageBuffer = readFileBinarySync('./logo.png')
 *
 *   // Read a compressed file
 *   const gzipData = readFileBinarySync('./archive.gz')
 *   ```
 *
 * @param filepath - Path to file.
 * @param options - Read options (encoding is forced to null for binary)
 *
 * @returns Buffer containing file contents
 */
export declare function readFileBinarySync(filepath: PathLike, options?: ReadFileOptions | undefined): string | NonSharedBuffer;
/**
 * Read a file as UTF-8 text asynchronously. Returns a string with the file
 * contents decoded as UTF-8. This is the most common way to read text files.
 *
 * @example
 *   ;```ts
 *   // Read a text file
 *   const content = await readFileUtf8('./README.md')
 *
 *   // Read with custom encoding
 *   const content = await readFileUtf8('./data.txt', { encoding: 'utf-8' })
 *   ```
 *
 * @param filepath - Path to file.
 * @param options - Read options including encoding and abort signal.
 *
 * @returns Promise resolving to string containing file contents
 */
export declare function readFileUtf8(filepath: PathLike, options?: ReadFileOptions | undefined): Promise<string>;
/**
 * Read a file as UTF-8 text synchronously. Returns a string with the file
 * contents decoded as UTF-8. This is the most common way to read text files
 * synchronously.
 *
 * @example
 *   ;```ts
 *   // Read a configuration file
 *   const config = readFileUtf8Sync('./config.txt')
 *
 *   // Read with custom options
 *   const data = readFileUtf8Sync('./data.txt', { encoding: 'utf8' })
 *   ```
 *
 * @param filepath - Path to file.
 * @param options - Read options including encoding.
 *
 * @returns String containing file contents
 */
export declare function readFileUtf8Sync(filepath: PathLike, options?: ReadFileOptions | undefined): string | NonSharedBuffer;
/**
 * Safely read a file asynchronously, returning undefined on error. Useful when
 * you want to attempt reading a file without handling errors explicitly.
 * Returns undefined for any error (file not found, permission denied, etc.).
 * Defaults to UTF-8 encoding, returning a string unless encoding is explicitly
 * set to null.
 *
 * @example
 *   ;```ts
 *   // Try to read a file as UTF-8 string (default), get undefined if it doesn't exist
 *   const content = await safeReadFile('./optional-config.txt')
 *   if (content) {
 *     console.log('Config found:', content)
 *   }
 *
 *   // Read with specific encoding
 *   const data = await safeReadFile('./data.txt', { encoding: 'utf8' })
 *
 *   // Read as Buffer by setting encoding to null
 *   const buffer = await safeReadFile('./binary.dat', { encoding: null })
 *   ```
 *
 * @param filepath - Path to file.
 * @param options - Read options including encoding and default value.
 *
 * @returns Promise resolving to file contents (string by default), or undefined
 *   on error.
 */
export declare function safeReadFile(filepath: PathLike, options: SafeReadOptions & {
    encoding: null;
}): Promise<Buffer | undefined>;
export declare function safeReadFile(filepath: PathLike, options?: SafeReadOptions | undefined): Promise<string | undefined>;
/**
 * Safely read a file synchronously, returning undefined on error. Useful when
 * you want to attempt reading a file without handling errors explicitly.
 * Returns undefined for any error (file not found, permission denied, etc.).
 * Defaults to UTF-8 encoding, returning a string unless encoding is explicitly
 * set to null.
 *
 * @example
 *   ;```ts
 *   // Try to read a config file as UTF-8 string (default)
 *   const config = safeReadFileSync('./config.txt')
 *   if (config) {
 *     console.log('Config loaded successfully')
 *   }
 *
 *   // Read with explicit encoding
 *   const data = safeReadFileSync('./data.txt', { encoding: 'utf8' })
 *
 *   // Read binary file by setting encoding to null
 *   const buffer = safeReadFileSync('./image.png', { encoding: null })
 *   ```
 *
 * @param filepath - Path to file.
 * @param options - Read options including encoding and default value.
 *
 * @returns File contents (string by default), or undefined on error
 */
export declare function safeReadFileSync(filepath: PathLike, options: SafeReadOptions & {
    encoding: null;
}): Buffer | undefined;
export declare function safeReadFileSync(filepath: PathLike, options?: SafeReadOptions | undefined): string | undefined;
