@filebox/core 1.0.10 → 1.0.12

package/README.md

@@ -1,599 +1,49 @@
-# @filebox/core - FileBox核心模块
+# @filebox/core
 
-[![npm version](https://img.shields.io/npm/v/@filebox/core.svg)](https://www.npmjs.com/package/@filebox/core)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-FileBox 是一个强大的虚拟文件系统抽象层,用于统一管理多个异构存储后端。它提供了一致的 API 来操作不同的存储服务(如云盘、本地存储、HTTP文件系统等),支持挂载、缓存、加密等高级特性。
-
-## 特性
-
-- 🔌 **多存储后端支持** - 通过插件系统支持各种存储服务
-- 🗂️ **虚拟文件系统** - 统一的文件系统抽象,像操作本地文件一样操作云盘
-- ⚡ **智能缓存** - 内置多种缓存策略(LRU、LFU等),支持依赖追踪
-- 🔐 **文件加密** - 支持文件名和内容加密
-- 🎯 **路径解析** - 强大的路径处理工具集
-- 📊 **文件元数据** - 完整的文件统计信息(Stat)
-- 🔄 **事件系统** - 支持生命周期钩子和自定义事件
-- 🚀 **高性能** - 支持直接模式和递归模式两种访问策略
-- 🌐 **跨平台** - 支持浏览器和 Node.js 环境
+FileBox 的虚拟文件系统核心包，用来把不同存储驱动挂载到统一的路径空间里，并通过同一套 API 读写文件。
 
 ## 安装
 
 ```bash
-npm install @filebox/core
-# 或
 pnpm add @filebox/core
-# 或
-yarn add @filebox/core
-```
-
-## 快速开始
-
-### 基础用法
-
-```typescript
-import { FileBox, FileSystem } from '@filebox/core'
-
-// 创建 FileBox 实例
-const fs = new FileBox({
-  events: {
-    beforeMount: (path, options) => console.log('挂载前:', path),
-    afterMount: (path, volume) => console.log('挂载后:', path),
-  },
-})
-
-// 挂载存储后端
-const volume = await fs.mount({
-  name: '/my-drive',
-  provider: 'custom-provider',
-  auth: {
-    token: 'your-token',
-  },
-  rootPath: '/',
-})
-
-// 列出文件
-const { data, total } = await fs.list('/my-drive')
-console.log('文件列表:', data)
-
-// 读取文件
-const content = await fs.readFile('/my-drive/file.txt')
-
-// 创建目录
-await fs.mkdir('/my-drive/new-folder')
-
-// 上传文件
-await fs.upload('/my-drive/new-folder', file)
-
-// 删除文件
-await fs.remove('/my-drive/file.txt')
-```
-
-### 使用缓存策略
-
-```typescript
-import { FileBox, Cache } from '@filebox/core'
-import { LRUStrategy } from '@filebox/core'
-
-// 创建带缓存的 FileBox 实例
-const fs = new FileBox({
-  cacheStrategy: new LRUStrategy({
-    maxSize: 1000,
-    ttl: 1000 * 60 * 30, // 30分钟
-  }),
-})
-
-// 挂载时指定 TTL
-const volume = await fs.mount({
-  name: '/cached-drive',
-  provider: 'custom-provider',
-  ttl: 1, // 启用缓存
-  auth: { token: 'token' },
-})
-```
-
-### 自定义文件系统驱动
-
-```typescript
-import { FileSystem } from '@filebox/core'
-
-class MyFileSystem extends FileSystem<YourDataType> {
-  constructor(config) {
-    super(config)
-  }
-
-  // 实现必需的抽象方法
-  getName(data: YourDataType): string {
-    return data.name
-  }
-
-  getId(data: YourDataType): string | number {
-    return data.id
-  }
-
-  getSize(data: YourDataType): number {
-    return data.size
-  }
-
-  getMTime(data: YourDataType): number {
-    return data.modifiedTime
-  }
-
-  getExt(data: YourDataType): string {
-    return data.extension
-  }
-
-  isFile(data: YourDataType): boolean {
-    return data.type === 'file'
-  }
-
-  getRecursiveKey(target: YourDataType): string | number {
-    return target.id
-  }
-
-  async fetchList(id: string | number): Promise<YourDataType[]> {
-    // 从远程 API 获取文件列表
-    const response = await fetch(`/api/files/${id}`)
-    return response.json()
-  }
-
-  // 可选:实现额外的方法
-  async mkdir(stat: Stat, name: string) {
-    // 实现创建目录逻辑
-  }
-
-  async remove(stat: Stat) {
-    // 实现删除逻辑
-  }
-
-  async upload(stat: Stat, file: any) {
-    // 实现上传逻辑
-  }
-}
-
-// 注册驱动
-FileBox.use({
-  name: 'my-provider',
-  package: MyFileSystem,
-})
-```
-
-## 核心概念
-
-### 1. FileBox - 虚拟文件系统
-
-FileBox 是主要的文件系统管理器,负责:
-
-- 挂载和管理多个存储卷(Volume)
-- 路由文件操作到正确的存储后端
-- 提供统一的文件操作 API
-- 触发生命周期事件
-
-### 2. Volume - 存储卷
-
-Volume 代表一个挂载的存储后端,分为两种类型:
-
-- **`Volume`** - 可读写的存储卷
-- **`ReadOnlyVolume`** - 只读的存储卷
-
-每个 Volume 都有自己的:
-
-- 挂载路径(mountPath)
-- 根路径(rootPath)
-- 文件系统实例(FileSystem)
-
-### 3. FileSystem - 文件系统抽象
-
-FileSystem 是存储后端的抽象基类,提供:
-
-- **两种访问模式**:
-  - `Mode.indirect` - 递归模式,通过父子关系遍历(默认)
-  - `Mode.direct` - 直接模式,直接通过路径访问
-- **缓存支持** - 自动缓存文件列表
-- **格式化** - 将原始数据转换为统一的 Stat 对象
-
-### 4. Stat - 文件元数据
-
-Stat 表示文件或目录的元数据:
-
-```typescript
-interface IStat {
-  id: string | number // 文件 ID
-  name: string // 文件名
-  size: any // 格式化的大小(如 "1.5 MB")
-  byte: number | null // 字节大小
-  thumbnail: string | null // 缩略图 URL
-  atime?: string | null // 访问时间
-  ctime?: string | null // 创建时间
-  mtime: string | null // 修改时间
-  type: string | null // 文件类型/扩展名
-  hash?: {
-    // 文件哈希
-    md5?: string
-    sha1?: string
-    sha256?: string
-  }
-}
-```
-
-### 5. Cache - 缓存系统
-
-FileBox 提供了强大的缓存系统:
-
-**缓存策略**:
-
-- `LRUStrategy` - 最近最少使用
-- `LFUStrategy` - 最不经常使用
-- `FIFOStrategy` - 先进先出
-- `TTLStrategy` - 基于时间的过期
-
-**依赖追踪**:
-缓存系统会自动追踪文件之间的依赖关系,当某个文件变更时,会自动失效相关的缓存。
-
-```typescript
-// 文件操作会自动更新缓存
-await fs.mkdir('/my-drive/folder') // 自动失效父目录缓存
-await fs.remove('/my-drive/file') // 自动失效父目录和文件缓存
-await fs.rename('/my-drive/old', 'new') // 自动更新缓存
 ```
 
-### 6. Path - 路径工具
-
-提供了完整的路径处理工具集:
-
-```typescript
-import { path } from '@filebox/core'
-
-// 基础操作
-path.join('/foo', 'bar', 'baz') // => '/foo/bar/baz'
-path.normalize('/foo//bar/../baz') // => '/foo/baz'
-path.basename('/foo/bar.txt') // => 'bar.txt'
-path.dirname('/foo/bar.txt') // => '/foo'
-path.extname('/foo/bar.txt') // => '.txt'
-
-// 高级操作
-path.split('/drive/foo/bar') // => ['drive', '/foo/bar']
-path.reverseSplist('/foo/bar/baz') // => ['/foo/bar', 'baz']
-path.toArray('/foo/bar/baz') // => ['foo', 'bar', 'baz']
-```
+## 使用
 
-### 7. Plugin - 插件系统
+```ts
+import FileBox from "@filebox/core";
+import WebDAVDriver from "./drivers/webdav";
 
-插件系统用于注册和管理文件系统驱动:
-
-```typescript
-// 注册插件
 FileBox.use({
-  name: 'my-driver',
-  package: MyFileSystem,
-  install() {
-    console.log('插件已安装')
-  },
-  uninstall() {
-    console.log('插件已卸载')
-  },
-})
-
-// 获取插件
-const driver = Plugin.get('my-driver')
-
-// 列出所有插件
-const drivers = Plugin.list()
-
-// 卸载插件
-Plugin.uninstall('my-driver')
-```
-
-## API 文档
-
-### FileBox 类
+  name: "webdav",
+  package: WebDAVDriver,
+});
 
-#### 构造函数
+const filebox = new FileBox();
 
-```typescript
-new FileBox(options?: {
-  events?: Record<string, EventCallback | EventCallback[]>
-  plugins?: Array<any>
-  cacheStrategy?: ICacheStrategy
-})
-```
-
-#### 静态方法
-
-- **`use(module: any): typeof FileBox`** - 注册插件
-
-#### 实例方法
-
-##### 挂载和卸载
-
-- **`mount(options: MountOptions): Promise<Volume>`** - 挂载存储后端
-- **`mountRaw(options: MountOptions): void`** - 挂载只读存储
-- **`unmount(volume: Volume): Promise<void>`** - 卸载存储卷
-- **`getVolume(name?: string): Volume | Map<string, Volume>`** - 获取存储卷
-
-##### 文件操作
-
-- **`stat(path: string): Promise<Stat>`** - 获取文件信息
-- **`list(path: string, options?): Promise<{data: Stat[], total: number}>`** - 列出目录内容
-- **`readFile(path: string): Promise<any>`** - 读取文件内容
-- **`mkdir(path: string, options?): Promise<Stat>`** - 创建目录
-- **`rename(path: string, newName: string): Promise<Stat>`** - 重命名
-- **`remove(path: string): Promise<any>`** - 删除文件/目录
-- **`upload(path: string, file: any, progress?): Promise<Stat>`** - 上传文件
-- **`download(path: string, options?): Promise<string[]>`** - 获取下载链接
-- **`copy(src: string, dest: string, options?): Promise<any>`** - 复制文件
-- **`move(src: string, dest: string, options?): Promise<any>`** - 移动文件
-- **`bulkRemove(options: {paths: string[]}): Promise<any[]>`** - 批量删除
-
-##### 缓存管理
-
-- **`setCache(strategy: ICacheStrategy): void`** - 设置全局缓存策略
-- **`getCache(): ICacheStrategy | undefined`** - 获取缓存策略
-
-### FileSystem 类
-
-#### 必须实现的抽象方法
-
-```typescript
-abstract getName(data: T): string
-abstract getId(data: T): string | number
-abstract getSize(data: T): string | number | null
-abstract getMTime(data: T): string | number
-abstract getExt(data: T): string
-abstract isFile(data: T): boolean
-abstract getRecursiveKey(target: T): string | number
-abstract fetchList(keyOrPath: string | number, options?): Promise<any>
-```
-
-#### 可选实现的方法
-
-```typescript
-getThumbnail?(data: T): string
-getATime?(data: T): string | number | null
-getCTime?(data: T): string | number
-getHash?(data: T): any
-getQuota?(data: T): any
-isEmpty?(data: T): boolean
-
-mkdir?(stat: Stat, name: string): Promise<any>
-remove?(stat: Stat): Promise<any>
-rename?(stat: Stat, name: string): Promise<any>
-copy?(source: Stat, target: Stat): Promise<any>
-move?(source: Stat, target: Stat): Promise<any>
-upload?(stat: Stat, file: any): Promise<any>
-rapidupload?(stat: Stat, file: any): Promise<any>
-share?(stat: Stat, obj: any): Promise<any>
-save?(stat: Stat, obj: any): Promise<any>
-link?(stat: Stat): Promise<any>
-```
-
-### Volume 类
-
-#### 只读方法
-
-- **`stat(path: string | Stat): Promise<Stat>`** - 获取文件信息
-- **`list(path: string | Stat, options?): Promise<{data: Stat[], total: number}>`** - 列出目录
-- **`readFile(path: string): Promise<any>`** - 读取文件
-- **`hasMethod(method: string): boolean`** - 检查是否支持某个方法
-- **`refresh(path: string): Promise<void>`** - 刷新缓存
-
-#### 读写方法(仅 Volume)
-
-- **`mkdir(path: string | Stat, options?): Promise<Stat>`** - 创建目录
-- **`rename(path: string, newName: string): Promise<Stat>`** - 重命名
-- **`remove(path: string, options?): Promise<any>`** - 删除
-- **`upload(path: string, file: any, progress?): Promise<Stat>`** - 上传
-- **`download(path: string, options?): Promise<string[]>`** - 下载
-- **`copy(src: string, dest: string, options?): Promise<any>`** - 复制
-- **`move(src: string, dest: string, options?): Promise<any>`** - 移动
-- **`bulkRemove(paths: string[], options?): Promise<any[]>`** - 批量删除
-- **`bulkCopy(src: string[], dest: string, options?): Promise<any[]>`** - 批量复制
-- **`share(options, path?): Promise<any>`** - 分享文件
-- **`save(option, dest?): Promise<any>`** - 保存文件
-- **`search(data: any): Promise<Stat[]>`** - 搜索文件
-
-## 事件系统
-
-FileBox 支持以下生命周期事件:
-
-```typescript
-const fs = new FileBox({
-  events: {
-    // 挂载事件
-    beforeMount: (path, options) => {},
-    afterMount: (path, volume) => {},
-
-    // 文件操作事件
-    beforeList: (path, options) => {},
-    afterList: (path, result) => {},
-    beforeStat: (path) => {},
-    afterStat: (path, stat) => {},
-    beforeReadFile: (path) => {},
-    afterReadFile: (path, content) => {},
-    beforeMkdir: (path, options) => {},
-    afterMkdir: (path, result) => {},
-    beforeRename: (path, newName) => {},
-    afterRename: (path, newName, result) => {},
-    beforeRemove: (path) => {},
-    afterRemove: (path, result) => {},
-    beforeUpload: (path, file) => {},
-    afterUpload: (path, result) => {},
-    beforeDownload: (path, options) => {},
-    afterDownload: (path, result) => {},
-    beforeCopy: (src, dest, options) => {},
-    afterCopy: (src, dest, result) => {},
-    beforeMove: (src, dest, options) => {},
-    afterMove: (src, dest, result) => {},
-    beforeBulkRemove: (paths, options) => {},
-    afterBulkRemove: (paths, result) => {},
-
-    // 认证事件
-    authChange: (path, options) => {},
-  },
-})
-```
-
-## 过滤和分页
-
-### 文件过滤
-
-```typescript
-const { data, total, filter } = await fs.list('/my-drive', {
-  filter: {
-    name: '.*\\.txt$', // 正则表达式匹配文件名
-    size: '${size} > 1024', // 文件大小条件
-    type: 'txt,md', // 文件类型
-    mode: 'strict', // 匹配模式: 'normal' 或 'strict'
-  },
-})
-```
-
-### 分页和排序
-
-```typescript
-const result = await fs.list('/my-drive', {
-  pagination: {
-    page: 1,
-    pageSize: 20,
-  },
-  sort: {
-    field: 'name',
-    order: 'asc',
+await filebox.mount({
+  name: "/dav",
+  provider: "webdav",
+  rootPath: "/",
+  auth: {
+    url: "https://example.com/dav/",
+    username: "user",
+    password: "password",
   },
-})
-```
-
-## 加密支持
-
-FileBox 提供了文件加密功能:
-
-```typescript
-import { crypt } from '@filebox/core'
-
-// 加密文件名
-const encrypted = crypt.encryptName('secret.txt', 'password')
-
-// 解密文件名
-const decrypted = crypt.decryptName(encrypted, 'password')
-
-// 文件内容加密/解密
-// 详见 src/crypt 模块
-```
-
-## 类型定义
-
-```typescript
-// 挂载选项
-interface MountOptions {
-  name: string // 挂载路径
-  provider: string // 驱动名称
-  auth?: any // 认证信息
-  rootPath?: string // 根路径
-  ttl?: number // 缓存时间(秒)
-  readOnly?: boolean // 是否只读
-  userConfig?: any // 用户配置
-}
-
-// 列表选项
-interface ListOptions {
-  pagination?: {
-    page: number
-    pageSize: number
-  }
-  sort?: {
-    field: string
-    order: 'asc' | 'desc'
-  }
-  filter?: {
-    name?: string
-    size?: string
-    type?: string
-    mode?: 'normal' | 'strict'
-  }
-}
-```
-
-## 构建格式
-
-该包提供三种构建格式:
-
-- **ESM** (`dist/index.mjs`) - ES Modules
-- **CJS** (`dist/index.cjs`) - CommonJS
-- **UMD** (`dist/index.browser.js`) - 浏览器 Universal Module Definition
-
-## 依赖
-
-- `bytes` - 字节格式化
-- `dayjs` - 日期处理
-- `debug` - 调试日志
-- `lru-cache` - LRU 缓存
-- `mime-types` - MIME 类型处理
-- `mitt` - 事件总线
-- `pako` - 压缩/解压
-- `path-browserify` - 浏览器路径处理
-
-## 开发
+});
 
-```bash
-# 安装依赖
-pnpm install
-
-# 构建
-pnpm run build
-
-# 监听模式
-pnpm run watch
-
-# 测试
-pnpm test
+const list = await filebox.list("/dav");
+const stat = await filebox.stat("/dav/readme.txt");
 ```
 
-## 发布
-
-该包使用语义化版本控制。发布前会自动构建 dist 目录。
-
-```bash
-# 发布补丁版本 (1.0.0 -> 1.0.1)
-npm run publish:patch
-
-# 发布次版本 (1.0.0 -> 1.1.0)
-npm run publish:minor
-
-# 发布主版本 (1.0.0 -> 2.0.0)
-npm run publish:major
-```
-
-**注意事项:**
-
-- 只有 `dist` 目录和 `LICENSE` 会被发布到 npm,README.md 和源码不会被包含
-- 发布前会自动执行 `prepublishOnly` 钩子进行构建
-- 确保已登录 npm: `npm login`
-- 确保有发布权限: `npm whoami`
-- **作为 scoped package (@filebox/core),发布命令已自动添加 `--access public` 参数发布为公开包**
-- **需要启用双因素认证(2FA)** 或使用带有 bypass 2fa 权限的 access token
-
-  ```bash
-  # 启用 2FA
-  npm profile enable-2fa auth-and-writes
-
-  # 或使用 automation token (推荐用于 CI/CD)
-  npm token create --type=automation
-  ```
-
-## 许可证
-
-MIT License - 详见 [LICENSE](./LICENSE) 文件
-
-## 相关包
-
-- `@filebox/drivers` - 官方驱动集合
-- `@filebox/backend` - FileBox 后端服务
-- `@filebox/ui` - 文件管理器 UI 组件
-
-## 贡献
+常用 API：
 
-欢迎提交 Issue 和 Pull Request!
+- `mount(options)`：挂载一个驱动到指定路径。
+- `unmount(path)`：卸载已挂载的路径。
+- `list(path)`：读取目录。
+- `stat(path)`：读取文件或目录信息。
+- `mkdir(path, name)`、`upload(path, file)`、`remove(path)`、`rename(path, name)`：常见文件操作。
 
-## 作者
+## License
 
-ppnow <ppnows@gmail.com>
+MIT