lit-query 中 UndefinedInitialDataOptions 类型解析initialData 可选查询选项的类型设计【免费下载链接】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/queryUndefinedInitialDataOptions是tanstack/lit-query中queryOptions()第三个重载签名所使用的查询选项类型用于描述initialData可以被省略或为undefined这一类查询配置。本文基于官方参考文档与 queryOptions.ts 的源码实现完整梳理该类型的定义、类型参数、它在queryOptions()重载体系中的位置以及它与DefinedInitialDataOptions、UnusedSkipTokenOptions的分工关系帮助你在 Lit 项目中编写类型安全的查询选项并理解其底层的类型推导机制。类型定义与定义位置该类型的完整定义对应参考文档 UndefinedInitialDataOptions.md如下type UndefinedInitialDataOptionsTQueryFnData, TError, TData, TQueryKey QueryObserverOptionsTQueryFnData, TError, TData, TQueryFnData, TQueryKey object源码中位于 packages/lit-query/src/queryOptions.ts#L58-L74其真实展开形式为/** * Query options where initialData can be omitted or undefined. */ export type UndefinedInitialDataOptions TQueryFnData unknown, TError DefaultError, TData TQueryFnData, TQueryKey extends QueryKey QueryKey, QueryObserverOptions TQueryFnData, TError, TData, TQueryFnData, TQueryKey { initialData?: | undefined | InitialDataFunctionNonUndefinedGuardTQueryFnData | NonUndefinedGuardTQueryFnData }即以QueryObserverOptions为基底再通过交叉类型把initialData字段显式收窄为可选的三种取值——undefined、返回非undefined数据的惰性函数、或者直接的非undefined数据。文档页面中呈现的initialData?声明与之一致optional initialData: | InitialDataFunctionNonUndefinedGuardTQueryFnData | NonUndefinedGuardTQueryFnData;注意类型参数中的TQueryData第四个位置参数在传给QueryObserverOptions时被固定为TQueryFnData这是 TanStack Query 统一选项类型的标准约定——查询函数返回的数据类型即缓存中的数据类型。四个类型参数及其默认值类型参数默认值 / 约束含义TQueryFnDataunknown查询函数queryFn返回的原始数据类型TErrorDefaultError查询失败时错误对象类型DefaultError在未声明Register[defaultError]时回退为Error见 types.ts#L45-L49TDataTQueryFnData最终暴露给消费者的数据类型通常是TQueryFnData经过select转换后的结果TQueryKey约束extends QueryKey默认QueryKey查询键类型QueryKey在未声明Register[queryKey]时回退为ReadonlyArrayunknown这四个默认值与参考文档 UndefinedInitialDataOptions.md 中 Type Parameters 一节完全一致。它属于哪个函数queryOptions()的三重载体系UndefinedInitialDataOptions并非孤立存在它是queryOptions()三个重载之一第三个的参数与返回基础。在 queryOptions.ts#L130-L139 中export function queryOptions TQueryFnData unknown, TError DefaultError, TData TQueryFnData, TQueryKey extends QueryKey QueryKey, ( options: UndefinedInitialDataOptionsTQueryFnData, TError, TData, TQueryKey, ): UndefinedInitialDataOptionsTQueryFnData, TError, TData, TQueryKey { queryKey: DataTagTQueryKey, TQueryFnData, TError }整个文件定义了三个语义上互相区分的选项类型分别对应三个重载详见 queryOptions 函数参考文档类型源码位置语义DefinedInitialDataOptionsqueryOptions.ts#L16-L29initialData必填保证查询数据一定处于 defined 状态此时queryFn变为可选UnusedSkipTokenOptionsqueryOptions.ts#L34-L53提供queryFn且排除SkipTokenqueryFn类型被Exclude..., SkipToken \| undefined收窄UndefinedInitialDataOptionsqueryOptions.ts#L58-L74initialData可省略或为undefined是最通用的兜底分支三者通过重载排列顺序DefinedInitialDataOptions→UnusedSkipTokenOptions→UndefinedInitialDataOptions让 TypeScript 按“信息量从强到弱”的方式匹配优先尝试推导“数据必然存在”的最强类型若推导不出来比如你既没有initialData也不排除skipToken最终落入UndefinedInitialDataOptions分支。真正的函数实现是同一个恒等函数queryOptions.ts#L141-L143export function queryOptions(options: unknown) { return options }也就是说queryOptions()在运行期不改变任何值它的价值完全在编译期把queryKey品牌化branding为DataTagTQueryKey, TQueryFnData, TError使数据与错误类型能沿着queryKey在整个 TanStack Query API如queryClient.getQueryData()、prefetchQuery()等之间传播。DataTag的定义在 packages/query-core/src/types.ts#L71-L80其本质是通过两个 Symbol 键dataTagSymbol/dataTagErrorSymbol在类型上附加不可见的标记。关键构成类型拆解initialData、NonUndefinedGuard 与 QueryObserverOptionsUndefinedInitialDataOptions的可读性取决于它引用的三个底层类型它们都来自tanstack/query-core1.QueryObserverOptions与initialData基线QueryObserverOptions继承自QueryOptions并强制queryKey必填types.ts#L315-L325。而initialData字段本身声明在QueryOptions中types.ts#L259initialData?: TData | InitialDataFunctionTDataUndefinedInitialDataOptions通过交叉类型把该字段重写为以NonUndefinedGuardTQueryFnData为准的可选变体从而允许“不传initialData”这一合法场景同时禁止把undefined字面量伪装成初始数据。2.NonUndefinedGuard把 undefined 挡在 initialData 门外// packages/query-core/src/types.ts#L12 export type NonUndefinedGuardT T extends undefined ? never : T它把undefined类型折叠为never。因此当TQueryFnData推导为string | undefined这类含undefined的联合时initialData的合法取值会被自动收窄避免你用undefined作为“初始数据”——这在语义上是矛盾的“没有初始数据”与“初始数据就是 undefined”不是一回事。3.InitialDataFunction惰性初始数据// packages/query-core/src/types.ts#L173 export type InitialDataFunctionT () T | undefined支持传入函数而非直接值适合需要运行时计算初始数据的场景例如从 URL 参数、本地存储或全局状态中恢复。在 Lit 项目中的实战用法queryOptions()返回带DataTag品牌化queryKey的选项对象供 lit-query 的查询控制器如createQueryController类型CreateQueryOptions从 queryOptions.ts 与 createQueryController.js 导出等 API 消费。类型三兄弟均通过 packages/lit-query/src/index.ts#L55-L60 从包入口公开导出export type { DefinedInitialDataOptions, UndefinedInitialDataOptions, UnusedSkipTokenOptions, } from ./queryOptions.js export { queryOptions } from ./queryOptions.js源码注释中自带的示例queryOptions.ts#L83-L92演示了带initialData的用法import { queryOptions } from tanstack/lit-query const todosOptions queryOptions({ queryKey: [todos], queryFn: fetchTodos, initialData: [], })而在不需要初始数据、或数据尚未就绪的场景中initialData可以直接省略此时命中的正是UndefinedInitialDataOptions重载import { queryOptions } from tanstack/lit-query // 不传 initialData命中第三个重载数据在首次加载前为 pending const userOptions queryOptions({ queryKey: [user, id], queryFn: () fetchUser(id), })从源码结构看重载的匹配顺序保证了只要你在选项里提供了“必然存在的数据”initialData或不含skipToken的queryFn推导出的选项类型就会携带更强的类型信息只有在最宽松的场景下才回落到UndefinedInitialDataOptions此时data等结果属性会在类型上体现“可能为undefined”的语义迫使消费者处理加载态。小结UndefinedInitialDataOptionsTQueryFnData, TError, TData, TQueryKey定义于 packages/lit-query/src/queryOptions.ts#L58-L74语义为“initialData可省略或为undefined”的查询选项是queryOptions()第三个重载的参数与返回基础。它与DefinedInitialDataOptionsinitialData必填、数据必然 defined和UnusedSkipTokenOptionsqueryFn必须存在且非skipToken共同构成queryOptions()的三重载推导体系运行期均为恒等透传价值全在编译期的DataTag品牌化queryKey。initialData的合法取值由NonUndefinedGuardtypes.ts#L12与InitialDataFunctiontypes.ts#L173联合约束确保初始数据“要么不存在、要么必然有值”。相关文档可继续延伸阅读DefinedInitialDataOptions、UnusedSkipTokenOptions、queryOptions 函数完整可运行的 Lit 示例项目可参考 examples/lit/basic。【免费下载链接】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），仅供参考