Svelte Query 的 CreateMutationOptionscreateMutation 完整配置类型解析与源码级实现【免费下载链接】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导读CreateMutationOptions是 tanstack/svelte-query 中createMutation的选项类型别名它规定了 Svelte 应用中一切变更操作创建、更新、删除数据或执行服务端副作用的配置契约。本文从该类型的定义出发逐一解析其四个泛型参数、继承自核心包的十余个配置字段并结合 createMutation.svelte.ts 的实现与类型测试说明这些选项在响应式环境中的真实运行机制。读完本文你将能写出类型完备、推断精准、支持乐观更新与全局状态查询的 Svelte Query 变更逻辑。CreateMutationOptions 的定义与定位在 packages/svelte-query/src/types.ts 中该类型定义如下/** Options for createMutation */ export type CreateMutationOptions TData unknown, TError DefaultError, TVariables void, TOnMutateResult unknown, OmitKeyof MutationObserverOptionsTData, TError, TVariables, TOnMutateResult, _defaulted 官方类型参考页对其的说明只有一句话Options for createMutationcreateMutation的选项。从源码结构看它本质上是对核心包tanstack/query-core中MutationObserverOptions的再封装唯一的变化是借助OmitKeyof工具类型剔除内部的_defaulted标记字段——该字段是查询/变更观察器在内部完成选项默认值填充后设置的内部标志源码位于 packages/query-core/src/types.ts对外部调用方没有意义因此从公共 API 中隐藏。OmitKeyof与MutationObserverOptions均从tanstack/query-core导入见 types.ts这体现了 svelte-query 作为框架适配层、query-core 承载全部通用逻辑的分层设计。四个类型参数含义与默认值原类型参考页对每个泛型参数给出了默认值逐项说明如下类型参数默认值含义TDataunknownmutationFn成功 resolve 后的数据类型会作为onSuccess第一个参数与返回结果中data字段的类型TErrorDefaultError变更失败时的错误类型默认是核心包定义的DefaultError即Error会作为onError第一个参数与结果中error字段的类型TVariablesvoidmutationFn接收的变量入参类型决定mutate/mutateAsync的入参类型TOnMutateResultunknownonMutate回调的返回值类型用于乐观更新时携带上下文context失败时透传给onError作为第三个参数TOnMutateResult乐观更新的上下文通道TOnMutateResult是四个参数中最具实战意义的一个。它的典型用法是在onMutate中先取消进行中的查询、保存旧数据并提前写入新数据乐观 UI然后把旧数据作为返回值若变更失败onError通过第三个参数拿到该返回值并回滚。这一模式被封装进类型系统createMutation.test-d.ts 中的类型测试验证了onMutate返回{ token: string }时onSuccess收到类型为{ token: string }而onError收到{ token: string } | undefined——因为onError在onMutate失败或未定义时确实可能拿到undefined。完整选项字段清单继承自 MutationObserverOptions由于CreateMutationOptions直接展开自MutationObserverOptions后者的全部字段即前者可用的全部配置。MutationObserverOptions在 packages/query-core/src/types.ts 中定义它先继承MutationOptions的全部字段再额外增加throwOnError。逐字段说明MutationOptions 基础字段mutationFn?: MutationFunctionTData, TVariables执行变更的核心函数接收(variables, context)返回PromiseTData。context为MutationFunctionContext包含client、meta与可选的mutationKey。mutationKey?: MutationKey变更的唯一标识只读数组用于配合useMutationState跨组件定位该变更。onMutate?: (variables, context) PromiseTOnMutateResult | TOnMutateResult变更执行前同步触发常用于乐观更新与副作用准备。onSuccess?: (data, variables, onMutateResult, context) ...变更成功后触发。onError?: (error, variables, onMutateResult | undefined, context) ...变更失败后触发onMutateResult在onMutate未返回或自身抛错时为undefined。onSettled?: (data | undefined, error | null, variables, onMutateResult | undefined, context) ...无论成败都会触发适合做收尾如失效查询。retry?: RetryValueTError失败重试次数或重试判定函数boolean | number | (failureCount, error) boolean。retryDelay?: RetryDelayValueTError重试间隔可为数值或基于failureCount与error计算延迟的函数。networkMode?: NetworkMode网络模式取值如online/offlineFirst/always控制离线时的执行策略。gcTime?: number变更从内存中被垃圾回收前的保留时间毫秒。meta?: MutationMeta附加到变更上的任意元数据可在MutationFunctionContext中读取。scope?: MutationScope变更作用域{ id: string }用于控制变更的并发隔离。_defaulted?: boolean内部字段已被OmitKeyof从公共类型中剔除。MutationObserverOptions 独有字段throwOnError?: boolean | ((error: TError) boolean)当为true或判定函数返回true时mutateAsync返回的 Promise 会以错误拒绝而非吞掉错误在 Svelte 中还可与错误边界error boundary配合使用。该字段是MutationObserverOptions相比MutationOptions唯一的新增项见 types.ts。与 createMutation 的配合选项的响应式形态CreateMutationOptions并非孤立存在它是createMutation的第一个参数类型。在 createMutation.svelte.ts 中export function createMutation TData unknown, TError DefaultError, TVariables void, TContext unknown, ( options: AccessorCreateMutationOptionsTData, TError, TVariables, TContext, queryClient?: AccessorQueryClient, ): CreateMutationResultTData, TError, TVariables, TContext两个关键点选项是响应式读取器options的类型是AccessorT () T见 types.ts即一个返回CreateMutationOptions的函数。这意味着你传入的配置对象本身可以是 Svelte 5 runes 的派生值选项变化时会自动生效。可指定自定义 QueryClient第二个参数同样是AccessorQueryClient缺省时使用最近上下文中的QueryClient。运行时实现要点从 createMutation.svelte.ts 的实现可以推断其底层机制内部持有MutationObserver来自tanstack/query-core其构造与重建由watchChanges监听client变化触发$effect.pre中调用observer.setOptions(options())使选项的响应式更新同步到观察器返回结果通过Proxy包装mutate与mutateAsync被注入结果对象mutateAsync实际复用观察器自身的mutate返回 Promise而mutate则调用后catch(noop)吞掉未处理的拒绝状态字段isPending、status、data、error等由观察器的订阅回调批量写入通知经由notifyManager.batchCalls合并。最小可用示例script langts import { createMutation, useQueryClient } from tanstack/svelte-query const queryClient useQueryClient() const addMutation createMutation(() ({ mutationFn: addTodo, // (variables: string) PromiseTodo onSuccess: () queryClient.invalidateQueries({ queryKey: [todos] }), })) /script {#if addMutation.isPending} 正在添加… {:else if addMutation.isError} 添加失败{addMutation.error.message} {:else} button onclick{() addMutation.mutate(Item)}Add/button {/if}此示例中无需显式标注任何泛型——TData、TVariables均从mutationFn自动推断。类型测试证实了以下推断行为见 createMutation.test-d.tsmutationFn: () Promise.resolve(data)时data推断为string | undefinederror为DefaultError | nullmutationFn: (vars: { id: string }) ...时mutate仅接受{ id: string }无参mutationFn时TVariables默认voidmutate()可不带参数调用自定义错误类可通过createMutationstring, CustomError(...)显式传入error随之推断为CustomError | nullmutateAsync的返回类型与mutationFn的 Promise 泛型一致如Promisenumber。对应的运行时测试位于 createMutation.svelte.test.ts覆盖了reset清除错误、多次mutate的onSuccess/onSettled触发次数、failureCount/failureReason在多轮调用间的正确归零与更新以及QueryClient切换时观察器重建等行为。共享选项mutationOptions 与类型的关系当需要在多个createMutation调用点之间共享同一份CreateMutationOptions或希望借助mutationKey在组件外查询变更状态时官方推荐mutationOptions辅助函数。它提供两个重载见 mutationOptions.md要求mutationKey的重载返回WithRequiredCreateMutationOptions..., mutationKey适合配合useMutationState实现全局保存中…指示器不要求mutationKey的重载返回OmitCreateMutationOptions..., mutationKey适合单纯共享配置。script langts import { mutationOptions, createMutation } from tanstack/svelte-query const createPostOptions mutationOptions({ mutationKey: [posts, create], mutationFn: createPost, }) const mutation createMutation(() createPostOptions) /script button onclick{() mutation.mutate({ title: Hello })}Create/buttonmutationOptions的返回值本身就是CreateMutationOptions的派生形态可直接塞进createMutation的Accessor中二者类型天然兼容。相关类型链围绕CreateMutationOptionstypes.ts 中还定义了一组配套类型理解它们有助于掌握完整类型系统CreateMutationResultTData, TError, TVariables, TOnMutateResultcreateMutation的返回值在核心包MutationObserverResult基础上重写了mutateCreateMutateFunction返回void并追加mutateAsyncCreateMutateAsyncFunction返回 Promise。CreateMutateFunction/CreateMutateAsyncFunction分别对应同步触发与可等待的触发函数形态。MutationStateOptions与MutationTypeFromResult服务于useMutationState的过滤器与类型提取。结语CreateMutationOptions虽只是一行类型别名却是 svelte-query 变更体系createMutation→MutationObserver→Mutation的配置入口。理解它的四个泛型参数与全部字段意味着你同时理解了 query-core 中MutationObserverOptions的能力边界再结合Accessor包裹的响应式形态即可在 Svelte 5 的 runes 体系下写出类型安全、状态可控、可全局追踪的完整变更方案。若要深入底层执行与重试细节可继续阅读 packages/query-core/src/mutationObserver.ts 与 packages/query-core/src/mutationCache.ts 中的观察器与缓存实现。【免费下载链接】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），仅供参考