Svelte Query 的 CreateMutationResult 类型全解析createMutation 返回值结构与状态机【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/queryCreateMutationResult是tanstack/svelte-query中createMutation函数的返回值类型它完整刻画了一次服务端副作用创建 / 更新 / 删除数据从触发到落定的全部状态与能力。本文将以该类型定义为骨架结合 svelte-query 与 query-core 的源码实现和测试用例讲解其四个类型参数、联合类型状态机、mutate/mutateAsync/reset等核心成员并给出可直接运行的 Svelte 5 实战示例帮助你在 TypeScript 中写出类型安全、状态完备的 mutation 逻辑。类型定义一行别名背后的完整契约在 packages/svelte-query/src/types.ts:139 中CreateMutationResult的定义极其简洁/** Result from createMutation */ export type CreateMutationResult TData unknown, TError DefaultError, TVariables unknown, TOnMutateResult unknown, CreateBaseMutationResultTData, TError, TVariables, TOnMutateResult它本质上是对CreateBaseMutationResult的类型别名。追根溯源CreateBaseMutationResult在 types.ts:121 中定义export type CreateBaseMutationResult TData unknown, TError DefaultError, TVariables unknown, TOnMutateResult unknown, Override MutationObserverResultTData, TError, TVariables, TOnMutateResult, { mutate: CreateMutateFunctionTData, TError, TVariables, TOnMutateResult } { mutateAsync: CreateMutateAsyncFunction TData, TError, TVariables, TOnMutateResult }这里有两个关键动作用Override类型改写mutate成员MutationObserverResult中原本的mutate是MutateFunction同步返回void或 Promise 的通用形态svelte-query 将其收窄为CreateMutateFunction——一个只接受variables与可选回调参数、同步返回void的调用形态见 types.ts:103-112这与 React Query 中mutate的只管触发、不返回 Promise语义保持一致。并集追加mutateAsync通过交叉类型补上CreateMutateAsyncFunction即原始的MutateFunctiontypes.ts:114-119每次调用返回独立的PromiseTData。Override工具类型本身位于 packages/query-core/src/types.ts:31它遍历目标类型 A 的每个键若该键在类型 B 中存在则采用 B 的类型否则保留 A 的类型。四个类型参数TData、TError、TVariables、TOnMutateResultCreateMutationResult的四个泛型参数与createMutation的入参选项一一对应默认值分别为参数默认值含义TDataunknownmutationFn成功后的返回值类型TErrorDefaultError失败时的错误类型默认是ErrorTVariablesunknown调用mutate/mutateAsync时传入的变量类型TOnMutateResultunknownonMutate钩子的返回值乐观更新上下文类型在绝大多数场景下你不需要显式填写它们——TypeScript 会从createMutation的选项自动推断。测试文件 packages/svelte-query/tests/createMutation/createMutation.test-d.ts 明确验证了这一点it(should infer TData from mutationFn return type, () { const mutation createMutation(() ({ mutationFn: () Promise.resolve(data), })) // mutation.data 被推断为 string | undefined }) it(should infer TVariables from mutationFn parameter, () { const mutation createMutation(() ({ mutationFn: (vars: { id: string }) Promise.resolve(vars.id), })) // mutation.variables 被推断为 { id: string } | undefined }) it(should infer TOnMutateResult from onMutate return type, () { createMutation(() ({ mutationFn: () Promise.resolve(data), onMutate: () { return { token: abc } }, })) // onMutate 的返回类型被用于 TOnMutateResult })TOnMutateResult是乐观更新的关键onMutate返回的上下文对象如变更前的旧数据会被原样传给onError、onSettled用于失败时回滚。底层状态机MutationObserverResult 的四态联合CreateMutationResult的主体来自 query-core 的MutationObserverResult。在 packages/query-core/src/types.ts:1352 中它是一个可辨识联合类型discriminated unionexport type MutationObserverResult TData unknown, TError DefaultError, TVariables void, TOnMutateResult unknown, | MutationObserverIdleResultTData, TError, TVariables, TOnMutateResult | MutationObserverLoadingResultTData, TError, TVariables, TOnMutateResult | MutationObserverErrorResultTData, TError, TVariables, TOnMutateResult | MutationObserverSuccessResultTData, TError, TVariables, TOnMutateResult四种形态都继承自MutationObserverBaseResulttypes.ts:1203后者包含以下核心成员data: TData | undefined—— 最近一次成功的数据variables: TVariables | undefined—— 传给mutationFn的变量error: TError | null—— 错误对象默认nullisError/isIdle/isPending/isSuccess—— 由status派生的布尔标记status: idle | pending | error | successmutate—— 触发 mutation 的函数reset: () void—— 将 mutation 重置回初始状态四种形态通过status字段区分且各自收窄了其他字段的类型这是 TypeScript 收窄与自动补全的基础形态statusdataerrorvariablesMutationObserverIdleResultidleundefinednullundefinedMutationObserverLoadingResultpendingundefinednullTVariablesMutationObserverErrorResulterrorundefinedTErrorTVariablesMutationObserverSuccessResultsuccessTDatanullTVariables生命周期一目了然创建后处于idle初始态→ 调用mutate后进入pending执行中→ 成功进入success失败进入errorreset()可随时把状态拉回idle。测试组件 packages/svelte-query/tests/createMutation/Success.svelte 与 Failure.svelte 分别验证了成功与失败两条路径的状态流转。createMutation 如何构建并返回该结果createMutation在 packages/svelte-query/src/createMutation.svelte.ts:171 中返回CreateMutationResultTData, TError, TVariables, TContext。其内部实现值得注意创建MutationObserver实例并订阅其状态变化通过notifyManager.batchCalls批量更新 Svelte 响应式状态result用Proxy包装结果对象createMutation.svelte.ts:227-240每次属性读取时都会重建一个包含mutate与mutateAsync的对象其中mutate被替换为调用observer.mutate并吞掉 Promise 拒绝.catch(noop)的版本——这就是CreateMutateFunction同步返回void的运行时实现这也是为什么CreateBaseMutationResult需要Override改写mutate的类型运行时行为与类型签名严格一致。另外createMutation的选项被Accessor() T函数包裹因此选项本身可以响应式地随 Svelte 状态变化见 types.ts:22 的AccessorT () T。实战在 Svelte 5 中使用 CreateMutationResult以下是CreateMutationResult的典型消费方式。选项可通过mutationOptions复用也可直接内联传给createMutationscript langts import { createMutation, useQueryClient } from tanstack/svelte-query const queryClient useQueryClient() const addMutation createMutation(() ({ mutationFn: addTodo, // TData 与 TVariables 从这里推断 onSuccess: () queryClient.invalidateQueries({ queryKey: [todos] }), })) /script button onclick{() addMutation.mutate(Item, { onError: (error) console.error(Failed to add item:, error), }) } Add /button借助联合类型的状态收窄渲染层可以直接基于isPending/isError/isSuccess分支TypeScript 会在各分支内自动收窄data与error的类型script langts import { createMutation, useQueryClient } from tanstack/svelte-query const queryClient useQueryClient() const addMutation createMutation(() ({ mutationFn: addTodo, onSuccess: () queryClient.invalidateQueries({ queryKey: [todos] }), })) /script {#if addMutation.isPending} Adding todo... {:else} {#if addMutation.isError} divAn error occurred: {addMutation.error.message}/div {/if} button onclick{() addMutation.mutate(Item)}Add/button {/if}需要拿到每次调用的 Promise 时例如批量提交后统一等待使用mutateAsync——它每个调用返回独立的PromiseTData而mutate上的onSuccess回调只在最后一次调用成功后触发script langts import { createMutation, useQueryClient } from tanstack/svelte-query const queryClient useQueryClient() const addMutation createMutation(() ({ mutationFn: addTodo, onSuccess: () queryClient.invalidateQueries({ queryKey: [todos] }), })) async function handleAddAll(todos: Arraystring) { await Promise.all(todos.map((todo) addMutation.mutateAsync(todo))) } /script button onclick{() handleAddAll([Todo 1, Todo 2, Todo 3])} Add all /button若部分 mutation 可能独立失败、且需要知道具体哪些失败可将Promise.all换成Promise.allSettled避免第一个 reject 吞掉其余结果。乐观更新TOnMutateResult 的典型用法onMutate返回的上下文会被CreateMutationResult的类型系统完整保留并注入后续回调script langts import { createMutation, useQueryClient } from tanstack/svelte-query const queryClient useQueryClient() const addMutation createMutation(() ({ mutationFn: addTodo, onMutate: async (newTodo: string) { await queryClient.cancelQueries({ queryKey: [todos] }) const previousTodos queryClient.getQueryDataArraystring([todos]) queryClient.setQueryDataArraystring([todos], (old) [ ...(old ?? []), newTodo, ]) return { previousTodos } // 这个对象就是 TOnMutateResult }, onError: (_err, _newTodo, context) { // context 被推断为 { previousTodos: string[] | undefined } | undefined queryClient.setQueryData([todos], context?.previousTodos) }, })) /script与其他 API 的协同mutationOptionspackages/svelte-query/src/mutationOptions.ts把可复用的选项提取为独立对象可要求mutationKey再传入createMutation(() options)选项对象本身同时是CreateMutationOptions与返回值类型一一对应。useMutationStatepackages/svelte-query/src/useMutationState.svelte.ts通过mutationKey读取其他位置 mutation 的状态例如全局保存中…指示器。useIsMutating统计当前正在进行中的 mutation 数量常与isPending组合实现全局加载态。小结CreateMutationResult虽只有一行别名背后却是 query-core 精心设计的四态联合类型与 svelte-query 的运行时 Proxy 包装的协同产物四个泛型参数让数据、错误、变量与乐观更新上下文全程类型安全status联合类型让模板分支在编译期获得字段收窄mutate的同步触发与mutateAsync的逐调用 Promise 语义则分别对应即发即忘与精确等待两种编程需求。理解这一类型就等于理解了 svelte-query mutation 的全部状态契约。延伸阅读createMutation 函数文档CreateMutationOptions 类型文档mutationOptions 函数文档useMutationState 函数文档svelte-query 类型定义源码createMutation 实现源码query-core 结果类型源码类型推断测试【免费下载链接】query Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query.项目地址: https://gitcode.com/GitHub_Trending/qu/query创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
