@czf0613/http_client 0.1.0 → 0.1.2

package/README.md

@@ -2,6 +2,8 @@
 
 A simple HTTP client library built with fetch API, supporting a modified SSE (Server-Sent Events) protocol for browser environments.
 
+No any dependencies, it is very lightweight.
+
 ## Requirements
 
 - **Runtime**: ES2018+ compatible browsers
@@ -68,11 +70,36 @@ Makes an HTTP request with default configuration using the Fetch API.
   - 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
+- `timeoutMs` (number): Timeout in milliseconds. Default: 5000. **Note: this value is the *connect timeout*, not the total request timeout. You need to handle the *read timeout* in your application logic.**
+
+**Returns:** `Promise<ExtendedResponse>` - Extended Response object with additional helper methods. It's the same as the standard Response object, but with additional methods for convenience.
+
+#### ExtendedResponse Methods
+
+In addition to all standard Response methods (`json()`, `text()`, `arrayBuffer()`, `blob()`, `bytes()`), ExtendedResponse provides the following timeout-enabled methods:
+
+**`jsonWithTimeout<T>(readTimeoutMs?: number): Promise<T>`**
+Reads the response body as JSON with a configurable timeout. Default timeout is 5000ms.
+- Throws `Error` with message `"JSON read timeout after Xms"` if timeout occurs
+- Throws parsing errors if JSON is invalid
+
+**`textWithTimeout(readTimeoutMs?: number): Promise<string>`**
+Reads the response body as text with a configurable timeout. Default timeout is 5000ms.
+- Throws `Error` with message `"Text read timeout after Xms"` if timeout occurs
+
+**`arrayBufferWithTimeout(readTimeoutMs?: number): Promise<ArrayBuffer>`**
+Reads the response body as ArrayBuffer with a configurable timeout. Default timeout is 5000ms.
+- Throws `Error` with message `"ArrayBuffer read timeout after Xms"` if timeout occurs
 
-**Returns:** Promise<Response> - Fetch API Response object
+**`blobWithTimeout(readTimeoutMs?: number): Promise<Blob>`**
+Reads the response body as Blob with a configurable timeout. Default timeout is 5000ms.
+- Throws `Error` with message `"Blob read timeout after Xms"` if timeout occurs
 
-**Note:** This function does not handle exceptions by default. You should wrap it in a try-catch block.
+**`bytesWithTimeout(readTimeoutMs?: number): Promise<Uint8Array<ArrayBuffer>>`**
+Reads the response body as Uint8Array with a configurable timeout. Default timeout is 5000ms.
+- Throws `Error` with message `"Bytes read timeout after Xms"` if timeout occurs
+
+**Note:** This function(including methods in `ExtendedResponse`) does not handle exceptions by default. You should wrap it in a try-catch block or using a promise chain.
 
 **Example:**
 
@@ -128,10 +155,14 @@ Makes an SSE (Server-Sent Events) request and returns an async generator that yi
 - `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
+- `connectTimeoutMs` (number): Connection timeout in milliseconds. Default: 30000
+- `messageTimeoutMs` (number): Timeout for each message read in milliseconds. Default: 30000
 
 **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)
+This method will **not** throw exceptions, you can get the success/failure status from 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:**
 
@@ -144,7 +175,9 @@ async function streamChat() {
     'POST',
     null,
     null,
-    { message: 'Hello' }
+    { message: 'Hello' },
+    30000,  // connectTimeoutMs
+    10000   // messageTimeoutMs
   );
 
   // Manually iterate to receive chunks
@@ -166,6 +199,14 @@ async function streamChat() {
 }
 ```
 
+## Test
+
+Run tests using:
+
+```bash
+npm test
+```
+
 ## License
 
 MIT

package/dist/http_client.d.ts

@@ -1,3 +1,4 @@
+import { ExtendedResponse } from './response_ext';
 /**
  * 拼接URL和查询参数，会自动处理转义
  * @param url 基础URL，不要带任何查询参数
@@ -15,9 +16,9 @@ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD';
  * @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对象
+ * @returns 返回Fetch API的Response对象，用法完全一样，但是会被包装成ExtendedResponse，增加了一些方法
  */
-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>;
+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<ExtendedResponse>;
 /**
  * 发起一个SSE请求，返回一个异步生成器，每次迭代返回一个字符串（流式响应）
  * 这个方法是拿来补充浏览器里面的EventSource的，扩展了很多没有的功能，跟原版的SSE协议不完全兼容。

package/dist/http_client.js

@@ -1,4 +1,6 @@
-import { sleep, TIMEOUT_MARKER } from './timer';
+import { sleep, TIMEOUT_MARKER, DEFAULT_TIMEOUT } from './timer';
+import { ExtendedResponse } from './response_ext';
+import { extractSSELine } from './parser';
 /**
  * 拼接URL和查询参数，会自动处理转义
  * @param url 基础URL，不要带任何查询参数
@@ -20,8 +22,6 @@ export function joinUrlWithParams(url, queryParams) {
     });
     return `${url}?${params.toString()}`;
 }
-// 默认超时时间，单位毫秒
-const DEFAULT_TIMEOUT = 5000;
 /**
  * 发起一个带有默认配置的 HTTP 请求
  * 默认不处理异常，需要try catch
@@ -31,7 +31,7 @@ const DEFAULT_TIMEOUT = 5000;
  * @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对象
+ * @returns 返回Fetch API的Response对象，用法完全一样，但是会被包装成ExtendedResponse，增加了一些方法
  */
 export async function makeHttpRequest(url, method = 'GET', queryParams = null, customHeaders = null, body = null, timeoutMs = DEFAULT_TIMEOUT) {
     // 处理查询参数
@@ -71,7 +71,7 @@ export async function makeHttpRequest(url, method = 'GET', queryParams = null, c
         signal: controller.signal,
     });
     clearTimeout(timeoutId);
-    return resp;
+    return ExtendedResponse.create(resp);
 }
 /**
  * 发起一个SSE请求，返回一个异步生成器，每次迭代返回一个字符串（流式响应）
@@ -85,16 +85,18 @@ export async function makeHttpRequest(url, method = 'GET', queryParams = null, c
  */
 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, connectTimeoutMs);
-    if (!resp.ok) {
-        return false;
-    }
-    const reader = (_a = resp.body) === null || _a === void 0 ? void 0 : _a.getReader();
-    if (reader == null) {
-        return false;
-    }
-    let buffer = new Uint8Array(0);
+    // 最后需要释放它的锁，所以需要写出来
+    let reader = void 0;
     try {
+        const resp = await makeHttpRequest(url, method, queryParams, customHeaders, body, connectTimeoutMs);
+        if (!resp.ok) {
+            return false;
+        }
+        reader = (_a = resp.body) === null || _a === void 0 ? void 0 : _a.getReader();
+        if (reader == null) {
+            return false;
+        }
+        let buffer = new Uint8Array(0);
         while (true) {
             const raceResult = await Promise.race([
                 sleep(messageTimeoutMs),
@@ -157,36 +159,9 @@ export async function* makeSSERequest(url, method = 'GET', queryParams = null, c
         return false;
     }
     finally {
-        reader.releaseLock();
-    }
-    return true;
-}
-/**
- * 解析SSE响应中的一行数据
- * @param buffer 需要处理的数组（只读，该函数不会修改它）
- * @returns 返回解析到的一行数据的结束索引，如果没有完整的一行数据，返回null。这个值指向最后一个\n的位置，slice的时候注意坐标运算
- */
-function extractSSELine(buffer) {
-    if (buffer.length < 8) {
-        // 每行数据至少都有'data: \n\n'，不够8个字节一定是不完整的
-        return null;
-    }
-    // 判断开头的6个字节是否是'data: '
-    if (buffer[0] !== 0x64 ||
-        buffer[1] !== 0x61 ||
-        buffer[2] !== 0x74 ||
-        buffer[3] !== 0x61 ||
-        buffer[4] !== 0x3A ||
-        buffer[5] !== 0x20) {
-        // 不是的话就有问题了
-        throw new Error('SSE data is not valid');
-    }
-    // 查找\n\n的位置
-    for (let i = 0; i < buffer.length - 1; ++i) {
-        if (buffer[i] === 0x0A && buffer[i + 1] === 0x0A) {
-            return i + 1;
+        if (reader != null) {
+            reader.releaseLock();
         }
     }
-    // 没有找到\n\n，返回null
-    return null;
+    return true;
 }

package/dist/index.d.ts

@@ -1 +1,2 @@
 export { joinUrlWithParams, makeHttpRequest, makeSSERequest } from './http_client';
+export { type ExtendedResponse } from './response_ext';

package/dist/parser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 解析SSE响应中的一行数据
+ * @param buffer 需要处理的数组（只读，该函数不会修改它）
+ * @returns 返回解析到的一行数据的结束索引，如果没有完整的一行数据，返回null。这个值指向最后一个\n的位置，slice的时候注意坐标运算
+ */
+export declare function extractSSELine(buffer: Uint8Array): number | null;

package/dist/parser.js

@@ -0,0 +1,29 @@
+/**
+ * 解析SSE响应中的一行数据
+ * @param buffer 需要处理的数组（只读，该函数不会修改它）
+ * @returns 返回解析到的一行数据的结束索引，如果没有完整的一行数据，返回null。这个值指向最后一个\n的位置，slice的时候注意坐标运算
+ */
+export function extractSSELine(buffer) {
+    if (buffer.length < 8) {
+        // 每行数据至少都有'data: \n\n'，不够8个字节一定是不完整的
+        return null;
+    }
+    // 判断开头的6个字节是否是'data: '
+    if (buffer[0] !== 0x64 ||
+        buffer[1] !== 0x61 ||
+        buffer[2] !== 0x74 ||
+        buffer[3] !== 0x61 ||
+        buffer[4] !== 0x3A ||
+        buffer[5] !== 0x20) {
+        // 不是的话就有问题了
+        throw new Error('SSE data is not valid');
+    }
+    // 查找\n\n的位置
+    for (let i = 0; i < buffer.length - 1; ++i) {
+        if (buffer[i] === 0x0A && buffer[i + 1] === 0x0A) {
+            return i + 1;
+        }
+    }
+    // 没有找到\n\n，返回null
+    return null;
+}

package/dist/response_ext.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 扩展的Response类，使用Proxy自动代理所有Response属性和方法
+ * 用户可以像普通的Response对象一样使用，也可以调用额外的方法
+ */
+export declare class ExtendedResponse implements Response {
+    private _response;
+    private constructor();
+    get [Symbol.toStringTag](): string;
+    static create(response: Response): ExtendedResponse;
+    clone(): ExtendedResponse;
+    /**
+     * 从响应体中读取JSON数据，支持超时设置
+     * @param readTimeoutMs 读取请求体的超时时间，单位毫秒
+     * @returns 解析后的JSON数据
+     * @throws 如果读取超时或解析失败，会抛出错误
+     */
+    jsonWithTimeout<T>(readTimeoutMs?: number): Promise<T>;
+    /**
+     * 从响应体中读取文本数据，支持超时设置
+     * @param readTimeoutMs 读取请求体的超时时间，单位毫秒
+     * @returns 解析后的文本数据
+     * @throws 如果读取超时或解析失败，会抛出错误
+     */
+    textWithTimeout(readTimeoutMs?: number): Promise<string>;
+    /**
+     * 从响应体中读取数组缓冲区数据，支持超时设置
+     * @param readTimeoutMs 读取请求体的超时时间，单位毫秒
+     * @returns 解析后的数组缓冲区数据
+     * @throws 如果读取超时或解析失败，会抛出错误
+     */
+    arrayBufferWithTimeout(readTimeoutMs?: number): Promise<ArrayBuffer>;
+    /**
+     * 从响应体中读取Blob数据，支持超时设置
+     * @param readTimeoutMs 读取请求体的超时时间，单位毫秒
+     * @returns 解析后的Blob数据
+     * @throws 如果读取超时或解析失败，会抛出错误
+     */
+    blobWithTimeout(readTimeoutMs?: number): Promise<Blob>;
+    /**
+     * 从响应体中读取字节数据，支持超时设置
+     * @param readTimeoutMs 读取请求体的超时时间，单位毫秒
+     * @returns 解析后的字节数据
+     * @throws 如果读取超时或解析失败，会抛出错误
+     */
+    bytesWithTimeout(readTimeoutMs?: number): Promise<Uint8Array<ArrayBuffer>>;
+    readonly body: ReadableStream<Uint8Array<ArrayBuffer>> | null;
+    readonly bodyUsed: boolean;
+    readonly headers: Headers;
+    readonly ok: boolean;
+    readonly redirected: boolean;
+    readonly status: number;
+    readonly statusText: string;
+    readonly type: ResponseType;
+    readonly url: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    blob(): Promise<Blob>;
+    bytes(): Promise<Uint8Array<ArrayBuffer>>;
+    formData(): Promise<FormData>;
+    json(): Promise<any>;
+    text(): Promise<string>;
+}

package/dist/response_ext.js

@@ -0,0 +1,150 @@
+import { sleep, TIMEOUT_MARKER, DEFAULT_TIMEOUT } from "./timer";
+/**
+ * 扩展的Response类，使用Proxy自动代理所有Response属性和方法
+ * 用户可以像普通的Response对象一样使用，也可以调用额外的方法
+ */
+export class ExtendedResponse {
+    // 私有构造函数，通过静态方法创建实例
+    constructor(response) {
+        this._response = response;
+    }
+    // Symbol.toStringTag 用于正确的类型识别
+    get [Symbol.toStringTag]() {
+        return 'ExtendedResponse';
+    }
+    // 静态工厂方法，创建代理后的ExtendedResponse实例
+    static create(response) {
+        const instance = new ExtendedResponse(response);
+        // 使用Proxy自动代理所有属性访问
+        return new Proxy(instance, {
+            get(target, prop) {
+                // 如果是ExtendedResponse自定义的属性或方法，优先从target获取
+                switch (prop) {
+                    case '_response':
+                    case 'create':
+                    case 'clone':
+                    case 'jsonWithTimeout':
+                    case 'textWithTimeout':
+                    case 'arrayBufferWithTimeout':
+                    case 'blobWithTimeout':
+                    case 'bytesWithTimeout':
+                        return target[prop];
+                    default:
+                        // 否则从原始Response获取
+                        const value = target._response[prop];
+                        // 如果是函数，需要绑定this
+                        return typeof value === 'function' ? value.bind(target._response) : value;
+                }
+            }
+        });
+    }
+    // clone方法要特殊处理
+    clone() {
+        return ExtendedResponse.create(this._response.clone());
+    }
+    // 以下是一些额外的方法
+    /**
+     * 从响应体中读取JSON数据，支持超时设置
+     * @param readTimeoutMs 读取请求体的超时时间，单位毫秒
+     * @returns 解析后的JSON数据
+     * @throws 如果读取超时或解析失败，会抛出错误
+     */
+    async jsonWithTimeout(readTimeoutMs = DEFAULT_TIMEOUT) {
+        const raceResult = await Promise.race([
+            sleep(readTimeoutMs),
+            this._response.json(),
+        ]);
+        // 如果timeout先完成，说明超时了
+        if (raceResult === TIMEOUT_MARKER) {
+            throw new Error(`JSON read timeout after ${readTimeoutMs}ms`);
+        }
+        return raceResult;
+    }
+    /**
+     * 从响应体中读取文本数据，支持超时设置
+     * @param readTimeoutMs 读取请求体的超时时间，单位毫秒
+     * @returns 解析后的文本数据
+     * @throws 如果读取超时或解析失败，会抛出错误
+     */
+    async textWithTimeout(readTimeoutMs = DEFAULT_TIMEOUT) {
+        const raceResult = await Promise.race([
+            sleep(readTimeoutMs),
+            this._response.text(),
+        ]);
+        // 如果timeout先完成，说明超时了
+        if (raceResult === TIMEOUT_MARKER) {
+            throw new Error(`Text read timeout after ${readTimeoutMs}ms`);
+        }
+        return raceResult;
+    }
+    /**
+     * 从响应体中读取数组缓冲区数据，支持超时设置
+     * @param readTimeoutMs 读取请求体的超时时间，单位毫秒
+     * @returns 解析后的数组缓冲区数据
+     * @throws 如果读取超时或解析失败，会抛出错误
+     */
+    async arrayBufferWithTimeout(readTimeoutMs = DEFAULT_TIMEOUT) {
+        const raceResult = await Promise.race([
+            sleep(readTimeoutMs),
+            this._response.arrayBuffer(),
+        ]);
+        // 如果timeout先完成，说明超时了
+        if (raceResult === TIMEOUT_MARKER) {
+            throw new Error(`ArrayBuffer read timeout after ${readTimeoutMs}ms`);
+        }
+        return raceResult;
+    }
+    /**
+     * 从响应体中读取Blob数据，支持超时设置
+     * @param readTimeoutMs 读取请求体的超时时间，单位毫秒
+     * @returns 解析后的Blob数据
+     * @throws 如果读取超时或解析失败，会抛出错误
+     */
+    async blobWithTimeout(readTimeoutMs = DEFAULT_TIMEOUT) {
+        const raceResult = await Promise.race([
+            sleep(readTimeoutMs),
+            this._response.blob(),
+        ]);
+        // 如果timeout先完成，说明超时了
+        if (raceResult === TIMEOUT_MARKER) {
+            throw new Error(`Blob read timeout after ${readTimeoutMs}ms`);
+        }
+        return raceResult;
+    }
+    /**
+     * 从响应体中读取字节数据，支持超时设置
+     * @param readTimeoutMs 读取请求体的超时时间，单位毫秒
+     * @returns 解析后的字节数据
+     * @throws 如果读取超时或解析失败，会抛出错误
+     */
+    async bytesWithTimeout(readTimeoutMs = DEFAULT_TIMEOUT) {
+        const raceResult = await Promise.race([
+            sleep(readTimeoutMs),
+            this._response.bytes(),
+        ]);
+        // 如果timeout先完成，说明超时了
+        if (raceResult === TIMEOUT_MARKER) {
+            throw new Error(`Bytes read timeout after ${readTimeoutMs}ms`);
+        }
+        return raceResult;
+    }
+    // Response接口的方法（实际通过Proxy代理到原始Response，这里的方法都也是骗编译器的）
+    arrayBuffer() {
+        throw new Error('Method not implemented.');
+    }
+    blob() {
+        throw new Error('Method not implemented.');
+    }
+    bytes() {
+        throw new Error('Method not implemented.');
+    }
+    formData() {
+        throw new Error('Method not implemented.');
+    }
+    json() {
+        throw new Error('Method not implemented.');
+    }
+    text() {
+        throw new Error('Method not implemented.');
+    }
+}

package/dist/timer.d.ts

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

package/dist/timer.js

@@ -1,3 +1,5 @@
+// 默认超时时间，单位毫秒
+export const DEFAULT_TIMEOUT = 5000;
 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.1.0",
+  "version": "0.1.2",
   "description": "Simple http client with fetch, supporting modified SSE protocol",
   "keywords": [
     "http client",
@@ -21,7 +21,8 @@
   "scripts": {
     "build": "tsc",
     "prepack": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "pretest": "npm run build",
+    "test": "npx tsx tests/run_all.ts"
   },
   "repository": {
     "type": "git",
@@ -32,6 +33,7 @@
   "license": "MIT",
   "homepage": "https://github.com/czf0613/http_client_ts#readme",
   "devDependencies": {
+    "@types/node": "^25.3.3",
     "typescript": "^5.9.3"
   }
 }