@filebox/core 1.0.10

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 FileBox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,599 @@
+# @filebox/core - FileBox核心模块
+
+[![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 环境
+
+## 安装
+
+```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 - 插件系统
+
+插件系统用于注册和管理文件系统驱动:
+
+```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 类
+
+#### 构造函数
+
+```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',
+  },
+})
+```
+
+## 加密支持
+
+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
+```
+
+## 发布
+
+该包使用语义化版本控制。发布前会自动构建 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 组件
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request!
+
+## 作者
+
+ppnow <ppnows@gmail.com>