refactor(core): add generic utilities for resolving value-or-function patterns, replace specialized resolveStaleTime and resolveEnabled

This commit introduces `isFunctionVariant()` and `resolveValueOrFunction()` utilities to replace repetitive `typeof === 'function'` checks throughout the codebase, consolidating the common "value or function that computes value" pattern.

Author: braden-w

packages/query-core/src/query.ts

@@ -2,7 +2,7 @@ import {
   ensureQueryFn,
   noop,
   replaceData,
-  resolveEnabled,
+  resolveValueOrFunction,
   skipToken,
   timeUntilStale,
 } from './utils'
@@ -255,7 +255,8 @@ export class Query<
 
   isActive(): boolean {
     return this.observers.some(
-      (observer) => resolveEnabled(observer.options.enabled, this) !== false,
+      (observer) =>
+        resolveValueOrFunction(observer.options.enabled, this) !== false,
     )
   }
 
@@ -659,17 +660,12 @@ function getDefaultState<
 >(
   options: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
 ): QueryState<TData, TError> {
-  const data =
-    typeof options.initialData === 'function'
-      ? (options.initialData as InitialDataFunction<TData>)()
-      : options.initialData
+  const data = resolveValueOrFunction(options.initialData)
 
   const hasData = data !== undefined
 
   const initialDataUpdatedAt = hasData
-    ? typeof options.initialDataUpdatedAt === 'function'
-      ? (options.initialDataUpdatedAt as () => number | undefined)()
-      : options.initialDataUpdatedAt
+    ? resolveValueOrFunction(options.initialDataUpdatedAt)
     : 0
 
   return {

packages/query-core/src/queryClient.ts

@@ -4,7 +4,7 @@ import {
   hashQueryKeyByOptions,
   noop,
   partialMatchKey,
-  resolveStaleTime,
+  resolveValueOrFunction,
   skipToken,
 } from './utils'
 import { QueryCache } from './queryCache'
@@ -156,7 +156,9 @@ export class QueryClient {
 
     if (
       options.revalidateIfStale &&
-      query.isStaleByTime(resolveStaleTime(defaultedOptions.staleTime, query))
+      query.isStaleByTime(
+        resolveValueOrFunction(defaultedOptions.staleTime, query),
+      )
     ) {
       void this.prefetchQuery(defaultedOptions)
     }
@@ -364,7 +366,7 @@ export class QueryClient {
     const query = this.#queryCache.build(this, defaultedOptions)
 
     return query.isStaleByTime(
-      resolveStaleTime(defaultedOptions.staleTime, query),
+      resolveValueOrFunction(defaultedOptions.staleTime, query),
     )
       ? query.fetch(defaultedOptions)
       : Promise.resolve(query.state.data as TData)

packages/query-core/src/queryObserver.ts

@@ -8,8 +8,7 @@ import {
   isValidTimeout,
   noop,
   replaceData,
-  resolveEnabled,
-  resolveStaleTime,
+  resolveValueOrFunction,
   shallowEqualObjects,
   timeUntilStale,
 } from './utils'
@@ -157,8 +156,10 @@ export class QueryObserver<
       this.options.enabled !== undefined &&
       typeof this.options.enabled !== 'boolean' &&
       typeof this.options.enabled !== 'function' &&
-      typeof resolveEnabled(this.options.enabled, this.#currentQuery) !==
-        'boolean'
+      typeof resolveValueOrFunction(
+        this.options.enabled,
+        this.#currentQuery,
+      ) !== 'boolean'
     ) {
       throw new Error(
         'Expected enabled to be a boolean or a callback that returns a boolean',
@@ -201,10 +202,10 @@ export class QueryObserver<
     if (
       mounted &&
       (this.#currentQuery !== prevQuery ||
-        resolveEnabled(this.options.enabled, this.#currentQuery) !==
-          resolveEnabled(prevOptions.enabled, this.#currentQuery) ||
-        resolveStaleTime(this.options.staleTime, this.#currentQuery) !==
-          resolveStaleTime(prevOptions.staleTime, this.#currentQuery))
+        resolveValueOrFunction(this.options.enabled, this.#currentQuery) !==
+          resolveValueOrFunction(prevOptions.enabled, this.#currentQuery) ||
+        resolveValueOrFunction(this.options.staleTime, this.#currentQuery) !==
+          resolveValueOrFunction(prevOptions.staleTime, this.#currentQuery))
     ) {
       this.#updateStaleTimeout()
     }
@@ -215,8 +216,8 @@ export class QueryObserver<
     if (
       mounted &&
       (this.#currentQuery !== prevQuery ||
-        resolveEnabled(this.options.enabled, this.#currentQuery) !==
-          resolveEnabled(prevOptions.enabled, this.#currentQuery) ||
+        resolveValueOrFunction(this.options.enabled, this.#currentQuery) !==
+          resolveValueOrFunction(prevOptions.enabled, this.#currentQuery) ||
         nextRefetchInterval !== this.#currentRefetchInterval)
     ) {
       this.#updateRefetchInterval(nextRefetchInterval)
@@ -344,7 +345,7 @@ export class QueryObserver<
 
   #updateStaleTimeout(): void {
     this.#clearStaleTimeout()
-    const staleTime = resolveStaleTime(
+    const staleTime = resolveValueOrFunction(
       this.options.staleTime,
       this.#currentQuery,
     )
@@ -368,9 +369,10 @@ export class QueryObserver<
 
   #computeRefetchInterval() {
     return (
-      (typeof this.options.refetchInterval === 'function'
-        ? this.options.refetchInterval(this.#currentQuery)
-        : this.options.refetchInterval) ?? false
+      resolveValueOrFunction(
+        this.options.refetchInterval,
+        this.#currentQuery,
+      ) ?? false
     )
   }
 
@@ -381,7 +383,8 @@ export class QueryObserver<
 
     if (
       isServer ||
-      resolveEnabled(this.options.enabled, this.#currentQuery) === false ||
+      resolveValueOrFunction(this.options.enabled, this.#currentQuery) ===
+        false ||
       !isValidTimeout(this.#currentRefetchInterval) ||
       this.#currentRefetchInterval === 0
     ) {
@@ -489,15 +492,11 @@ export class QueryObserver<
         skipSelect = true
       } else {
         // compute placeholderData
-        placeholderData =
-          typeof options.placeholderData === 'function'
-            ? (
-                options.placeholderData as unknown as PlaceholderDataFunction<TQueryData>
-              )(
-                this.#lastQueryWithDefinedData?.state.data,
-                this.#lastQueryWithDefinedData as any,
-              )
-            : options.placeholderData
+        placeholderData = resolveValueOrFunction(
+          options.placeholderData,
+          this.#lastQueryWithDefinedData?.state.data,
+          this.#lastQueryWithDefinedData as any,
+        )
       }
 
       if (placeholderData !== undefined) {
@@ -660,9 +659,7 @@ export class QueryObserver<
 
       const { notifyOnChangeProps } = this.options
       const notifyOnChangePropsValue =
-        typeof notifyOnChangeProps === 'function'
-          ? notifyOnChangeProps()
-          : notifyOnChangeProps
+        resolveValueOrFunction(notifyOnChangeProps)
 
       if (
         notifyOnChangePropsValue === 'all' ||
@@ -740,7 +737,7 @@ function shouldLoadOnMount(
   options: QueryObserverOptions<any, any, any, any>,
 ): boolean {
   return (
-    resolveEnabled(options.enabled, query) !== false &&
+    resolveValueOrFunction(options.enabled, query) !== false &&
     query.state.data === undefined &&
     !(query.state.status === 'error' && options.retryOnMount === false)
   )
@@ -764,8 +761,8 @@ function shouldFetchOn(
     (typeof options)['refetchOnWindowFocus'] &
     (typeof options)['refetchOnReconnect'],
 ) {
-  if (resolveEnabled(options.enabled, query) !== false) {
-    const value = typeof field === 'function' ? field(query) : field
+  if (resolveValueOrFunction(options.enabled, query) !== false) {
+    const value = resolveValueOrFunction(field, query)
 
     return value === 'always' || (value !== false && isStale(query, options))
   }
@@ -780,7 +777,7 @@ function shouldFetchOptionally(
 ): boolean {
   return (
     (query !== prevQuery ||
-      resolveEnabled(prevOptions.enabled, query) === false) &&
+      resolveValueOrFunction(prevOptions.enabled, query) === false) &&
     (!options.suspense || query.state.status !== 'error') &&
     isStale(query, options)
   )
@@ -791,8 +788,8 @@ function isStale(
   options: QueryObserverOptions<any, any, any, any, any>,
 ): boolean {
   return (
-    resolveEnabled(options.enabled, query) !== false &&
-    query.isStaleByTime(resolveStaleTime(options.staleTime, query))
+    resolveValueOrFunction(options.enabled, query) !== false &&
+    query.isStaleByTime(resolveValueOrFunction(options.staleTime, query))
   )
 }
 

packages/query-core/src/retryer.ts

@@ -1,7 +1,7 @@
 import { focusManager } from './focusManager'
 import { onlineManager } from './onlineManager'
 import { pendingThenable } from './thenable'
-import { isServer, sleep } from './utils'
+import { isServer, resolveValueOrFunction, sleep } from './utils'
 import type { CancelOptions, DefaultError, NetworkMode } from './types'
 
 // TYPES
@@ -166,10 +166,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
         // Do we need to retry the request?
         const retry = config.retry ?? (isServer ? 0 : 3)
         const retryDelay = config.retryDelay ?? defaultRetryDelay
-        const delay =
-          typeof retryDelay === 'function'
-            ? retryDelay(failureCount, error)
-            : retryDelay
+        const delay = resolveValueOrFunction(retryDelay, failureCount, error)
         const shouldRetry =
           retry === true ||
           (typeof retry === 'number' && failureCount < retry) ||

packages/query-core/src/utils.ts

@@ -1,16 +1,14 @@
+import type { Mutation } from './mutation'
+import type { FetchOptions, Query } from './query'
 import type {
   DefaultError,
-  Enabled,
   FetchStatus,
   MutationKey,
   MutationStatus,
   QueryFunction,
   QueryKey,
   QueryOptions,
-  StaleTime,
 } from './types'
-import type { Mutation } from './mutation'
-import type { FetchOptions, Query } from './query'
 
 // TYPES
 
@@ -79,6 +77,94 @@ export function noop(): void
 export function noop(): undefined
 export function noop() {}
 
+/**
+ * Type guard that checks if a value is the function variant of a union type.
+ *
+ * This utility is designed for the common pattern in TanStack Query where options
+ * can be either a direct value or a function that computes that value.
+ *
+ * @template T - The direct value type
+ * @template TArgs - Array of argument types that the function variant accepts
+ * @param value - The value to check, which can be either T or a function that returns something
+ * @returns True if the value is a function, false otherwise. When true, TypeScript narrows the type to the function variant.
+ *
+ * @example
+ * ```ts
+ * // Basic usage with no arguments
+ * const initialData: string | (() => string) = getValue()
+ * if (isFunctionVariant(initialData)) {
+ *   // TypeScript knows initialData is () => string here
+ *   const result = initialData()
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Usage with function arguments
+ * const staleTime: number | ((query: Query) => number) = getStaleTime()
+ * if (isFunctionVariant<number, [Query]>(staleTime)) {
+ *   // TypeScript knows staleTime is (query: Query) => number here
+ *   const result = staleTime(query)
+ * }
+ * ```
+ */
+function isFunctionVariant<T, TArgs extends Array<any> = []>(
+  value: T | ((...args: TArgs) => any),
+): value is (...args: TArgs) => any {
+  return typeof value === 'function'
+}
+
+/**
+ * Resolves a value that can either be a direct value or a function that computes the value.
+ *
+ * This utility eliminates the need for repetitive `typeof value === 'function'` checks
+ * throughout the codebase and provides a clean way to handle the common pattern where
+ * options can be static values or dynamic functions.
+ *
+ * @template T - The type of the resolved value
+ * @template TArgs - Array of argument types when resolving function variants
+ * @param value - Either a direct value of type T or a function that returns T
+ * @param args - Arguments to pass to the function if value is a function
+ * @returns The resolved value of type T
+ *
+ * @example
+ * ```ts
+ * // Zero-argument function resolution (like initialData)
+ * const initialData: string | (() => string) = 'hello'
+ * const resolved = resolveValueOrFunction(initialData) // 'hello'
+ *
+ * const initialDataFn: string | (() => string) = () => 'world'
+ * const resolved2 = resolveValueOrFunction(initialDataFn) // 'world'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Function with arguments (like staleTime, retryDelay)
+ * const staleTime: number | ((query: Query) => number) = (query) => query.state.dataUpdatedAt + 5000
+ * const resolved = resolveValueOrFunction(staleTime, query) // number
+ *
+ * const retryDelay: number | ((failureCount: number, error: Error) => number) = 1000
+ * const resolved2 = resolveValueOrFunction(retryDelay, 3, new Error()) // 1000
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Replaces verbose patterns like:
+ * // const delay = typeof retryDelay === 'function'
+ * //   ? retryDelay(failureCount, error)
+ * //   : retryDelay
+ *
+ * // With:
+ * const delay = resolveValueOrFunction(retryDelay, failureCount, error)
+ * ```
+ */
+export function resolveValueOrFunction<T, TArgs extends Array<any>>(
+  value: T | ((...args: TArgs) => T),
+  ...args: TArgs
+): T {
+  return isFunctionVariant(value) ? value(...args) : value
+}
+
 export function functionalUpdate<TInput, TOutput>(
   updater: Updater<TInput, TOutput>,
   input: TInput,
@@ -96,30 +182,6 @@ export function timeUntilStale(updatedAt: number, staleTime?: number): number {
   return Math.max(updatedAt + (staleTime || 0) - Date.now(), 0)
 }
 
-export function resolveStaleTime<
-  TQueryFnData = unknown,
-  TError = DefaultError,
-  TData = TQueryFnData,
-  TQueryKey extends QueryKey = QueryKey,
->(
-  staleTime: undefined | StaleTime<TQueryFnData, TError, TData, TQueryKey>,
-  query: Query<TQueryFnData, TError, TData, TQueryKey>,
-): number | undefined {
-  return typeof staleTime === 'function' ? staleTime(query) : staleTime
-}
-
-export function resolveEnabled<
-  TQueryFnData = unknown,
-  TError = DefaultError,
-  TData = TQueryFnData,
-  TQueryKey extends QueryKey = QueryKey,
->(
-  enabled: undefined | Enabled<TQueryFnData, TError, TData, TQueryKey>,
-  query: Query<TQueryFnData, TError, TData, TQueryKey>,
-): boolean | undefined {
-  return typeof enabled === 'function' ? enabled(query) : enabled
-}
-
 export function matchQuery(
   filters: QueryFilters,
   query: Query<any, any, any, any>,