minigame-std/dist/types/fs.d.ts

Cross-platform standard library for WeChat minigame and web browsers with unified APIs for crypto, fs, fetch, storage, and more.

import { FsRequestInit, UploadRequestInit, ZipFromUrlRequestInit, AppendOptions, DownloadFileTempResponse, ExistsOptions, WriteOptions, ZipOptions } from 'happy-opfs';
import * as happyOpfs from 'happy-opfs';
export { happyOpfs as opfs };
import { FetchInit, FetchTask } from '@happy-ts/fetch-t';
import { AsyncVoidIOResult, AsyncIOResult, VoidIOResult, IOResult } from 'happy-rusty';

/**
 * 公共类型定义模块。
 *
 * @module defines
 */
/**
 * 数据源类型，可以是 string 或者 BufferSource。
 * @since 1.8.0
 * @example
 * ```ts
 * // 字符串类型
 * const strData: DataSource = 'Hello, World!';
 *
 * // ArrayBuffer 类型
 * const bufferData: DataSource = new ArrayBuffer(8);
 *
 * // Uint8Array 类型
 * const u8aData: DataSource = new Uint8Array([1, 2, 3]);
 * ```
 */
type DataSource = string | BufferSource;

/**
 * @internal
 * 小游戏平台文件系统请求的内部类型定义。
 */

/**
 * 下载文件的选项。
 */
interface DownloadFileOptions extends Omit<WechatMinigame.DownloadFileOption, 'url' | 'filePath' | 'header' | 'success' | 'fail'> {
    headers?: Record<string, string>;
    onProgress?: FetchInit['onProgress'];
}
/**
 * 上传文件的选项。
 */
interface UploadFileOptions extends Omit<WechatMinigame.UploadFileOption, 'url' | 'filePath' | 'name' | 'header' | 'success' | 'fail'> {
    headers?: Record<string, string>;
    /**
     * 可选的文件名称。
     */
    name?: string;
}

/**
 * 异步写入文件的内容类型，支持 `ArrayBuffer` `TypedArray` `string`。
 * 小游戏不支持 `Blob` 和 `ReadableStream`，因此直接使用 `DataSource`。
 * @since 1.0.0
 * @example
 * ```ts
 * import { fs, type WriteFileContent } from 'minigame-std';
 *
 * const content: WriteFileContent = '文本内容';
 * await fs.writeFile('/path/to/file.txt', content);
 * ```
 */
type WriteFileContent = DataSource;
/**
 * 读取文件的内容类型，支持 `Uint8Array<ArrayBuffer>` `string`。
 * 小游戏不支持 `Blob`、`File` 和 `ReadableStream`。
 * @since 1.0.0
 * @example
 * ```ts
 * import type { ReadFileContent } from 'minigame-std';
 *
 * // ReadFileContent 可以是 Uint8Array<ArrayBuffer> 或 string
 * const content: ReadFileContent = new Uint8Array(8);
 * ```
 */
type ReadFileContent = Uint8Array<ArrayBuffer> | string;
/**
 * 指定编码读取文件的选项。
 * @since 1.0.0
 * @example
 * ```ts
 * import type { ReadOptions } from 'minigame-std';
 *
 * const options: ReadOptions = { encoding: 'utf8' };
 * ```
 */
interface ReadOptions {
    /**
     * 读取文件的编码类型，支持 `bytes(Uint8Array)` `utf8(string)`。
     *
     * @defaultValue `'bytes'`
     */
    encoding?: FileEncoding;
}
/**
 * 支持的文件编码格式。
 * @since 1.0.0
 * @example
 * ```ts
 * import type { FileEncoding } from 'minigame-std';
 *
 * const encoding: FileEncoding = 'utf8';
 * ```
 */
type FileEncoding = 'bytes' | 'utf8';
/**
 * 统一下载请求的选项。
 * @since 1.0.0
 * @example
 * ```ts
 * import type { UnionDownloadFileOptions } from 'minigame-std';
 *
 * const options: UnionDownloadFileOptions = {
 *     headers: { 'Authorization': 'Bearer token' },
 *     timeout: 30000,
 *     onProgress: (p) => console.log(p.progress),
 * };
 * ```
 */
interface UnionDownloadFileOptions extends Omit<FsRequestInit & DownloadFileOptions, 'headers'> {
    headers?: Record<string, string>;
}
/**
 * 统一上传请求的选项。
 * @since 1.0.0
 * @example
 * ```ts
 * import type { UnionUploadFileOptions } from 'minigame-std';
 *
 * const options: UnionUploadFileOptions = {
 *     name: 'file',
 *     headers: { 'Authorization': 'Bearer token' },
 *     formData: { key: 'value' },
 * };
 * ```
 */
interface UnionUploadFileOptions extends Omit<UploadRequestInit & UploadFileOptions, 'headers'> {
    headers?: Record<string, string>;
}
/**
 * stat 操作的选项。
 * @since 1.0.0
 * @example
 * ```ts
 * import { fs, type StatOptions } from 'minigame-std';
 *
 * const options: StatOptions = { recursive: true };
 * const result = await fs.stat('/path/to/dir', options);
 * ```
 */
interface StatOptions {
    /**
     * 是否递归读取目录内容。
     */
    recursive: boolean;
}
/**
 * `unzipFromUrl` 的统一选项。
 * @since 1.4.0
 * @example
 * ```ts
 * import { fs, type ZipFromUrlOptions } from 'minigame-std';
 *
 * const options: ZipFromUrlOptions = {
 *     headers: { 'Authorization': 'Bearer token' },
 *     onProgress: (p) => console.log(p.progress),
 * };
 * await fs.unzipFromUrl('https://example.com/archive.zip', '/path/to/output', options);
 * ```
 */
interface ZipFromUrlOptions extends Omit<DownloadFileOptions & ZipFromUrlRequestInit, 'headers'> {
    headers?: Record<string, string>;
}

/**
 * 递归创建文件夹，相当于 `mkdir -p`。
 * @param dirPath - 将要创建的目录的路径。
 * @returns 创建成功返回的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await mkdir('/path/to/dir');
 * if (result.isOk()) {
 *     console.log('目录创建成功');
 * }
 * ```
 */
declare function mkdir(dirPath: string): AsyncVoidIOResult;
/**
 * 移动或重命名文件或目录。
 * @param srcPath - 原始路径。
 * @param destPath - 新路径。
 * @returns 操作成功返回的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await move('/old/path', '/new/path');
 * if (result.isOk()) {
 *     console.log('移动成功');
 * }
 * ```
 */
declare function move(srcPath: string, destPath: string): AsyncVoidIOResult;
/**
 * 异步读取指定目录下的所有文件和子目录。
 * @param dirPath - 需要读取的目录路径。
 * @returns 包含目录内容的字符串数组的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await readDir('/path/to/dir');
 * if (result.isOk()) {
 *     console.log(result.unwrap()); // ['file1.txt', 'file2.txt', 'subdir']
 * }
 * ```
 */
declare function readDir(dirPath: string): AsyncIOResult<string[]>;
/**
 * 以 UTF-8 格式读取文件。
 * @param filePath - 文件路径。
 * @param options - 读取选项，指定编码为 'utf8'。
 * @returns 包含文件内容的字符串的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await readFile('/path/to/file.txt', { encoding: 'utf8' });
 * if (result.isOk()) {
 *     console.log(result.unwrap());
 * }
 * ```
 */
declare function readFile(filePath: string, options: ReadOptions & {
    encoding: 'utf8';
}): AsyncIOResult<string>;
/**
 * 以二进制格式读取文件。
 * @param filePath - 文件路径。
 * @param options - 读取选项，指定编码为 'bytes'。
 * @returns 包含文件内容的 Uint8Array<ArrayBuffer> 的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await readFile('/path/to/file.txt', { encoding: 'bytes' });
 * if (result.isOk()) {
 *     const bytes = result.unwrap();
 *     console.log(decodeUtf8(bytes));
 * }
 * ```
 */
declare function readFile(filePath: string, options?: ReadOptions & {
    encoding: 'bytes';
}): AsyncIOResult<Uint8Array<ArrayBuffer>>;
/**
 * 读取文件内容。
 * @param filePath - 文件的路径。
 * @param options - 可选的读取选项。
 * @returns 包含文件内容的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await readFile('/path/to/file.txt');
 * if (result.isOk()) {
 *     const bytes = result.unwrap();
 *     console.log(decodeUtf8(bytes));
 * }
 * ```
 */
declare function readFile(filePath: string, options?: ReadOptions): AsyncIOResult<ReadFileContent>;
/**
 * 删除文件或目录。
 * @param path - 要删除的文件或目录的路径。
 * @returns 删除成功返回的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await remove('/path/to/file.txt');
 * if (result.isOk()) {
 *     console.log('删除成功');
 * }
 * ```
 */
declare function remove(path: string): AsyncVoidIOResult;
/**
 * 获取单个文件或目录的状态信息。
 * @param path - 文件或目录的路径。
 * @param options - 可选选项，recursive 设置为 false（默认）获取单个文件状态。
 * @returns 包含状态信息的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await stat('/path/to/file.txt');
 * if (result.isOk()) {
 *     const stats = result.unwrap();
 *     console.log(stats.isFile()); // true
 * }
 * ```
 */
declare function stat(path: string, options?: StatOptions & {
    recursive: false;
}): AsyncIOResult<WechatMinigame.Stats>;
/**
 * 递归获取目录下所有文件和子目录的状态信息。
 * @param path - 目录的路径。
 * @param options - 选项，recursive 设置为 true 以递归获取。
 * @returns 包含所有文件状态信息数组的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await stat('/path/to/dir', { recursive: true });
 * if (result.isOk()) {
 *     const fileStats = result.unwrap();
 *     fileStats.forEach(file => console.log(file.path));
 * }
 * ```
 */
declare function stat(path: string, options: StatOptions & {
    recursive: true;
}): AsyncIOResult<WechatMinigame.FileStats[]>;
declare function stat(path: string, options?: StatOptions): AsyncIOResult<WechatMinigame.Stats | WechatMinigame.FileStats[]>;
/**
 * 写入文件，文件不存在则创建，同时创建对应目录。
 * @param filePath - 文件路径。
 * @param contents - 要写入的内容，支持 ArrayBuffer 和 string（需确保是 UTF-8 编码）。
 * @param options - 可选写入选项。
 * @returns 写入成功返回的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await writeFile('/path/to/file.txt', 'Hello, World!');
 * if (result.isOk()) {
 *     console.log('写入成功');
 * }
 * ```
 */
declare function writeFile(filePath: string, contents: WriteFileContent, options?: WriteOptions): AsyncVoidIOResult;
/**
 * 向文件追加内容。
 * @param filePath - 文件路径。
 * @param contents - 要追加的内容。
 * @param options - 可选的追加选项。
 * @returns 追加成功返回的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await appendFile('/path/to/file.txt', '\nNew content');
 * if (result.isOk()) {
 *     console.log('追加成功');
 * }
 * ```
 */
declare function appendFile(filePath: string, contents: WriteFileContent, options?: AppendOptions): AsyncVoidIOResult;
/**
 * 复制文件或文件夹。
 * @param srcPath - 源文件或文件夹路径。
 * @param destPath - 目标文件或文件夹路径。
 * @returns 操作的异步结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await copy('/src/file.txt', '/dest/file.txt');
 * if (result.isOk()) {
 *     console.log('复制成功');
 * }
 * ```
 */
declare function copy(srcPath: string, destPath: string): AsyncVoidIOResult;
/**
 * 检查指定路径的文件或目录是否存在。
 * @param path - 文件或目录的路径。
 * @param options - 可选的检查选项。
 * @returns 存在返回 true 的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await exists('/path/to/file.txt');
 * if (result.isOk() && result.unwrap()) {
 *     console.log('文件存在');
 * }
 * ```
 */
declare function exists(path: string, options?: ExistsOptions): AsyncIOResult<boolean>;
/**
 * 清空指定目录下的所有文件和子目录。
 * @param dirPath - 目录路径。
 * @returns 清空成功返回的异步操作结果。
 * @since 1.0.1
 * @example
 * ```ts
 * const result = await emptyDir('/path/to/dir');
 * if (result.isOk()) {
 *     console.log('目录已清空');
 * }
 * ```
 */
declare function emptyDir(dirPath: string): AsyncVoidIOResult;
/**
 * 读取 JSON 文件并解析为对象。
 * @typeParam T - JSON 解析后的类型。
 * @param filePath - 文件路径。
 * @returns 解析后的对象。
 * @since 1.6.0
 * @example
 * ```ts
 * const result = await readJsonFile<{ name: string }>('/path/to/config.json');
 * if (result.isOk()) {
 *     console.log(result.unwrap().name);
 * }
 * ```
 */
declare function readJsonFile<T>(filePath: string): AsyncIOResult<T>;
/**
 * 读取文本文件的内容。
 * @param filePath - 文件路径。
 * @returns 包含文件文本内容的异步操作结果。
 * @since 1.0.0
 * @example
 * ```ts
 * const result = await readTextFile('/path/to/file.txt');
 * if (result.isOk()) {
 *     console.log(result.unwrap());
 * }
 * ```
 */
declare function readTextFile(filePath: string): AsyncIOResult<string>;
/**
 * 将数据序列化为 JSON 并写入文件。
 * @typeParam T - 要写入数据的类型。
 * @param filePath - 文件路径。
 * @param data - 要写入的数据。
 * @returns 写入操作的异步结果。
 * @since 2.0.0
 * @example
 * ```ts
 * const result = await writeJsonFile('/path/to/config.json', { name: 'test' });
 * if (result.isOk()) {
 *     console.log('写入成功');
 * }
 * ```
 */
declare function writeJsonFile<T>(filePath: string, data: T): AsyncVoidIOResult;
/**
 * 下载文件并保存到临时文件。
 * @param fileUrl - 文件的网络 URL。
 * @param options - 可选的下载参数。
 * @returns 下载操作的 FetchTask，可用于取消或监听进度。
 * @since 1.0.0
 * @example
 * ```ts
 * const task = downloadFile('https://example.com/file.zip');
 * const result = await task.result;
 * if (result.isOk()) {
 *     console.log('下载完成:', result.unwrap().tempFilePath);
 * }
 * ```
 */
declare function downloadFile(fileUrl: string, options?: UnionDownloadFileOptions): FetchTask<WechatMinigame.DownloadFileSuccessCallbackResult | DownloadFileTempResponse>;
/**
 * 下载文件并保存到指定路径。
 * @param fileUrl - 文件的网络 URL。
 * @param filePath - 下载后文件存储的路径。
 * @param options - 可选的请求初始化参数。
 * @returns 下载操作的 FetchTask。
 * @since 1.0.0
 * @example
 * ```ts
 * const task = downloadFile('https://example.com/file.zip', '/path/to/save.zip');
 * const result = await task.result;
 * if (result.isOk()) {
 *     console.log('下载完成');
 * }
 * ```
 */
declare function downloadFile(fileUrl: string, filePath: string, options?: UnionDownloadFileOptions): FetchTask<WechatMinigame.DownloadFileSuccessCallbackResult | Response>;
/**
 * 上传本地文件到服务器。
 * @param filePath - 需要上传的文件路径。
 * @param fileUrl - 目标服务器的 URL。
 * @param options - 可选的请求初始化参数。
 * @returns 上传操作的 FetchTask。
 * @since 1.0.0
 * @example
 * ```ts
 * const task = uploadFile('/path/to/file.txt', 'https://example.com/upload');
 * const result = await task.result;
 * if (result.isOk()) {
 *     console.log('上传成功');
 * }
 * ```
 */
declare function uploadFile(filePath: string, fileUrl: string, options?: UnionUploadFileOptions): FetchTask<WechatMinigame.UploadFileSuccessCallbackResult | Response>;
/**
 * 解压 zip 文件。
 * @param zipFilePath - 要解压的 zip 文件路径。
 * @param targetPath - 要解压到的目标文件夹路径。
 * @returns 解压操作的异步结果。
 * @since 1.3.0
 * @example
 * ```ts
 * const result = await unzip('/path/to/archive.zip', '/path/to/output');
 * if (result.isOk()) {
 *     console.log('解压成功');
 * }
 * ```
 */
declare function unzip(zipFilePath: string, targetPath: string): AsyncVoidIOResult;
/**
 * 从网络下载 zip 文件并解压。
 * @param zipFileUrl - Zip 文件的网络地址。
 * @param targetPath - 要解压到的目标文件夹路径。
 * @param options - 可选的下载参数。
 * @returns 下载并解压操作的异步结果。
 * @since 1.4.0
 * @example
 * ```ts
 * const result = await unzipFromUrl('https://example.com/archive.zip', '/path/to/output');
 * if (result.isOk()) {
 *     console.log('下载并解压成功');
 * }
 * ```
 */
declare function unzipFromUrl(zipFileUrl: string, targetPath: string, options?: UnionDownloadFileOptions): AsyncVoidIOResult;
/**
 * 压缩文件或文件夹到内存。
 * @param sourcePath - 需要压缩的文件（夹）路径。
 * @param options - 可选的压缩参数。
 * @returns 压缩后的 Uint8Array。
 * @since 1.3.0
 * @example
 * ```ts
 * const result = await zip('/path/to/source');
 * if (result.isOk()) {
 *     console.log('压缩成功:', result.unwrap().length, 'bytes');
 * }
 * ```
 */
declare function zip(sourcePath: string, options?: ZipOptions): AsyncIOResult<Uint8Array<ArrayBuffer>>;
/**
 * 压缩文件或文件夹并保存到指定路径。
 * @param sourcePath - 需要压缩的文件（夹）路径。
 * @param zipFilePath - 压缩后的 zip 文件路径。
 * @param options - 可选的压缩参数。
 * @returns 压缩操作的异步结果。
 * @since 1.3.0
 * @example
 * ```ts
 * const result = await zip('/path/to/source', '/path/to/archive.zip');
 * if (result.isOk()) {
 *     console.log('压缩成功');
 * }
 * ```
 */
declare function zip(sourcePath: string, zipFilePath: string, options?: ZipOptions): AsyncVoidIOResult;
/**
 * 下载文件并压缩到内存。
 * @param sourceUrl - 要下载的文件 URL。
 * @param options - 合并的下载和压缩选项。
 * @returns 压缩后的 Uint8Array。
 * @since 1.4.0
 * @example
 * ```ts
 * const result = await zipFromUrl('https://example.com/file.txt');
 * if (result.isOk()) {
 *     console.log('下载并压缩成功');
 * }
 * ```
 */
declare function zipFromUrl(sourceUrl: string, options?: ZipFromUrlOptions): AsyncIOResult<Uint8Array<ArrayBuffer>>;
/**
 * 下载文件并压缩为 zip 文件。
 * @param sourceUrl - 要下载的文件 URL。
 * @param zipFilePath - 要输出的 zip 文件路径。
 * @param options - 合并的下载和压缩选项。
 * @returns 操作的异步结果。
 * @since 1.4.0
 * @example
 * ```ts
 * const result = await zipFromUrl('https://example.com/file.txt', '/path/to/archive.zip');
 * if (result.isOk()) {
 *     console.log('下载并压缩成功');
 * }
 * ```
 */
declare function zipFromUrl(sourceUrl: string, zipFilePath: string, options?: ZipFromUrlOptions): AsyncVoidIOResult;

/**
 * `mkdir` 的同步版本，递归创建文件夹。
 * @param dirPath - 将要创建的目录的路径。
 * @returns 创建成功返回的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = mkdirSync('/path/to/dir');
 * if (result.isOk()) {
 *     console.log('目录创建成功');
 * }
 * ```
 */
declare function mkdirSync(dirPath: string): VoidIOResult;
/**
 * `move` 的同步版本，移动或重命名文件或目录。
 * @param srcPath - 原始路径。
 * @param destPath - 新路径。
 * @returns 操作成功返回的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = moveSync('/old/path', '/new/path');
 * if (result.isOk()) {
 *     console.log('移动成功');
 * }
 * ```
 */
declare function moveSync(srcPath: string, destPath: string): VoidIOResult;
/**
 * `readDir` 的同步版本，读取指定目录下的所有文件和子目录。
 * @param dirPath - 需要读取的目录路径。
 * @returns 包含目录内容的字符串数组的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = readDirSync('/path/to/dir');
 * if (result.isOk()) {
 *     console.log(result.unwrap()); // ['file1.txt', 'file2.txt']
 * }
 * ```
 */
declare function readDirSync(dirPath: string): IOResult<string[]>;
/**
 * 以 UTF-8 格式读取文件。
 * @param filePath - 文件路径。
 * @param options - 读取选项，指定编码为 'utf8'。
 * @returns 包含文件内容的字符串的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = readFileSync('/path/to/file.txt', { encoding: 'utf8' });
 * if (result.isOk()) {
 *     console.log(result.unwrap());
 * }
 * ```
 */
declare function readFileSync(filePath: string, options: ReadOptions & {
    encoding: 'utf8';
}): IOResult<string>;
/**
 * 以二进制格式读取文件。
 * @param filePath - 文件路径。
 * @param options - 读取选项，指定编码为 'bytes'。
 * @returns 包含文件内容的 Uint8Array<ArrayBuffer> 的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = readFileSync('/path/to/file.txt', { encoding: 'bytes' });
 * if (result.isOk()) {
 *     const bytes = result.unwrap();
 *     console.log(decodeUtf8(bytes));
 * }
 * ```
 */
declare function readFileSync(filePath: string, options?: ReadOptions & {
    encoding: 'bytes';
}): IOResult<Uint8Array<ArrayBuffer>>;
/**
 * `readFile` 的同步版本，读取文件内容。
 * @param filePath - 文件的路径。
 * @param options - 可选的读取选项。
 * @returns 包含文件内容的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = readFileSync('/path/to/file.txt');
 * if (result.isOk()) {
 *     const bytes = result.unwrap();
 *     console.log(decodeUtf8(bytes));
 * }
 * ```
 */
declare function readFileSync(filePath: string, options?: ReadOptions): IOResult<ReadFileContent>;
/**
 * `remove` 的同步版本，删除文件或目录。
 * @param path - 要删除的文件或目录的路径。
 * @returns 删除成功返回的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = removeSync('/path/to/file.txt');
 * if (result.isOk()) {
 *     console.log('删除成功');
 * }
 * ```
 */
declare function removeSync(path: string): VoidIOResult;
/**
 * `stat` 的同步版本，获取文件或目录的状态信息。
 * @param path - 文件或目录的路径。
 * @returns 包含状态信息的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = statSync('/path/to/file.txt');
 * if (result.isOk()) {
 *     console.log(result.unwrap().isFile()); // true
 * }
 * ```
 */
declare function statSync(path: string, options?: StatOptions & {
    recursive: false;
}): IOResult<WechatMinigame.Stats>;
/**
 * `stat` 的同步版本，递归获取目录下所有文件和子目录的状态信息。
 * @param path - 目录的路径。
 * @param options - 选项，recursive 设置为 true 时递归获取。
 * @returns 包含目录下所有文件状态信息数组的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = statSync('/path/to/dir', { recursive: true });
 * if (result.isOk()) {
 *     result.unwrap().forEach(item => {
 *         console.log(item.path, item.stats.isDirectory());
 *     });
 * }
 * ```
 */
declare function statSync(path: string, options: StatOptions & {
    recursive: true;
}): IOResult<WechatMinigame.FileStats[]>;
/**
 * `stat` 的同步版本，获取文件或目录的状态信息。
 * @param path - 文件或目录的路径。
 * @param options - 可选选项，包含 recursive 可递归获取目录下所有文件状态。
 * @returns 包含状态信息的操作结果，根据 options.recursive 返回单个 Stats 或 FileStats 数组。
 * @since 1.1.0
 */
declare function statSync(path: string, options?: StatOptions): IOResult<WechatMinigame.Stats | WechatMinigame.FileStats[]>;
/**
 * `writeFile` 的同步版本，写入文件。
 * @param filePath - 文件路径。
 * @param contents - 要写入的内容。
 * @returns 写入成功返回的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = writeFileSync('/path/to/file.txt', 'Hello, World!');
 * if (result.isOk()) {
 *     console.log('写入成功');
 * }
 * ```
 */
declare function writeFileSync(filePath: string, contents: WriteFileContent): VoidIOResult;
/**
 * `appendFile` 的同步版本，向文件追加内容。
 * @param filePath - 文件路径。
 * @param contents - 要追加的内容。
 * @param options - 可选的追加选项。
 * @returns 追加成功返回的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = appendFileSync('/path/to/file.txt', '\nNew content');
 * if (result.isOk()) {
 *     console.log('追加成功');
 * }
 * ```
 */
declare function appendFileSync(filePath: string, contents: WriteFileContent, options?: AppendOptions): VoidIOResult;
/**
 * `copy` 的同步版本，复制文件或文件夹。
 * @param srcPath - 源文件或文件夹路径。
 * @param destPath - 目标文件或文件夹路径。
 * @returns 操作的结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = copySync('/src/file.txt', '/dest/file.txt');
 * if (result.isOk()) {
 *     console.log('复制成功');
 * }
 * ```
 */
declare function copySync(srcPath: string, destPath: string): VoidIOResult;
/**
 * `exists` 的同步版本，检查指定路径的文件或目录是否存在。
 * @param path - 文件或目录的路径。
 * @param options - 可选的检查选项。
 * @returns 存在返回 true 的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = existsSync('/path/to/file.txt');
 * if (result.isOk() && result.unwrap()) {
 *     console.log('文件存在');
 * }
 * ```
 */
declare function existsSync(path: string, options?: ExistsOptions): IOResult<boolean>;
/**
 * `emptyDir` 的同步版本，清空指定目录下的所有文件和子目录。
 * @param dirPath - 目录路径。
 * @returns 清空成功返回的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = emptyDirSync('/path/to/dir');
 * if (result.isOk()) {
 *     console.log('目录已清空');
 * }
 * ```
 */
declare function emptyDirSync(dirPath: string): VoidIOResult;
/**
 * `readJsonFile` 的同步版本，读取 JSON 文件并解析为对象。
 * @typeParam T - JSON 解析后的类型。
 * @param filePath - 文件路径。
 * @returns 解析后的对象。
 * @since 1.6.0
 * @example
 * ```ts
 * const result = readJsonFileSync<{ name: string }>('/path/to/config.json');
 * if (result.isOk()) {
 *     console.log(result.unwrap().name);
 * }
 * ```
 */
declare function readJsonFileSync<T>(filePath: string): IOResult<T>;
/**
 * `readTextFile` 的同步版本，读取文本文件的内容。
 * @param filePath - 文件路径。
 * @returns 包含文件文本内容的操作结果。
 * @since 1.1.0
 * @example
 * ```ts
 * const result = readTextFileSync('/path/to/file.txt');
 * if (result.isOk()) {
 *     console.log(result.unwrap());
 * }
 * ```
 */
declare function readTextFileSync(filePath: string): IOResult<string>;
/**
 * `writeJsonFile` 的同步版本，将数据序列化为 JSON 并写入文件。
 * @typeParam T - 要写入数据的类型。
 * @param filePath - 文件路径。
 * @param data - 要写入的数据。
 * @returns 写入操作的结果。
 * @since 2.0.0
 * @example
 * ```ts
 * const result = writeJsonFileSync('/path/to/config.json', { name: 'test' });
 * if (result.isOk()) {
 *     console.log('写入成功');
 * }
 * ```
 */
declare function writeJsonFileSync<T>(filePath: string, data: T): VoidIOResult;
/**
 * `unzip` 的同步版本，解压 zip 文件。
 * @param zipFilePath - 要解压的 zip 文件路径。
 * @param targetPath - 要解压到的目标文件夹路径。
 * @returns 解压操作的结果。
 * @since 1.3.0
 * @example
 * ```ts
 * const result = unzipSync('/path/to/archive.zip', '/path/to/output');
 * if (result.isOk()) {
 *     console.log('解压成功');
 * }
 * ```
 */
declare function unzipSync(zipFilePath: string, targetPath: string): VoidIOResult;
/**
 * 压缩文件或文件夹到内存。
 * @param sourcePath - 需要压缩的文件（夹）路径。
 * @param options - 可选的压缩参数。
 * @returns 压缩后的 Uint8Array。
 * @since 1.3.0
 * @example
 * ```ts
 * const result = zipSync('/path/to/source');
 * if (result.isOk()) {
 *     console.log('压缩成功:', result.unwrap().length, 'bytes');
 * }
 * ```
 */
declare function zipSync(sourcePath: string, options?: ZipOptions): IOResult<Uint8Array<ArrayBuffer>>;
/**
 * `zip` 的同步版本，压缩文件或文件夹。
 * @param sourcePath - 需要压缩的文件（夹）路径。
 * @param zipFilePath - 压缩后的 zip 文件路径。
 * @param options - 可选的压缩参数。
 * @returns 压缩操作的结果。
 * @since 1.3.0
 * @example
 * ```ts
 * const result = zipSync('/path/to/source', '/path/to/archive.zip');
 * if (result.isOk()) {
 *     console.log('压缩成功');
 * }
 * ```
 */
declare function zipSync(sourcePath: string, zipFilePath: string, options?: ZipOptions): VoidIOResult;

export { appendFile, appendFileSync, copy, copySync, downloadFile, emptyDir, emptyDirSync, exists, existsSync, mkdir, mkdirSync, move, moveSync, readDir, readDirSync, readFile, readFileSync, readJsonFile, readJsonFileSync, readTextFile, readTextFileSync, remove, removeSync, stat, statSync, unzip, unzipFromUrl, unzipSync, uploadFile, writeFile, writeFileSync, writeJsonFile, writeJsonFileSync, zip, zipFromUrl, zipSync };
export type { FileEncoding, ReadFileContent, ReadOptions, StatOptions, UnionDownloadFileOptions, UnionUploadFileOptions, WriteFileContent, ZipFromUrlOptions };