@data-loom/storage-js 0.4.4-alpha.11 → 0.4.4-alpha.12

package/README.md

@@ -7,7 +7,7 @@ Dataloom 存储服务 JavaScript SDK，基于 Supabase Storage 修改而来，
 - 📁 **文件上传和下载** - 支持多种文件格式的上传和下载
 - 🔗 **签名URL** - 创建具有时效性的安全文件访问链接
 - 🗑️ **文件管理** - 删除、列表等文件操作
-- 🌐 **URL上传** - 从公共URL下载文件并上传到存储桶
+- 🖼️ **图片转换** - 支持图片尺寸调整、质量优化等转换功能
 - 📊 **批量操作** - 支持批量创建签名URL等批量操作
 - 🔍 **文件搜索** - 支持文件搜索和分页
 - 🛡️ **错误处理** - 完善的错误处理机制
@@ -77,179 +77,69 @@ constructor(
 )
 ```
 
----
-
 ### 文件上传
 
-#### `upload(path, fileBody, fileOptions?)` - 重载1
-
-上传文件到指定的存储桶路径。
-
-**入参：**
-```typescript
-function upload(
-  path: string,           // 文件路径，格式为 `folder/subfolder/filename.png`
-  fileBody: FileBody,     // 文件内容
-  fileOptions?: FileOptions  // 上传选项
-): Promise<UploadResult>
-```
-
-**出参：**
-```typescript
-type UploadResult =
-  | { data: UploadFileData; error: null }
-  | { data: null; error: StorageError }
-```
-
-**示例：**
-```javascript
-const { data, error } = await storage.upload('avatars/user-123.jpg', file, {
-  cacheControl: 3600,
-  contentType: 'image/jpeg',
-  upsert: false
-});
-```
-
----
+#### `uploadFile(fileBody, fileOptions?)` **(推荐)**
 
-#### `upload(fileBody, fileOptions?)` - 重载2
+使用文件选项上传文件（推荐, 无需关注filePath）。
 
-使用 FileOptionsV2 上传文件，路径通过 options.filePath 指定。
+**参数：**
+- `fileBody` (FileBody): 文件内容
+- `fileOptions` (FileOptionsV2, 可选): 文件选项，可指定 filePath 等
 
-**入参：**
-```typescript
-function upload(
-  fileBody: FileBody,         // 文件内容
-  fileOptions?: FileOptionsV2 // 上传选项（包含 filePath）
-): Promise<UploadResult>
-```
-
-**出参：**
-```typescript
-type UploadResult =
-  | { data: UploadFileData; error: null }
-  | { data: null; error: StorageError }
-```
+**返回：** 同 `upload` 方法
 
 **示例：**
 ```javascript
-const { data, error } = await storage.upload(file, {
+const { data, error } = await storage.uploadFile(file, {
   filePath: 'documents/report.pdf',
+  cacheControl: 3600,
   contentType: 'application/pdf',
   contentDisposition: 'attachment; filename="report.pdf"'
 });
 ```
 
----
+#### `upload(path, fileBody, fileOptions?)`
 
-#### `uploadFile(fileBody, fileOptions?)`
+上传文件到指定的存储桶路径。
 
-使用文件选项上传文件（推荐，与 upload 重载2 功能相同）。
+**参数：**
+- `path` (string): 文件路径，格式为 `folder/subfolder/filename.png`
+- `fileBody` (FileBody): 文件内容，支持多种格式
+- `fileOptions` (FileOptions, 可选): 文件选项
 
-**入参：**
+**返回：**
 ```typescript
-function uploadFile(
-  fileBody: FileBody,         // 文件内容
-  fileOptions?: FileOptionsV2 // 上传选项
-): Promise<UploadResult>
-```
-
-**出参：**
-```typescript
-type UploadResult =
-  | { data: UploadFileData; error: null }
-  | { data: null; error: StorageError }
+{
+  data: UploadFileData;  // 包含文件ID、路径、存储桶ID和下载URL
+  error: null;
+} | {
+  data: null;
+  error: StorageError;
+}
 ```
 
 **示例：**
 ```javascript
-const { data, error } = await storage.uploadFile(file, {
-  filePath: 'documents/report.pdf',
-  cacheControl: 3600,
-  contentType: 'application/pdf',
-  contentDisposition: 'attachment; filename="report.pdf"'
+const fileInput = document.getElementById('fileInput');
+const file = fileInput.files[0];
+
+const { data, error } = await storage.upload('avatars/user-123.jpg', file, {
+  cacheControl: '3600',
+  contentType: 'image/jpeg',
+  upsert: false
 });
 ```
 
----
-
 ### 文件更新
 
 #### `update(path, fileBody, fileOptions?)`
 
 替换指定路径的现有文件。
 
-**入参：**
-```typescript
-function update(
-  path: string,              // 文件路径
-  fileBody: FileBody,        // 文件内容
-  fileOptions?: FileOptions  // 上传选项
-): Promise<UploadResult>
-```
-
-**出参：**
-```typescript
-type UploadResult =
-  | { data: UploadFileData; error: null }
-  | { data: null; error: StorageError }
-```
-
----
-
-### 从URL上传文件
+**参数：** 同 `upload` 方法
 
-#### `uploadFromUrl(url)`
-
-从公共URL上传文件到存储桶。自动透传响应头（content-type、content-disposition、cache-control）到上传请求。对于火山引擎北京区域的 TOS URL，会使用服务端复制优化性能。
-
-**入参：**
-```typescript
-function uploadFromUrl(
-  url: string  // 公共文件URL（如 CDN 链接）
-): Promise<UploadFromUrlResult>
-```
-
-**出参：**
-```typescript
-type UploadFromUrlResult =
-  | { data: UploadFileData; error: null }
-  | { data: null; error: StorageError }
-```
-
-**功能特性：**
-- ✅ 只允许 `http://` 和 `https://` 协议
-- ✅ 自动透传响应头到上传请求（contentType、contentDisposition、cacheControl）
-- ✅ 检测并拒绝空文件
-- ✅ 火山引擎北京区域 TOS URL 使用服务端复制优化
-
-**示例：**
-```javascript
-// 基本用法
-const { data, error } = await storage.uploadFromUrl(
-  'https://cdn.example.com/images/photo.jpg'
-);
-
-if (data) {
-  console.log('文件上传成功:', data.download_url);
-}
-```
-
-**错误处理：**
-```javascript
-const { data, error } = await storage.uploadFromUrl('https://example.com/file.pdf');
-
-if (error) {
-  // 可能的错误类型：
-  // - 'Invalid URL provided' - URL格式无效
-  // - 'Only http and https protocols are supported' - 协议不支持
-  // - 'Failed to download file from URL: 404 Not Found' - 下载失败
-  // - 'Downloaded file is empty' - 下载的文件为空
-  console.error(error.message);
-}
-```
-
----
+**返回：** 同 `upload` 方法
 
 ### 创建签名URL
 
@@ -257,23 +147,22 @@ if (error) {
 
 创建具有时效性的安全文件访问链接。
 
-**入参：**
-```typescript
-function createSignedUrl(
-  path: string,      // 文件路径或 download_url
-  expiresIn: number, // 过期时间（秒）
-  options?: {
-    download?: string | boolean;    // 是否触发下载
-    transform?: TransformOptions;   // 图片转换选项
-  }
-): Promise<SignedUrlResult>
-```
-
-**出参：**
-```typescript
-type SignedUrlResult =
-  | { data: { signedUrl: string }; error: null }
-  | { data: null; error: StorageError }
+**参数：**
+- `path` (string): 文件路径或上传接口返回的download_url
+- `expiresIn` (number): 过期时间（秒）
+- `options` (object, 可选): 选项
+  - `download` (string | boolean): 是否触发下载，可指定文件名
+  - `transform` (TransformOptions): 图片转换选项
+
+**返回：**
+```typescript
+{
+  data: { signedUrl: string };
+  error: null;
+} | {
+  data: null;
+  error: StorageError;
+}
 ```
 
 **示例：**
@@ -292,99 +181,80 @@ const { data, error } = await storage.createSignedUrl('images/photo.jpg', 3600,
 });
 ```
 
----
-
 #### `createSignedUrls(paths, expiresIn, options?)`
 
 批量创建签名URL。
 
-**入参：**
-```typescript
-function createSignedUrls(
-  paths: string[],    // 文件路径或 download_url 数组
-  expiresIn: number,  // 过期时间（秒）
-  options?: {
-    download?: string | boolean;
-  }
-): Promise<SignedUrlsResult>
-```
-
-**出参：**
-```typescript
-type SignedUrlsResult =
-  | {
-      data: Array<{
-        error: string | null;
-        path: string | null;
-        signedUrl: string;
-      }>;
-      error: null
-    }
-  | { data: null; error: StorageError }
-```
-
-**示例：**
-```javascript
-const { data, error } = await storage.createSignedUrls(
-  ['file1.pdf', 'file2.pdf', 'file3.pdf'],
-  3600
-);
+**参数：**
+- `paths` (string[]): 文件路径或上传接口返回的download_url数组
+- `expiresIn` (number): 过期时间（秒）
+- `options` (object, 可选): 选项
+
+**返回：**
+```typescript
+{
+  data: Array<{
+    error: string | null;
+    path: string | null;
+    signedUrl: string;
+  }>;
+  error: null;
+} | {
+  data: null;
+  error: StorageError;
+}
 ```
 
----
-
 ### 文件下载
 
 #### `download(path, options?)`
 
 从私有存储桶下载文件。
 
-**入参：**
-```typescript
-function download(
-  path: string,  // 文件路径
-  options?: {
-    transform?: TransformOptions;  // 图片转换选项
-  }
-): Promise<DownloadResult>
-```
+**参数：**
+- `path` (string): 文件路径
+- `options` (object, 可选): 选项
+  - `transform` (TransformOptions): 图片转换选项
 
-**出参：**
+**返回：**
 ```typescript
-type DownloadResult =
-  | { data: Blob; error: null }
-  | { data: null; error: StorageError }
+{
+  data: Blob;
+  error: null;
+} | {
+  data: null;
+  error: StorageError;
+}
 ```
 
 **示例：**
 ```javascript
 const { data, error } = await storage.download('documents/report.pdf');
 if (data) {
+  // 处理下载的文件数据
   const url = URL.createObjectURL(data);
   window.open(url);
 }
 ```
 
----
-
 ### 文件删除
 
 #### `remove(paths)`
 
 删除指定路径的文件。
 
-**入参：**
-```typescript
-function remove(
-  paths: string[]  // 文件路径或 download_url 数组
-): Promise<RemoveResult>
-```
+**参数：**
+- `paths` (string[]): 要删除的文件路径或上传接口返回的download_url数组
 
-**出参：**
+**返回：**
 ```typescript
-type RemoveResult =
-  | { data: FileObject[]; error: null }
-  | { data: null; error: StorageError }
+{
+  data: FileObject[];  // 被删除的文件信息
+  error: null;
+} | {
+  data: null;
+  error: StorageError;
+}
 ```
 
 **示例：**
@@ -395,28 +265,26 @@ const { data, error } = await storage.remove([
 ]);
 ```
 
----
-
 ### 文件列表
 
 #### `list(path?, options?, parameters?)`
 
 列出存储桶中的文件。
 
-**入参：**
-```typescript
-function list(
-  path?: string,              // 文件夹路径
-  options?: SearchOptions,    // 搜索选项
-  parameters?: FetchParameters // 请求参数
-): Promise<ListResult>
-```
+**参数：**
+- `path` (string, 可选): 文件夹路径
+- `options` (SearchOptions, 可选): 搜索选项
+- `parameters` (FetchParameters, 可选): 请求参数
 
-**出参：**
+**返回：**
 ```typescript
-type ListResult =
-  | { data: FileObject[]; error: null }
-  | { data: null; error: StorageError }
+{
+  data: FileObject[];  // 文件列表
+  error: null;
+} | {
+  data: null;
+  error: StorageError;
+}
 ```
 
 **示例：**
@@ -436,208 +304,99 @@ const { data, error } = await storage.list('documents', {
 });
 ```
 
----
-
 ## 类型定义
 
 ### FileBody
-
 支持以下文件格式：
-
-```typescript
-type FileBody =
-  | ArrayBuffer
-  | ArrayBufferView
-  | Blob
-  | Buffer
-  | File
-  | FormData
-  | NodeJS.ReadableStream
-  | ReadableStream<Uint8Array>
-  | URLSearchParams
-  | string;
-```
+- `ArrayBuffer`
+- `ArrayBufferView` 
+- `Blob`
+- `Buffer`
+- `File`
+- `FormData`
+- `NodeJS.ReadableStream`
+- `ReadableStream<Uint8Array>`
+- `URLSearchParams`
+- `string`
 
 ### FileOptions
-
 ```typescript
 interface FileOptions {
-  /** 缓存控制时间（秒），设置 Cache-Control: max-age=<seconds> 头 */
-  cacheControl?: string | number;
-  /** Content-Type 头值 */
-  contentType?: string;
-  /** 是否覆盖已存在文件，默认 false */
-  upsert?: boolean;
-  /** 双工流选项 */
-  duplex?: string;
-  /** 文件元数据 */
-  metadata?: Record<string, any>;
-  /** 额外请求头 */
-  headers?: Record<string, string>;
+  cacheControl?: string | number;    // 缓存控制（秒）
+  contentType?: string;              // 内容类型
+  upsert?: boolean;                  // 是否覆盖已存在文件
+  duplex?: string;                   // 双工流选项
+  metadata?: Record<string, any>;    // 元数据
+  headers?: Record<string, string>;   // 额外请求头
 }
 ```
 
 ### FileOptionsV2
-
 ```typescript
 interface FileOptionsV2 {
-  /** 文件上传路径 */
-  filePath?: string;
-  /** 缓存控制时间（秒） */
-  cacheControl?: string | number;
-  /** Content-Type 头值 */
-  contentType?: string;
-  /** 是否覆盖已存在文件，默认 false */
-  upsert?: boolean;
-  /** Content-Disposition 响应头值 */
-  contentDisposition?: string;
+  filePath?: string;                 // 文件路径（用于 uploadFile）
+  cacheControl?: string | number;    // 缓存控制（秒）
+  contentType?: string;              // 内容类型
+  upsert?: boolean;                  // 是否覆盖已存在文件
+  contentDisposition?: string;       // 内容处置
 }
 ```
 
-### UploadFileData
-
+### TransformOptions
 ```typescript
-interface UploadFileData {
-  /** 文件ID */
-  id: string;
-  /** 文件路径 */
-  file_path: string;
-  /** 存储桶ID */
-  bucket_id: string;
-  /** 下载URL */
-  download_url: string;
+interface TransformOptions {
+  width?: number;                    // 宽度（像素）
+  height?: number;                   // 高度（像素）
+  resize?: 'cover' | 'contain' | 'fill';  // 调整大小模式
+  quality?: number;                  // 质量（20-100）
+  format?: 'origin';                 // 格式
 }
 ```
 
-### FileObject
-
+### UploadFileData
 ```typescript
-interface FileObject {
-  /** 文件名 */
-  name: string;
-  /** 存储桶ID */
-  bucket_id: string;
-  /** 所有者 */
-  owner: string;
-  /** 文件ID */
-  id: string;
-  /** 更新时间 */
-  updated_at: string;
-  /** 创建时间 */
-  created_at: string;
-  /** 创建者 */
-  created_by: string;
-  /** 更新者 */
-  updated_by: string;
-  /** 最后访问时间 */
-  last_accessed_at?: string;
-  /** 元数据 */
-  metadata: Record<string, any>;
-  /** 存储桶信息 */
-  buckets: Bucket;
+interface UploadFileData {
+  id: string;                        // 文件ID
+  file_path: string;                 // 文件路径
+  bucket_id: string;                 // 存储桶ID
+  download_url: string;              // 下载URL
 }
 ```
 
-### Bucket
-
+### FileObject
 ```typescript
-interface Bucket {
-  /** 存储桶ID */
-  id: string;
-  /** 存储桶类型 */
-  type?: 'STANDARD' | 'ANALYTICS';
-  /** 存储桶名称 */
-  name: string;
-  /** 所有者 */
-  owner: string;
-  /** 文件大小限制 */
-  file_size_limit?: number;
-  /** 允许的MIME类型 */
-  allowed_mime_types?: string[];
-  /** 创建时间 */
-  created_at: string;
-  /** 更新时间 */
-  updated_at: string;
-  /** 是否公开 */
-  public: boolean;
+interface FileObject {
+  name: string;                      // 文件名
+  bucket_id: string;                 // 存储桶ID
+  owner: string;                     // 所有者
+  id: string;                        // 文件ID
+  updated_at: string;                // 更新时间
+  created_at: string;                // 创建时间
+  created_by: string;                // 创建者
+  updated_by: string;                // 更新者
+  last_accessed_at?: string;         // 最后访问时间
+  metadata: Record<string, any>;     // 元数据
+  buckets: Bucket;                   // 存储桶信息
 }
 ```
 
 ### SearchOptions
-
 ```typescript
 interface SearchOptions {
-  /** 返回文件数量，默认 100 */
-  limit?: number;
-  /** 起始位置 */
-  offset?: number;
-  /** 排序选项 */
-  sortBy?: SortBy;
-  /** 搜索字符串 */
-  search?: string;
-}
-```
-
-### SortBy
-
-```typescript
-interface SortBy {
-  /** 排序列名 */
-  column?: string;
-  /** 排序顺序：'asc' | 'desc' */
-  order?: string;
-}
-```
-
-### TransformOptions
-
-```typescript
-interface TransformOptions {
-  /** 宽度（像素） */
-  width?: number;
-  /** 高度（像素） */
-  height?: number;
-  /** 调整大小模式 */
-  resize?: 'cover' | 'contain' | 'fill';
-  /** 质量（20-100） */
-  quality?: number;
-  /** 格式 */
-  format?: 'origin';
+  limit?: number;                    // 返回文件数量（默认100）
+  offset?: number;                   // 起始位置
+  sortBy?: SortBy;                   // 排序选项
+  search?: string;                   // 搜索字符串
 }
 ```
 
 ### FetchParameters
-
 ```typescript
 interface FetchParameters {
-  /** AbortController 信号，用于取消请求 */
-  signal?: AbortSignal;
-}
-```
-
-### StorageError
-
-```typescript
-class StorageError extends Error {
-  message: string;
+  signal?: AbortSignal;              // AbortController 信号
 }
 ```
 
-### OnRequestErrorType
-
-```typescript
-interface OnRequestErrorType {
-  code: number;
-  details: string;
-  hint: string | null;
-  message: string;
-  status: number;
-  statusText: string;
-}
-```
-
----
-
 ## 错误处理
 
 所有API方法都返回包含 `data` 和 `error` 的对象。当操作成功时，`error` 为 `null`，`data` 包含返回数据；当操作失败时，`data` 为 `null`，`error` 包含错误信息。
@@ -647,13 +406,13 @@ const { data, error } = await storage.upload('test.jpg', file);
 
 if (error) {
   console.error('操作失败:', error.message);
+  // 错误处理
 } else {
   console.log('操作成功:', data);
+  // 处理返回数据
 }
 ```
 
----
-
 ## 高级用法
 
 ### 日志记录
@@ -685,6 +444,7 @@ const storage = new StorageFileApi(
   false,
   (error) => {
     console.error('请求错误:', error);
+    // 自定义错误处理
   }
 );
 ```
@@ -708,8 +468,6 @@ const storage = new StorageFileApi(
 );
 ```
 
----
-
 ## 许可证
 
 MIT License