luoyu-oss-unified 0.0.1

package/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}

package/README.md

@@ -0,0 +1,496 @@
+# luoyu-oss-unified - 统一对象存储客户端
+
+一个统一的多平台对象存储客户端，支持 MinIO、阿里云、腾讯云、七牛云等多种对象存储服务。
+
+## 特性
+
+- 🚀 统一的 API 接口，支持多种对象存储服务
+- 📦 轻量级设计，易于集成
+- 🔧 支持上传、下载、删除、列表、目录操作等功能
+- 🔄 支持分片上传和断点续传
+- 🛡️ TypeScript 支持，类型安全
+- ⚡ 事件监听机制，支持进度监控和错误处理
+
+## 安装
+
+```bash
+npm install luoyu-oss-unified
+```
+
+## 快速开始
+
+### 基本使用
+
+```typescript
+import { OSSClient, OSSProvider } from 'luoyu-oss-unified';
+
+// MinIO 配置
+const minioConfig = {
+  provider: OSSProvider.MINIO,
+  endpoint: 'http://your-minio-server.com',
+  accessKeyId: 'your-access-key',
+  accessKeySecret: 'your-secret-key',
+  bucket: 'your-bucket',
+  region: 'us-east-1'
+};
+
+// 创建客户端
+const ossClient = new OSSClient(minioConfig);
+
+// 上传文件
+await ossClient.upload({
+  path: 'images/photo.jpg',
+  file: fs.readFileSync('./photo.jpg'),
+  contentType: 'image/jpeg'
+});
+```
+
+### 七牛云配置示例
+
+```typescript
+const qiniuConfig = {
+  provider: OSSProvider.QINIU,
+  accessKeyId: 'your-access-key',
+  accessKeySecret: 'your-secret-key',
+  bucket: 'your-bucket',
+  region: 'z0', // z0: 华东, z1: 华北, z2: 华南, na0: 北美, as0: 新加坡
+  domain: 'your-domain.qiniudn.com'
+};
+```
+
+## API 文档
+
+### OSSClient
+
+#### 构造函数
+
+```typescript
+new OSSClient(config: OSSConfig)
+```
+
+**参数：**
+
+- `config` - 配置对象
+
+**配置选项：**
+
+- [provider](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L3-L3) - 存储提供商 ([MINIO](file://e:\project\code\npm\ts-project\src\packages\types\enums.ts#L4-L4), `ALIBABA`, [TENCENT](file://e:\project\code\npm\ts-project\src\packages\types\enums.ts#L2-L2), [QINIU](file://e:\project\code\npm\ts-project\src\packages\types\enums.ts#L3-L3))
+- [endpoint](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L8-L8) - 服务端点
+- [accessKeyId](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L4-L4) - 访问密钥 ID
+- [accessKeySecret](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L5-L5) - 访问密钥
+- [bucket](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L6-L6) - 存储桶名称
+- [region](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L7-L7) - 区域
+- [secure](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L10-L10) - 是否使用 HTTPS (默认: true)
+- [domain](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L9-L9) - 自定义域名 (可选)
+
+#### 上传文件
+
+```typescript
+await ossClient.upload(options: UploadOptions)
+```
+
+**参数：**
+
+- [path](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L16-L16) - 文件路径
+- [file](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L17-L17) - 文件内容 (Buffer | string | ReadableStream)
+- [contentType](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L72-L72) - 内容类型 (可选)
+- [mode](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L22-L22) - 上传模式 (普通/分片)
+- [partSize](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L23-L23) - 分片大小 (分片上传时使用)
+- [progressCallback](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L21-L21) - 进度回调函数
+
+**示例：**
+
+```typescript
+await ossClient.upload({
+  path: 'files/document.pdf',
+  file: fs.readFileSync('./document.pdf'),
+  contentType: 'application/pdf',
+  progressCallback: (progress) => {
+    console.log(`上传进度: ${progress.percent}%`);
+  }
+});
+```
+
+#### 下载文件
+
+```typescript
+const buffer = await ossClient.download(options: DownloadOptions)
+```
+
+**参数：**
+
+- [path](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L16-L16) - 文件路径
+- [destination](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L36-L36) - 本地保存路径 (可选)
+
+**示例：**
+
+```typescript
+const fileBuffer = await ossClient.download({
+  path: 'images/photo.jpg'
+});
+```
+
+#### 删除文件
+
+```typescript
+await ossClient.delete(path: string)
+```
+
+**示例：**
+
+```typescript
+await ossClient.delete('images/photo.jpg');
+```
+
+#### 列出文件
+
+```typescript
+const result = await ossClient.list(options: ListOptions)
+```
+
+**参数：**
+
+- [prefix](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L52-L52) - 前缀过滤 (可选)
+- [limit](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L60-L60) - 返回数量限制 (可选)
+- [delimiter](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L56-L56) - 分隔符 (可选)
+- [marker](file://e:\project\code\npm\ts-project\src\packages\types\index.ts#L64-L64) - 分页标记 (可选)
+
+**示例：**
+
+```typescript
+const result = await ossClient.list({
+  prefix: 'images/',
+  limit: 10
+});
+console.log(result.objects); // 文件列表
+```
+
+#### 创建目录
+
+```typescript
+await ossClient.createDirectory(path: string)
+```
+
+**示例：**
+
+```typescript
+await ossClient.createDirectory('documents/');
+```
+
+#### 列出目录
+
+```typescript
+const directories = await ossClient.listDirectories(prefix?: string)
+```
+
+**示例：**
+
+```typescript
+const dirs = await ossClient.listDirectories('images/');
+console.log(dirs); // 目录列表
+```
+
+#### 获取签名 URL
+
+```typescript
+const url = await ossClient.getSignedUrl(path: string, expires: number)
+```
+
+**参数：**
+
+- `path` - 文件路径
+- `expires` - 过期时间 (秒，默认: 3600)
+
+**示例：**
+
+```typescript
+const url = await ossClient.getSignedUrl('images/photo.jpg', 3600);
+console.log(url); // 可访问的临时链接
+```
+
+#### 批量操作
+
+##### 批量上传
+
+```typescript
+const results = await ossClient.batchUpload(uploads: UploadOptions[])
+```
+
+**示例：**
+
+```typescript
+const results = await ossClient.batchUpload([
+  { path: 'images/1.jpg', file: fs.readFileSync('./1.jpg') },
+  { path: 'images/2.jpg', file: fs.readFileSync('./2.jpg') }
+]);
+```
+
+##### 批量删除
+
+```typescript
+await ossClient.batchDelete(paths: string[])
+```
+
+**示例：**
+
+```typescript
+await ossClient.batchDelete(['images/1.jpg', 'images/2.jpg']);
+```
+
+## 高级功能扩展
+
+### 事件监听器
+
+```typescript
+import { OSSClient, UploadOptions } from 'luoyu-oss-unified';
+
+class EnhancedOSSClient extends OSSClient {
+  private eventListeners: Map<string, Function[]> = new Map();
+
+  on(event: string, listener: Function) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, []);
+    }
+    this.eventListeners.get(event)!.push(listener);
+  }
+
+  emit(event: string, ...args: any[]) {
+    const listeners = this.eventListeners.get(event) || [];
+    listeners.forEach(listener => listener(...args));
+  }
+
+  async uploadWithEvents(options: UploadOptions) {
+    this.emit('upload:start', options);
+    try {
+      const result = await super.upload(options);
+      this.emit('upload:complete', result);
+      return result;
+    } catch (error) {
+      this.emit('upload:error', error);
+      throw error;
+    }
+  }
+}
+
+// 使用示例
+const enhancedClient = new EnhancedOSSClient(minioConfig);
+
+enhancedClient.on('upload:start', (options) => {
+  console.log('上传开始:', options.path);
+});
+
+enhancedClient.on('upload:complete', (result) => {
+  console.log('上传完成:', result);
+});
+
+enhancedClient.on('upload:error', (error) => {
+  console.error('上传错误:', error);
+});
+
+// 触发带事件的上传
+await enhancedClient.uploadWithEvents({
+  path: 'files/document.pdf',
+  file: fs.readFileSync('./document.pdf')
+});
+```
+
+### 分片上传
+
+对于大文件，推荐使用分片上传：
+
+```typescript
+await ossClient.upload({
+  path: 'videos/large-video.mp4',
+  file: fs.readFileSync('./large-video.mp4'),
+  mode: UploadMode.MULTIPART,
+  partSize: 10 * 1024 * 1024, // 10MB 每片
+  progressCallback: (progress) => {
+    console.log(`Upload progress: ${progress.percent}%`);
+  }
+});
+```
+
+### 存在性检查
+
+```typescript
+const exists = await ossClient.exists('images/photo.jpg');
+console.log(exists); // true/false
+```
+
+### 获取文件信息
+
+```typescript
+const fileInfo = await ossClient.head('images/photo.jpg');
+if (fileInfo) {
+  console.log(fileInfo.size); // 文件大小
+  console.log(fileInfo.lastModified); // 最后修改时间
+}
+```
+
+## 支持的提供商
+
+- ✅ **MinIO** - 高性能对象存储
+- ✅ **七牛云** - 国内主流 CDN 服务商
+- ⏳ **阿里云 OSS** - 企业级对象存储服务
+- ⏳ **腾讯云 COS** - 腾讯云对象存储
+
+## 环境要求
+
+- Node.js >= 14.0.0
+- TypeScript >= 4.0.0 (可选，但推荐)
+
+## 完整测试代码示例
+
+```typescript
+import { OSSClient, OSSConfig, OSSProvider, UploadMode } from 'luoyu-oss-unified';
+import fs from 'fs';
+import path from 'path';
+
+// MinIO 配置
+const minioConfig = {
+  provider: OSSProvider.MINIO,
+  endpoint: 'http://your-minio-server.com',
+  accessKeyId: 'your-access-key',
+  accessKeySecret: 'your-secret-key',
+  bucket: 'your-bucket',
+  region: 'us-east-1'
+};
+
+// 七牛云配置
+const qiniuConfig: OSSConfig = {
+  provider: OSSProvider.QINIU,
+  accessKeyId: 'your-access-key',
+  accessKeySecret: 'your-secret-key',
+  bucket: 'your-bucket',
+  region: 'z0',
+  domain: 'your-domain.qiniudn.com'
+};
+
+// 创建客户端
+const ossClient = new OSSClient(minioConfig);
+
+// 上传文件
+export async function uploadFile() {
+  const filePath = path.join(__dirname, '../upload/file.jpg');
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File does not exist: ${filePath}`);
+  }
+  
+  const result = await ossClient.upload({
+    path: 'images/test.jpg',
+    file: fs.readFileSync(filePath),
+    contentType: 'image/jpeg',
+    progressCallback: (progress) => {
+      console.log(`Upload progress: ${progress.percent}%`);
+    }
+  });
+  console.log('File uploaded:', result);
+}
+
+// 下载文件
+export async function downloadFile() {
+  const buffer = await ossClient.download({
+    path: 'images/test.jpg'
+  });
+  return buffer;
+}
+
+// 列出文件
+export async function listFiles() {
+  const result = await ossClient.list({
+    prefix: 'images/',
+    limit: 10
+  });
+  console.log('Files:', result.objects);
+}
+
+// 列出目录
+export async function listDirectories() {
+  const dirs = await ossClient.listDirectories('images/');
+  console.log('Directories:', dirs);
+  return dirs;
+}
+
+// 创建目录
+export async function createDir() {
+  await ossClient.createDirectory('documents/');
+}
+
+// 上传大文件
+export async function uploadLargeFile() {
+  const filePath = path.join(__dirname, '../upload/large-file.mp4');
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File does not exist: ${filePath}`);
+  }
+  
+  const result = await ossClient.upload({
+    path: 'videos/large.mp4',
+    file: fs.readFileSync(filePath),
+    mode: UploadMode.MULTIPART,
+    partSize: 10 * 1024 * 1024,
+    progressCallback: (progress) => {
+      console.log(`Upload progress: ${progress.percent}%`);
+    }
+  });
+  console.log('Large file uploaded:', result);
+}
+
+// 获取签名 URL
+export async function getPresignedUrl() {
+  const url = await ossClient.getSignedUrl('images/test.jpg', 3600);
+  console.log('Presigned URL:', url);
+}
+
+// 批量操作
+export async function batchOperations() {
+  const uploadResults = await ossClient.batchUpload([
+    { path: 'images/1.jpg', file: fs.readFileSync(path.join(__dirname, '../upload/image1.jpg')) },
+    { path: 'images/2.jpg', file: fs.readFileSync(path.join(__dirname, '../upload/image2.jpg')) }
+  ]);
+  console.log('Upload results:', uploadResults);
+  
+  // 批量删除
+  await ossClient.batchDelete(['images/1.jpg', 'images/2.jpg']);
+}
+
+// 带事件监听的高级客户端示例
+class EnhancedOSSClient extends OSSClient {
+  private eventListeners: Map<string, Function[]> = new Map();
+
+  on(event: string, listener: Function) {
+    if (!this.eventListeners.has(event)) {
+      this.eventListeners.set(event, []);
+    }
+    this.eventListeners.get(event)!.push(listener);
+  }
+
+  emit(event: string, ...args: any[]) {
+    const listeners = this.eventListeners.get(event) || [];
+    listeners.forEach(listener => listener(...args));
+  }
+
+  async uploadWithEvents(options: UploadOptions) {
+    this.emit('upload:start', options);
+    try {
+      const result = await super.upload(options);
+      this.emit('upload:complete', result);
+      return result;
+    } catch (error) {
+      this.emit('upload:error', error);
+      throw error;
+    }
+  }
+}
+```
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+MIT License
+
+---
+
+这个 npm 插件提供了统一的 API 来操作不同的对象存储服务，让开发者可以轻松切换存储提供商而无需更改业务代码。通过事件监听器机制，还可以实现更精细的进度监控和错误处理。

package/dist/lib/adapters/aliyun-adapter.d.ts

@@ -0,0 +1,20 @@
+import { BaseOSSAdapter } from './base-adapter';
+import { type OSSConfig, type UploadOptions, type DownloadOptions, type ListOptions, type ListResult, type OSSObject, type MultipartUploadInfo, type PartInfo } from '../types';
+export declare class AliyunOSSAdapter extends BaseOSSAdapter {
+    private client;
+    constructor(config: OSSConfig);
+    upload(options: UploadOptions): Promise<string>;
+    download(options: DownloadOptions): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    list(options?: ListOptions): Promise<ListResult>;
+    head(path: string): Promise<OSSObject | null>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, expires?: number): Promise<string>;
+    initiateMultipartUpload(path: string, partSize?: number): Promise<MultipartUploadInfo>;
+    uploadPart(uploadInfo: MultipartUploadInfo, partNumber: number, data: Buffer, start: number, end: number): Promise<PartInfo>;
+    completeMultipartUpload(uploadInfo: MultipartUploadInfo, parts: PartInfo[]): Promise<string>;
+    abortMultipartUpload(uploadInfo: MultipartUploadInfo): Promise<void>;
+    listParts(uploadInfo: MultipartUploadInfo): Promise<PartInfo[]>;
+    private uploadMultipartParts;
+}
+//# sourceMappingURL=aliyun-adapter.d.ts.map

package/dist/lib/adapters/aliyun-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliyun-adapter.d.ts","sourceRoot":"","sources":["../../../packages/adapters/aliyun-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EACH,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EAEhB,MAAM,UAAU,CAAC;AAElB,qBAAa,gBAAiB,SAAQ,cAAc;IAChD,OAAO,CAAC,MAAM,CAAM;gBAER,MAAM,EAAE,SAAS;IAavB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAuC/C,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAcnD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInC,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAuBpD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAkB7C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKtC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAInE,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAwB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IASvG,UAAU,CACZ,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAC,MAAM,EACZ,GAAG,EAAC,MAAM,GACX,OAAO,CAAC,QAAQ,CAAC;IAiBd,uBAAuB,CACzB,UAAU,EAAE,mBAAmB,EAC/B,KAAK,EAAE,QAAQ,EAAE,GAClB,OAAO,CAAC,MAAM,CAAC;IAmBZ,oBAAoB,CAAC,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpE,SAAS,CAAC,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YAavD,oBAAoB;CAwCrC"}