@data-loom/storage-js 0.4.3 → 0.4.4-alpha.10

package/README.md

@@ -7,7 +7,7 @@ Dataloom 存储服务 JavaScript SDK，基于 Supabase Storage 修改而来，
 - 📁 **文件上传和下载** - 支持多种文件格式的上传和下载
 - 🔗 **签名URL** - 创建具有时效性的安全文件访问链接
 - 🗑️ **文件管理** - 删除、列表等文件操作
-- 🖼️ **图片转换** - 支持图片尺寸调整、质量优化等转换功能
+- 🌐 **URL上传** - 从公共URL下载文件并上传到存储桶
 - 📊 **批量操作** - 支持批量创建签名URL等批量操作
 - 🔍 **文件搜索** - 支持文件搜索和分页
 - 🛡️ **错误处理** - 完善的错误处理机制
@@ -77,69 +77,179 @@ constructor(
 )
 ```
 
+---
+
 ### 文件上传
 
-#### `uploadFile(fileBody, fileOptions?)` **(推荐)**
+#### `upload(path, fileBody, fileOptions?)` - 重载1
 
-使用文件选项上传文件（推荐, 无需关注filePath）。
+上传文件到指定的存储桶路径。
 
-**参数：**
-- `fileBody` (FileBody): 文件内容
-- `fileOptions` (FileOptionsV2, 可选): 文件选项，可指定 filePath 等
+**入参：**
+```typescript
+function upload(
+  path: string,           // 文件路径，格式为 `folder/subfolder/filename.png`
+  fileBody: FileBody,     // 文件内容
+  fileOptions?: FileOptions  // 上传选项
+): Promise<UploadResult>
+```
 
-**返回：** 同 `upload` 方法
+**出参：**
+```typescript
+type UploadResult =
+  | { data: UploadFileData; error: null }
+  | { data: null; error: StorageError }
+```
 
 **示例：**
 ```javascript
-const { data, error } = await storage.uploadFile(file, {
-  filePath: 'documents/report.pdf',
+const { data, error } = await storage.upload('avatars/user-123.jpg', file, {
   cacheControl: 3600,
+  contentType: 'image/jpeg',
+  upsert: false
+});
+```
+
+---
+
+#### `upload(fileBody, fileOptions?)` - 重载2
+
+使用 FileOptionsV2 上传文件，路径通过 options.filePath 指定。
+
+**入参：**
+```typescript
+function upload(
+  fileBody: FileBody,         // 文件内容
+  fileOptions?: FileOptionsV2 // 上传选项（包含 filePath）
+): Promise<UploadResult>
+```
+
+**出参：**
+```typescript
+type UploadResult =
+  | { data: UploadFileData; error: null }
+  | { data: null; error: StorageError }
+```
+
+**示例：**
+```javascript
+const { data, error } = await storage.upload(file, {
+  filePath: 'documents/report.pdf',
   contentType: 'application/pdf',
   contentDisposition: 'attachment; filename="report.pdf"'
 });
 ```
 
-#### `upload(path, fileBody, fileOptions?)`
+---
 
-上传文件到指定的存储桶路径。
+#### `uploadFile(fileBody, fileOptions?)`
 
-**参数：**
-- `path` (string): 文件路径，格式为 `folder/subfolder/filename.png`
-- `fileBody` (FileBody): 文件内容，支持多种格式
-- `fileOptions` (FileOptions, 可选): 文件选项
+使用文件选项上传文件（推荐，与 upload 重载2 功能相同）。
 
-**返回：**
+**入参：**
 ```typescript
-{
-  data: UploadFileData;  // 包含文件ID、路径、存储桶ID和下载URL
-  error: null;
-} | {
-  data: null;
-  error: StorageError;
-}
+function uploadFile(
+  fileBody: FileBody,         // 文件内容
+  fileOptions?: FileOptionsV2 // 上传选项
+): Promise<UploadResult>
+```
+
+**出参：**
+```typescript
+type UploadResult =
+  | { data: UploadFileData; error: null }
+  | { data: null; error: StorageError }
 ```
 
 **示例：**
 ```javascript
-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
+const { data, error } = await storage.uploadFile(file, {
+  filePath: 'documents/report.pdf',
+  cacheControl: 3600,
+  contentType: 'application/pdf',
+  contentDisposition: 'attachment; filename="report.pdf"'
 });
 ```
 
+---
+
 ### 文件更新
 
 #### `update(path, fileBody, fileOptions?)`
 
 替换指定路径的现有文件。
 
-**参数：** 同 `upload` 方法
+**入参：**
+```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);
+}
+```
+
+---
 
 ### 创建签名URL
 
@@ -147,22 +257,23 @@ const { data, error } = await storage.upload('avatars/user-123.jpg', file, {
 
 创建具有时效性的安全文件访问链接。
 
-**参数：**
-- `path` (string): 文件路径或上传接口返回的download_url
-- `expiresIn` (number): 过期时间（秒）
-- `options` (object, 可选): 选项
-  - `download` (string | boolean): 是否触发下载，可指定文件名
-  - `transform` (TransformOptions): 图片转换选项
-
-**返回：**
-```typescript
-{
-  data: { signedUrl: string };
-  error: null;
-} | {
-  data: null;
-  error: StorageError;
-}
+**入参：**
+```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 }
 ```
 
 **示例：**
@@ -181,80 +292,99 @@ const { data, error } = await storage.createSignedUrl('images/photo.jpg', 3600,
 });
 ```
 
+---
+
 #### `createSignedUrls(paths, expiresIn, options?)`
 
 批量创建签名URL。
 
-**参数：**
-- `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;
-}
+**入参：**
+```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
+);
+```
+
+---
+
 ### 文件下载
 
 #### `download(path, options?)`
 
 从私有存储桶下载文件。
 
-**参数：**
-- `path` (string): 文件路径
-- `options` (object, 可选): 选项
-  - `transform` (TransformOptions): 图片转换选项
+**入参：**
+```typescript
+function download(
+  path: string,  // 文件路径
+  options?: {
+    transform?: TransformOptions;  // 图片转换选项
+  }
+): Promise<DownloadResult>
+```
 
-**返回：**
+**出参：**
 ```typescript
-{
-  data: Blob;
-  error: null;
-} | {
-  data: null;
-  error: StorageError;
-}
+type DownloadResult =
+  | { 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)`
 
 删除指定路径的文件。
 
-**参数：**
-- `paths` (string[]): 要删除的文件路径或上传接口返回的download_url数组
+**入参：**
+```typescript
+function remove(
+  paths: string[]  // 文件路径或 download_url 数组
+): Promise<RemoveResult>
+```
 
-**返回：**
+**出参：**
 ```typescript
-{
-  data: FileObject[];  // 被删除的文件信息
-  error: null;
-} | {
-  data: null;
-  error: StorageError;
-}
+type RemoveResult =
+  | { data: FileObject[]; error: null }
+  | { data: null; error: StorageError }
 ```
 
 **示例：**
@@ -265,26 +395,28 @@ const { data, error } = await storage.remove([
 ]);
 ```
 
+---
+
 ### 文件列表
 
 #### `list(path?, options?, parameters?)`
 
 列出存储桶中的文件。
 
-**参数：**
-- `path` (string, 可选): 文件夹路径
-- `options` (SearchOptions, 可选): 搜索选项
-- `parameters` (FetchParameters, 可选): 请求参数
+**入参：**
+```typescript
+function list(
+  path?: string,              // 文件夹路径
+  options?: SearchOptions,    // 搜索选项
+  parameters?: FetchParameters // 请求参数
+): Promise<ListResult>
+```
 
-**返回：**
+**出参：**
 ```typescript
-{
-  data: FileObject[];  // 文件列表
-  error: null;
-} | {
-  data: null;
-  error: StorageError;
-}
+type ListResult =
+  | { data: FileObject[]; error: null }
+  | { data: null; error: StorageError }
 ```
 
 **示例：**
@@ -304,99 +436,208 @@ const { data, error } = await storage.list('documents', {
 });
 ```
 
+---
+
 ## 类型定义
 
 ### FileBody
+
 支持以下文件格式：
-- `ArrayBuffer`
-- `ArrayBufferView` 
-- `Blob`
-- `Buffer`
-- `File`
-- `FormData`
-- `NodeJS.ReadableStream`
-- `ReadableStream<Uint8Array>`
-- `URLSearchParams`
-- `string`
+
+```typescript
+type FileBody =
+  | ArrayBuffer
+  | ArrayBufferView
+  | Blob
+  | Buffer
+  | File
+  | FormData
+  | NodeJS.ReadableStream
+  | ReadableStream<Uint8Array>
+  | URLSearchParams
+  | string;
+```
 
 ### FileOptions
+
 ```typescript
 interface FileOptions {
-  cacheControl?: string | number;    // 缓存控制（秒）
-  contentType?: string;              // 内容类型
-  upsert?: boolean;                  // 是否覆盖已存在文件
-  duplex?: string;                   // 双工流选项
-  metadata?: Record<string, any>;    // 元数据
-  headers?: Record<string, string>;   // 额外请求头
+  /** 缓存控制时间（秒），设置 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>;
 }
 ```
 
 ### FileOptionsV2
-```typescript
-interface FileOptionsV2 {
-  filePath?: string;                 // 文件路径（用于 uploadFile）
-  cacheControl?: string | number;    // 缓存控制（秒）
-  contentType?: string;              // 内容类型
-  upsert?: boolean;                  // 是否覆盖已存在文件
-  contentDisposition?: string;       // 内容处置
-}
-```
 
-### TransformOptions
 ```typescript
-interface TransformOptions {
-  width?: number;                    // 宽度（像素）
-  height?: number;                   // 高度（像素）
-  resize?: 'cover' | 'contain' | 'fill';  // 调整大小模式
-  quality?: number;                  // 质量（20-100）
-  format?: 'origin';                 // 格式
+interface FileOptionsV2 {
+  /** 文件上传路径 */
+  filePath?: string;
+  /** 缓存控制时间（秒） */
+  cacheControl?: string | number;
+  /** Content-Type 头值 */
+  contentType?: string;
+  /** 是否覆盖已存在文件，默认 false */
+  upsert?: boolean;
+  /** Content-Disposition 响应头值 */
+  contentDisposition?: string;
 }
 ```
 
 ### UploadFileData
+
 ```typescript
 interface UploadFileData {
-  id: string;                        // 文件ID
-  file_path: string;                 // 文件路径
-  bucket_id: string;                 // 存储桶ID
-  download_url: string;              // 下载URL
+  /** 文件ID */
+  id: string;
+  /** 文件路径 */
+  file_path: string;
+  /** 存储桶ID */
+  bucket_id: string;
+  /** 下载URL */
+  download_url: string;
 }
 ```
 
 ### FileObject
+
 ```typescript
 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;                   // 存储桶信息
+  /** 文件名 */
+  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;
+}
+```
+
+### Bucket
+
+```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;
 }
 ```
 
 ### SearchOptions
+
 ```typescript
 interface SearchOptions {
-  limit?: number;                    // 返回文件数量（默认100）
-  offset?: number;                   // 起始位置
-  sortBy?: SortBy;                   // 排序选项
-  search?: string;                   // 搜索字符串
+  /** 返回文件数量，默认 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';
 }
 ```
 
 ### FetchParameters
+
 ```typescript
 interface FetchParameters {
-  signal?: AbortSignal;              // AbortController 信号
+  /** AbortController 信号，用于取消请求 */
+  signal?: AbortSignal;
+}
+```
+
+### StorageError
+
+```typescript
+class StorageError extends Error {
+  message: string;
 }
 ```
 
+### 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` 包含错误信息。
@@ -406,13 +647,13 @@ const { data, error } = await storage.upload('test.jpg', file);
 
 if (error) {
   console.error('操作失败:', error.message);
-  // 错误处理
 } else {
   console.log('操作成功:', data);
-  // 处理返回数据
 }
 ```
 
+---
+
 ## 高级用法
 
 ### 日志记录
@@ -444,7 +685,6 @@ const storage = new StorageFileApi(
   false,
   (error) => {
     console.error('请求错误:', error);
-    // 自定义错误处理
   }
 );
 ```
@@ -468,6 +708,8 @@ const storage = new StorageFileApi(
 );
 ```
 
+---
+
 ## 许可证
 
 MIT License