import type { ZodType } from "zod";
import type { FileEncoding, FileHashAlgorithm, FileStats, FilesystemResult, ReadDirEntry, ReadDirOptions, WriteFileOptions } from "../../types/index.js";
/**
 * Reads a text file.
 *
 * @param path - File path (relative paths resolve against `process.cwd()`).
 * @param encoding - Text encoding (default: `"utf8"`).
 * @returns Safe Result with the file contents as a string.
 *
 * @example
 * ```ts
 * import { useReadFile } from "katanakit-js";
 *
 * const result = await useReadFile("data/books.json");
 * if (result.ok) console.log(result.data);
 * ```
 */
export declare function useReadFile(path: string, encoding?: FileEncoding): Promise<FilesystemResult<string>>;
/**
 * Reads a file as raw bytes (no encoding).
 *
 * @param path - File path.
 * @returns Safe Result with the contents as a `Uint8Array`.
 *
 * @example
 * ```ts
 * const result = await useReadFileBuffer("assets/logo.png");
 * if (result.ok) upload(result.data);
 * ```
 */
export declare function useReadFileBuffer(path: string): Promise<FilesystemResult<Uint8Array>>;
/**
 * Streams a file and returns its checksum as a lowercase hex digest.
 *
 * @param path - File path.
 * @param algorithm - `"md5" | "sha1" | "sha256" | "sha512"` (default: `"sha256"`).
 * @returns Safe Result with the hex digest.
 *
 * @example
 * ```ts
 * const result = await useHashFile("image.iso"); // sha256
 * const md5 = await useHashFile("image.iso", "md5");
 * ```
 */
export declare function useHashFile(path: string, algorithm?: FileHashAlgorithm): Promise<FilesystemResult<string>>;
/**
 * Verifies a file checksum against an expected value (case-insensitive).
 *
 * @param path - File path.
 * @param expected - Expected hex digest (from a `.sha256` sidecar, release page, …).
 * @param algorithm - Algorithm used for both values (default: `"sha256"`).
 * @returns Safe Result with `true` when the digests match.
 *
 * @example
 * ```ts
 * const check = await useVerifyFileHash("image.iso", "e3b0c442…");
 * if (check.ok && !check.data) throw new Error("checksum mismatch");
 * ```
 */
export declare function useVerifyFileHash(path: string, expected: string, algorithm?: FileHashAlgorithm): Promise<FilesystemResult<boolean>>;
/**
 * Writes (or overwrites) a file, creating it when missing.
 *
 * @param path - Destination file path.
 * @param data - Text or bytes to write.
 * @param options - Encoding, mode and flag overrides.
 * @returns Safe Result with the written path.
 *
 * @example
 * ```ts
 * const result = await useWriteFile("logs/app.log", "started\n");
 * ```
 */
export declare function useWriteFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<FilesystemResult<string>>;
/**
 * Appends text or bytes to a file, creating it when missing.
 *
 * @param path - Destination file path.
 * @param data - Text or bytes to append.
 * @param options - Encoding, mode and flag overrides.
 * @returns Safe Result with the written path.
 *
 * @example
 * ```ts
 * await useAppendFile("logs/app.log", "request handled\n");
 * ```
 */
export declare function useAppendFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<FilesystemResult<string>>;
/**
 * Reads and parses a JSON file, optionally validating it with a Zod schema.
 *
 * @typeParam T - Expected parsed (and validated) shape.
 * @param path - File path.
 * @param schema - Optional Zod schema; invalid shapes fail with `ERR_VALIDATION`.
 * @returns Safe Result with the parsed data, or `ERR_INVALID_JSON` / `ERR_VALIDATION`.
 *
 * @example
 * ```ts
 * import { z } from "zod";
 *
 * const BookSchema = z.object({ title: z.string() });
 * const result = await useReadJsonFile("data/books.json", BookSchema);
 * ```
 */
export declare function useReadJsonFile<T = unknown>(path: string, schema?: ZodType<T>): Promise<FilesystemResult<T>>;
/**
 * Serializes data to JSON and writes it to a file (pretty-printed by default).
 *
 * @param path - Destination file path.
 * @param data - Value to serialize (`JSON.stringify` rules apply).
 * @param options - Set `pretty: false` for compact output.
 * @returns Safe Result with the written path.
 *
 * @example
 * ```ts
 * await useWriteJsonFile("data/books.json", books);
 * ```
 */
export declare function useWriteJsonFile(path: string, data: unknown, options?: {
    pretty?: boolean;
}): Promise<FilesystemResult<string>>;
/**
 * Lists a directory with type flags resolved per entry.
 *
 * @param path - Directory path.
 * @param options - `recursive: true` walks nested directories.
 * @returns Safe Result with `{ name, path, isFile, isDirectory }` entries.
 *
 * @example
 * ```ts
 * const result = await useReadDir("content", { recursive: true });
 * if (result.ok) result.data.filter((entry) => entry.isFile);
 * ```
 */
export declare function useReadDir(path: string, options?: ReadDirOptions): Promise<FilesystemResult<ReadDirEntry[]>>;
/**
 * Creates a directory (and any missing parents).
 *
 * @param path - Directory path to ensure.
 * @returns Safe Result with the directory path.
 *
 * @example
 * ```ts
 * await useEnsureDir("data/cache/books");
 * ```
 */
export declare function useEnsureDir(path: string): Promise<FilesystemResult<string>>;
/**
 * Checks whether a path exists and is accessible.
 * Never throws: returns `false` for missing paths and non-Node runtimes.
 *
 * @param path - Path to check.
 * @returns `true` when the path exists.
 *
 * @example
 * ```ts
 * if (await useFileExists("data/books.json")) {
 *   // read it
 * }
 * ```
 */
export declare function useFileExists(path: string): Promise<boolean>;
/**
 * Returns a portable stats subset for a file or directory.
 *
 * @param path - Path to inspect (follows symlinks).
 * @returns Safe Result with size, type flags and epoch-ms timestamps.
 *
 * @example
 * ```ts
 * const result = await useGetFileStats("assets/logo.png");
 * if (result.ok) console.log(result.data.size);
 * ```
 */
export declare function useGetFileStats(path: string): Promise<FilesystemResult<FileStats>>;
/**
 * Copies a file. Existing destinations are overwritten unless
 * `overwrite: false` is passed (`COPYFILE_EXCL`).
 *
 * @param source - Source file path.
 * @param destination - Destination file path.
 * @param options - Set `overwrite: false` to fail when the target exists.
 * @returns Safe Result with the destination path.
 *
 * @example
 * ```ts
 * await useCopyFile("data/books.json", "backup/books.json");
 * ```
 */
export declare function useCopyFile(source: string, destination: string, options?: {
    overwrite?: boolean;
}): Promise<FilesystemResult<string>>;
/**
 * Moves (renames) a file or directory.
 *
 * @param source - Source path.
 * @param destination - Destination path.
 * @returns Safe Result with the destination path.
 *
 * @example
 * ```ts
 * await useMoveFile("data/draft.json", "data/books.json");
 * ```
 */
export declare function useMoveFile(source: string, destination: string): Promise<FilesystemResult<string>>;
/**
 * Removes a file.
 *
 * @param path - File path to remove.
 * @returns Safe Result with the removed path.
 *
 * @example
 * ```ts
 * await useRemoveFile("data/cache/books.json");
 * ```
 */
export declare function useRemoveFile(path: string): Promise<FilesystemResult<string>>;
/**
 * Removes a directory tree. Recursive by default; `force: false`
 * surfaces `ENOENT` instead of ignoring missing paths.
 *
 * @param path - Directory path to remove.
 * @param options - `recursive` (default `true`) and `force` (default `false`).
 * @returns Safe Result with the removed path.
 *
 * @example
 * ```ts
 * await useRemoveDir("data/cache");
 * ```
 */
export declare function useRemoveDir(path: string, options?: {
    force?: boolean;
    recursive?: boolean;
}): Promise<FilesystemResult<string>>;
/**
 * Reads a file resolved from the caller's module directory — the
 * `__dirname` + relative path pattern, without `__dirname`.
 *
 * @param importMetaUrl - Your module's `import.meta.url`.
 * @param relativePath - Path relative to that module (e.g. `"../data/books.json"`).
 * @param encoding - Text encoding (default: `"utf8"`).
 * @returns Safe Result with the file contents as a string.
 *
 * @example
 * ```ts
 * const css = await useReadModuleFile(import.meta.url, "./theme.css");
 * ```
 */
export declare function useReadModuleFile(importMetaUrl: string, relativePath: string, encoding?: FileEncoding): Promise<FilesystemResult<string>>;
/**
 * Reads and parses a JSON file resolved from the caller's module directory,
 * optionally validating it with a Zod schema.
 *
 * @typeParam T - Expected parsed (and validated) shape.
 * @param importMetaUrl - Your module's `import.meta.url`.
 * @param relativePath - Path relative to that module.
 * @param schema - Optional Zod schema for runtime validation.
 * @returns Safe Result with the parsed data.
 *
 * @example
 * ```ts
 * const result = await useReadModuleJson<Book[]>(import.meta.url, "../data/books.json");
 * if (result.ok) initBooks(result.data);
 * ```
 */
export declare function useReadModuleJson<T = unknown>(importMetaUrl: string, relativePath: string, schema?: ZodType<T>): Promise<FilesystemResult<T>>;
//# sourceMappingURL=filesystem.service.d.ts.map