TypeScript tweaks for “React Query with a custom fetcher setup” (useGraphQL)

[connorjs]

Overview

I have just finished trying out the recommended @tanstack/react-query + graphql-request approach described in the docs. I wanted to discuss a few changes I made when writing the useGraphql hook in my own project.

#8989 Presents a similar discussion, but I felt creating a new one was appropriate here.

Goal

I would like to receive feedback and/or discuss my changes. I plan to submit a pull request to change the documentation following this. (Even if only some minor pieces and not all of these.)

Thanks in advance for thoughts!

---

Original code

For completeness, the following shows the doc code at time of writing. (I will omit imports for brevity.)

export function useGraphQL<TResult, TVariables>(
  document: TypedDocumentNode<TResult, TVariables>,
  ...[variables]: TVariables extends Record<string, never> ? [] : [TVariables]
): UseQueryResult<TResult> {
  return useQuery([(document.definitions[0] as any).name.value, variables], async ({ queryKey }) =>
    request(
      'https://swapi-graphql.netlify.app/.netlify/functions/index',
      document,
      queryKey[1] ? queryKey[1] : undefined
    )
  )
}

No any

The first change I made was to remove the any. I used OperationDefinitionNode instead given my understanding of TypedDocumentNode (and confirmed with my own query).

I added some extra code as a result (for example, throwing an error for no name), but we do not need to include that in the update.

Change variables type

I made a couple changes to the variable types.

First, I used undefined instead of [] to remove the (imo) hard-to-read (for non TS experts) type spreading. This changes the hook to always require two parameters, but (a) few GraphQL queries actually have no variables and (b) many APIs seem to prefer “consistency” over “cute” these days.

Second, this also means that we no longer need the ternary (or nullish coalescing operator) for the third parameter to request.

ESLint disable

When I add Tanstack’s Query ESLint plugin (see docs), the @tanstack/query/exhaustive-deps rule throws. As mentioned in the related discussion, this is fine (although I found that discussion only once writing up this discussion). My code includes an eslint-disable comment.

Naming

Finally, I renamed useGraphql to useGraphqlQuery to allow for the corresponding useGraphqlMutation to build on top of Tanstack’s useMutation. Note: I have not actually built/tried the mutation side. That’s up next on my list.

My code

My code in its current form follows. Note: I prefer the *T naming for generics; this habit comes from Google’s style guide from my Java days.

// Hooks inspired by GraphQL Code Generator’s recommendations:
// https://the-guild.dev/graphql/codegen/docs/guides/react-vue#appendix-i-react-query-with-a-custom-fetcher-setup

/**
 * Hook for GraphQL Queries. Uses `@tanstack/react-query`.
 *
 * @param document - The GraphQL query document
 * @param variables - The variables for the document
 * @returns Tanstack query result.
 */
export function useGraphqlQuery<ResultT, VariablesT>(
	document: TypedDocumentNode<ResultT, VariablesT>,
	variables: Strict<VariablesT>,
): UseQueryResult<ResultT> {
	const operationName = (document.definitions[0] as OperationDefinitionNode)
		.name?.value;
	if (!operationName) {
		throw new Error(`Could not find operation name for document: ${document}`);
	}
	const queryKey = [operationName, variables] as const;
	return useQuery({
		/* eslint-disable-next-line @tanstack/query/exhaustive-deps -- Using
		   operation name should uniquely represent the document, so we do not need
		   the entire document in the query key. Also see GraphQL Code Generator’s
		   recommendation (link at top of file). */
		queryKey,
		queryFn: async ({ queryKey }) =>
			// Use `queryKey[1]` via the context to reduce closure scope (I think)
			request(`<ENDPOINT>`, document, queryKey[1]),
	});
}

/** Helper type to force empty object to undefined. */
type Strict<T> = T extends Record<string, never> ? undefined : NonNullable<T>;
// Bike-shed this helper name. `Strict` does not feel exactly right.