@ticatec/restful_service_api 0.2.1 → 0.5.0

package/README-CN.md

@@ -14,7 +14,37 @@
 - 🛡️ **错误处理**: 内置错误处理机制，包含自定义 ApiError 类
 - ⚡ **拦截器**: 支持请求前后拦截器，用于身份验证和数据处理
 - 🎯 **灵活性**: 支持自定义请求头、超时设置和数据处理器
+- 📁 **文件操作**: 专用的文件上传/下载接口
 - 🌐 **浏览器优先**: 专为前端应用程序设计
+- ✨ **PATCH 支持**: 完整支持 HTTP PATCH 方法进行部分更新
+
+## ⚠️ v0.5.0 重大变更
+
+**从 0.5.0 版本开始，此包已迁移到 ESM (ECMAScript Modules) 格式。**
+
+### 对您的影响
+
+- 您的项目必须使用 ESM 格式（package.json 中包含 `"type": "module"` 或使用 `.mjs` 扩展名）
+- 不再支持 `require()`，请使用 `import` 语句
+
+### 迁移指南
+
+如果您正在从 0.5.0 之前的版本升级：
+
+**之前 (CommonJS):**
+```javascript
+const RestService = require('@ticatec/restful_service_api');
+```
+
+**之后 (ESM):**
+```typescript
+import RestService from '@ticatec/restful_service_api';
+```
+
+对于 CommonJS 项目，您可能需要使用动态导入：
+```javascript
+const { default: RestService } = await import('@ticatec/restful_service_api');
+```
 
 ## 安装
 
@@ -25,7 +55,7 @@ npm install @ticatec/restful_service_api
 ## 快速开始
 
 ```typescript
-import RestService from '@ticatec/restful_service_api';
+import RestService, { FileService } from '@ticatec/restful_service_api';
 
 // 实现 RestService 接口
 class MyApiClient implements RestService {
@@ -37,42 +67,78 @@ class MyApiClient implements RestService {
     // 在这里实现
   }
 
+  async patch(url: string, data?: any, options?: RestfulOptions) {
+    // 在这里实现
+  }
+
   // ... 其他方法
 }
 
+// 实现 FileService 接口
+class MyFileClient implements FileService {
+  async upload(url: string, params: any, file: File, fileKey?: string, dataProcessor?: DataProcessor) {
+    // 在这里实现
+  }
+
+  async asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string) {
+    // 在这里实现
+  }
+
+  async download(url: string, filename: string, params: any, method?: string, formData?: any) {
+    // 在这里实现
+  }
+}
+
 const api = new MyApiClient();
+const fileApi = new MyFileClient();
 
-// 发起请求
+// 发起 REST 请求
 const users = await api.get('/users');
 const newUser = await api.post('/users', { name: '张三' });
+const partialUpdate = await api.patch('/users/1', { status: 'active' });
+
+// 文件操作
+const result = await fileApi.upload('/upload', { userId: 123 }, file);
 ```
 
 ## API 参考
 
 ### RestService 接口
 
-定义 REST 操作契约的主要接口：
+用于标准 HTTP REST 操作的主要接口：
 
 ```typescript
 interface RestService {
   get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any>;
   post(url: string, data?: any, options?: RestfulOptions): Promise<any>;
   put(url: string, data?: any, options?: RestfulOptions): Promise<any>;
+  patch(url: string, data?: any, options?: RestfulOptions): Promise<any>;
   del(url: string, data?: any, options?: RestfulOptions): Promise<any>;
+}
+```
+
+### FileService 接口
+
+专用于文件上传和下载操作的接口：
+
+```typescript
+interface FileService {
   upload(url: string, params: any, file: File, fileKey?: string, dataProcessor?: DataProcessor): Promise<any>;
   asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string): Promise<UploadProgress>;
   download(url: string, filename: string, params: any, method?: string, formData?: any): Promise<any>;
 }
 ```
 
-### 方法说明
+### RestService 方法
 
 #### `get(url, params?, dataProcessor?)`
+执行 HTTP GET 请求获取资源。
 - **url**: 接口端点 URL
 - **params**: 查询参数（可选）
 - **dataProcessor**: 处理响应数据的函数（可选）
 
 #### `post(url, data?, options?)`
+执行 HTTP POST 请求创建新资源。
 - **url**: 接口端点 URL
 - **data**: 请求载荷（可选）
 - **options**: 可选的配置对象，包含：
@@ -81,20 +147,36 @@ interface RestService {
   - **dataProcessor**: 处理响应数据的函数（可选）
 
 #### `put(url, data?, options?)`
-类似于 POST，但用于更新操作。所有参数均为可选。
+执行 HTTP PUT 请求更新整个资源。
+- **url**: 接口端点 URL
+- **data**: 请求载荷（可选）
+- **options**: 可选的配置对象，包含：
+  - **params**: 查询参数（可选）
+  - **contentType**: Content-Type 请求头（可选，默认为 application/json）
+  - **dataProcessor**: 处理响应数据的函数（可选）
+
+#### `patch(url, data?, options?)`
+执行 HTTP PATCH 请求部分更新资源。
+- **url**: 接口端点 URL
+- **data**: 包含要更新字段的请求载荷（可选）
 - **options**: 可选的配置对象，包含：
   - **params**: 查询参数（可选）
   - **contentType**: Content-Type 请求头（可选，默认为 application/json）
   - **dataProcessor**: 处理响应数据的函数（可选）
 
 #### `del(url, data?, options?)`
-用于删除操作，支持可选的请求体。
+执行 HTTP DELETE 请求删除资源。
+- **url**: 接口端点 URL
+- **data**: 请求体数据（可选）
 - **options**: 可选的配置对象，包含：
   - **params**: 查询参数（可选）
   - **contentType**: Content-Type 请求头（可选，默认为 application/json）
   - **dataProcessor**: 处理响应数据的函数（可选）
 
+### FileService 方法
+
 #### `upload(url, params, file, fileKey?, dataProcessor?)`
+执行同步文件上传操作。
 - **url**: 上传端点 URL
 - **params**: 上传请求的附加参数
 - **file**: 要上传的文件对象
@@ -102,6 +184,7 @@ interface RestService {
 - **dataProcessor**: 处理响应数据的函数（可选）
 
 #### `asyncUpload(url, params, file, callback, fileKey?)`
+执行异步文件上传，支持进度监控和取消功能。
 - **url**: 上传端点 URL
 - **params**: 上传请求的附加参数
 - **file**: 要上传的文件对象
@@ -110,6 +193,7 @@ interface RestService {
 - **返回值**: 返回 Promise，解析为 UploadProgress 对象，可用于取消上传
 
 #### `download(url, filename, params, method?, formData?)`
+执行文件下载操作。
 - **url**: 下载端点 URL
 - **filename**: 保存下载文件的名称
 - **params**: 下载请求参数
@@ -202,13 +286,16 @@ await api.post('/upload', data, {}, { contentType: TYPE_JSON });
 
 以下是使用原生 fetch API 的完整实现示例：
 
+### RestService 实现
+
 ```typescript
 import RestService, {
   ApiError,
   PreInterceptor,
   PostInterceptor,
   RestfulOptions,
-  TYPE_JSON
+  TYPE_JSON,
+  DataProcessor
 } from '@ticatec/restful_service_api';
 
 class FetchRestService implements RestService {
@@ -241,6 +328,13 @@ class FetchRestService implements RestService {
     return this.request('PUT', url + queryString, data, contentType, options?.dataProcessor);
   }
 
+  async patch(url: string, data?: any, options?: RestfulOptions): Promise<any> {
+    const contentType = options?.contentType || TYPE_JSON;
+    const params = options?.params;
+    const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+    return this.request('PATCH', url + queryString, data, contentType, options?.dataProcessor);
+  }
+
   async del(url: string, data?: any, options?: RestfulOptions): Promise<any> {
     const contentType = options?.contentType || TYPE_JSON;
     const params = options?.params;
@@ -298,60 +392,140 @@ class FetchRestService implements RestService {
 const api = new FetchRestService('https://api.example.com');
 const users = await api.get('/users');
 const newUser = await api.post('/users', { name: '张三' });
-const updatedUser = await api.put('/users/1', { name: '李四' });
+const partialUpdate = await api.patch('/users/1', { status: 'active' });
+const fullUpdate = await api.put('/users/1', { name: '李四', age: 30 });
 ```
 
-### 文件上传和下载示例
+### FileService 实现
 
 ```typescript
-import RestService, { 
-    UploadCallback, 
-    UploadProgress 
-} from '@ticatec/restful_service_api';
+import FileService, { UploadCallback, UploadProgress, DataProcessor } from '@ticatec/restful_service_api';
 
-// 简单文件上传
-const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
-const file = fileInput.files[0];
+class FetchFileService implements FileService {
+  private baseURL: string;
 
-try {
-    const result = await api.upload('/upload', { userId: 123 }, file);
-    console.log('上传成功:', result);
-} catch (error) {
-    console.error('上传失败:', error);
-}
+  constructor(baseURL: string) {
+    this.baseURL = baseURL;
+  }
 
-// 带进度跟踪的异步上传
-const uploadCallback: UploadCallback = {
-    method: 'POST',
-    progressUpdate: (uploadedBytes: number) => {
-        console.log(`已上传: ${uploadedBytes} 字节`);
-    },
-    handleError: (error: Error) => {
-        console.error('上传错误:', error);
-    },
-    onCompleted: (data: any) => {
-        console.log('上传完成:', data);
+  async upload(url: string, params: any, file: File, fileKey?: string, dataProcessor?: DataProcessor): Promise<any> {
+    const formData = new FormData();
+    formData.append(fileKey || 'file', file);
+
+    // 添加附加参数
+    Object.keys(params).forEach(key => {
+      formData.append(key, params[key]);
+    });
+
+    const response = await fetch(this.baseURL + url, {
+      method: 'POST',
+      body: formData
+    });
+
+    if (!response.ok) {
+      throw new Error(`上传失败: ${response.statusText}`);
     }
-};
 
-const uploadProgress = await api.asyncUpload('/upload', { userId: 123 }, file, uploadCallback);
+    const data = await response.json();
+    return dataProcessor ? dataProcessor(data) : data;
+  }
+
+  async asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string): Promise<UploadProgress> {
+    const formData = new FormData();
+    formData.append(fileKey || 'file', file);
 
-// 需要时可以取消上传
-setTimeout(() => {
-    uploadProgress.cancel();
-}, 5000);
+    Object.keys(params).forEach(key => {
+      formData.append(key, params[key]);
+    });
 
-// 文件下载
-try {
-    await api.download('/files/document.pdf', 'my-document.pdf', { userId: 123 });
-    console.log('下载完成');
-} catch (error) {
-    console.error('下载失败:', error);
+    const xhr = new XMLHttpRequest();
+
+    return new Promise((resolve) => {
+      xhr.upload.addEventListener('progress', (e) => {
+        if (e.lengthComputable && callback.progressUpdate) {
+          callback.progressUpdate(e.loaded);
+        }
+      });
+
+      xhr.addEventListener('load', () => {
+        if (xhr.status >= 200 && xhr.status < 300) {
+          const data = JSON.parse(xhr.responseText);
+          callback.onCompleted(data);
+        } else if (callback.handleError) {
+          callback.handleError(new Error(`上传失败: ${xhr.statusText}`));
+        }
+      });
+
+      xhr.addEventListener('error', () => {
+        if (callback.handleError) {
+          callback.handleError(new Error('网络错误'));
+        }
+      });
+
+      xhr.open(callback.method || 'POST', this.baseURL + url);
+      xhr.send(formData);
+
+      resolve({
+        cancel: () => xhr.abort()
+      });
+    });
+  }
+
+  async download(url: string, filename: string, params: any, method?: string, formData?: any): Promise<any> {
+    let fullUrl = this.baseURL + url;
+
+    if (method === 'POST' && formData) {
+      const form = new FormData();
+      Object.keys(formData).forEach(key => {
+        form.append(key, formData[key]);
+      });
+
+      const response = await fetch(fullUrl, {
+        method: 'POST',
+        body: form
+      });
+
+      const blob = await response.blob();
+      const downloadUrl = window.URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = downloadUrl;
+      a.download = filename;
+      a.click();
+      window.URL.revokeObjectURL(downloadUrl);
+    } else {
+      const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+      fullUrl += queryString;
+
+      const response = await fetch(fullUrl);
+      const blob = await response.blob();
+      const downloadUrl = window.URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = downloadUrl;
+      a.download = filename;
+      a.click();
+      window.URL.revokeObjectURL(downloadUrl);
+    }
+  }
 }
 
-// 使用表单数据的 POST 下载
-const formData = { reportType: 'monthly', format: 'pdf' };
-await api.download('/reports/generate', 'monthly-report.pdf', {}, 'POST', formData);
+// 使用示例
+const fileApi = new FetchFileService('https://api.example.com');
+const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
+const file = fileInput.files[0];
+
+// 简单上传
+const result = await fileApi.upload('/upload', { userId: 123 }, file);
+
+// 带进度跟踪的异步上传
+const progress = await fileApi.asyncUpload('/upload', { userId: 123 }, file, {
+  method: 'POST',
+  progressUpdate: (loaded) => console.log(`已上传: ${loaded} 字节`),
+  onCompleted: (data) => console.log('完成！', data),
+  handleError: (err) => console.error('错误！', err)
+});
+
+// 下载文件
+await fileApi.download('/files/document.pdf', 'my-document.pdf', { userId: 123 });
 ```
 
 ## 工具函数
@@ -362,20 +536,20 @@ await api.download('/reports/generate', 'monthly-report.pdf', {}, 'POST', formDa
 import utils from '@ticatec/restful_service_api/utils';
 
 // 将对象转换为查询字符串
-const queryString = utils.toQueryString({ name: 'John', age: 30 });
-// 返回: "name=John&age=30"
+const queryString = utils.toQueryString({ name: '张三', age: 30 });
+// 返回: "name=张三&age=30"
 
 // 将 URL 与参数组合
 const fullUrl = utils.combineUrl('/api/users', { page: 1, limit: 10 });
 // 返回: "/api/users?page=1&limit=10"
 
 // 生成 HTTP 请求选项
-const options = utils.generateRequestOptions('POST', { id: 1 }, { name: 'John' });
-// 返回: { method: 'POST', headers: {}, params: { id: 1 }, data: { name: 'John' } }
+const options = utils.generateRequestOptions('POST', { id: 1 }, { name: '张三' });
+// 返回: { method: 'POST', headers: {}, params: { id: 1 }, data: { name: '张三' } }
 
 // 清理参数（移除 null、undefined、空字符串，修剪字符串值）
-const cleanedParams = utils.cleanParams({ name: ' John ', age: null, email: '' });
-// 返回: { name: 'John' }
+const cleanedParams = utils.cleanParams({ name: ' 张三 ', age: null, email: '' });
+// 返回: { name: '张三' }
 
 // 函数工具
 utils.invokeFunction(callback, arg1, arg2); // 安全地调用函数（如果存在）
@@ -423,6 +597,7 @@ const api = new FetchRestService(
 // 现在所有请求都会自动包含认证头
 const profile = await api.get('/user/profile');
 const updated = await api.put('/user/profile', { name: '新名称' });
+const partial = await api.patch('/user/profile', { status: 'active' });
 ```
 
 ## 贡献

package/README.md

@@ -14,7 +14,36 @@ A lightweight TypeScript RESTful API client for browsers with comprehensive erro
 - 🛡️ **Error Handling**: Built-in error handling with custom ApiError class
 - ⚡ **Interceptors**: Pre and post request interceptors for authentication and data processing
 - 🎯 **Flexible**: Support for custom headers, timeouts, and data processors
+- 📁 **File Operations**: Dedicated interface for file upload/download operations
 - 🌐 **Browser-First**: Designed specifically for frontend applications
+- ✨ **PATCH Support**: Full support for HTTP PATCH method for partial updates
+
+## ⚠️ Breaking Changes in v0.5.0
+
+**Starting from version 0.5.0, this package has migrated to ESM (ECMAScript Modules) format.**
+
+### What This Means for You
+
+- Your project must use ESM format (have `"type": "module"` in package.json or use `.mjs` extension)
+- `require()` is no longer supported. Use `import` statements instead
+### Migration Guide
+
+If you're upgrading from a version prior to 0.5.0:
+
+**Before (CommonJS):**
+```javascript
+const RestService = require('@ticatec/restful_service_api');
+```
+
+**After (ESM):**
+```typescript
+import RestService from '@ticatec/restful_service_api';
+```
+
+For CommonJS projects, you may need to use dynamic import:
+```javascript
+const { default: RestService } = await import('@ticatec/restful_service_api');
+```
 
 ## Installation
 
@@ -25,7 +54,7 @@ npm install @ticatec/restful_service_api
 ## Quick Start
 
 ```typescript
-import RestService from '@ticatec/restful_service_api';
+import RestService, { FileService } from '@ticatec/restful_service_api';
 
 // Your implementation of RestService interface
 class MyApiClient implements RestService {
@@ -37,42 +66,78 @@ class MyApiClient implements RestService {
         // Implementation here
     }
 
+    async patch(url: string, data?: any, options?: RestfulOptions) {
+        // Implementation here
+    }
+
     // ... other methods
 }
 
+// Your implementation of FileService interface
+class MyFileClient implements FileService {
+    async upload(url: string, params: any, file: File, fileKey?: string, dataProcessor?: DataProcessor) {
+        // Implementation here
+    }
+
+    async asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string) {
+        // Implementation here
+    }
+
+    async download(url: string, filename: string, params: any, method?: string, formData?: any) {
+        // Implementation here
+    }
+}
+
 const api = new MyApiClient();
+const fileApi = new MyFileClient();
 
-// Make requests
+// Make REST requests
 const users = await api.get('/users');
 const newUser = await api.post('/users', { name: 'John Doe' });
+const partialUpdate = await api.patch('/users/1', { status: 'active' });
+
+// File operations
+const result = await fileApi.upload('/upload', { userId: 123 }, file);
 ```
 
 ## API Reference
 
 ### RestService Interface
 
-The main interface that defines the contract for REST operations:
+The main interface for standard HTTP REST operations:
 
 ```typescript
 interface RestService {
     get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any>;
     post(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     put(url: string, data?: any, options?: RestfulOptions): Promise<any>;
+    patch(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     del(url: string, data?: any, options?: RestfulOptions): Promise<any>;
+}
+```
+
+### FileService Interface
+
+Dedicated interface for file upload and download operations:
+
+```typescript
+interface FileService {
     upload(url: string, params: any, file: File, fileKey?: string, dataProcessor?: DataProcessor): Promise<any>;
     asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string): Promise<UploadProgress>;
     download(url: string, filename: string, params: any, method?: string, formData?: any): Promise<any>;
 }
 ```
 
-### Methods
+### RestService Methods
 
 #### `get(url, params?, dataProcessor?)`
+Performs HTTP GET request to retrieve a resource.
 - **url**: The endpoint URL
 - **params**: Query parameters (optional)
 - **dataProcessor**: Function to process response data (optional)
 
 #### `post(url, data?, options?)`
+Performs HTTP POST request to create a new resource.
 - **url**: The endpoint URL
 - **data**: Request payload (optional)
 - **options**: Optional configuration object containing:
@@ -81,20 +146,36 @@ interface RestService {
   - **dataProcessor**: Function to process response data (optional)
 
 #### `put(url, data?, options?)`
-Similar to POST but for update operations. All parameters are optional.
+Performs HTTP PUT request to update an entire resource.
+- **url**: The endpoint URL
+- **data**: Request payload (optional)
+- **options**: Optional configuration object containing:
+  - **params**: Query parameters (optional)
+  - **contentType**: Content-Type header (optional, defaults to application/json)
+  - **dataProcessor**: Function to process response data (optional)
+
+#### `patch(url, data?, options?)`
+Performs HTTP PATCH request to partially update a resource.
+- **url**: The endpoint URL
+- **data**: Request payload with fields to update (optional)
 - **options**: Optional configuration object containing:
   - **params**: Query parameters (optional)
   - **contentType**: Content-Type header (optional, defaults to application/json)
   - **dataProcessor**: Function to process response data (optional)
 
 #### `del(url, data?, options?)`
-For delete operations with optional request body.
+Performs HTTP DELETE request to delete a resource.
+- **url**: The endpoint URL
+- **data**: Request body data (optional)
 - **options**: Optional configuration object containing:
   - **params**: Query parameters (optional)
   - **contentType**: Content-Type header (optional, defaults to application/json)
   - **dataProcessor**: Function to process response data (optional)
 
+### FileService Methods
+
 #### `upload(url, params, file, fileKey?, dataProcessor?)`
+Performs synchronous file upload operation.
 - **url**: The upload endpoint URL
 - **params**: Additional parameters for the upload request
 - **file**: The File object to upload
@@ -102,6 +183,7 @@ For delete operations with optional request body.
 - **dataProcessor**: Function to process response data (optional)
 
 #### `asyncUpload(url, params, file, callback, fileKey?)`
+Performs asynchronous file upload with progress monitoring and cancellation support.
 - **url**: The upload endpoint URL
 - **params**: Additional parameters for the upload request
 - **file**: The File object to upload
@@ -110,6 +192,7 @@ For delete operations with optional request body.
 - **Returns**: Promise that resolves to UploadProgress object for cancellation
 
 #### `download(url, filename, params, method?, formData?)`
+Performs file download operation.
 - **url**: The download endpoint URL
 - **filename**: The name to save the downloaded file
 - **params**: Download request parameters
@@ -202,13 +285,16 @@ await api.post('/upload', data, {}, { contentType: TYPE_JSON });
 
 Here's a complete example implementation using the native fetch API:
 
+### RestService Implementation
+
 ```typescript
 import RestService, {
     ApiError,
     PreInterceptor,
     PostInterceptor,
     RestfulOptions,
-    TYPE_JSON
+    TYPE_JSON,
+    DataProcessor
 } from '@ticatec/restful_service_api';
 
 class FetchRestService implements RestService {
@@ -241,6 +327,13 @@ class FetchRestService implements RestService {
         return this.request('PUT', url + queryString, data, contentType, options?.dataProcessor);
     }
 
+    async patch(url: string, data?: any, options?: RestfulOptions): Promise<any> {
+        const contentType = options?.contentType || TYPE_JSON;
+        const params = options?.params;
+        const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+        return this.request('PATCH', url + queryString, data, contentType, options?.dataProcessor);
+    }
+
     async del(url: string, data?: any, options?: RestfulOptions): Promise<any> {
         const contentType = options?.contentType || TYPE_JSON;
         const params = options?.params;
@@ -298,60 +391,140 @@ class FetchRestService implements RestService {
 const api = new FetchRestService('https://api.example.com');
 const users = await api.get('/users');
 const newUser = await api.post('/users', { name: 'John Doe' });
-const updatedUser = await api.put('/users/1', { name: 'Jane Doe' });
+const partialUpdate = await api.patch('/users/1', { status: 'active' });
+const fullUpdate = await api.put('/users/1', { name: 'Jane Doe', age: 30 });
 ```
 
-### File Upload and Download Examples
+### FileService Implementation
 
 ```typescript
-import RestService, { 
-    UploadCallback, 
-    UploadProgress 
-} from '@ticatec/restful_service_api';
+import FileService, { UploadCallback, UploadProgress, DataProcessor } from '@ticatec/restful_service_api';
 
-// Simple file upload
-const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
-const file = fileInput.files[0];
+class FetchFileService implements FileService {
+    private baseURL: string;
 
-try {
-    const result = await api.upload('/upload', { userId: 123 }, file);
-    console.log('Upload successful:', result);
-} catch (error) {
-    console.error('Upload failed:', error);
-}
+    constructor(baseURL: string) {
+        this.baseURL = baseURL;
+    }
 
-// Async upload with progress tracking
-const uploadCallback: UploadCallback = {
-    method: 'POST',
-    progressUpdate: (uploadedBytes: number) => {
-        console.log(`Uploaded: ${uploadedBytes} bytes`);
-    },
-    handleError: (error: Error) => {
-        console.error('Upload error:', error);
-    },
-    onCompleted: (data: any) => {
-        console.log('Upload completed:', data);
+    async upload(url: string, params: any, file: File, fileKey?: string, dataProcessor?: DataProcessor): Promise<any> {
+        const formData = new FormData();
+        formData.append(fileKey || 'file', file);
+
+        // Add additional parameters
+        Object.keys(params).forEach(key => {
+            formData.append(key, params[key]);
+        });
+
+        const response = await fetch(this.baseURL + url, {
+            method: 'POST',
+            body: formData
+        });
+
+        if (!response.ok) {
+            throw new Error(`Upload failed: ${response.statusText}`);
+        }
+
+        const data = await response.json();
+        return dataProcessor ? dataProcessor(data) : data;
     }
-};
 
-const uploadProgress = await api.asyncUpload('/upload', { userId: 123 }, file, uploadCallback);
+    async asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string): Promise<UploadProgress> {
+        const formData = new FormData();
+        formData.append(fileKey || 'file', file);
 
-// Cancel upload if needed
-setTimeout(() => {
-    uploadProgress.cancel();
-}, 5000);
+        Object.keys(params).forEach(key => {
+            formData.append(key, params[key]);
+        });
 
-// File download
-try {
-    await api.download('/files/document.pdf', 'my-document.pdf', { userId: 123 });
-    console.log('Download completed');
-} catch (error) {
-    console.error('Download failed:', error);
+        const xhr = new XMLHttpRequest();
+
+        return new Promise((resolve) => {
+            xhr.upload.addEventListener('progress', (e) => {
+                if (e.lengthComputable && callback.progressUpdate) {
+                    callback.progressUpdate(e.loaded);
+                }
+            });
+
+            xhr.addEventListener('load', () => {
+                if (xhr.status >= 200 && xhr.status < 300) {
+                    const data = JSON.parse(xhr.responseText);
+                    callback.onCompleted(data);
+                } else if (callback.handleError) {
+                    callback.handleError(new Error(`Upload failed: ${xhr.statusText}`));
+                }
+            });
+
+            xhr.addEventListener('error', () => {
+                if (callback.handleError) {
+                    callback.handleError(new Error('Network error'));
+                }
+            });
+
+            xhr.open(callback.method || 'POST', this.baseURL + url);
+            xhr.send(formData);
+
+            resolve({
+                cancel: () => xhr.abort()
+            });
+        });
+    }
+
+    async download(url: string, filename: string, params: any, method?: string, formData?: any): Promise<any> {
+        let fullUrl = this.baseURL + url;
+
+        if (method === 'POST' && formData) {
+            const form = new FormData();
+            Object.keys(formData).forEach(key => {
+                form.append(key, formData[key]);
+            });
+
+            const response = await fetch(fullUrl, {
+                method: 'POST',
+                body: form
+            });
+
+            const blob = await response.blob();
+            const downloadUrl = window.URL.createObjectURL(blob);
+            const a = document.createElement('a');
+            a.href = downloadUrl;
+            a.download = filename;
+            a.click();
+            window.URL.revokeObjectURL(downloadUrl);
+        } else {
+            const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+            fullUrl += queryString;
+
+            const response = await fetch(fullUrl);
+            const blob = await response.blob();
+            const downloadUrl = window.URL.createObjectURL(blob);
+            const a = document.createElement('a');
+            a.href = downloadUrl;
+            a.download = filename;
+            a.click();
+            window.URL.revokeObjectURL(downloadUrl);
+        }
+    }
 }
 
-// POST download with form data
-const formData = { reportType: 'monthly', format: 'pdf' };
-await api.download('/reports/generate', 'monthly-report.pdf', {}, 'POST', formData);
+// Usage
+const fileApi = new FetchFileService('https://api.example.com');
+const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
+const file = fileInput.files[0];
+
+// Simple upload
+const result = await fileApi.upload('/upload', { userId: 123 }, file);
+
+// Async upload with progress
+const progress = await fileApi.asyncUpload('/upload', { userId: 123 }, file, {
+    method: 'POST',
+    progressUpdate: (loaded) => console.log(`Uploaded: ${loaded} bytes`),
+    onCompleted: (data) => console.log('Done!', data),
+    handleError: (err) => console.error('Error!', err)
+});
+
+// Download file
+await fileApi.download('/files/document.pdf', 'my-document.pdf', { userId: 123 });
 ```
 
 ## Utility Functions

package/dist/ApiError.d.ts

@@ -1,9 +1,26 @@
+/**
+ * API error class for handling HTTP request errors
+ */
 export default class ApiError extends Error {
     private _code;
     private _details;
     private _status;
+    /**
+     * Error code from the API response
+     */
     get code(): any;
+    /**
+     * Detailed error information from the API response
+     */
     get details(): any;
+    /**
+     * HTTP status code of the error response
+     */
     get status(): any;
+    /**
+     * Creates a new API error instance
+     * @param status HTTP status code
+     * @param err Error object containing code and details
+     */
     constructor(status: any, err: any);
 }

package/dist/ApiError.js

@@ -1,13 +1,30 @@
+/**
+ * API error class for handling HTTP request errors
+ */
 export default class ApiError extends Error {
+    /**
+     * Error code from the API response
+     */
     get code() {
         return this._code;
     }
+    /**
+     * Detailed error information from the API response
+     */
     get details() {
         return this._details;
     }
+    /**
+     * HTTP status code of the error response
+     */
     get status() {
         return this._status;
     }
+    /**
+     * Creates a new API error instance
+     * @param status HTTP status code
+     * @param err Error object containing code and details
+     */
     constructor(status, err) {
         super(err.code);
         this.name = this.constructor.name;

package/dist/FileService.d.ts

@@ -0,0 +1,92 @@
+import UploadCallback from "./UploadCallback";
+import { DataProcessor } from "./RestService";
+/**
+ * File service interface for file upload and download operations
+ */
+export default interface FileService {
+    /**
+     * Performs synchronous file upload operation
+     * @param url The target URL path for upload
+     * @param params Parameters object for the upload request
+     * @param file The file object to upload
+     * @param fileKey Optional file field name, defaults to 'file'
+     * @param dataProcessor Optional data processing function to transform response data before returning
+     * @returns Promise that resolves to the server response data
+     *
+     * @example
+     * ```typescript
+     * // Simple file upload
+     * const file = document.querySelector('input[type="file"]').files[0];
+     * const result = await fileService.upload('/api/upload', { userId: 123 }, file);
+     *
+     * // Upload with custom file key
+     * const result = await fileService.upload('/api/upload', {}, file, 'avatar');
+     *
+     * // Upload with data processor
+     * const result = await fileService.upload('/api/upload', {}, file, 'file', (data) => data.url);
+     * ```
+     */
+    upload(url: string, params: any, file: File, fileKey?: string, dataProcessor?: DataProcessor): Promise<any>;
+    /**
+     * Performs asynchronous file upload operation with progress monitoring and cancellation support
+     * @param url The target URL path for upload
+     * @param params Parameters object for the upload request
+     * @param file The file object to upload
+     * @param callback Callback function during upload process, including progress updates, error handling, etc.
+     * @param fileKey Optional file field name, defaults to 'file'
+     * @returns Promise that resolves to UploadProgress object, which can be used to cancel the upload
+     *
+     * @example
+     * ```typescript
+     * // Async upload with progress monitoring
+     * const progress = await fileService.asyncUpload(
+     *   '/api/upload',
+     *   { userId: 123 },
+     *   file,
+     *   {
+     *     onProgress: (loaded, total, percent) => {
+     *       console.log(`Upload: ${percent}%`);
+     *     },
+     *     onCompleted: (data) => {
+     *       console.log('Upload complete:', data);
+     *     },
+     *     onError: (error) => {
+     *       console.error('Upload failed:', error);
+     *     }
+     *   }
+     * );
+     *
+     * // Cancel the upload
+     * progress.abort();
+     * ```
+     */
+    asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string): Promise<import("./UploadCallback").UploadProgress>;
+    /**
+     * Performs file download operation
+     * @param url The URL path to download the file
+     * @param filename The filename to save as
+     * @param params Parameters object for the download request
+     * @param method Optional HTTP method, defaults to GET
+     * @param formData Optional form data for POST download
+     * @returns Promise that resolves to the download result
+     *
+     * @example
+     * ```typescript
+     * // Simple file download
+     * await fileService.download('/api/files/123', 'document.pdf', {});
+     *
+     * // Download with parameters
+     * await fileService.download('/api/files/export', 'report.xlsx', {
+     *   format: 'xlsx',
+     *   date: '2024-01-01'
+     * });
+     *
+     * // Download via POST
+     * await fileService.download('/api/files/generate', 'custom.pdf', {}, 'POST', {
+     *   template: 'invoice',
+     *   data: invoiceData
+     * });
+     * ```
+     */
+    download(url: string, filename: string, params: any, method?: string, formData?: any): Promise<any>;
+}

package/dist/FileService.js

@@ -0,0 +1 @@
+export {};

package/dist/RestService.d.ts

@@ -1,97 +1,171 @@
-import UploadCallback, { UploadProgress } from "./UploadCallback";
+/**
+ * Result object returned by pre-interceptor
+ */
 export interface PreInterceptorResult {
     /**
-     * 待增加的headers
+     * Additional headers to add to the request
      */
     headers: any;
     /**
-     * 访问过期时间
+     * Request timeout in milliseconds
      */
     timeout?: number;
 }
+/**
+ * Data processor function type for transforming response data
+ */
 export type DataProcessor = (data: any) => any;
+/**
+ * Pre-interceptor function type for modifying requests before sending
+ * @param method HTTP method (GET, POST, etc.)
+ * @param url Request URL
+ * @returns PreInterceptorResult object with optional headers and timeout
+ */
 export type PreInterceptor = (method: string, url: string) => PreInterceptorResult;
+/**
+ * Post-interceptor function type for processing responses after receiving
+ * @param data Response data from the server
+ * @returns Promise that resolves to processed data
+ */
 export type PostInterceptor = (data: any) => Promise<any>;
+/**
+ * Error handler function type for handling request errors
+ * @param ex The error object
+ * @returns Boolean indicating if the error was handled (true) or should be thrown (false)
+ */
 export type ErrorHandler = (ex: Error) => boolean;
+/**
+ * RESTful API request options
+ */
 export type RestfulOptions = {
     /**
-     * 可选的Content-Type头部，默认为application/json
+     * Optional Content-Type header, defaults to 'application/json'
      */
     contentType?: string;
     /**
-     * 可选的数据处理函数，用于在返回前转换响应数据
+     * Optional data processing function to transform response data before returning
      */
     dataProcessor?: DataProcessor;
     /**
-     * 可选的查询参数对象，将被转换为URL查询字符串
+     * Optional query parameters object that will be converted to URL query string
      */
     params?: any;
 };
+/**
+ * HTTP header name for Content-Type
+ */
 export declare const CONTENT_TYPE_NAME = "Content-Type";
+/**
+ * MIME type for JSON content
+ */
 export declare const TYPE_JSON = "application/json";
+/**
+ * MIME type for HTML content
+ */
 export declare const TYPE_HTML = "text/html";
+/**
+ * MIME type for plain text content
+ */
 export declare const TYPE_TEXT = "text/plain";
+/**
+ * RESTful API service interface for standard HTTP operations
+ */
 export default interface RestService {
     /**
-     * 执行HTTP GET请求获取资源
-     * @param url 请求的目标URL路径
-     * @param params 查询参数对象，将被转换为URL查询字符串
-     * @param dataProcessor 可选的数据处理函数，用于在返回前转换响应数据
-     * @returns 返回Promise，解析为服务器响应数据
+     * Performs an HTTP GET request to retrieve a resource
+     * @param url The target URL path for the request
+     * @param params Query parameters object that will be converted to URL query string
+     * @param dataProcessor Optional data processing function to transform response data before returning
+     * @returns Promise that resolves to the server response data
+     *
+     * @example
+     * ```typescript
+     * // Simple GET request
+     * const users = await restService.get('/api/users');
+     *
+     * // GET with query parameters
+     * const filteredUsers = await restService.get('/api/users', { page: 1, limit: 10 });
+     *
+     * // GET with data processor
+     * const users = await restService.get('/api/users', null, (data) => data.items);
+     * ```
      */
     get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any>;
     /**
-     * 执行HTTP POST请求创建新资源
-     * @param url 请求的目标URL路径
-     * @param data 要发送的请求体数据，通常为对象或字符串
-     * @param options 可选的请求配置选项，包含contentType和dataProcessor
-     * @returns 返回Promise，解析为服务器响应数据
+     * Performs an HTTP POST request to create a new resource
+     * @param url The target URL path for the request
+     * @param data Request body data to be sent, typically an object or string
+     * @param options Optional request configuration options, including contentType and dataProcessor
+     * @returns Promise that resolves to the server response data
+     *
+     * @example
+     * ```typescript
+     * // Simple POST request
+     * const newUser = await restService.post('/api/users', { name: 'John', age: 30 });
+     *
+     * // POST with custom content type
+     * const result = await restService.post('/api/data', formData, {
+     *   contentType: 'multipart/form-data'
+     * });
+     *
+     * // POST with data processor
+     * const user = await restService.post('/api/users', userData, {
+     *   dataProcessor: (data) => data.result
+     * });
+     * ```
      */
     post(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     /**
-     * 执行HTTP PUT请求更新现有资源
-     * @param url 请求的目标URL路径
-     * @param data 可选的要发送的请求体数据，用于更新资源
-     * @param options 可选的请求配置选项，包含contentType和dataProcessor
-     * @returns 返回Promise，解析为服务器响应数据
+     * Performs an HTTP PUT request to update an existing resource
+     * @param url The target URL path for the request
+     * @param data Optional request body data to be sent for updating the resource
+     * @param options Optional request configuration options, including contentType and dataProcessor
+     * @returns Promise that resolves to the server response data
+     *
+     * @example
+     * ```typescript
+     * // Update a user
+     * const updatedUser = await restService.put('/api/users/123', { name: 'John Doe' });
+     *
+     * // PUT without data (some APIs may support this)
+     * const result = await restService.put('/api/users/123/toggle-status');
+     * ```
      */
     put(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     /**
-     * 执行HTTP DELETE请求删除资源
-     * @param url 请求的目标URL路径
-     * @param data 可选的请求体数据，某些DELETE操作可能需要发送数据
-     * @param options 可选的请求配置选项，包含contentType和dataProcessor
-     * @returns 返回Promise，解析为服务器响应数据
+     * Performs an HTTP DELETE request to delete a resource
+     * @param url The target URL path for the request
+     * @param data Optional request body data, some DELETE operations may require sending data
+     * @param options Optional request configuration options, including contentType and dataProcessor
+     * @returns Promise that resolves to the server response data
+     *
+     * @example
+     * ```typescript
+     * // Delete a user
+     * await restService.del('/api/users/123');
+     *
+     * // DELETE with request body
+     * await restService.del('/api/users/batch', { ids: [1, 2, 3] });
+     * ```
      */
     del(url: string, data?: any, options?: RestfulOptions): Promise<any>;
     /**
-     * 执行同步文件上传操作
-     * @param url 上传的目标URL路径
-     * @param params 上传请求的参数对象
-     * @param file 要上传的文件对象
-     * @param fileKey 可选的文件字段名，默认为'file'
-     * @param dataProcessor 可选的数据处理函数，用于在返回前转换响应数据
-     * @returns 返回Promise，解析为服务器响应数据
+     * Performs an HTTP PATCH request to partially update a resource
+     * @param url The target URL path for the request
+     * @param data Optional request body data to be sent for partially updating the resource
+     * @param options Optional request configuration options, including contentType and dataProcessor
+     * @returns Promise that resolves to the server response data
+     *
+     * @example
+     * ```typescript
+     * // Partially update a user
+     * const updatedUser = await restService.patch('/api/users/123', { status: 'active' });
+     *
+     * // PATCH with options
+     * const result = await restService.patch('/api/users/123', { age: 31 }, {
+     *   dataProcessor: (data) => data.user
+     * });
+     * ```
      */
-    upload(url: string, params: any, file: File, fileKey?: string, dataProcessor?: DataProcessor): Promise<any>;
-    /**
-     * 执行异步文件上传操作，支持进度监控和取消功能
-     * @param url 上传的目标URL路径
-     * @param params 上传请求的参数对象
-     * @param file 要上传的文件对象
-     * @param callback 上传过程中的回调函数，包含进度更新、错误处理等
-     * @param fileKey 可选的文件字段名，默认为'file'
-     * @returns 返回Promise，解析为UploadProgress对象，可用于取消上传
-     */
-    asyncUpload(url: string, params: any, file: File, callback: UploadCallback, fileKey?: string): Promise<UploadProgress>;
-    /**
-     * 执行文件下载操作
-     * @param url 下载文件的URL路径
-     * @param filename 保存的文件名
-     * @param params 下载请求的参数对象
-     * @param method 可选的HTTP方法，默认为GET
-     * @param formData 可选的表单数据，用于POST下载
-     * @returns 返回Promise，解析为下载结果
-     */
-    download(url: string, filename: string, params: any, method?: string, formData?: any): Promise<any>;
+    patch(url: string, data?: any, options?: RestfulOptions): Promise<any>;
 }

package/dist/RestService.js

@@ -1,4 +1,16 @@
+/**
+ * HTTP header name for Content-Type
+ */
 export const CONTENT_TYPE_NAME = 'Content-Type';
+/**
+ * MIME type for JSON content
+ */
 export const TYPE_JSON = "application/json";
+/**
+ * MIME type for HTML content
+ */
 export const TYPE_HTML = "text/html";
+/**
+ * MIME type for plain text content
+ */
 export const TYPE_TEXT = "text/plain";

package/dist/UploadCallback.d.ts

@@ -1,51 +1,51 @@
 /**
- * 上传进度更新回调函数类型
- * @param uploadBytes 已上传的字节数
+ * Upload progress update callback function type
+ * @param uploadBytes Number of bytes uploaded
  */
 export type ProgressUpdate = (uploadBytes: number) => void;
 /**
- * 上传错误处理回调函数类型
- * @param e 上传过程中发生的错误对象
+ * Upload error handling callback function type
+ * @param e Error object that occurred during upload
  */
 export type ErrorHandler = (e: Error) => void;
 /**
- * 上传完成回调函数类型
- * @param data 服务器返回的响应数据
+ * Upload completion callback function type
+ * @param data Response data returned from the server
  */
 export type OnCompleted = (data: any) => void;
 /**
- * 上传进度控制接口，提供上传过程中的控制功能
+ * Upload progress control interface, providing control functions during upload process
  */
 export interface UploadProgress {
     /**
-     * 取消正在进行的上传操作
+     * Cancel the ongoing upload operation
      */
     cancel: () => void;
 }
 /**
- * 文件上传完成后的回调函数类型
- * @param url 上传后文件的访问URL
- * @param thumbnail 可选的缩略图URL
+ * Callback function type after file upload completion
+ * @param url File access URL after upload
+ * @param thumbnail Optional thumbnail URL
  */
 export type OnUploaded = (url: string, thumbnail?: string) => void;
 /**
- * 文件上传回调接口，定义上传过程中的各种回调函数
+ * File upload callback interface, defining various callback functions during upload process
  */
 export default interface UploadCallback {
     /**
-     * HTTP请求方法，默认是POST，特殊情况允许PUT等方法
+     * HTTP request method, defaults to POST, but allows PUT or other methods in special cases
      */
     method: string;
     /**
-     * 可选的上传进度更新回调函数
+     * Optional upload progress update callback function
      */
     progressUpdate?: ProgressUpdate;
     /**
-     * 可选的错误处理回调函数
+     * Optional error handling callback function
      */
     handleError?: ErrorHandler;
     /**
-     * 必需的上传完成回调函数
+     * Required upload completion callback function
      */
     onCompleted: OnCompleted;
 }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import ApiError from "./ApiError";
 import RestService from "./RestService";
+import FileService from "./FileService";
 import { ErrorHandler, PostInterceptor, PreInterceptor, DataProcessor } from "./RestService";
 import { PreInterceptorResult } from "./RestService";
 import { CONTENT_TYPE_NAME, TYPE_JSON, TYPE_HTML, TYPE_TEXT } from "./RestService";
@@ -7,6 +8,8 @@ import UploadCallback, { UploadProgress, ProgressUpdate, OnCompleted, OnUploaded
 import { RestfulOptions } from "./RestService";
 export default RestService;
 export { ApiError };
+export { RestService };
+export { FileService };
 export type { ErrorHandler, PostInterceptor, PreInterceptor, DataProcessor };
 export type { PreInterceptorResult };
 export { CONTENT_TYPE_NAME, TYPE_JSON, TYPE_HTML, TYPE_TEXT };

package/package.json

@@ -1,7 +1,8 @@
 {
+  "type": "module",
   "name": "@ticatec/restful_service_api",
-  "version": "0.2.1",
-  "description": "A lightweight TypeScript RESTful API client for browsers with error handling.",
+  "version": "0.5.0",
+  "description": "A lightweight TypeScript RESTful API client for browsers with error handling. (ESM only, v0.5.0+)",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",