TypedDocumentNode react-query hooks

[dusty]

I stumbled upon TypedDocumentNode and its a pretty nice helper for typescript and graphql.

https://the-guild.dev/blog/typed-document-node
https://graphql-code-generator.com/docs/plugins/typed-document-node

Using that, I was able to build a pretty simple and fully typed wrapper around graphql using fetch and then utilize that in some simple react-query graphql hooks. In this implementation, I prefixes all cache keys with the operationName, which makes it easy to do cache invalidations after a mutation.

I made a little sample here at this codepen, feel free to check it out. Let me know if you see any opportunities for improvement.

https://codesandbox.io/s/festive-villani-ngswo?file=/src/App.tsx

NOTE: The free api I'm using doesn't actually persist the mutations, so you won't see a create mutation show up in the list, but you can see the that the query was invalidated and refetched after the mutation.

Here is a taste of what the API looks like. See the useGraphql.ts file for implementation details.

const queryClient = useQueryClient();

const getPosts = useGraphqlQuery(PostsDocument, {
  options: {
    paginate: { limit: 10 },
    sort: [{ field: "id", order: SortOrderEnum.Desc }]
  }
}, { enabled: true });

const createPost = useGraphqlMutation(CreatePostDocument, {
  onSuccess: () => queryClient.invalidateQueries("posts")
});

You can see the types come through

The idea is that you create some .graphql files with your schema and then your documents. You run npm run codegen and it will spit out all the types and the typed document nodes into a file. You can then import those typed document nodes and pass the to any of the useGraphql functions.

[amosbastian]

Why wouldn't you just use the hooks generated by the code generator?

[amosbastian]

I can definitely see the advantage of doing it like this, so thanks for sharing! I think I'll probably take the same approach, especially since I'll need to add a user's token to the authorisation header after they log in anyway.

We also now have a nice custom package for our hooks where we added middleware, cache invalidation, pagination automation (based on our common schemas), etc..

For cache invalidation (using onSuccess) I don't see any reason why the generated hooks would have any different behaviour, or do you mean something different? As for pagination automation, I'm pretty curious 👀

[dusty]

For invalidations.

We built up a Map of operationName to queryKey prefixes. Then in the onSuccess of a mutation we iterate through it and clear out all the caches. We originally tried to do this by parsing the schema in graphql codegen and automatically figuring the the different types that could be returned in a query, but we found we couldn't quite get it right because of our schema.

It looks something like this. This resides in the hook package.

/*
  Map of mutations to queries that should be invalidated
  {
    'createUser': ['getUser', 'searchUsers']
  }
*/
export const GraphqlMutationInvalidations: Map<string, Set<string>> = new Map()

/*
  Add a mutation and associated queries to the map

  addGraphqlMutationInvalidations({
    'createUser': ['getUser', 'searchUsers']
  })
*/
export const addGraphqlMutationInvalidations = (map: Record<string, string[]>) => {
  Object.entries(map).forEach(([mutationName, queries]) => {
    const set = GraphqlMutationInvalidations.get(mutationName) || new Set()
    queries.forEach(query => set.add(query))
    GraphqlMutationInvalidations.set(mutationName, set)
  })
}

Now, further down in the mutation

/*
  Graphql wrapper around react-query `useMutation`.

  const createUser = useGraphlMutation(CreateUserDocument, { ...useMutationOptions })

  try {
    const res = await createUser.mutateAsync({ name: 'me' })
    Alert.success(`${res.createUser.name} was created`)
  } catch (err) {
    Alert.error(err)
  }
*/
export const useGraphqlMutation = <TData = any, TVariables = Record<string, any>>(
  operation: TypedDocumentNode<TData, TVariables>,
  options?: UseMutationOptions<TData, GraphqlError, TVariables>,
  middleware?: GraphqlFetchMiddleware
) => {
  const operationName = useMemo(() => getOperationName(operation) || '', [operation])
  const queryClient = useQueryClient()
  const opts = useMemo(() => {
    return {
      ...options,
      onSuccess(data: TData, variables: TVariables, context: unknown) {
        options?.onSuccess && options.onSuccess(data, variables, context)
        // invalidate based on the typenames associated with this mutation
        if (!isProduction) console.group(`invalidate: ${operationName}`)
        GraphqlMutationInvalidations.get(operationName)?.forEach(op => {
          if (!isProduction) console.log(op)
          queryClient.invalidateQueries(op)
        })
        if (!isProduction) console.groupEnd()
      }
    }
  }, [options, queryClient, operationName])
  return useMutation(
    (variables?: TVariables) => graphqlFetch(operation, variables, middleware),
    opts
  )
}

So, what is that doing?

In our init inside our app, we define the mutation operationNames to query operationNames

/*
  Set Mutation to Query invalidations

  This is done manually because its too inaccurate to fully understand the relationship
  between the data sets.

  The first argument is the mutation name, the second argument is one or more queries
  that should be invalidated.
 */
addGraphqlMutationInvalidations({
  updateUser: ['getUser', 'searchUsers'],
  createUser: ['searchUsers'],
  deleteUser: ['searchUsers']
})

Since the first part of all our keys is the operationName, we can set these all up in advance and don't have to remember these things through the app.

So, in the example above, I might have a searchUsers query, the actual key might be something like ['searchUsers', {limit: 10, search: 'something'}]. But, with the invalidation, you can give it a prefix and it will invalidate all the caches that start with that prefix.

So, when we do a createUser mutation, it will automatically invalidate all the searchUsers caches. This will update the current view and make sure if we change pages, those will be invalidated and refetched. It might seem overkill, but its really not that much different than having a staleTime of 0. In a particular page, we probably only have 1 at the most 2 queries that are being observed for a particular prefix.

[dusty]

For the pagination automation, our schema follows a particular format, something like

{
  data: [User]
  results: {
    totalCount: Int!
    hasMore: Boolean!
  }
}

Since we know the data will look like that, when we are using an infinate query, we are able to automaticaly generate the getNextPageParam by looking at the results that we received. So, our useGraphqlInfiniteQuery will automatically add the getNextPageParam to the options unless its passed in. That means we can just use fetchNextPage, hasNextPage without having to add any logic.

[dusty]

Also, since we are in control of the fetch as well, we were able to add middlewares into the flow that can handle the token headers. We added a mock implementation that can shortcircuit the fetch request and return whatever data we supply to it for a particular operationName. That is helpful if you are building out a page before the backend is ready. We even have an error handler in there that gets called if its a non ok response.

In our case, making a custom hook that handles all this was pretty easy using this setup. If you are going to make a generic package that a large audience is going to consume, it can be more difficult to predict all the use cases and variables that might be needed.

But, I'd be happy to share more if you are looking to do something similar.

[amosbastian]

Thanks a lot for your replies, really makes sense what you did and I'll probably end up implementing something that is very similar 🤩 I'm definitely also interested in hearing more about the middleware you've added for token headers if you have time, as that is something I will need to do as well.

[amosbastian]

Was wondering how you handle hydration?

[dusty]

I use this in a client side app

[amosbastian]

I see, no worries. Finally using this in a real project and it works like a charm! About to start adding middleware, so let's see how that goes 😆

[amosbastian]

I think the type of options are broken by a recent update of one of the packages it depends on in case someone tries using this. Not sure how to fix it as I haven't had time to look into it myself yet.