动作
动作会给您 TypeScript UI 中的每个服务器调用相同的待处理状态、重试、回滚和信件, 从每个动作一个声明.
它取代了加载旗,错误消息和撤消代码,否则您会在每一个更改服务器数据的呼叫周围写入. 优化的更新和重试都是选入的,不需要UI框架. 它需要TypeScript 5.0或更晚,以及一个无害环境管理捆绑器. 这取决于 @cplieger/reactive 财务报告和审定财务报表 @cplieger/fetch 并且根据Apache-2.0获得许可.
为什么用它
动作是为香草 TypeScript 前端构建的,这些前端希望每个服务器呼叫中的行为相同.
- 乐观的更新在请求前更改了UI,并在失败或取消时回滚取消.
- 以指数方式重试后退,只重试您标记为瞬态的故障,并在浏览器下线时暂停.
scope运行同一键的发送顺序,dedupe将它们合并为一个请求abort()或一个AbortSignal转至dispatch()取消单一发送.isPending财务报告和审定财务报表pendingCount反应通过@cplieger/reactive,因此一个按钮可以在动作运行时自行禁用.- 失败或取消解决发送到
null而不是拒绝,与 两种例外情况,以及handle.outcome告诉三个结局分开. onSuccess, (中文(简体) ),onError财务报告和审定财务报表onSettled跟着TanStack Query的变异回调,和configureApi跟踪 RTK 查询fetchBaseQuery。 。 。 .- 仅
bindLoadingState财务报告和审定财务报表withAsyncFeedback需要一个DOM。 其余也运行于节点.
考虑 TanStack 查询 如果您还需要服务器状态缓存, 在突变后缓存无效, 以及像 React 这样的框架钩钩 useMutation。 。 。 .
安装
npx jsr add @cplieger/actions
# or
npm i @cplieger/actions
使用量
启动时连接您的通知显示, 在模块范围定义每个动作, 然后从事件处理器中发送 .
import { configure, apiAction, retryNetwork } from "@cplieger/actions";
configure({
success: (msg) => showToast("success", msg),
error: (msg, retry) => showToast("error", msg, retry?.onClick),
});
const deleteItem = apiAction<string>({
name: "items.delete",
request: (id) => ({ method: "DELETE", path: `/api/items/${id}` }),
error: "Could not delete the item",
retryable: retryNetwork,
retry: { count: 2, delay: 300 },
});
await deleteItem.dispatch(itemId);
dispatch() 决定结果,或 null 在失败或取消之后。 失败后, 错误消息已经显示 。 重试需要两个设置 . retryable 决定哪些失败是短暂的,以及 retry 设置尝试和等待的次数。 与 retry 单枪匹马 什么都没有被重审.
乐观更新返回回滚需要恢复的内容 :
const toggleDone = apiAction<{ id: string; done: boolean }, Todo, Todo>({
name: "todos.toggle",
request: ({ id, done }) => ({ method: "PATCH", path: `/api/todos/${id}`, body: { done } }),
optimistic: ({ id, done }) => {
const previous = store.get(id);
store.setDone(id, done);
return previous;
},
rollback: ({ id }, previous) => {
if (previous) store.set(id, previous);
},
scope: ({ id }) => `todo:${id}`,
});
rollback 运行在错误或取消上,永远不会成功. scope 使同一项目的两个切换相继运行.
在动作运行时禁用按钮, 并读取结果状态 :
bindLoadingState("todos.toggle", toggleButton);
const outcome = await toggleDone.dispatch({ id, done: true }).outcome;
if (outcome.status === "error") console.warn(outcome.error.message);
API 密码
- 设置, 启动时一次 :
configure连接您的通知显示,并configureApi设置 HTTP 动作的基础 URL、信头和证书.configureTransport将频道连接成流命令,例如端点,其答复通过服务器发送事件到达. - 工厂:
defineAction对于任何同步函数,apiAction用于HTTP请求,transportAction对流指令. - 帮助者 :
debouncedDispatch, (中文(简体) ),pollAction, (中文(简体) ),pollUntil, (中文(简体) ),bindLoadingState, (中文(简体) ),withAsyncFeedback, (中文(简体) ),registerCleanup。 。 。 . - 状况和活动:
isPending, (中文(简体) ),pendingCount, (中文(简体) ),subscribeToActions, (中文(简体) ),subscribeByName, (中文(简体) ),getActionLog。 。 。 . - 错误和预设 :
ActionError, (中文(简体) ),retryNetwork, (中文(简体) ),classifyFetchError, (中文(简体) ),hasErrorString, (中文(简体) ),RETRY_STANDARD, (中文(简体) ),IDEMPOTENCY_HEADER, (中文(简体) ),IDEMPOTENCY_COMMAND_FIELD。 。 。 . - 测试 :
resetActionFramework从@cplieger/actions/testing,用于beforeEach。 。 。 .
本文全文取自文件评论 日 尔。 。 。 .
服务器文本和参数需要注意
- 错误消息可以包含服务器响应的文本.
configure适配器使它成为文本,而不是HTML. - 单位
decodeError, (中文(简体) ),info.body是解析失败响应的正文 。 在读出字段之前检查它的形状 . - 与
baseUrl设置,请求路径不能改变来源。 无baseUrl,路径fetch()没有改变, 因此永远不要从服务器文本中构建整个路径 . - 动作日志,它的收听器和重试按钮保留了每个调度的参数并产生内存. 设定
sensitive: true(a) 其论点或结果含有秘密、象征或个人资料的行动。 它的日志条目然后不包含参数,结果或错误,也不需要重试. 见 敏感行动。 。 。 .
不支持设计
| 特性 | 原因 |
|---|---|
| 查询缓存, stale- while- revalidate | 这是动作跑车,不是数据缓存。 并用 TanStack 查询 . |
| 缓存无效, 重新验证 | 数据缓存问题. |
| React, Vue 或 Svelte 的框架适配器 | 香草TypeScript设计. 框架约束属于单独的包. |
| 视觉 DevTools 面板 | 一个单独的包裹. getActionLog 财务报告和审定财务报表 subscribeByName 给它数据. |
| 安全部门改革和水合 | 动作是必须的突变, 没有状态可以从服务器到客户端 . |
跳过 maxWait | 刻意简化. 打电话 flush() 当一个调度必须开火. |
| 喉管辅助器 | 并非专门针对行动。 在你打电话前发抖 dispatch()。 。 。 . |
condition 或执行前警卫 | 一个 if 来电者会这么做. dedupe 涵盖主案. |
onProgress 回调 | 交通专用. 报告进展情况 run() 函数. |
| 批量发送 | 一个商店的担心, 而这个图书馆没有一家商店. |
dispose() 或行动注销登记 | 一个闲置的动作几乎没有记忆,所以一个现实的应用不会泄露. |
文档
- 调度生命周期 包括通知、重试、货币、注销、回调和输入结果.
- HTTP 和流动动作 覆盖
configureApi,请求路径,响应解码和transportAction。 。 。 . - UI 和 投票助手 包括解封,投票,装入状态,按钮反馈,可观察性和测试.
捐款
欢迎提出问题和拉动请求。 见 捐款额。 。 。 .
免责声明
这个项目是精心设计的,遵循安全最佳做法,但打算供个人/自发使用。 不保证生产环境的适宜性. 自己冒险使用.
这个项目是利用AI辅助工具,使用 克劳德, (中文(简体) ), 常规,以及 基罗人类维护者界定建筑、监督实施和作出所有最后决定.
许可证
阿帕奇2.0 (英语). 见 自由主义。 。 。 .