Problems with typification of useQueries

[andreynovikov]

I have created a helper hook based on useQueries. The idea is to encapsulate specific fetching logic in queryFn and reformat results for easier use. It works as intended, but I can not fix typescript errors. The full code is:

// hook can be called with extra query options
type SkipQueryOptions<TData, TError, TResult> = OmitKeyof<
  UseQueryOptions<TData, TError, TResult>,
  "queryFn" | "queryKey"
>;
type SkipQueryOptionsForUseQueries<TData, TError, TResult> = OmitKeyof<SkipQueryOptions<TData, TError, TResult>, "placeholderData" | "subscribed"> & {
  placeholderData?: TData | QueriesPlaceholderDataFunction<TData>;
};

// `queryFn` injects variant for later use in `combine` function
type MultipleApiData<TData> = {
  variant: string,
  data: TData
}
// result is a dictionary of variants with corresponding data, plus some flags
type ResultMapping<TResult> = {
  [key: string]: TResult;
}
type MultipleApiDataResult<TResult> = {
  data: ResultMapping<TResult>,
  pending: boolean,
}

// TData is what is returned by API in fetch result
// TResult is what can be returned by `select` function if it transporms data
export const useMultipleApiData = <TData, TResult = TData>(
  service: ServiceVariant,
  model: string,
  variants: string[],
  pathMappingFn: (variant: string) => string,
  queryOptions?: SkipQueryOptionsForUseQueries<MultipleApiData<TData>, FetchError, MultipleApiDataResult<TResult>>,
  sileceErrors: boolean = false,
  refetchOnWindowFocus: boolean = true
): MultipleApiDataResult<TResult> => {
  // `combine` should be memoized according to docs
  const combine = useCallback((results: UseQueryResult<TData, unknown>[]) => {
    return {
      data: results.filter((result) => result.data !== undefined).reduce((variantResults, result) => {
        // @ts-expect-error Broken typing (too complex to fix)
        variantResults[result.data!.variant] = result.data!.data;
        return variantResults;
      }, {} as ResultMapping<TResult>),
      pending: results.some((result) => result.isPending),
    }
  }, []);
  const sessionContext = useSession();
  const token = sessionContext.data?.user.tokens.access.token;
  return useQueries<MultipleApiData<TData>[], MultipleApiDataResult<TResult>>({
    queries: variants.map((variant) => ({
      refetchOnWindowFocus: refetchOnWindowFocus,
      ...queryOptions,
      queryKey: [service, model, variant, token],
      queryFn: async ({ queryKey }: { queryKey: string[]}) => {
        const accessToken = queryKey.at(-1) ?? (await getSession())?.user.tokens.access.token;
        const authHeaders: HeadersInit = accessToken !== undefined
          ? { Authorization: `Bearer ${accessToken}` } : {};

        const response = await fetch(
          getApiBaseUrl(service) + `/${model}/` + pathMappingFn(variant),
          {
            method: "GET",
            headers: {
              "Content-Type": "application/json",
              ...authHeaders,
            },
          }
        );

        if (!response.ok)
          throw new FetchError(response);

        const data = await response.json() as TData;
        return { variant, data } as MultipleApiData<TData>;
      },
    })) as unknown as QueriesOptions<MultipleApiData<TData>[]>,
    combine,
  });
};

The main problem is with @ts-expect-error - I didn't manage to fix it. The other problem is with as unknown as..., without it it doesn't work too.

P.S. I have a similar helper hook for single useQuery, and I've managed to typificate it without problems.

[mg1986jp]

The type errors come from two things: useQueries expects a tuple of query option objects (not a generic array), and the combine callback's type inference doesn't flow through dynamic arrays well.

The main fix: don't fight the generic parameters on useQueries — cast at the query array level and type the combine result explicitly.

export const useMultipleApiData = <TData, TResult = TData>(
  // ...params
): MultipleApiDataResult<TResult> => {

  const combine = useCallback(
    (results: Array<UseQueryResult<MultipleApiData<TData>, FetchError>>) => {
      return {
        data: results
          .filter((r) => r.data !== undefined)
          .reduce<ResultMapping<TResult>>((acc, r) => {
            acc[r.data!.variant] = r.data!.data as unknown as TResult;
            return acc;
          }, {}),
        pending: results.some((r) => r.isPending),
      };
    },
    []
  );

  const queries = variants.map((variant) => ({
    queryKey: [service, model, variant, token] as const,
    queryFn: async () => {
      // ...fetch logic
      return { variant, data } satisfies MultipleApiData<TData>;
    },
    ...queryOptions,
  }));

  return useQueries({
    queries: queries as any, // dynamic arrays can't satisfy the tuple inference
    combine,
  }) as MultipleApiDataResult<TResult>;
};

The as any on queries is unavoidable here because useQueries uses mapped tuple types to infer each query's result type individually. When you .map() over an array, TypeScript collapses it to Array<...> and loses the per-element inference. The combine return type then can't be inferred either.

Casting queries as any and explicitly typing combine's parameter + your hook's return type gives you full type safety at the API boundary — the internals just can't be inferred automatically with dynamic arrays.

The @ts-expect-error in your combine is the same root cause: result.data is typed as TData (what useQueries infers from the collapsed array) instead of MultipleApiData<TData>.

[DaCameraGirl]

The root cause here is a fundamental TypeScript limitation with useQueries: when you build the queries array dynamically with .map(), TypeScript loses the tuple-level type inference that useQueries expects for its combine function. The generics work perfectly when the queries are defined inline as a literal tuple — but collapse to unknown/any when constructed dynamically.

Here are the fixes:

Fix 1: Explicitly Type the combine Callback Parameters

Instead of relying on TypeScript to infer the results type from your dynamic queries array, annotate the combine parameter explicitly:

import { useQueries, UseQueryResult } from '@tanstack/react-query'

function useMultipleApiData<TResult>(
  variants: string[],
  options?: SkipQueryOptionsForUseQueries<MultipleApiData<TResult>, FetchError, TResult>
): MultipleApiDataResult<TResult> {
  const queries = variants.map((variant) => ({
    queryKey: ['api', variant],
    queryFn: async (): Promise<MultipleApiData<TResult>> => {
      const data = await fetchVariant<TResult>(variant)
      return { variant, data }
    },
    ...options,
  }))

  return useQueries({
    queries: queries as any, // ← bypass the dynamic array vs tuple mismatch
    combine: (
      results: Array<UseQueryResult<MultipleApiData<TResult>, FetchError>> // ← explicit type
    ): MultipleApiDataResult<TResult> => {
      const data = results.reduce<ResultMapping<TResult>>((acc, r) => {
        if (r.data) {
          acc[r.data.variant] = r.data.data
        }
        return acc
      }, {})

      return {
        data,
        pending: results.some((r) => r.isPending),
        errors: results.filter((r) => r.isError).map((r) => r.error as FetchError),
      }
    },
  })
}

The as any on queries is the key — it's a controlled escape hatch just at the call site, not a loss of type safety throughout your code. Your return type MultipleApiDataResult<TResult> is still fully typed at the hook's API boundary.

Fix 2: Use a Generic Array Type Helper

If you want to avoid as any entirely, you can use the QueriesOptions helper type that TanStack Query exposes internally:

import { useQueries, QueriesOptions, QueriesResults } from '@tanstack/react-query'

function useMultipleApiData<TResult>(
  variants: string[]
): MultipleApiDataResult<TResult> {
  const queries = variants.map((variant) => ({
    queryKey: ['api', variant] as const,
    queryFn: (): Promise<MultipleApiData<TResult>> =>
      fetchVariant<TResult>(variant).then((data) => ({ variant, data })),
  }))

  return useQueries({
    // Cast to satisfy the tuple constraint
    queries: queries as unknown as QueriesOptions<typeof queries>,
    combine: (results) => {
      // results is now typed as QueriesResults<typeof queries>
      const data = results.reduce<ResultMapping<TResult>>((acc, r) => {
        const result = r as UseQueryResult<MultipleApiData<TResult>>
        if (result.data) acc[result.data.variant] = result.data.data
        return acc
      }, {})
      return {
        data,
        pending: results.some((r) => r.isPending),
        errors: results.filter((r) => r.isError).map((r) => r.error as FetchError),
      }
    },
  })
}

Fix 3: Separate the Combine Logic (Cleanest for Complex Cases)

If the hook is complex, separate the combine function so TypeScript can infer it independently:

const combineResults = (
  results: Array<UseQueryResult<MultipleApiData<TResult>, FetchError>>
): MultipleApiDataResult<TResult> => ({
  data: Object.fromEntries(
    results.filter((r) => r.data).map((r) => [r.data!.variant, r.data!.data])
  ) as ResultMapping<TResult>,
  pending: results.some((r) => r.isPending),
  errors: results.filter((r) => r.isError).map((r) => r.error!),
})

// Then use it:
return useQueries({
  queries: queries as any,
  combine: combineResults,
})

Why This Happens (Brief Explanation)

useQueries is typed with conditional types that map each element of a tuple to its result type. When you use .map(), TypeScript infers the type as Array<{...}> instead of a tuple [{...}, {...}, ...], and the conditional type machinery breaks down. This is a known TypeScript limitation with dynamic arrays vs. fixed-length tuples — see microsoft/TypeScript#27808.

The as any cast at the queries argument is the standard community workaround, and it's what the TanStack Query docs implicitly recommend for dynamic query arrays.

[MILLERMARRU]

Two separate problems are stacking here, and the explicit generics are making both worse.

The first type parameter of useQueries describes the shape of the queries array, not your data type, so useQueries<MultipleApiData<TData>[], ...> sends inference sideways from the start. The second issue is that building the array with .map() erases tuple-level inference, which is fine in your case (all queries share one shape) but means you must give TypeScript the element type instead of expecting it to be recovered.

The combination that works without @ts-expect-error: drop the explicit generics on useQueries, build each element with the queryOptions helper so the element type is carried by the array itself, and type the combine parameter yourself with the real data type:

const combine = useCallback(
  (results: UseQueryResult<MultipleApiData<TData>, FetchError>[]) => ({
    data: results.reduce((acc, r) => {
      if (r.data !== undefined) acc[r.data.variant] = r.data.data as unknown as TResult
      return acc
    }, {} as ResultMapping<TResult>),
    pending: results.some((r) => r.isPending),
  }),
  []
)

return useQueries({
  queries: variants.map((variant) =>
    queryOptions({
      queryKey: [service, model, variant, token] as const,
      queryFn: () => fetchVariant(variant),
      ...extraOptions,
    })
  ),
  combine,
})

Your original annotation typed results as UseQueryResult<TData, unknown>[], so result.data.variant could not typecheck, the data there is MultipleApiData<TData>, not TData. That alone is what forced the expect-error.

One more mismatch worth fixing: in SkipQueryOptionsForUseQueries you pass MultipleApiDataResult<TResult> as the select output, but select runs per query, so its output type should be per-query data. The combined mapping type belongs only to combine's return. Once those two levels stop sharing a generic, the rest of the inference falls into place.