yann-fs/README.md

Enhanced fs-extra with better error handling

# yann-fs

一个增强版的 fs-extra 工具库，提供更优雅的错误处理方式和完整的 TypeScript 类型支持。

## 特性

- 完整封装 fs-extra 的异步方法
- 统一的错误处理返回格式 `[error, data]`
- 支持全局错误处理配置
- 完整的 TypeScript 类型支持
- 同时支持 ESM 和 CommonJS
- 支持 Promise 和 async/await

## 安装

```bash
npm i yann-fs -S
```

## 快速上手

### mjs 模式

```js
import fs, { remove } from 'yann-fs';

const [err, data] = await fs.remove(path);
// or
const [err, data] = await remove(path);
```

### cjs 模式

```js
const fs = require('yann-fs);

const [err, data] = await fs.remove(path);
```

## API 文档

### 错误处理
- `fsConfig`: 全局错误处理配置对象
  - `errHandler`: 设置全局错误处理函数
- `fsTo<T>`: 统一的错误处理包装函数，将 [error, data] 转换为单一返回值

### 文件操作
- `copy(src: string, dest: string, options?: CopyOptions)`: 复制文件或目录
- `move(src: string, dest: string, options?: MoveOptions)`: 移动文件或目录
- `remove(path: string)`: 删除文��或目录
- `emptyDir(path: string)`: 清空目录但保留目录本身
- `ensureFile(path: string)`: 确保文件存在，如果不存在则创建
- `createFile(file: string)`: 创建新文件
- `readFile(path: string, options?: ReadOptions)`: 读取文件内容
- `writeFile(file: string, data: any, options?: WriteFileOptions)`: 写入文件内容
- `appendFile(path: string, data: any, options?: WriteFileOptions)`: 追加内容到文件
- `truncate(path: PathLike, len?: number)`: 截断文件到指定长度
- `unlink(path: PathLike)`: 删除文件链接

### JSON 操作
- `readJson<T>(path: string, options?: ReadOptions)`: 读取 JSON 文件
- `writeJson(file: string, data: any, options?: WriteOptions)`: 写入 JSON 文件
- `outputJson(file: string, data: any, options?: WriteOptions)`: 写入 JSON 文件，自动创建目录

### 目录操作
- `ensureDir(path: string, options?: EnsureOptions)`: 确保目录存在，如果不存在则创建
- `mkdir(dir: string, options?: EnsureOptions)`: 创建目录
- `mkdirs(dir: string, options?: EnsureOptions)`: 递归创建目录
- `mkdtemp(prefix: string, options?: ObjectEncodingOptions)`: 创建临时目录
- `readdir(path: string, options?)`: 读取目录内容
- `rmdir(path: string)`: 删除目录

### 链接操作
- `ensureLink(src: string, dest: string)`: 确保硬链接存��，如果不存在则创建
- `ensureSymlink(src: string, dest: string)`: 确保符号链接存在，如果不存在则创建
- `createLink(src: string, dest: string)`: 创建硬链接
- `createSymlink(src: string, dest: string)`: 创建符号链接

### 文件信息
- `stat(path: PathLike)`: 获取文件状态信息
- `lstat(path: PathLike)`: 获取文件状态信息（不解析符号链接）
- `pathExists(path: string)`: 检查路径是否存在
- `isDir(path: PathLike, errHandler?)`: 检查路径是否为目录
- `exists(path: string)`: 检查文件是否存在（不推荐使用）

### 权限操作
- `chmod(path: PathLike, mode: Mode)`: 修改文件权限
- `chown(path: PathLike, uid: number, gid: number)`: 修改文件所有者
- `access(path: PathLike, mode?: number)`: 检查文件访问权限

### 时间戳操作
- `utimes(path: PathLike, atime: string | number | Date, mtime: string | number | Date)`: 修改文件访问和修改时间

### 文件监听
- `watch`: 监听文件或目录变化