@ticatec/restful_service_api 0.7.0 → 0.8.0

package/README-CN.md

@@ -18,6 +18,34 @@
 - 🌐 **浏览器优先**: 专为前端应用程序设计
 - ✨ **PATCH 支持**: 完整支持 HTTP PATCH 方法进行部分更新
 
+## ⚠️ v0.8.0 重大变更
+
+**`ErrorHandler` 已变更为返回 `Promise`（支持异步处理）。**
+
+### 对您的影响
+
+- `ErrorHandler` 函数类型现为 `(ex: Error) => Promise<boolean | void>`。
+- 错误处理器现在应定义为 `async` 异步函数或返回 `Promise`。
+- `UploadCallback.handleError` 统一采用 Promise 异步的 `ErrorHandler` 定义。
+
+### 迁移指南
+
+**之前（v0.7.x 及更早版本）：**
+```typescript
+const errorHandler: ErrorHandler = (error: Error) => {
+  console.error('API 错误:', error);
+  return true;
+};
+```
+
+**之后（v0.8.0+）：**
+```typescript
+const errorHandler: ErrorHandler = async (error: Error) => {
+  console.error('API 错误:', error);
+  return true;
+};
+```
+
 ## ⚠️ v0.7.0 重大变更
 
 **`RestfulOptions.contentType` 已被移除，改为使用通用的 `headers` 字段。**
@@ -282,7 +310,7 @@ const postInterceptor: PostInterceptor = async (data: any) => {
 };
 
 // 错误处理器
-const errorHandler: ErrorHandler = (error: Error) => {
+const errorHandler: ErrorHandler = async (error: Error) => {
   console.error('API 错误:', error);
   return true; // 返回 true 表示错误已处理
 };
@@ -498,18 +526,18 @@ class FetchFileService implements FileService {
         }
       });
 
-      xhr.addEventListener('load', () => {
+      xhr.addEventListener('load', async () => {
         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}`));
+          await callback.handleError(new Error(`上传失败: ${xhr.statusText}`));
         }
       });
 
-      xhr.addEventListener('error', () => {
+      xhr.addEventListener('error', async () => {
         if (callback.handleError) {
-          callback.handleError(new Error('网络错误'));
+          await callback.handleError(new Error('网络错误'));
         }
       });
 
@@ -572,7 +600,7 @@ 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)
+  handleError: async (err) => console.error('错误！', err)
 });
 
 // 下载文件

package/README.md

@@ -18,6 +18,34 @@ A lightweight TypeScript RESTful API client for browsers with comprehensive erro
 - 🌐 **Browser-First**: Designed specifically for frontend applications
 - ✨ **PATCH Support**: Full support for HTTP PATCH method for partial updates
 
+## ⚠️ Breaking Changes in v0.8.0
+
+**`ErrorHandler` has been changed to return a `Promise` (async support).**
+
+### What This Means for You
+
+- The `ErrorHandler` function type is now `(ex: Error) => Promise<boolean | void>`.
+- Error handler functions should now be `async` functions or return a `Promise`.
+- `UploadCallback.handleError` now adopts the unified Promise-based `ErrorHandler` type.
+
+### Migration Guide
+
+**Before (v0.7.x and earlier):**
+```typescript
+const errorHandler: ErrorHandler = (error: Error) => {
+    console.error('API Error:', error);
+    return true;
+};
+```
+
+**After (v0.8.0+):**
+```typescript
+const errorHandler: ErrorHandler = async (error: Error) => {
+    console.error('API Error:', error);
+    return true;
+};
+```
+
 ## ⚠️ Breaking Changes in v0.7.0
 
 **`RestfulOptions.contentType` has been removed in favor of a general-purpose `headers` field.**
@@ -281,7 +309,7 @@ const postInterceptor: PostInterceptor = async (data: any) => {
 };
 
 // Error handler
-const errorHandler: ErrorHandler = (error: Error) => {
+const errorHandler: ErrorHandler = async (error: Error) => {
     console.error('API Error:', error);
     return true; // Return true if error is handled
 };
@@ -498,18 +526,18 @@ class FetchFileService implements FileService {
                 }
             });
 
-            xhr.addEventListener('load', () => {
+            xhr.addEventListener('load', async () => {
                 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}`));
+                    await callback.handleError(new Error(`Upload failed: ${xhr.statusText}`));
                 }
             });
 
-            xhr.addEventListener('error', () => {
+            xhr.addEventListener('error', async () => {
                 if (callback.handleError) {
-                    callback.handleError(new Error('Network error'));
+                    await callback.handleError(new Error('Network error'));
                 }
             });
 
@@ -572,7 +600,7 @@ 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)
+    handleError: async (err) => console.error('Error!', err)
 });
 
 // Download file

package/dist/FileService.d.ts

@@ -51,7 +51,7 @@ export default interface FileService {
      *     onCompleted: (data) => {
      *       console.log('Upload complete:', data);
      *     },
-     *     handleError: (error) => {
+     *     handleError: async (error) => {
      *       console.error('Upload failed:', error);
      *     }
      *   }

package/dist/RestService.d.ts

@@ -31,9 +31,9 @@ export type PostInterceptor = (data: any) => Promise<any>;
 /**
  * Error handler function type for handling request errors
  * @param ex The error object
- * @returns Optional boolean or void. Errors always reject the returned Promise.
+ * @returns Promise that resolves to boolean or void. Errors always reject the returned Promise.
  */
-export type ErrorHandler = (ex: Error) => boolean | void;
+export type ErrorHandler = (ex: Error) => Promise<boolean | void>;
 /**
  * RESTful API request options
  */

package/dist/UploadCallback.d.ts

@@ -1,3 +1,4 @@
+import type { ErrorHandler } from "./RestService.js";
 /**
  * Upload progress update callback function type
  * @param uploadBytes Number of bytes uploaded
@@ -5,9 +6,8 @@
 export type ProgressUpdate = (uploadBytes: number) => void;
 /**
  * Upload error handling callback function type
- * @param e Error object that occurred during upload
  */
-export type ErrorHandler = (e: Error) => void;
+export type { ErrorHandler };
 /**
  * Upload completion callback function type
  * @param data Response data returned from the server

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@ticatec/restful_service_api",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A lightweight TypeScript RESTful API client for browsers with error handling. (ESM only, v0.6.0+)",
   "main": "dist/index.js",
   "module": "dist/index.js",