@czf0613/http_client 0.0.1 → 0.1.0

package/README.md

@@ -1 +1,171 @@
-# http_client_ts
+# @czf0613/http_client
+
+A simple HTTP client library built with fetch API, supporting a modified SSE (Server-Sent Events) protocol for browser environments.
+
+## Requirements
+
+- **Runtime**: ES2018+ compatible browsers
+- **Module System**: ES Module only (not compatible with CommonJS)
+- **Environment**: Browser only (Chrome, Firefox, Safari)
+- **Browser Support**: Works well on all major modern browsers
+
+## Installation
+
+Install the package using your preferred package manager:
+
+```bash
+# npm
+npm install @czf0613/http_client
+
+# pnpm
+pnpm add @czf0613/http_client
+
+# yarn
+yarn add @czf0613/http_client
+```
+
+## Usage
+
+### `joinUrlWithParams`
+
+Concatenates a URL with query parameters, automatically handling URL encoding.
+
+**Parameters:**
+- `url` (string): The base URL without any query parameters
+- `queryParams` (Record<string, string | number | boolean>): Query parameters as key-value pairs
+
+**Returns:** string - The complete URL with query parameters
+
+**Example:**
+
+```javascript
+import { joinUrlWithParams } from '@czf0613/http_client';
+
+const url = joinUrlWithParams('https://api.example.com/users', {
+  page: 1,
+  limit: 10,
+  search: 'hello world'
+});
+// Result: 'https://api.example.com/users?page=1&limit=10&search=hello%20world'
+
+// Automatic URL encoding for special characters
+const url2 = joinUrlWithParams('https://api.example.com/search', {
+  keyword: '你好世界'
+});
+// Result: 'https://api.example.com/search?keyword=%E4%BD%A0%E5%A5%BD%E4%B8%96%E7%95%8C'
+```
+
+### `makeHttpRequest`
+
+Makes an HTTP request with default configuration using the Fetch API.
+
+**Parameters:**
+- `url` (string): The request URL (without query parameters)
+- `method` (HttpMethod): HTTP method ('GET', 'POST', 'PUT', 'DELETE', 'HEAD'). Default: 'GET'
+- `queryParams` (Record<string, string | number> | null): Query parameters to be appended to the URL. Default: null
+- `customHeaders` (Record<string, string> | null): Custom headers (Content-Type is handled automatically). **Important: Do NOT include Content-Type in customHeaders as it will interfere with the automatic Content-Type generation.** Default: null
+- `body` (any | null): Request body for POST/PUT requests. Default: null
+  - String or number: sent as `text/plain`
+  - Object: sent as `application/json`
+  - FormData: sent as `multipart/form-data`
+- `timeoutMs` (number): Timeout in milliseconds. Default: 5000
+
+**Returns:** Promise<Response> - Fetch API Response object
+
+**Note:** This function does not handle exceptions by default. You should wrap it in a try-catch block.
+
+**Example:**
+
+```javascript
+import { makeHttpRequest } from '@czf0613/http_client';
+
+// GET request with query parameters
+const response = await makeHttpRequest(
+  'https://api.example.com/users',
+  'GET',
+  { page: 1, limit: 10 }
+);
+const data = await response.json();
+
+// POST request with JSON body
+const response = await makeHttpRequest(
+  'https://api.example.com/users',
+  'POST',
+  null,
+  null,
+  { name: 'John', age: 30 }
+);
+
+// POST request with FormData
+const formData = new FormData();
+formData.append('file', fileInput.files[0]);
+const response = await makeHttpRequest(
+  'https://api.example.com/upload',
+  'POST',
+  null,
+  null,
+  formData
+);
+
+// Custom timeout
+const response = await makeHttpRequest(
+  'https://api.example.com/slow-endpoint',
+  'GET',
+  null,
+  null,
+  null,
+  10000 // 10 seconds timeout
+);
+```
+
+### `makeSSERequest`
+
+Makes an SSE (Server-Sent Events) request and returns an async generator that yields streaming responses. This is an enhanced version of the browser's EventSource with additional features, but it's not fully compatible with the standard SSE protocol.
+
+**Parameters:**
+- `url` (string): The request URL (without query parameters)
+- `method` (HttpMethod): HTTP method ('GET', 'POST', 'PUT', 'DELETE', 'HEAD'). Default: 'GET'
+- `queryParams` (Record<string, string | number> | null): Query parameters to be appended to the URL. Default: null
+- `customHeaders` (Record<string, string> | null): Custom headers. **Important: Do NOT include Content-Type in customHeaders.** Default: null
+- `body` (any | null): Request body for POST/PUT requests. Default: null
+
+**Note:** For detailed parameter descriptions, see [`makeHttpRequest`](#makehttprequest) above. This function only handles responses in the format `data: xxx\n\n`. It does not throw exceptions by default; success/failure is indicated in the generator's return value.
+
+**Returns:** AsyncGenerator<string, boolean, undefined> - An async generator that yields each message as a string, and returns a boolean indicating success (true) or failure (false)
+
+**Example:**
+
+```javascript
+import { makeSSERequest } from '@czf0613/http_client';
+
+async function streamChat() {
+  const generator = makeSSERequest(
+    'https://api.example.com/chat',
+    'POST',
+    null,
+    null,
+    { message: 'Hello' }
+  );
+
+  // Manually iterate to receive chunks
+  while(true) {
+    const { done, value } = await generator.next();
+
+    if (done) {
+      // Check if the stream completed successfully
+      if (!value) {
+        console.error('SSE stream failed');
+      }
+
+      break;
+    }
+
+    // Get the message value
+    console.log('Received:', value);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/http_client.d.ts

@@ -14,6 +14,7 @@ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD';
  * @param queryParams 查询参数，会被自动拼接到url中（会自动进行转义）
  * @param customHeaders 自定义请求头，不需要写content-type这种会被自动处理的头
  * @param body 请求体，适用于POST/PUT请求，传入字符串、数字会被处理成text/plain，传入对象会被处理成application/json，传入FormData会被处理成multipart/form-data，目前不建议直接发送二进制对象
+ * @param timeoutMs 超时时间，单位毫秒，默认5秒。这个超时的时间指的是发出请求，到接收到请求头的时间，不包含读取请求体的时间。如果需要控制读取请求体的超时，请自行用Promise.race实现。
  * @returns 返回Fetch API的Response对象
  */
 export declare function makeHttpRequest(url: string, method?: HttpMethod, queryParams?: Record<string, string | number> | null, customHeaders?: Record<string, string> | null, body?: any | null, timeoutMs?: number): Promise<Response>;
@@ -23,7 +24,9 @@ export declare function makeHttpRequest(url: string, method?: HttpMethod, queryP
  * 目前这个接口只支持处理后端不停发送data: xxx\n\n这种格式的响应
  * 默认不抛出异常，会在生成器的返回值里面指明成功还是失败
  * @see makeHttpRequest 这里的参数说明
+ * @param connectTimeoutMs 连接超时时间，单位毫秒，默认30秒
+ * @param messageTimeoutMs 每条消息超时时间，单位毫秒，默认30秒
  * @returns 返回一个异步生成器，每次迭代返回一个字符串（流式响应）
  */
-export declare function makeSSERequest(url: string, method?: HttpMethod, queryParams?: Record<string, string | number> | null, customHeaders?: Record<string, string> | null, body?: any | null): AsyncGenerator<string, boolean, undefined>;
+export declare function makeSSERequest(url: string, method?: HttpMethod, queryParams?: Record<string, string | number> | null, customHeaders?: Record<string, string> | null, body?: any | null, connectTimeoutMs?: number, messageTimeoutMs?: number): AsyncGenerator<string, boolean, undefined>;
 export {};

package/dist/http_client.js

@@ -1,3 +1,4 @@
+import { sleep, TIMEOUT_MARKER } from './timer';
 /**
  * 拼接URL和查询参数，会自动处理转义
  * @param url 基础URL，不要带任何查询参数
@@ -29,6 +30,7 @@ const DEFAULT_TIMEOUT = 5000;
  * @param queryParams 查询参数，会被自动拼接到url中（会自动进行转义）
  * @param customHeaders 自定义请求头，不需要写content-type这种会被自动处理的头
  * @param body 请求体，适用于POST/PUT请求，传入字符串、数字会被处理成text/plain，传入对象会被处理成application/json，传入FormData会被处理成multipart/form-data，目前不建议直接发送二进制对象
+ * @param timeoutMs 超时时间，单位毫秒，默认5秒。这个超时的时间指的是发出请求，到接收到请求头的时间，不包含读取请求体的时间。如果需要控制读取请求体的超时，请自行用Promise.race实现。
  * @returns 返回Fetch API的Response对象
  */
 export async function makeHttpRequest(url, method = 'GET', queryParams = null, customHeaders = null, body = null, timeoutMs = DEFAULT_TIMEOUT) {
@@ -44,7 +46,9 @@ export async function makeHttpRequest(url, method = 'GET', queryParams = null, c
         // 无body时，不设置Content-Type
     }
     else if (body instanceof FormData) {
-        // 使用FormData时，浏览器会自动设置Content-Type和boundary，不要多手
+        // 使用FormData时，浏览器会自动设置Content-Type和boundary，不要多手，有我也得给你删了
+        delete customHeaders['Content-Type'];
+        delete customHeaders['content-type'];
     }
     else if (typeof body === 'string') {
         customHeaders['Content-Type'] = 'text/plain';
@@ -75,11 +79,13 @@ export async function makeHttpRequest(url, method = 'GET', queryParams = null, c
  * 目前这个接口只支持处理后端不停发送data: xxx\n\n这种格式的响应
  * 默认不抛出异常，会在生成器的返回值里面指明成功还是失败
  * @see makeHttpRequest 这里的参数说明
+ * @param connectTimeoutMs 连接超时时间，单位毫秒，默认30秒
+ * @param messageTimeoutMs 每条消息超时时间，单位毫秒，默认30秒
  * @returns 返回一个异步生成器，每次迭代返回一个字符串（流式响应）
  */
-export async function* makeSSERequest(url, method = 'GET', queryParams = null, customHeaders = null, body = null) {
+export async function* makeSSERequest(url, method = 'GET', queryParams = null, customHeaders = null, body = null, connectTimeoutMs = 30000, messageTimeoutMs = 30000) {
     var _a;
-    const resp = await makeHttpRequest(url, method, queryParams, customHeaders, body, 30000);
+    const resp = await makeHttpRequest(url, method, queryParams, customHeaders, body, connectTimeoutMs);
     if (!resp.ok) {
         return false;
     }
@@ -90,7 +96,15 @@ export async function* makeSSERequest(url, method = 'GET', queryParams = null, c
     let buffer = new Uint8Array(0);
     try {
         while (true) {
-            const { done, value } = await reader.read();
+            const raceResult = await Promise.race([
+                sleep(messageTimeoutMs),
+                reader.read(),
+            ]);
+            // 如果timeout先完成，说明超时了
+            if (raceResult === TIMEOUT_MARKER) {
+                throw new Error('SSE message timeout');
+            }
+            const { done, value } = raceResult;
             if (done || !value) {
                 break;
             }

package/dist/timer.d.ts

@@ -0,0 +1,2 @@
+export declare const TIMEOUT_MARKER: unique symbol;
+export declare function sleep(ms: number): Promise<typeof TIMEOUT_MARKER>;

package/dist/timer.js

@@ -0,0 +1,4 @@
+export const TIMEOUT_MARKER = Symbol('timeout');
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(() => resolve(TIMEOUT_MARKER), ms));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@czf0613/http_client",
   "private": false,
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Simple http client with fetch, supporting modified SSE protocol",
   "keywords": [
     "http client",
@@ -20,7 +20,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "prepack": "rm -rf dist || true && npm run build",
+    "prepack": "npm run build",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "repository": {