Common Patterns for React? onCompleted callbacks?

[JacksonChristopherHowell]

Hello All,

I am having trouble finding examples of common patterns in react, outside the bare minimum, super-simple query setup.

I can't anything find about best practices for using urql in conjunction with state-management tools like zustand, for example.

Also, wondering what the preferred pattern for something like Apollo client's "onCompleted" hook would look like? ChatGPT4 is telling me to use an useEffect hook, but that doesn't seem great to me, too many potential side-effects with the dependency array and whatnot.

Would love to see any resources out there! Thanks!

[JoviDeCroock]

What's your use-case behind the need for onCompleted, I personally feel it's a bit imperative in the realm of React 😅 I do support the idea of having an effect to react to the side-effect of data being fetched as that ties into the React (and Suspense) cycle much better.

There's also the case of variables changing, do you always want that callback to be invoked, we could be showing the previous state from the hook as new data comes in?

An example of the effect would be

useEffect(() => {
  if (result.fetching) return 'we are loading'

  if (result.data || result.error) return 'we have completed loading'
}, [result.fetching, result.data, result.error])

however nothing is stopping you from abstracting this into your own useQuery hook.

What are other use-cases or patterns you are looking for?

[JacksonChristopherHowell]

Hi @JoviDeCroock, thanks for getting back to me so quickly! Very kind of you.

We are introducing a new product at my company. The existing product uses Apollo client and we rely heavily on the onCompleted and onError hooks to parse query results into new data-structures optimized for display on the front-end, and handle errors. After parsing we often set them into a store, like zustand. Sometimes we store different parts of a single query in different state variables/stores etc. I think this is all pretty common.

Sorry for not being more specific at the moment, but I am just beginning to play with URQL. I have been searching online and am really struggling to find examples for React, like a custom hook or even a common pattern, beyond a basic query with loading and error. The ones in the docs are not super useful in this scenario. The infinite scroll example is interesting but I'm not really concerned with that use-case yet. Maybe there is a simple pattern to abstract from that example but I'm not seeing it.

[JoviDeCroock]

I mean, the above useEffect is similar to the onCompleted/onError API combined, no?

useEffect(() => {
  if (result.fetching) {
    // Do your loading logic
    return;
  }

  if (result.stale) {
    // Do your stale logic (background refetch)
    return;
  }
  
  if (result.data) {
    // Do your completed logic, this might still have errors, this is GraphQL.
    return;
  }
  
  if (result.error) {
    // Do your error logic, as this is a fatal one, no data
  }
}, [result.fetching, result.stale, result.data, result.error])

if we expand that logic we can just do

export const useQueryWithHelpers = () => ...

I do want to emphasise that most data-fetching libraries move away from these callbacks as it's a footgun in terms of timing/... there are a lot of cases where we have data/errors that can bite back. Example: https://twitter.com/TkDodo/status/1647341498227097600

[JacksonChristopherHowell]

Hey thanks again! I really appreciate the discussion.

Gotcha. Yes, I understand. And okay, wow, interesting tweet! I was not aware.

One issue I have is I tend to avoid useEffects where possible since they can introduce some side-effects from time to time. Sorry to be lazy, but a quick ChatGPT4 gives us the following potential drawbacks:

The useEffect hook in React is a powerful tool for handling side effects in functional components. However, like any feature, it comes with potential disadvantages or pitfalls if not used carefully. Here are some of the key ones:

Over-Fetching or Unnecessary Renders: Mismanagement of dependencies in the dependency array of useEffect can lead to excessive re-rendering or over-fetching of data. For instance, if you include a prop or state value that changes often, the effect will run too frequently.

Memory Leaks: Not cleaning up listeners or asynchronous tasks can lead to memory leaks. If an effect sets up a subscription or starts an asynchronous task, it should return a cleanup function to avoid memory leaks, especially in cases where the component might unmount before the task completes.

Complex Dependency Management: Understanding and managing dependencies can be tricky, especially in effects that depend on props or state. Mistakes in specifying dependencies can lead to bugs that are hard to trace, such as stale state or props.

Performance Issues: Inappropriate use of useEffect can lead to performance issues. For example, performing heavy operations like deep object comparisons or complex calculations without memoization can slow down your application.

Infinite Loops: Incorrect dependency handling can lead to infinite loops. If an effect modifies a state or prop that it also depends on, without proper conditions, it can trigger an endless re-render cycle.

Testing Complexity: Components with many side effects can be more challenging to test. The more a component relies on useEffect for its functionality, the more you need to consider mocking and spies in your tests.

Delay in Rendering: Since useEffect runs after the render is committed to the screen, there can be a noticeable delay in updating the UI, especially if the effect is doing substantial work. This can lead to a less smooth user experience.

Server-Side Rendering (SSR) Limitations: Effects do not run during server-side rendering. If your application relies heavily on useEffect for loading data or other initial setup, you might need additional logic to handle server-side rendering.

Misuse in Place of Other Hooks: Sometimes, other hooks like useMemo or useCallback might be more appropriate for certain cases, but over-reliance or misunderstanding of useEffect can lead to suboptimal solutions.

Complexity with Cleanup and Asynchronous Operations: Managing cleanup functions, especially in combination with asynchronous operations, can increase the complexity of your component logic.

To mitigate these disadvantages, it's important to have a solid understanding of how useEffect works, particularly its dependency array and cleanup mechanism. Careful planning and thoughtful consideration of when and how to use useEffect can help avoid these pitfalls.

Now that said, I do still use them from time to time, just a little wary of making them such a crux of my pattern throughout the app. Wondering if there are other options/patterns that folks have come up with.

[kitten]

Disclaimer: I know this got quite long, sorry! But the tl;dr here is that:

• external state stores aren't quite as straightforward (nor the best solution for problems most of the time) than they seem,
• effects and synchronising state while avoiding tearing is what you want, but without knowing that it's hard to explain what you're looking for
• you can still call into client.query directly, inside of an effect, use an effect on useQuery's output (which delays further state updates, causing tearing though), or directly update your state in render (which is an “advanced” pattern and must be used with caution, so I wouldn't recommend it)
  • tl;dr: there be dragons
• and lastly, there's some problems here that I see coming up, and while I hate shifting blame here straight away, they don't come down to “urql v Apollo” but to other problems

---

Let's back up here a little. I'd like to respond with some notes of caution, but I'll put them at the end, since they're not immediately relevant to the question you posted.

You're basically asking two things:

• do the urql React bindings have a callback that's fired on each result? (and if not, why?)
• is there a way to respond to and update external state on each result?

The answer to the first question is simple; no, no bindings across all frameworks have an escape hatch in their “binding-appropriate” code to attach effects to any given GraphQL operation. This goes so far in fact, that we struck out and won't add a promise return-value to executeQuery. And this is done for very specific, but complex reasons.
To put it short: This is done to guide you (a) towards good UI practices (both in terms of React and in general), and (b) to avoid potential pitfalls and footguns.

To answer the second question, there's multiple ways to respond to results. React’s useEffect exists for a reason and it’s explicitly a hook to separate side-effects into a separate flow in React that is isolated in terms of timing. React gets full control over when this runs, which of course, can sometimes be problematic in certain conditions.
So, in fact, they don't optionally introduce side-effects, they mark and isolate them.

We can go at this from a few different angles,

• how to actually approach adding additional state and side-effects between urql and React
• how Apollo and other libraries like react-query handle onComplete
• how React handles effects and the timing of renders, effects, and state flushes

useEffect

Now, again, the simple answer to your question on how to hook into results is to use useEffect. We'd set up an effect that simply synchronises urql’s result to your state store.

This introduces timing issues that libraries like Apollo and urql face themselves in their bindings to React.
The long story short is that there's multiple concepts of state and effects in React that are hidden away and change depending on what's going on, e.g. whether something has suspended, whether strict mode is enabled, whether there's queued effects or renders, etc.

The short note here is: you either synchronise state updates or you don't.
There's a lot of different timings you can choose, but what you're concerned about is basically that useEffect doesn't synchronise your state updates to urql’s state update triggered re-renders.

If that's the case you could opt to write your state updates directly in the render function; not really suitable at all times, and potentially a foot gun.

client.query

The other answer here is, how do I, instead of synchronising state updates in React synchronously, sync them up with urql, so that they're simultaneous to an urql update?

The answer here is simpler.

All of React's render cycles are delayed and potentially batched and/or deferred. But, if we update our state at the same time as urql “reports” new state, then from React’s perspective, they happen at the same time.

In other words, we don't have the following not only because they encourage control flow and non-UI code within UI bindings:

• onComplete
• configurable callbacks in useQuery
• promises returned by executeQuery

but, we also don't have them because there's a single way to opt out of them: calling the Client directly and having your own effect.
You can even do this in parallel to useQuery.

const client = useClient();

useEffect(() => {
  return client.query(/*...*/).subscribe((result) => {
    // update external state here
  }).unsubscribe;
}, [/*potentially query inputs*/]);

This here means that the inputs into query may be delayed, but ultimately, updating any React state (which shouldn't be necessary over a useMemo if a useQuery is present) or updating external state stores (what you're interested in) is done at the same tick both for useQuery and your store.

In other words, since the tick for the update will be the same for any setState store that cascades out of this result event, React sees them all at once, and tearing is prevented.
useQuery itself (like other bindings, e.g. Apollo’s) have special ways of opting out of interruptible renders anyway, but that's a side-note and a more complex topic.

But the short of it is: you're essentially avoiding tearing — or, different parts of the UI being out-of-sync from one another.

how do other libraries handle this?

To pull the curtains back a little.
Apollo implements onCompleted completely in their bindings too, which is kind of necessary.

Hypothetically, let's say you call setState in the render function, which is an explicit opt-out and restarts the current components render. This can sometimes mess with your expectations. It's in essence what useQuery for us does, and while Apollo uses useSyncExternalStore it's a similar situation.

For multiple reasons, adding on more state updates within the render function may not always yield expected and intuitive results.

This is actually solved in Apollo by delaying the call to onCompleted for a tick. To put it differently, Apollo solves this by delaying your effect. This can have unintended consequences and may not avoid tearing, and instead, simply means they don't guarantee as much as you think by doing this.

This is why react-query is looking to remove this pattern, afaik, although I'm not certain of their guarantees and behaviour.

The promised disclaimers

So, to summarise, I've left some notes on:

• tearing in React and React update/render/effect timings
• two/three approaches to synchronising your state store to urql/React state
• a bit of info on what these all do and mean

I know this is a lot, but I did promise some more notes in the beginning, because essentially, these two things you said raise alarm bells for me:

to parse query results into new data-structures optimized for display on the front-end

After parsing we often set them into a store, like zustand. Sometimes we store different parts of a single query in different state variables/stores etc.

It isn't that this is wrong in any way, or it's not the case that you can't do this.
However, I would recommend to see this in a different light and maybe evaluate the above and some other reasons of why this might not be a good approach.

When you say you're moving state into Zustand, you're basically introducing an additional state store.
If you were to look at Jotai, you can see how much it takes to make an external state store that's deeply integrated with React's timing and API.

In short, and to simplify a little, creating non-computed UI state outside of React, sync'ing it back and forth, and using it as UI state external to your components is a slippery slope that can look appealing, but introduce more problems down the line.

In a way, GraphQL opposes this by being a comprehensive and opinionated solution for “data” in apps, i.e. all data will be mapped to UI/components directly.
Once you step into local UI state (say forms) but pull it out into separate state stores and overdo this (i.e. start to have another form of external state that stores “UI state + data”) you've basically coupled multiple pieces of state back to themselves, losing a lot of the benefits of GraphQL.

This also ties into the other statement, where you say you're mapping GraphQL data to “front-end friendly data”. I obviously don't know what shapes you're converting to and from, but I'd always expect GraphQL to exactly deliver what your frontend needs to map the data it requires to UI.

That's why fragments are also ingenious: We get to define fragments alongside components which define the data components accept and map to UI, passing data to more components along the way with their fragments defining what data they require.

Anyway, I tried keeping some of this short, but it's quite long, sorry! 😅
I have some of these ideas (but not in a GraphQL context) stashed away in this blog post too btw: https://formidable.com/blog/2021/react-components/
But I simply don't have a comprehensive doc to link to instead.

[JacksonChristopherHowell]

Wow, tremendous summary! Thanks so much for that thoughtful response and taking the time to be so thorough.

I understand what you mean when you say the following vis a vis state-management,

It isn't that this is wrong in any way, or it's not the case that you can't do this.
However, I would recommend to see this in a different light and maybe evaluate the above and some other reasons of why this might not be a good approach.

Indeed this is a constant topic lately for our team as a whole. And I do agree!

Unfortunately, our API is pretty complex at this point and there are some relationships between data from different queries we are forced to establish on the front-end from time to time. So while I do agree, there may be times we cannot avoid it; or maybe I'm just not understanding the better option yet, like how those relationships could be easily established otherwise.

This is has been helpful. I enjoyed that part about "done at the same tick both for useQuery and your store".

I will try out the useEffect pattern and see how it goes. If I encounter anything significant, or can provide more specific scenarios, I will reply with an update.

Thanks again!