Deterministic, finite states & caching

[jxom]

Yo!

So this lib is actually amazing, and very well thought out in terms of it's architecture. I'm really loving and enjoying using it too!

This library makes use of async logic (ens lookup, obtaining balance, switching networks, etc) quite a lot, and I have a few ideas to make the user experience even better:

1. Finite & deterministic states

At the moment, states in this library are implicit & indeterministic, meaning that it is not possible to retrieve a finite state from the values exposed from the hooks, which could lead to UX bugs. At the moment, we can represent async state via the following values:

• loading is the "loading" state, and is obviously explicitly represented,
• data is the "success" state, and it represented implicitly through data.
• error is the "error" state, and it represented implicitly through error.

Representing async state via these values works, but can lead to the following issue:

There is no idle state & implicit states can be confusing

Some hooks don't automatically invoke, so at the moment, if we wish to represent an "idle" state with the exposed hook values, it would be achieved like so:

if (!loading && !data && !error) {
  ...
}

which does look a bit confusing to me, and consumers could be bound to representing idle state like so if they are not careful, that could lead to UX quirks:

// error state leaks in this example
if (!loading && !data) {
  ...
}

// or

// loading state leaks in this example
if (!data && !error) {
}

It would be nice if we can represent all possible states with a set of finite & deterministic state variables. There could be state variables such as isIdle, isLoading, isSuccess & isError (which are deterministic, meaning only one can be truthy at a time, they can't overlap). This API is similar to react-query too.

const [{
  isIdle,
  isLoading,
  isSuccess,
  isError,
  data,
  error
}, signMessage] = useSignMessage();

This makes render logic cleaner, and easier to follow:

function Example() {
  const [{
    isIdle,
    isLoading,
    isSuccess,
    isError,
    data,
    error
  }, signMessage] = useSignMessage();

  return (
    <>
      {isIdle &&
        <button onClick={() => signMessage({ message: 'sup' })}>Sign da message</button>
      }
      {isLoading && 'Signing...'}
      {isSuccess && `Signed! Signature: ${data}`}
      {isError && `Error! ${error.message}`}
      
      /*
      before:
      {!loading && !data && !error && 
        <button>...</button>
      }
      {loading && 'Signing...'}
      {data && 'Signed!'}
      {error && 'Error!'}
      */
    </>
  )
} 

For some hooks, this terminology might not make sense, e.g. isIdle may not make sense for useConnect. We could make it more specific to "connecting" to a wallet?

const [{
  isDisconnected,
  isConnecting,
  isReconnecting,
  isConnected,
  data,
  error
}, connect] = useConnect();

2. Cache what we can, where we can

I really think there is room for improvement with the initial state UX for connecting to a wallet. I feel that most dapps these days have a "flash of loading wallet/resolving ens" experience, and if we can solve that issue in this lib, then that would be awesome.

At the moment, we see this "flash of loading wallet/resolving ens", which seems a bit jarring:

I think it would be nice if we could try to cache what we can, where we can. In this circumstance, I think it could be possible to cache stuff like account address, ens, avatar, balances, etc in local storage, and then display the data from local storage straight away when the user navigates back to the dapp. Representing this in the current API could be hard, as I feel like there should be a flag to indicate that the wallet is currently in a state of reconnecting. In the proposed API, this could be possible via the isReconnecting flag. Below is a diagram to represent a possible flow for useConnect:

I think this could be achievable integrating w/ an async state lib like react-query or swr, and utilise it for our async functions (also means we don't have to deal with caching as well as setting loading/success/error state as react-query/swr handles this internally).

Anyway, that's my idea & proposal!

What are your thoughts on this? Do you have any ideas?

Also, I am more than happy to contribute!

[sammdec]

Big fan of this proposal, I really like the deterministic way that react-query and swr represents state.

As for caching ens I would worry that caching it in local storage could create a lot of complexity in when to expire the cache or revalidate as technically the ens name and avatar could be updated at any time independent of the app lifecycle.

[jxom]

@sammdec – yes I agree that caching can defs create a lot of complexity in regards to stale data & when to invalidate. In my opinion, I think a possible solution to this would be to display the stale data while it revalidates in the background (aka "stale-while-revalidate" – react-query/swr has this built-in). I think this method will be acceptable for stuff like ENS data, token info, reading contracts & balances, but maybe not so much for fee data & block number? Guess we just have to choose which stuff a "stale-while-revalidate" approach works best for, and which stuff to disable the cache for. I think it'd also be nice for the consumer to have control over the time the data exists in the cache & the time before it takes the data to become stale.

[sammdec]

Yeah I agree with the swr approach for certain pieces of data. That’s where a isFetching state property might be useful as it allows for granularity in showing that data is available but that a background fetch is occurring.

I know that react-query comes with some nice configuration around handling stale data time etc. I do worry that adding a library like swr or react-query would bloat out this library especially when some people might be using one or the other in the rest of their app.

[sammdec]

I wonder if it’s possible to take some of the internals from things like react-query/swr and implement a subset into wagmi

[gosseti]

Some excellent thinking here. I’m a big fan of react-query and how it gives much more granularity to represent the lifecycle of a query/mutation. Having deterministic states will help build some really elegant UI that’s very declarative and easy to reason about.

My concern is the same as @sammdec’s, you’re then bundling in a (by no means) small dependency in with wagmi. If you already have react-query or SWR it could get funky having two query providers in your app. The concepts should certainly be borrowed though!

Quick aside: another thing I really like about the react-query hooks is the ability to couple callbacks with the hook itself, something along these lines:

const [state, connect] = useConnect({
  // keep additional logic involving connecting wallets coupled with the hook
  onConnected: wallet => {
    // do something on connect 
  },
  onError: error => {
    // handle the error 
  }  
})

Storing the address + ENS in localstorage could be a great optional thing to have, but I probably wouldn’t want that as a default behaviour (e.g. what would happen if I closed the tab, changed accounts and came back again… it could feel choppy vs. handling the isConnecting state).

[tmm]

Love this discussion. Major props @jxom for kicking things off.

1. Finite & deterministic states

We should do this. I'm a proponent of API standardization. Learn how one wagmi hook works (especially hooks related to data fetching) and apply that knowledge to working with others.

It would be great if there was a core useQuery hook that did the heavy lifting for data fetching, then most hooks could be thin wrappers around useQuery. Two additional considerations for a useQuery abstraction are updating on account, chain, and block changes.

Non-data-fetching hooks should also implement these or similar domain specific states (a la @jxom's useConnect example).

2. Cache what we can, where we can

This would be a boon for user experience (and Alchemy/Inufra bills lol). Like others mentioned, there are a few ideas: use local storage, add third-party lib to the core (react-query/swr), implement our own cache.

It could be interesting to approach this by using different package entrypoints for the hooks:

import { useEnsLookup } from 'wagmi'
import { useEnsLookup } from 'wagmi/swr'
import { useEnsLookup } from 'wagmi/react-query'

While the wagmi core useQuery hook could have some lite caching, this approach also allows projects to adopt more advanced caching without forcing a hard dependency into the core of the library. All hooks would follow the same API, even though they are different imports.

---

@jxom @gosseti @sammdec any thoughts? (anyone else welcome to chime in to!)

Some more granular details to chat about:

• How does a core useQuery hook look? Does it include lite caching?
• How does wagmi standardize hooks across core, swr, react-query? What should the states be? Do we start with swr or react-query?
• How does wagmi handle mutations (writing to contract and updating events) and cache updates? Is subscribing to blocks an acceptable (basic) approach?
• How do we want to contribute? Would love to divide and conquer, and make wagmi a sustainable, multi-contributor effort.

[sammdec]

Sorry have gone down with a cold but have been mulling this over still! How do we feel about splitting out mutation-esque actions and read actions into their own hooks

[tmm]

Sounds good to me. Got a quick example?

[sammdec]

For example

const {data, isLoading, is Success} = useAccount()
const {connect, disconnect, data} = useConnect()

or if we wanted to be even more explicit

const {data, isLoading, isError} = useAccount()
const {connect, disconnect,} = useConnectActions()
const {data, isLoading, is Error} = useConnectData()

[tmm]

Got it! (Sorry was AFK for a while.)

I'm usually down to make things more explicit, but worry about folks needing to remember a lot of hooks to be productive. (Also, think it's better to keep disconnect attached to useAccount.)

Let's keep the hooks in tuple form ([result, ...actions]) for now and get the finite states, etc. ready to go.

I have some time this week so happy to give feedback, pair, and/or migrate hooks once we get this kicked off.

[jxom]

yoyoyo! sorry, I have been so busy as of late, been moving house & busy @ 🌈!!!

I am currently in the middle of writing an RFC on this. Hope to get it finished by mid next week hopefully! But will be awesome to get some feedback on it, then we could go for a kick off?

[jemgold]

Love this thinking @jxom, thank you!

Two other options that spring to mind (I'm not sure if they're good ideas!):

1. tagged unions representing the full lifecycle of a hook.

it's been a while since I did anything like this, but this kind of pattern: https://matiasklemola.com/typescript-union-types

interface NotAsked {
    type: 'NotAsked'
}

interface Loading {
    type: 'Loading'
}

interface Success<T> {
    type: 'Success'
    data: T
}

interface Failure<E> {
    type: 'Failure'
    error: E
}

type RemoteData<T, E> = NotAsked | Loading | Success<T> | Failure<E>

2. alternatively a state machine ala xstate (but maybe that's too big of an API change / dependency; the whole nice thing with wagmi is how concise it is)

---

kinda tangent, but I'm also curious if there's a standardized way we could merge states from multiple queries, e.g. I've been doing something like this

const [{ loading: accountLoading }] = useAccount()
const [{ loading: messageLoading }] = useSignMessage()

// any : boolean[] -> boolean
const loading = any([ accountLoading, messageLoading, ... ])

[jemgold]

update to my last point about combining states - I think you could do something like this (pseudocode!)

type Predicate = (data: RemoteData) => bool

isLoading: Predicate = (data) => data.type === 'Loading'

any = (pred: Predicate, xs: RemoteData) => bool;
any(isLoading, [fooLoading, barLoading])

[jxom]

An RFC for this has been posted here: #153

[jxom]

A bit of an update:

We now have an active development branch for the new @wagmi/core package that will serve as a framework agnostic wagmi client (it is undocumented – however, feel free to check out the example and even the actions/ test cases).

Right now, we are working on migrating the wagmi (react) package to #247 as per this proposal.

If anyone wants to help with a swr adaptor, or even a svelte or vue client for wagmi, feel free to reach out! With the new foundation of @wagmi/core, building these framework specific clients should be trivial.

[jxom]

wagmi 0.3 has been released, introducing:

• First-class caching, request deduplication, and persistence
• Deterministic, finite states
• A vanilla JS client (the @wagmi/core package)

Check out the docs.

[eliobricenov]

I've got the same question as @carlbarrdahl

[eliobricenov]

Maybe use https://wagmi.sh/react/hooks/useContractRead#cacheonblock-optional? In theory, any change will be submitted in the next block so staling the data makes sense. That being said, this means that there will be some reads even if we don't need them so it would be really valuable if we could invalidate it manually.

[eliobricenov]

@carlbarrdahl just found out that we can use the refetch function from the hooks to refetch the read action.

https://wagmi.sh/react/hooks/useContractRead#return-value

[tommylinks]

I recently try to use wagmi and i was surprised how cool is it. BUT, then i faced a problem with the cache invalidating. I was confused because i can't manage cache by keys globally like in react query queryClient.invalidateQueries({ queryKey: ['todos'] }). And it's weird because i can import queryClient from wagmi and call queryClient.invalidateQueries({ queryKey: ['todos'] }) but it's not working properly.

Using refetch usually not an option, because the component where i need to refetch data may located far away in nested components, so i have to make prop drilling, and its a bad idea.

Using watch for useContractRead - it's working, but i guess its not a good idea, to make a request for each block, may bed for performance and rpc can block you.

@carlbarrdahl wrote about it almost a year ago, but as i can see the problem still exist.

It would be great to add ability to invalidate queries like in react-queries library and add refetchInterval to control the time of updating data automatically

[tmm]

Thanks for the feedback! Definitely something we are going to improve in the near future with wagmi@1.