@iquji-web/web-network 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +65 -16
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,27 +1,76 @@
1
- # Web network
1
+ # @iquji-web/web-network
2
2
 
3
- `@iquji-web/web-network` 提供通用 HTTP 传输,不包含认证、业务错误、重试或响应数据协议。它由 Community Web 子仓维护,包名与正式出口保持稳定。
3
+ 简体中文 | [English](README.en.md)
4
4
 
5
- 安装使用本目录锁文件,运行 `bun install --frozen-lockfile` 和 `bun run check`。正式入口只导出 `dist` 中的 JavaScript、类型声明,不要求消费者编译本包源码。
5
+ Iquji Web 网络传输抽象层,提供原生 HTTP 传输器、JSON 适配器、可注入 Fetch 实现、统一超时控制与取消信号。
6
6
 
7
- `@iquji-web/web-network/test-support` 单独提供可注入 FetchRecorder,不从生产主入口导出。
7
+ ---
8
+
9
+ ## 安装
10
+
11
+ ```bash
12
+ npm install @iquji-web/web-network
13
+ ```
14
+
15
+ ---
16
+
17
+ ## 核心特性与使用
18
+
19
+ ### 1. JSON 传输客户端 (`createJsonTransport`)
8
20
 
9
21
  ```ts
10
- import { createHttpTransport } from "@iquji-web/web-network";
11
-
12
- const request = createHttpTransport({ timeoutMs: 15_000 });
13
- const controller = new AbortController();
14
- const response = await request("/api/status", {
15
- method: "GET",
16
- credentials: "include",
17
- signal: controller.signal,
22
+ import { createJsonTransport, JsonTransportError } from "@iquji-web/web-network";
23
+
24
+ const api = createJsonTransport({
25
+ baseUrl: "https://api.example.com",
26
+ timeoutMs: 10000,
27
+ resolveHeaders: () => ({
28
+ Authorization: `Bearer ${localStorage.getItem("token") || ""}`,
29
+ }),
18
30
  });
31
+
32
+ // 发起强类型 JSON 请求
33
+ try {
34
+ const user = await api<{ id: string; name: string }>("/v1/user/profile", {
35
+ method: "GET",
36
+ });
37
+ console.log(user.name);
38
+ } catch (error) {
39
+ if (error instanceof JsonTransportError) {
40
+ console.error(`HTTP 错误响应码: ${error.status}`);
41
+ }
42
+ }
19
43
  ```
20
44
 
21
- `createHttpTransport({ fetchImplementation?, timeoutMs? })` 返回接受 `RequestInfo | URL` 和 `RequestInit & { timeoutMs?: number }` 的请求函数。它保留请求地址、正文、头部与 fetch 选项,直接返回原始 `Response`,包括非成功状态、响应头、重定向地址和未读取的响应流;状态判断与正文解析由消费者负责。
45
+ ### 2. 底层 HTTP 传输器 (`createHttpTransport`)
22
46
 
23
- 默认不设置超时。实例与逐请求 `timeoutMs` 接受 0 到 2147483647 的有限毫秒值;逐请求设置覆盖实例,0 关闭超时。超时覆盖等待响应头的阶段,随后清理定时器,不读取消费者正文。超时中止底层信号并抛出 `HttpTimeoutError`,其 `name` 为 `TimeoutError`、`timeoutMs` 为实际设置。调用方取消保留原始原因;请求返回后,调用方取消仍可传递给底层响应流。正文读取的时限由消费者管理。
47
+ 支持注入自定义 fetch(例如在测试替身或 Node.js 环境中):
24
48
 
25
- `fetchImplementation` 可注入浏览器 fetch、测试替身或宿主原生传输,并应遵守 fetch 的 `AbortSignal` 语义。代理连接由宿主原生或服务端适配器执行,本包不提供 `proxy` 配置。浏览器 fetch 使用浏览器自身的网络环境,不能通过请求选项指定自定义代理。
49
+ ```ts
50
+ import { createHttpTransport, HttpTimeoutError } from "@iquji-web/web-network";
51
+
52
+ const transport = createHttpTransport({
53
+ timeoutMs: 5000,
54
+ });
55
+
56
+ try {
57
+ const response = await transport.request("https://api.example.com/health");
58
+ console.log(response.status);
59
+ } catch (err) {
60
+ if (err instanceof HttpTimeoutError) {
61
+ console.warn("请求超时");
62
+ }
63
+ }
64
+ ```
65
+
66
+ ---
26
67
 
27
- `createJsonTransport` 在共享原始传输上保留现有合同:规范化 `baseUrl` 与相对路径、合并默认和请求头、序列化 JSON 正文、传递凭据及缓存设置。非成功状态抛出只含状态码的 `JsonTransportError`,成功状态解析 JSON;不读取失败响应正文。该适配器也接受实例与逐请求 `timeoutMs`。
68
+ ## 开发与构建
69
+
70
+ ```bash
71
+ bun install --frozen-lockfile
72
+ bun run build # 编译构建到 dist/
73
+ bun run typecheck # 类型校验
74
+ bun run test # 单元测试
75
+ bun run check # 完整自检
76
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@iquji-web/web-network",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "files": [