获取
@cplieger/fetch 覆盖平台 fetch 对于 TypeScript , JSON 请求从不掷出 。 每个调用返回一个输入的成功值或错误值,或只返回数据或 null 当你需要的就是这些.
它取代了 try编号 :catch,则 response.ok 检查和 JSON.parse 否则你每通电话都会写 它没有运行时间依赖和船舶作为只作为无害环境管理的TypeScript源,你的捆绑者用自己的代码编译. 它需要TypeScript 5.0或更晚,并运行于Node 18,Chrome 103,Safari 16和Firefox 100或更晚. 它根据Apache-2.0获得许可.
为什么用它
@cplieger/fetch 用于前端和服务器的代码,该代码可调用 JSON API ,并想要处理其中的每个失败 if。 。 。 .
- 网络故障、 超时、 取消请求、 非-2xx 响应以及 无法验证的机构 都以错误值返回
code。 。 。 . - 失败的反应保持了状态,标题和解析JSON的身体,所以429's
Retry-After是一个财产离开. - 验证是一个简单的函数,所以 Zod 或 valibot schema 插件作为
(v) => schema.parse(v)。 。 。 . - 有了绝对的基础URL,绝对或协议相对路径无法到达另一个来源.
- 它大约是2千B 精密和克齐普, 它的测试 与铬自己的
fetch, (中文(简体) ),Headers财务报告和审定财务报表AbortSignal。 。 。 .
考虑 凯 如果您想要在一个客户端中重试、挂钩、上传和下载进度。 考虑 函数 如果您需要在节点、浏览器和工人上进行流式响应和自动重试.
安装
npx jsr add @cplieger/fetch
# or
npm i @cplieger/fetch
使用量
每个后端创建一个实例, 然后在结果上创建分支 :
import { createFetch } from "@cplieger/fetch";
export const api = createFetch({ baseUrl: "https://api.example.com/v1" });
const res = await api.apiGetRaw<{ id: string; name: string }>("/users/me");
if (res.ok) {
console.log(res.data.name, res.headers.get("ETag"));
} else {
// status is 0 when no response arrived; code says why.
console.error(res.status, res.code, res.error);
}
当您只需要数据时,没有后缀的帮助者返回数据,或者 null 任何错误. apiPost, (中文(简体) ), apiPut 财务报告和审定财务报表 apiPatch 发送他们的第二个参数作为 JSON 与 Content-Type: application/json数字 :
const user = await api.apiGet<{ id: string; name: string }>("/users/me"); // the user, or null
const created = await api.apiPost<{ id: string }>("/items", { name: "widget" });
验证一个具有返回已键入值或抛出值的任何函数的响应正体。 抛出一个错误 code: "decode"数字 :
import { z } from "zod";
const User = z.object({ id: z.string(), name: z.string() });
const user = await api.apiGetTyped("/users/me", (v) => User.parse(v)); // typed, or null
每个帮手都要最后的 options 对取消信号、超时、额外标题、解码器、预编码机构、跳过成功机构或读取为 Blob数字 :
const controller = new AbortController();
await api.apiGetRaw("/slow", { signal: controller.signal, timeoutMs: 5_000 });
await api.apiDeleteRaw("/items/1", { ignoreBody: true });
const poster = await api.apiGet("/posters/42", { as: "blob" }); // a Blob, or null
在一个地方对每一次失败采取行动,如在会话到期时将用户发送到其中签字,使实例 onError 钩. 它看到每一个失败 与它的 code 已经从身体上读到, 并且它不扔或返回到呼叫者:
export const api = createFetch({
baseUrl: "https://api.example.com/v1",
onError: (err) => {
if (err.status === 401 && err.code === "session_expired") location.assign("/login");
},
});
在路径中设置查询参数, 例如 /items?page=2。要添加一个在启动后更改的页眉,例如一个符号,请在实例中读取 prepareHeaders 钩子,它运行在每一个请求。 超时开始于 prepareHeaders 返回,所以可以挂起的钩子需要自己的限制. 请求、超时和运行时间 覆盖每个设置和选项.
API 密码
- 实例 :
createFetch(config?)返回 aFetchInstance。 。 。 .FetchConfig持有baseUrl, (中文(简体) ),credentials, (中文(简体) ),prepareHeaders, (中文(简体) ),fetchFn, (中文(简体) ),maxResponseBytes财务报告和审定财务报表onError。 。 。 . - 一次请求:
requestRaw财务报告和审定财务报表request附加时apiGet, (中文(简体) ),apiPost, (中文(简体) ),apiPut, (中文(简体) ),apiPatch财务报告和审定财务报表apiDelete以简单形式返回数据或null(单位:千美元)*Raw以返回全部结果.apiGetTyped财务报告和审定财务报表apiPostTyped还取解码器. - 超时 :
withTimeout(signal, ms)财务报告和审定财务报表API_TIMEOUT_MS30,000毫秒(英语:. - 类型 :
ApiOk<T>, (中文(简体) ),ApiErr, (中文(简体) ),ApiResult<T>, (中文(简体) ),Decoder<T>, (中文(简体) ),FailedRequest, (中文(简体) ),HttpMethod, (中文(简体) ),RequestOptions<T>jSON读取和BlobRequestOptions页:1as: "blob"。 。 。 .
全文见 日 尔。 。 。 .
错误是值
requestRaw 和每个 *Raw 帮助者决心 ApiResult<T> 永远不要扔 一个成功是 { ok: true, status, data, headers }。错误是 { ok: false, status, error, code?, requestId?, headers?, body? }。 。 。 .
status 当没有回复时为 0. code 那时 network, (中文(简体) ), timeout, (中文(简体) ), cancelled 或者说 invalid时 invalid 表示请求无法构建且从未发送 。 不是JSON或者解码器故障的2xx尸体是 decode真实状态 非-2xx响应保持其状态和标题. 当它的身体是JSON时, body 拿着它,还有它的 error, (中文(简体) ), code 财务报告和审定财务报表 request_id 字段填充结果 error, (中文(简体) ), code 财务报告和审定财务报表 requestId。 。 。 .
服务器控制 code 发送 timeout 或另一个图书馆代码。 图书馆代码随之而来 status 0,或 2xx 状态 decode,而服务器代码总是随其非-2xx状态而来. 处理 body 作为不信任的输入.
一个204或一个空的2xx体给予 data: undefined被援助者变成 null一个JSON null, (中文(简体) ), 0, (中文(简体) ), false 或者说 "" 是真实的数据.
结果和错误 有完整的合同.
路径停留在您的基址下
绝对的 baseUrl,每个请求都会去那个计划和主机。 类似路径 https://other.example 或者说 //host 成为路径的一部分,所以 https://api.example.com/v1 加号 https://other.example 请求 https://api.example.com/v1/https://other.exampleA级 ..,一个点段或一个回击不能从基路径爬出,而查询字符串和片段是按书面发送的.
保护需要 baseUrl 有计划 和东道主。 空或相亲 baseUrl,一个与协议相对的路径仍然可以到达另一个来源. 没有 baseUrl,路径 fetch() 不变,所以永远不要通过不信任的输入作为整个路径.
基础 URL 和不信任的回复 覆盖此和响应大小上限 .
不支持设计
@cplieger/fetch 没有重试或回放、截取链、响应缓存、解码器梳理器、可变或全局设置、自动同位素键或请求ID头,或流式响应. 不支持设计 给出每个理由 以及用什么代替.
相关项目
- @cplieger/ 动作 以这个库为基础,并添加了备份的再试,请求去dupe,乐观的更新和通知.
- httpx 数据 是 Go 库,用于输出的 HTTP 调用, 并使用复写和备份 .
文档
- 结果和错误 列出每个结果字段、错误代码和空字符规则.
- 请求、超时和运行时间 包含实例设置、请求选项、超时和运行时版本.
- 基础 URL 和不信任的回复 解释路径规则,响应大小上限以及如何读取服务器控制的字段.
- 不支持设计 列出故意遗漏的特性,并说明理由.
捐款
欢迎提出问题和拉动请求。 见 捐款额。 。 。 .
免责声明
这个项目是精心设计的,遵循安全最佳做法,但打算供个人/自发使用。 不保证生产环境的适宜性. 自己冒险使用.
这个项目是利用AI辅助工具,使用 克劳德, (中文(简体) ), 常规,以及 基罗人类维护者界定建筑、监督实施和作出所有最后决定.
许可证
阿帕奇2.0 (英语). 见 自由主义。 。 。 .