feat(ensureQueryData): add 'revalidateIfStale' option

[andredewaard]

add a prefetchWhenStale property to the fetchQuery function.
This allows the function to work like useQuery.

• if data is fresh, return it immediately
• if data is stale, return it immediately and call prefetchQuery() in the background for the next consumer
• if there is no data in the cache (either first hit or after gcTime), await the fetch and return that

As discussed here: https://discord.com/channels/719702312431386674/1212427380912820315

Please feel free to give feedback about how to better implement this feature.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Ignored Deployment

Name	Status	Preview	Comments	Updated (UTC)
query	⬜️ Ignored (Inspect)	Visit Preview		Mar 13, 2024 8:23am

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 90aa502:

Sandbox	Source
@tanstack/query-example-angular-basic	Configuration
@tanstack/query-example-react-basic-typescript	Configuration
@tanstack/query-example-solid-basic-typescript	Configuration
@tanstack/query-example-svelte-basic	Configuration
@tanstack/query-example-vue-basic	Configuration

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 90aa502. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 2 targets

• nx affected --targets=test:format,test:sherif,test:knip,test:eslint,test:lib,test:types,test:build,build --parallel=3
• nx run-many --targets=test:format,test:sherif,test:knip,test:eslint,test:lib,test:types,test:build,build --parallel=3

---

Sent with 💌 from NxCloud.

[TkDodo]

Thanks for this. I thought about it for some time, and while I think there are ways to combine ensureQueryData / fetchQuery / prefetchQuery for a streamlined API, this would require a major version change, so I'll "defer" that decision for now.

---

I think the better API would be to add this option to ensureQueryData and keep fetchQuery as it is. ensureQueryData will right now:

• always return data if it exists in the cache
• if there is no data in the cache, it will fetch and wait for it, then return it.

what's missing is the piece in between: data exists, but is stale. I think we could just add a revalidateIfStale: boolean option here that defaults to false (current behaviour). If set to true, it would return stale data immediately, but trigger void queryClient.prefetchQuery() to make a background update to the cache for the next consumer.

Since your use-case is also router related, and we recommend using ensureQueryData in route loaders, I think this would align nicely. What do you think ?

[andredewaard]

alright that also makes sense, i added it to fetchQuery so it would be more aligned with how useQuery already works and since they are both kinda the same function but useQuery is for components i thought it would be better to add there.

But ensureQueryData would be better indeed. will revert my changes and try to implement the changes.

[TkDodo]

can you also add some tests for this please ?

[andredewaard]

can you also add some tests for this please ?

Will do

[andredewaard]

Test added. At first the test needs to return cached data which is 'old', we wait for the promise to resolve which will let the new call return 'new'

[TkDodo]

please fix prettier

[andredewaard]

@TkDodo For me it seems like the build is not build properly. in queryClient.d.ts the ensureQueryData looks like

ensureQueryData<TQueryFnData, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>): Promise<TData>;
    ensureQueryData<TQueryFnData, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: MaybeRefDeep<FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>>): Promise<TData>;

where it should be

ensureQueryData<TQueryFnData, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>): Promise<TData>;
    ensureQueryData<TQueryFnData, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: MaybeRefDeep<EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>>): Promise<TData>;

[TkDodo]

looks good on unpkg:

https://unpkg.com/browse/@tanstack/[email protected]/build/modern/queryClient-UWB6EkqM.d.ts

[andredewaard]

its inside the vue-query plugin, not in core
https://unpkg.com/browse/@tanstack/[email protected]/build/modern/queryClient.d.ts

[TkDodo]

ooh, that's because vue has it's own wrapper around the core because of this unref things, and we didn't update the types there:

query/packages/vue-query/src/queryClient.ts

Lines 87 to 98 in 61f4d74

	ensureQueryData<
	TQueryFnData,
	TError = DefaultError,
	TData = TQueryFnData,
	TQueryKey extends QueryKey = QueryKey,
	>(
	options: MaybeRefDeep<
	FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>
	>,
	): Promise<TData> {
	return super.ensureQueryData(cloneDeepUnref(options))
	}

can you do another PR to fix this please ?

[andredewaard]

A alright, yes will do.