zen-fs-webdav 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 zen-fs-webdav
+
+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,261 @@
+# zen-fs-webdav
+
+一个简单、现代的 WebDAV 客户端库，提供类似文件系统的 API。
+
+## 特性
+
+- 🚀 简单易用的 API，类似于 Node.js 的 fs 模块
+- 🔄 支持所有基本的 WebDAV 操作（读取、写入、复制、移动等）
+- 🔒 支持基本认证和令牌认证
+- 📁 支持目录操作和递归操作
+- 💪 完全使用 TypeScript 编写，提供完整的类型定义
+- 🌐 同时支持浏览器和 Node.js 环境
+
+## 安装
+
+```bash
+npm install zen-fs-webdav
+```
+
+或者使用 yarn：
+
+```bash
+yarn add zen-fs-webdav
+```
+
+## 快速开始
+
+```typescript
+import { WebDAVFileSystem } from 'zen-fs-webdav';
+
+// 创建 WebDAV 客户端实例
+const fs = createWebDAVFileSystem({
+  baseUrl: 'https://example.com/webdav',
+  username: 'user',
+  password: 'pass',
+});
+
+// 读取文件
+const content = await fs.readFile('/path/to/file.txt');
+console.log(content);
+
+// 写入文件
+await fs.writeFile('/path/to/newfile.txt', 'Hello, WebDAV!');
+
+// 列出目录内容
+const files = await fs.readdir('/path/to/directory');
+console.log(files);
+```
+
+## API 参考
+
+### 创建实例
+
+```typescript
+const fs = new WebDAVFileSystem(options);
+```
+
+#### 选项
+
+- `baseUrl`: WebDAV 服务器的基础 URL
+- `username`: 用户名（可选，用于基本认证）
+- `password`: 密码（可选，用于基本认证）
+- `token`: 认证令牌（可选，用于令牌认证）
+- `headers`: 自定义请求头（可选）
+- `fetch`: 自定义 fetch 函数（可选）
+
+### 文件操作
+
+#### 检查文件是否存在
+
+```typescript
+const exists = await fs.exists('/path/to/file.txt');
+```
+
+#### 读取文件
+
+```typescript
+// 读取为文本
+const text = await fs.readFile('/path/to/file.txt');
+
+// 读取为二进制数据
+const binary = await fs.readFile('/path/to/file.bin', { responseType: 'arraybuffer' });
+```
+
+#### 写入文件
+
+```typescript
+// 写入文本
+await fs.writeFile('/path/to/file.txt', 'Hello, WebDAV!');
+
+// 写入二进制数据
+const buffer = new ArrayBuffer(10);
+await fs.writeFile('/path/to/file.bin', buffer);
+
+// 指定内容类型
+await fs.writeFile('/path/to/file.json', '{"key": "value"}', { contentType: 'application/json' });
+```
+
+#### 删除文件
+
+```typescript
+await fs.unlink('/path/to/file.txt');
+```
+
+#### 获取文件信息
+
+```typescript
+const stats = await fs.stat('/path/to/file.txt');
+console.log(stats.size);
+console.log(stats.lastModified);
+console.log(stats.isDirectory);
+```
+
+### 目录操作
+
+#### 创建目录
+
+```typescript
+// 创建单个目录
+await fs.mkdir('/path/to/directory');
+
+// 递归创建目录
+await fs.mkdir('/path/to/nested/directory', { recursive: true });
+```
+
+#### 列出目录内容
+
+```typescript
+// 列出顶层内容
+const files = await fs.readdir('/path/to/directory');
+
+// 递归列出所有内容
+const allFiles = await fs.readdir('/path/to/directory', { depth: 'infinity' });
+```
+
+#### 删除目录
+
+```typescript
+// 删除空目录
+await fs.rmdir('/path/to/directory');
+
+// 递归删除目录及其内容
+await fs.rmdir('/path/to/directory', { recursive: true });
+```
+
+### 复制和移动
+
+#### 复制文件或目录
+
+```typescript
+// 复制文件
+await fs.copy('/source/file.txt', '/destination/file.txt');
+
+// 复制目录
+await fs.copy('/source/directory', '/destination/directory', { recursive: true });
+```
+
+#### 移动文件或目录
+
+```typescript
+await fs.move('/source/file.txt', '/destination/file.txt');
+```
+
+#### 重命名文件或目录
+
+```typescript
+await fs.rename('/path/to/oldname.txt', 'newname.txt');
+```
+
+### 流操作
+
+#### 创建可读流
+
+```typescript
+const readStream = await fs.createReadStream('/path/to/file.txt');
+// 使用流...
+```
+
+#### 创建可写流
+
+```typescript
+const writeStream = fs.createWriteStream('/path/to/file.txt');
+// 使用流...
+writeStream.write('Hello');
+writeStream.write(' WebDAV!');
+await writeStream.close();
+```
+
+## 错误处理
+
+所有方法在失败时都会抛出 `WebDAVError` 异常：
+
+```typescript
+try {
+  await fs.readFile('/path/to/nonexistent.txt');
+} catch (error) {
+  if (error.name === 'WebDAVError') {
+    console.error(`WebDAV 错误: ${error.message}, 状态码: ${error.status}`);
+  } else {
+    console.error(`其他错误: ${error}`);
+  }
+}
+```
+
+## 浏览器兼容性
+
+该库使用现代 Web API，如 `fetch` 和 `ReadableStream`/`WritableStream`。确保你的目标浏览器支持这些 API，或者使用适当的 polyfill。
+
+## 项目结构
+
+```
+├── .eslintrc.js - ESLint 配置文件
+├── .eslintrc.json - ESLint 配置文件
+├── .gitignore - Git 忽略规则
+├── .npmignore - NPM 发布忽略规则
+├── .prettierrc - Prettier 配置
+├── .prettierrc.js - Prettier 配置文件
+├── CHANGELOG.md - 变更日志
+├── CONTRIBUTING.md - 贡献指南
+├── coverage/ - 测试覆盖率报告
+├── docs/ - 文档
+│   └── api.md - API 文档
+├── examples/ - 示例代码
+│   ├── basic-usage.js - 基础使用示例(JS)
+│   ├── basic-usage.ts - 基础使用示例(TS)
+│   ├── browser-example.html - 浏览器示例
+│   ├── browser-usage.ts - 浏览器使用示例
+│   ├── node-example.js - Node.js 示例
+│   ├── node-usage.ts - Node.js 使用示例
+├── jest.config.js - Jest 配置
+├── jest.setup.js - Jest 设置
+├── LICENSE - 许可证文件
+├── package.json - 项目配置
+├── package-lock.json - 依赖锁定文件
+├── prompt.md - 提示文档
+├── README.md - 项目说明文档
+├── rollup.config.js - Rollup 配置
+├── src/ - 源代码目录
+│   ├── constants.ts - 常量定义
+│   ├── errors.ts - 错误处理
+│   ├── index.ts - 主入口文件
+│   ├── types.ts - 类型定义
+│   ├── ui/ - UI 相关代码
+│   ├── utils.ts - 工具函数
+│   ├── webdav-fs.ts - WebDAV 文件系统实现
+│   ├── webdav.ts - WebDAV 核心功能
+│   ├── WebDAVFileSystem.ts - WebDAV 文件系统类
+│   └── __tests__/ - 测试代码
+│       ├── errors.test.ts - 错误测试
+│       ├── integration.test.ts - 集成测试
+│       ├── utils.test.ts - 工具函数测试
+│       ├── webdav-fs.test.ts - 文件系统测试
+│       └── WebDAVFileSystem.test.ts - 文件系统类测试
+├── tsconfig.json - TypeScript 配置
+├── tsup.config.ts - Tsup 构建配置
+└── yarn.lock - Yarn 依赖锁定文件
+```
+
+## 许可证
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,278 @@
+/**
+ * WebDAV 文件系统配置选项
+ */
+interface WebDAVOptions {
+    /**
+     * WebDAV 服务器的基础 URL
+     */
+    baseUrl: string;
+    /**
+     * 认证用户名（可选）
+     */
+    username?: string;
+    /**
+     * 认证密码（可选）
+     */
+    password?: string;
+    /**
+     * 认证令牌（可选，如果提供则优先使用）
+     */
+    token?: string;
+    /**
+     * 自定义请求头（可选）
+     */
+    headers?: Record<string, string>;
+    /**
+     * 请求超时时间，单位毫秒（可选，默认 30000）
+     */
+    timeout?: number;
+}
+/**
+ * WebDAV 请求选项
+ */
+interface WebDAVRequestOptions {
+    /**
+     * 请求方法
+     */
+    method: string;
+    /**
+     * 请求头
+     */
+    headers?: Record<string, string>;
+    /**
+     * 请求体
+     */
+    body?: string | ArrayBuffer | null;
+    /**
+     * 请求超时时间，单位毫秒
+     */
+    timeout?: number;
+}
+/**
+ * 文件或目录条目
+ */
+interface FileEntry {
+    /**
+     * 文件或目录名称
+     */
+    name: string;
+    /**
+     * 是否为目录
+     */
+    isDirectory: boolean;
+    /**
+     * 文件大小（字节）
+     */
+    size?: number;
+    /**
+     * 最后修改时间
+     */
+    lastModified?: Date;
+    /**
+     * 创建时间
+     */
+    createdAt?: Date;
+    /**
+     * 文件或目录的完整路径
+     */
+    path: string;
+}
+/**
+ * 文件或目录统计信息
+ */
+interface Stats {
+    /**
+     * 是否为目录
+     */
+    isDirectory: boolean;
+    /**
+     * 是否为文件
+     */
+    isFile: boolean;
+    /**
+     * 文件大小（字节）
+     */
+    size: number;
+    /**
+     * 最后修改时间
+     */
+    lastModified?: Date;
+    /**
+     * 创建时间
+     */
+    createdAt?: Date;
+    /**
+     * 文件或目录名称
+     */
+    name: string;
+    /**
+     * 文件或目录的完整路径
+     */
+    path: string;
+    /**
+     * 文件的 MIME 类型
+     */
+    mimeType?: string;
+    /**
+     * 文件的 ETag
+     */
+    etag?: string;
+}
+/**
+ * 读取文件选项
+ */
+interface ReadFileOptions {
+    /**
+     * 响应类型
+     */
+    responseType?: 'text' | 'arraybuffer';
+    /**
+     * 编码（仅当 responseType 为 'text' 时有效）
+     */
+    encoding?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * 写入文件选项
+ */
+interface WriteFileOptions {
+    /**
+     * 是否覆盖现有文件
+     */
+    overwrite?: boolean;
+    /**
+     * 文件的 MIME 类型
+     */
+    contentType?: string;
+}
+/**
+ * 创建目录选项
+ */
+interface MkdirOptions {
+    /**
+     * 是否递归创建目录
+     */
+    recursive?: boolean;
+}
+/**
+ * 删除目录选项
+ */
+interface RmdirOptions {
+    /**
+     * 是否递归删除目录及其内容
+     */
+    recursive?: boolean;
+}
+/**
+ * 读取目录选项
+ */
+interface ReaddirOptions {
+    /**
+     * 是否包含详细信息
+     */
+    withFileTypes?: boolean;
+    /**
+     * 深度，1 表示只列出当前目录，大于 1 表示递归列出子目录
+     */
+    depth?: number;
+    includeHidden?: boolean;
+    headers?: Record<string, string>;
+    recursive?: boolean;
+}
+/**
+ * 复制选项
+ */
+interface CopyOptions {
+    /**
+     * 是否覆盖目标位置的现有文件
+     */
+    overwrite?: boolean;
+    /**
+     * 是否递归复制目录
+     */
+    recursive?: boolean;
+}
+/**
+ * 移动选项
+ */
+interface MoveOptions {
+    /**
+     * 是否覆盖目标位置的现有文件
+     */
+    overwrite?: boolean;
+}
+/**
+ * WebDAV操作结果
+ */
+interface WebDAVResult {
+    /**
+     * 操作是否成功
+     */
+    success: boolean;
+    /**
+     * HTTP状态码
+     */
+    statusCode: number;
+    /**
+     * 操作结果消息（可选）
+     */
+    message?: string;
+    /**
+     * 操作返回的数据（可选）
+     */
+    data?: unknown;
+}
+
+interface WebDAVFileSystem {
+    readFile(path: string, options?: ReadFileOptions): Promise<Buffer | string>;
+    writeFile(path: string, data: Buffer | string, options?: WriteFileOptions): Promise<WebDAVResult>;
+    deleteFile(path: string): Promise<WebDAVResult>;
+    readDir(path: string, options?: ReaddirOptions): Promise<Stats[]>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    rmdir(path: string, options?: boolean | {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    stat(path: string): Promise<Stats>;
+    exists(path: string): Promise<boolean>;
+    copy(source: string, destination: string, overwrite?: boolean): Promise<WebDAVResult>;
+    move(source: string, destination: string, overwrite?: boolean): Promise<WebDAVResult>;
+    unlink(path: string): Promise<void>;
+}
+
+/**
+ * 创建 WebDAV 文件系统实例（工厂函数）
+ * @param options WebDAV 配置选项
+ * @returns WebDAVFileSystem 实例
+ */
+declare function createWebDAVFileSystem(options: WebDAVOptions): WebDAVFileSystem;
+
+/**
+ * WebDAV文件系统库的错误类型定义
+ */
+/**
+ * WebDAV错误基类
+ */
+declare class WebDAVError extends Error {
+    /**
+     * HTTP状态码
+     */
+    status?: number;
+    /**
+     * 原始错误对象（如果有）
+     */
+    cause?: unknown;
+    constructor(message: string, status?: number, cause?: unknown);
+    toString(): string;
+    static fromResponse(response: {
+        status: number;
+        statusText: string;
+    }, message?: string): WebDAVError;
+    static fromError(error: unknown): WebDAVError;
+}
+
+export { type CopyOptions, type FileEntry, type MkdirOptions, type MoveOptions, type ReadFileOptions, type ReaddirOptions, type RmdirOptions, type Stats, WebDAVError, type WebDAVFileSystem, type WebDAVOptions, type WebDAVRequestOptions, type WriteFileOptions, createWebDAVFileSystem };