@ticatec/restful_service_api 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ticatec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-CN.md

@@ -0,0 +1,410 @@
+# @ticatec/restful_service_api
+
+中文版 | [English](README.md)
+
+一个轻量级的 TypeScript RESTful API 浏览器客户端，具有完善的错误处理和拦截器支持。
+
+## 特性
+
+- 🚀 **轻量级**: 零依赖，专为现代浏览器构建
+- 🔧 **TypeScript 支持**: 完整的类型安全和 TypeScript 定义
+- 🛡️ **错误处理**: 内置错误处理机制，包含自定义 ApiError 类
+- ⚡ **拦截器**: 支持请求前后拦截器，用于身份验证和数据处理
+- 🎯 **灵活性**: 支持自定义请求头、超时设置和数据处理器
+- 🌐 **浏览器优先**: 专为前端应用程序设计
+
+## 安装
+
+```bash
+npm install @ticatec/restful_service_api
+```
+
+## 快速开始
+
+```typescript
+import RestService from '@ticatec/restful_service_api';
+
+// 实现 RestService 接口
+class MyApiClient implements RestService {
+  async get(url: string, params?: any) {
+    // 在这里实现
+  }
+  
+  async post(url: string, data: any, params?: any, contentType?: string) {
+    // 在这里实现
+  }
+  
+  // ... 其他方法
+}
+
+const api = new MyApiClient();
+
+// 发起请求
+const users = await api.get('/users');
+const newUser = await api.post('/users', { name: '张三' });
+```
+
+## API 参考
+
+### RestService 接口
+
+定义 REST 操作契约的主要接口：
+
+```typescript
+interface RestService {
+  get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any>;
+  post(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+  put(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+  del(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+  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>;
+}
+```
+
+### 方法说明
+
+#### `get(url, params?, dataProcessor?)`
+- **url**: 接口端点 URL
+- **params**: 查询参数（可选）
+- **dataProcessor**: 处理响应数据的函数（可选）
+
+#### `post(url, data, params?, contentType?, dataProcessor?)`
+- **url**: 接口端点 URL
+- **data**: 请求载荷
+- **params**: 查询参数（可选）
+- **contentType**: Content-Type 请求头（可选，默认为 application/json）
+- **dataProcessor**: 处理响应数据的函数（可选）
+
+#### `put(url, data, params?, contentType?, dataProcessor?)`
+类似于 POST，但用于更新操作。
+
+#### `del(url, data, params?, contentType?, dataProcessor?)`
+用于删除操作，支持可选的请求体。
+
+#### `upload(url, params, file, fileKey?, dataProcessor?)`
+- **url**: 上传端点 URL
+- **params**: 上传请求的附加参数
+- **file**: 要上传的文件对象
+- **fileKey**: 可选的文件表单字段名（默认为 'file'）
+- **dataProcessor**: 处理响应数据的函数（可选）
+
+#### `asyncUpload(url, params, file, callback, fileKey?)`
+- **url**: 上传端点 URL
+- **params**: 上传请求的附加参数
+- **file**: 要上传的文件对象
+- **callback**: 上传回调对象，包含进度、错误和完成处理函数
+- **fileKey**: 可选的文件表单字段名（默认为 'file'）
+- **返回值**: 返回 Promise，解析为 UploadProgress 对象，可用于取消上传
+
+#### `download(url, filename, params, method?, formData?)`
+- **url**: 下载端点 URL
+- **filename**: 保存下载文件的名称
+- **params**: 下载请求参数
+- **method**: 可选的 HTTP 方法（默认为 GET）
+- **formData**: 可选的表单数据，用于 POST 下载
+
+### 错误处理
+
+库包含自定义的 `ApiError` 类用于处理 API 错误：
+
+```typescript
+import { ApiError } from '@ticatec/restful_service_api';
+
+try {
+  const result = await api.get('/users');
+} catch (error) {
+  if (error instanceof ApiError) {
+    console.log('状态码:', error.status);
+    console.log('错误代码:', error.code);
+    console.log('错误详情:', error.details);
+  }
+}
+```
+
+### 类型和拦截器
+
+```typescript
+import { 
+  PreInterceptor, 
+  PostInterceptor, 
+  ErrorHandler, 
+  DataProcessor 
+} from '@ticatec/restful_service_api';
+
+// 请求前拦截器，用于添加认证头
+const preInterceptor: PreInterceptor = (method: string, url: string) => {
+  return {
+    headers: {
+      'Authorization': 'Bearer ' + getToken(),
+      'X-Request-ID': generateRequestId()
+    },
+    timeout: 30000
+  };
+};
+
+// 响应后拦截器，用于处理响应数据
+const postInterceptor: PostInterceptor = async (data: any) => {
+  // 处理响应数据
+  return data;
+};
+
+// 错误处理器
+const errorHandler: ErrorHandler = (error: Error) => {
+  console.error('API 错误:', error);
+  return true; // 返回 true 表示错误已处理
+};
+
+// 数据处理器
+const dataProcessor: DataProcessor = (data: any) => {
+  // 转换响应数据
+  return data.results || data;
+};
+```
+
+### 内容类型
+
+预定义的内容类型常量：
+
+```typescript
+import { 
+  CONTENT_TYPE_NAME,
+  TYPE_JSON,
+  TYPE_HTML,
+  TYPE_TEXT 
+} from '@ticatec/restful_service_api';
+
+// 使用示例
+await api.post('/upload', data, {}, TYPE_JSON);
+```
+
+## 实现示例
+
+以下是使用原生 fetch API 的完整实现示例：
+
+```typescript
+import RestService, { 
+  ApiError, 
+  PreInterceptor, 
+  PostInterceptor,
+  TYPE_JSON 
+} from '@ticatec/restful_service_api';
+
+class FetchRestService implements RestService {
+  private baseURL: string;
+  private preInterceptor?: PreInterceptor;
+  private postInterceptor?: PostInterceptor;
+
+  constructor(baseURL: string, preInterceptor?: PreInterceptor, postInterceptor?: PostInterceptor) {
+    this.baseURL = baseURL;
+    this.preInterceptor = preInterceptor;
+    this.postInterceptor = postInterceptor;
+  }
+
+  async get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any> {
+    const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+    return this.request('GET', url + queryString, null, undefined, dataProcessor);
+  }
+
+  async post(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
+    return this.request('POST', url, data, contentType, dataProcessor);
+  }
+
+  async put(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
+    return this.request('PUT', url, data, contentType, dataProcessor);
+  }
+
+  async del(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
+    return this.request('DELETE', url, data, contentType, dataProcessor);
+  }
+
+  private async request(method: string, url: string, body?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any> {
+    const fullUrl = this.baseURL + url;
+    
+    // 应用请求前拦截器
+    const interceptorResult = this.preInterceptor?.(method, fullUrl) || { headers: {} };
+    
+    const headers = {
+      ...interceptorResult.headers,
+      ...(contentType && { 'Content-Type': contentType })
+    };
+
+    try {
+      const response = await fetch(fullUrl, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: interceptorResult.timeout ? AbortSignal.timeout(interceptorResult.timeout) : undefined
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new ApiError(response.status, errorData);
+      }
+
+      let data = await response.json();
+      
+      // 应用响应后拦截器
+      if (this.postInterceptor) {
+        data = await this.postInterceptor(data);
+      }
+      
+      // 应用数据处理器
+      if (dataProcessor) {
+        data = dataProcessor(data);
+      }
+
+      return data;
+    } catch (error) {
+      if (error instanceof ApiError) {
+        throw error;
+      }
+      throw new ApiError(0, { code: 'NETWORK_ERROR', message: error.message });
+    }
+  }
+}
+
+// 使用示例
+const api = new FetchRestService('https://api.example.com');
+const users = await api.get('/users');
+```
+
+### 文件上传和下载示例
+
+```typescript
+import RestService, { 
+    UploadCallback, 
+    UploadProgress 
+} from '@ticatec/restful_service_api';
+
+// 简单文件上传
+const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
+const file = fileInput.files[0];
+
+try {
+    const result = await api.upload('/upload', { userId: 123 }, file);
+    console.log('上传成功:', result);
+} catch (error) {
+    console.error('上传失败:', error);
+}
+
+// 带进度跟踪的异步上传
+const uploadCallback: UploadCallback = {
+    method: 'POST',
+    progressUpdate: (uploadedBytes: number) => {
+        console.log(`已上传: ${uploadedBytes} 字节`);
+    },
+    handleError: (error: Error) => {
+        console.error('上传错误:', error);
+    },
+    onCompleted: (data: any) => {
+        console.log('上传完成:', data);
+    }
+};
+
+const uploadProgress = await api.asyncUpload('/upload', { userId: 123 }, file, uploadCallback);
+
+// 需要时可以取消上传
+setTimeout(() => {
+    uploadProgress.cancel();
+}, 5000);
+
+// 文件下载
+try {
+    await api.download('/files/document.pdf', 'my-document.pdf', { userId: 123 });
+    console.log('下载完成');
+} catch (error) {
+    console.error('下载失败:', error);
+}
+
+// 使用表单数据的 POST 下载
+const formData = { reportType: 'monthly', format: 'pdf' };
+await api.download('/reports/generate', 'monthly-report.pdf', {}, 'POST', formData);
+```
+
+## 工具函数
+
+该库包含用于常见操作的工具函数：
+
+```typescript
+import utils from '@ticatec/restful_service_api/utils';
+
+// 将对象转换为查询字符串
+const queryString = utils.toQueryString({ name: 'John', age: 30 });
+// 返回: "name=John&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' } }
+
+// 清理参数（移除 null、undefined、空字符串，修剪字符串值）
+const cleanedParams = utils.cleanParams({ name: ' John ', age: null, email: '' });
+// 返回: { name: 'John' }
+
+// 函数工具
+utils.invokeFunction(callback, arg1, arg2); // 安全地调用函数（如果存在）
+const isFunc = utils.isFunction(someValue); // 检查值是否为函数
+```
+
+### 可用的工具函数
+
+- **`toQueryString(obj)`**: 将对象转换为 URL 查询字符串
+- **`combineUrl(url, params)`**: 将 URL 与查询参数组合
+- **`generateRequestOptions(method, params, data)`**: 生成 HTTP 请求选项
+- **`cleanParams(params)`**: 通过移除 null/空值和修剪字符串来清理参数
+- **`isFunction(value)`**: 检查值是否为函数
+- **`invokeFunction(func, ...args)`**: 安全地调用函数（如果存在）
+
+## 高级用法
+
+### 带认证的完整示例
+
+```typescript
+// 设置认证拦截器
+const authInterceptor: PreInterceptor = (method, url) => ({
+  headers: {
+    'Authorization': `Bearer ${localStorage.getItem('token')}`,
+    'Accept': 'application/json'
+  },
+  timeout: 10000
+});
+
+// 设置响应处理拦截器
+const responseInterceptor: PostInterceptor = async (data) => {
+  // 处理通用响应格式
+  if (data.success === false) {
+    throw new Error(data.message);
+  }
+  return data.data || data;
+};
+
+const api = new FetchRestService(
+  'https://api.example.com',
+  authInterceptor,
+  responseInterceptor
+);
+
+// 现在所有请求都会自动包含认证头
+const profile = await api.get('/user/profile');
+const updated = await api.put('/user/profile', { name: '新名称' });
+```
+
+## 贡献
+
+欢迎贡献代码！请随时提交 Pull Request。
+
+## 许可证
+
+MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。
+
+## 作者
+
+Henry Feng
+
+---
+
+更多示例和高级用法，请查看[文档](https://github.com/ticatec/restful_service_api)。

package/README.md

@@ -0,0 +1,376 @@
+# @ticatec/restful_service_api
+
+[中文版](README-CN.md) | English
+
+A lightweight TypeScript RESTful API client for browsers with comprehensive error handling and interceptor support.
+
+## Features
+
+- 🚀 **Lightweight**: Zero dependencies, built for modern browsers
+- 🔧 **TypeScript Support**: Full type safety with TypeScript definitions
+- 🛡️ **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
+- 🌐 **Browser-First**: Designed specifically for frontend applications
+
+## Installation
+
+```bash
+npm install @ticatec/restful_service_api
+```
+
+## Quick Start
+
+```typescript
+import RestService from '@ticatec/restful_service_api';
+
+// Your implementation of RestService interface
+class MyApiClient implements RestService {
+    async get(url: string, params?: any) {
+        // Implementation here
+    }
+
+    async post(url: string, data: any, params?: any, contentType?: string) {
+        // Implementation here
+    }
+
+    // ... other methods
+}
+
+const api = new MyApiClient();
+
+// Make requests
+const users = await api.get('/users');
+const newUser = await api.post('/users', { name: 'John Doe' });
+```
+
+## API Reference
+
+### RestService Interface
+
+The main interface that defines the contract for REST operations:
+
+```typescript
+interface RestService {
+    get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any>;
+    post(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+    put(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+    del(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+    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
+
+#### `get(url, params?, dataProcessor?)`
+- **url**: The endpoint URL
+- **params**: Query parameters (optional)
+- **dataProcessor**: Function to process response data (optional)
+
+#### `post(url, data, params?, contentType?, dataProcessor?)`
+- **url**: The endpoint URL
+- **data**: Request payload
+- **params**: Query parameters (optional)
+- **contentType**: Content-Type header (optional, defaults to application/json)
+- **dataProcessor**: Function to process response data (optional)
+
+#### `put(url, data, params?, contentType?, dataProcessor?)`
+Similar to POST but for update operations.
+
+#### `del(url, data, params?, contentType?, dataProcessor?)`
+For delete operations with optional request body.
+
+#### `upload(url, params, file, fileKey?, dataProcessor?)`
+- **url**: The upload endpoint URL
+- **params**: Additional parameters for the upload request
+- **file**: The File object to upload
+- **fileKey**: Optional form field name for the file (defaults to 'file')
+- **dataProcessor**: Function to process response data (optional)
+
+#### `asyncUpload(url, params, file, callback, fileKey?)`
+- **url**: The upload endpoint URL
+- **params**: Additional parameters for the upload request
+- **file**: The File object to upload
+- **callback**: Upload callback object with progress, error, and completion handlers
+- **fileKey**: Optional form field name for the file (defaults to 'file')
+- **Returns**: Promise that resolves to UploadProgress object for cancellation
+
+#### `download(url, filename, params, method?, formData?)`
+- **url**: The download endpoint URL
+- **filename**: The name to save the downloaded file
+- **params**: Download request parameters
+- **method**: Optional HTTP method (defaults to GET)
+- **formData**: Optional form data for POST downloads
+
+### Error Handling
+
+The library includes a custom `ApiError` class for handling API errors:
+
+```typescript
+import { ApiError } from '@ticatec/restful_service_api';
+
+try {
+    const result = await api.get('/users');
+} catch (error) {
+    if (error instanceof ApiError) {
+        console.log('Status:', error.status);
+        console.log('Code:', error.code);
+        console.log('Details:', error.details);
+    }
+}
+```
+
+### Types and Interceptors
+
+```typescript
+import {
+    PreInterceptor,
+    PostInterceptor,
+    ErrorHandler,
+    DataProcessor
+} from '@ticatec/restful_service_api';
+
+// Pre-interceptor for adding authentication headers
+const preInterceptor: PreInterceptor = (method: string, url: string) => {
+    return {
+        headers: {
+            'Authorization': 'Bearer ' + getToken(),
+            'X-Request-ID': generateRequestId()
+        },
+        timeout: 30000
+    };
+};
+
+// Post-interceptor for response processing
+const postInterceptor: PostInterceptor = async (data: any) => {
+    // Process response data
+    return data;
+};
+
+// Error handler
+const errorHandler: ErrorHandler = (error: Error) => {
+    console.error('API Error:', error);
+    return true; // Return true if error is handled
+};
+
+// Data processor
+const dataProcessor: DataProcessor = (data: any) => {
+    // Transform response data
+    return data.results || data;
+};
+```
+
+### Content Types
+
+Pre-defined content type constants:
+
+```typescript
+import {
+    CONTENT_TYPE_NAME,
+    TYPE_JSON,
+    TYPE_HTML,
+    TYPE_TEXT
+} from '@ticatec/restful_service_api';
+
+// Usage
+await api.post('/upload', data, {}, TYPE_JSON);
+```
+
+## Implementation Example
+
+Here's a complete example implementation using the native fetch API:
+
+```typescript
+import RestService, {
+    ApiError,
+    PreInterceptor,
+    PostInterceptor,
+    TYPE_JSON
+} from '@ticatec/restful_service_api';
+
+class FetchRestService implements RestService {
+    private baseURL: string;
+    private preInterceptor?: PreInterceptor;
+    private postInterceptor?: PostInterceptor;
+
+    constructor(baseURL: string, preInterceptor?: PreInterceptor, postInterceptor?: PostInterceptor) {
+        this.baseURL = baseURL;
+        this.preInterceptor = preInterceptor;
+        this.postInterceptor = postInterceptor;
+    }
+
+    async get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any> {
+        const queryString = params ? '?' + new URLSearchParams(params).toString() : '';
+        return this.request('GET', url + queryString, null, undefined, dataProcessor);
+    }
+
+    async post(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
+        return this.request('POST', url, data, contentType, dataProcessor);
+    }
+
+    async put(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
+        return this.request('PUT', url, data, contentType, dataProcessor);
+    }
+
+    async del(url: string, data: any, params?: any, contentType: string = TYPE_JSON, dataProcessor?: DataProcessor): Promise<any> {
+        return this.request('DELETE', url, data, contentType, dataProcessor);
+    }
+
+    private async request(method: string, url: string, body?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any> {
+        const fullUrl = this.baseURL + url;
+
+        // Apply pre-interceptor
+        const interceptorResult = this.preInterceptor?.(method, fullUrl) || { headers: {} };
+
+        const headers = {
+            ...interceptorResult.headers,
+            ...(contentType && { 'Content-Type': contentType })
+        };
+
+        try {
+            const response = await fetch(fullUrl, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: interceptorResult.timeout ? AbortSignal.timeout(interceptorResult.timeout) : undefined
+            });
+
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}));
+                throw new ApiError(response.status, errorData);
+            }
+
+            let data = await response.json();
+
+            // Apply post-interceptor
+            if (this.postInterceptor) {
+                data = await this.postInterceptor(data);
+            }
+
+            // Apply data processor
+            if (dataProcessor) {
+                data = dataProcessor(data);
+            }
+
+            return data;
+        } catch (error) {
+            if (error instanceof ApiError) {
+                throw error;
+            }
+            throw new ApiError(0, { code: 'NETWORK_ERROR', message: error.message });
+        }
+    }
+}
+
+// Usage
+const api = new FetchRestService('https://api.example.com');
+const users = await api.get('/users');
+```
+
+### File Upload and Download Examples
+
+```typescript
+import RestService, { 
+    UploadCallback, 
+    UploadProgress 
+} from '@ticatec/restful_service_api';
+
+// Simple file upload
+const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
+const file = fileInput.files[0];
+
+try {
+    const result = await api.upload('/upload', { userId: 123 }, file);
+    console.log('Upload successful:', result);
+} catch (error) {
+    console.error('Upload failed:', error);
+}
+
+// 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);
+    }
+};
+
+const uploadProgress = await api.asyncUpload('/upload', { userId: 123 }, file, uploadCallback);
+
+// Cancel upload if needed
+setTimeout(() => {
+    uploadProgress.cancel();
+}, 5000);
+
+// 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);
+}
+
+// POST download with form data
+const formData = { reportType: 'monthly', format: 'pdf' };
+await api.download('/reports/generate', 'monthly-report.pdf', {}, 'POST', formData);
+```
+
+## Utility Functions
+
+The library includes utility functions for common operations:
+
+```typescript
+import utils from '@ticatec/restful_service_api/utils';
+
+// Convert object to query string
+const queryString = utils.toQueryString({ name: 'John', age: 30 });
+// Returns: "name=John&age=30"
+
+// Combine URL with parameters
+const fullUrl = utils.combineUrl('/api/users', { page: 1, limit: 10 });
+// Returns: "/api/users?page=1&limit=10"
+
+// Generate HTTP request options
+const options = utils.generateRequestOptions('POST', { id: 1 }, { name: 'John' });
+// Returns: { method: 'POST', headers: {}, params: { id: 1 }, data: { name: 'John' } }
+
+// Clean parameters (removes null, undefined, empty strings, trims values)
+const cleanedParams = utils.cleanParams({ name: ' John ', age: null, email: '' });
+// Returns: { name: 'John' }
+
+// Function utilities
+utils.invokeFunction(callback, arg1, arg2); // Safely invoke function if it exists
+const isFunc = utils.isFunction(someValue); // Check if value is a function
+```
+
+### Available Utility Functions
+
+- **`toQueryString(obj)`**: Converts an object to URL query string
+- **`combineUrl(url, params)`**: Combines URL with query parameters
+- **`generateRequestOptions(method, params, data)`**: Generates HTTP request options
+- **`cleanParams(params)`**: Cleans parameters by removing null/empty values and trimming strings
+- **`isFunction(value)`**: Checks if a value is a function
+- **`invokeFunction(func, ...args)`**: Safely invokes a function if it exists
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+Henry Feng
+
+---
+
+For more examples and advanced usage, please check the [documentation](https://github.com/ticatec/restful_service_api).

package/dist/ApiError.d.ts

@@ -0,0 +1,9 @@
+export default class ApiError extends Error {
+    private _code;
+    private _details;
+    private _status;
+    get code(): any;
+    get details(): any;
+    get status(): any;
+    constructor(status: any, err: any);
+}

package/dist/ApiError.js

@@ -0,0 +1,18 @@
+export default class ApiError extends Error {
+    get code() {
+        return this._code;
+    }
+    get details() {
+        return this._details;
+    }
+    get status() {
+        return this._status;
+    }
+    constructor(status, err) {
+        super(err.code);
+        this.name = this.constructor.name;
+        this._code = err.code;
+        this._status = status;
+        this._details = err;
+    }
+}

package/dist/RestService.d.ts

@@ -0,0 +1,89 @@
+import UploadCallback, { UploadProgress } from "./UploadCallback";
+export interface PreInterceptorResult {
+    /**
+     * 待增加的headers
+     */
+    headers: any;
+    /**
+     * 访问过期时间
+     */
+    timeout?: number;
+}
+export type DataProcessor = (data: any) => any;
+export type PreInterceptor = (method: string, url: string) => PreInterceptorResult;
+export type PostInterceptor = (data: any) => Promise<any>;
+export type ErrorHandler = (ex: Error) => boolean;
+export declare const CONTENT_TYPE_NAME = "Content-Type";
+export declare const TYPE_JSON = "application/json";
+export declare const TYPE_HTML = "text/html";
+export declare const TYPE_TEXT = "text/plain";
+export default interface RestService {
+    /**
+     * 执行HTTP GET请求获取资源
+     * @param url 请求的目标URL路径
+     * @param params 查询参数对象，将被转换为URL查询字符串
+     * @param dataProcessor 可选的数据处理函数，用于在返回前转换响应数据
+     * @returns 返回Promise，解析为服务器响应数据
+     */
+    get(url: string, params?: any, dataProcessor?: DataProcessor): Promise<any>;
+    /**
+     * 执行HTTP POST请求创建新资源
+     * @param url 请求的目标URL路径
+     * @param data 要发送的请求体数据，通常为对象或字符串
+     * @param params 可选的查询参数对象，将被转换为URL查询字符串
+     * @param contentType 可选的Content-Type头部，默认为application/json
+     * @param dataProcessor 可选的数据处理函数，用于在返回前转换响应数据
+     * @returns 返回Promise，解析为服务器响应数据
+     */
+    post(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+    /**
+     * 执行HTTP PUT请求更新现有资源
+     * @param url 请求的目标URL路径
+     * @param data 要发送的请求体数据，用于更新资源
+     * @param params 可选的查询参数对象，将被转换为URL查询字符串
+     * @param contentType 可选的Content-Type头部，默认为application/json
+     * @param dataProcessor 可选的数据处理函数，用于在返回前转换响应数据
+     * @returns 返回Promise，解析为服务器响应数据
+     */
+    put(url: string, data: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+    /**
+     * 执行HTTP DELETE请求删除资源
+     * @param url 请求的目标URL路径
+     * @param data 可选的请求体数据，某些DELETE操作可能需要发送数据
+     * @param params 可选的查询参数对象，将被转换为URL查询字符串
+     * @param contentType 可选的Content-Type头部，默认为application/json
+     * @param dataProcessor 可选的数据处理函数，用于在返回前转换响应数据
+     * @returns 返回Promise，解析为服务器响应数据
+     */
+    del(url: string, data?: any, params?: any, contentType?: string, dataProcessor?: DataProcessor): Promise<any>;
+    /**
+     * 执行同步文件上传操作
+     * @param url 上传的目标URL路径
+     * @param params 上传请求的参数对象
+     * @param file 要上传的文件对象
+     * @param fileKey 可选的文件字段名，默认为'file'
+     * @param dataProcessor 可选的数据处理函数，用于在返回前转换响应数据
+     * @returns 返回Promise，解析为服务器响应数据
+     */
+    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>;
+}

package/dist/RestService.js

@@ -0,0 +1,4 @@
+export const CONTENT_TYPE_NAME = 'Content-Type';
+export const TYPE_JSON = "application/json";
+export const TYPE_HTML = "text/html";
+export const TYPE_TEXT = "text/plain";

package/dist/UploadCallback.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 上传进度更新回调函数类型
+ * @param uploadBytes 已上传的字节数
+ */
+export type ProgressUpdate = (uploadBytes: number) => void;
+/**
+ * 上传错误处理回调函数类型
+ * @param e 上传过程中发生的错误对象
+ */
+export type ErrorHandler = (e: Error) => void;
+/**
+ * 上传完成回调函数类型
+ * @param data 服务器返回的响应数据
+ */
+export type OnCompleted = (data: any) => void;
+/**
+ * 上传进度控制接口，提供上传过程中的控制功能
+ */
+export interface UploadProgress {
+    /**
+     * 取消正在进行的上传操作
+     */
+    cancel: () => void;
+}
+/**
+ * 文件上传完成后的回调函数类型
+ * @param url 上传后文件的访问URL
+ * @param thumbnail 可选的缩略图URL
+ */
+export type OnUploaded = (url: string, thumbnail?: string) => void;
+/**
+ * 文件上传回调接口，定义上传过程中的各种回调函数
+ */
+export default interface UploadCallback {
+    /**
+     * HTTP请求方法，默认是POST，特殊情况允许PUT等方法
+     */
+    method: string;
+    /**
+     * 可选的上传进度更新回调函数
+     */
+    progressUpdate?: ProgressUpdate;
+    /**
+     * 可选的错误处理回调函数
+     */
+    handleError?: ErrorHandler;
+    /**
+     * 必需的上传完成回调函数
+     */
+    onCompleted: OnCompleted;
+}

package/dist/UploadCallback.js

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,4 @@
+import ApiError from "./ApiError";
+import { CONTENT_TYPE_NAME, TYPE_JSON, TYPE_HTML, TYPE_TEXT } from "./RestService";
+export { ApiError };
+export { CONTENT_TYPE_NAME, TYPE_JSON, TYPE_HTML, TYPE_TEXT };

package/dist/utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility functions for HTTP requests and URL manipulation
+ */
+declare const _default: {
+    toQueryString: (obj: Record<string, any>) => string | null;
+    combineUrl: (url: string, params: Record<string, any> | null) => string;
+    generateRequestOptions: (method: string, params?: any, data?: any) => any;
+    isFunction: (fun: any) => fun is Function;
+    invokeFunction: (fun: Function | null | undefined, ...args: any[]) => void;
+    cleanParams: (params: Record<string, any> | null | undefined) => Record<string, any> | null;
+};
+export default _default;

package/dist/utils.js

@@ -0,0 +1,103 @@
+/**
+ * Converts an object to a URL query string
+ *
+ * @param obj - Object containing key-value pairs to convert
+ * @returns Query string without leading '?' or null if no valid parameters
+ */
+const toQueryString = (obj) => {
+    let list = [];
+    Object.keys(obj).forEach(key => {
+        if (obj[key] != null && obj[key] !== '') {
+            list.push(encodeURIComponent(key) + '=' + encodeURIComponent(obj[key]));
+        }
+    });
+    return list.length === 0 ? null : list.join('&');
+};
+/**
+ * Combines a URL with query parameters
+ *
+ * @param url - Base URL string
+ * @param params - Object containing query parameters
+ * @returns Complete URL with query string appended
+ */
+const combineUrl = (url, params) => {
+    let qs = params == null ? null : toQueryString(params);
+    return qs == null ? url : `${url}?${qs}`;
+};
+/**
+ * Generates HTTP request options object
+ *
+ * @param method - HTTP method (GET, POST, PUT, DELETE, etc.)
+ * @param params - Optional query parameters
+ * @param data - Optional request body data
+ * @returns Request options object with method, headers, params, and data
+ */
+const generateRequestOptions = (method, params = null, data = null) => {
+    return {
+        method: method,
+        headers: {},
+        params,
+        data
+    };
+};
+/**
+ * Checks if a value is a function
+ *
+ * @param fun - Value to check
+ * @returns True if the value is a function, false otherwise
+ */
+const isFunction = (fun) => {
+    return fun != null && fun instanceof Function;
+};
+/**
+ * Safely invokes a function if it exists and is callable
+ *
+ * @param fun - Function to invoke (can be null/undefined)
+ * @param args - Arguments to pass to the function
+ */
+const invokeFunction = (fun, ...args) => {
+    if (isFunction(fun)) {
+        fun(...args);
+    }
+};
+/**
+ * Cleans parameters object by removing null values, empty strings, and trimming string values
+ *
+ * @param params - Object containing parameters to clean
+ * @returns New object with cleaned parameters, or null if no valid parameters remain
+ */
+const cleanParams = (params) => {
+    if (params == null) {
+        return null;
+    }
+    const cleaned = {};
+    let hasValidParams = false;
+    Object.keys(params).forEach(key => {
+        let value = params[key];
+        // Skip null and undefined values
+        if (value == null) {
+            return;
+        }
+        // Trim string values and skip empty strings
+        if (typeof value === 'string') {
+            value = value.trim();
+            if (value === '') {
+                return;
+            }
+        }
+        cleaned[key] = value;
+        hasValidParams = true;
+    });
+    return hasValidParams ? cleaned : null;
+};
+/**
+ * Utility functions for HTTP requests and URL manipulation
+ */
+export default {
+    toQueryString,
+    combineUrl,
+    generateRequestOptions,
+    isFunction,
+    invokeFunction,
+    cleanParams
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ticatec/restful_service_api",
+  "version": "0.1.5",
+  "description": "A lightweight TypeScript RESTful API client for browsers with error handling.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./ApiError": {
+      "import": "./dist/ApiError.js",
+      "require": "./dist/ApiError.js",
+      "types": "./dist/ApiError.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils.js",
+      "require": "./dist/utils.js",
+      "types": "./dist/utils.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepare": "npm run clean && npm run build",
+    "publish:public": "npm publish --access public"
+  },
+  "keywords": [
+    "rest",
+    "typescript",
+    "axios",
+    "browser",
+    "frontend",
+    "api-client"
+  ],
+  "author": "Henry Feng",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ticatec/rest_service_api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ticatec/rest_service_api/issues"
+  },
+  "homepage": "https://github.com/ticatec/rest_service_api/tree/main/README.md",
+  "dependencies": {
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"target": "ES2019",
+		"module": "ESNext",
+		"lib": ["DOM", "ES2019"],
+		"moduleResolution": "bundler",
+		"esModuleInterop": true,
+		"declaration": true,
+		"outDir": "dist",
+		"rootDir": "src",
+		"strict": true,
+		"skipLibCheck": true
+	},
+	"include": ["src"]
+}