Hook for triggering validations manually (passive mode)

[shuding]

Motivation

There are a lot of existing discussions and feature requests about doing requests manually in SWR (e.g. #93, #116, #550, #1082), and we do see some valid use cases for it. In short, we need something that:

• Do not revalidate automatically (mount, focus, reconnect, retry...)
• Return a callback function for triggering the validation manually
• Backfill the request response to the cache*

*: Potentially we can have a switch to turn on/off this step.

One option is to have a new hook, because the arguments would be slightly different from the useSWR hook. Since we now have better abstractions to build such a hook, namely middlewares and revalidateWhenStale, this PR is such an attempt.

useSWRTrigger

import useSWRTrigger from 'swr/trigger'

// fetcher impl.
function getData(url, token, opts) { ... }

// normal SWR API, but it will never start the request
const { data, error, mutate, trigger } = useSWRTrigger('/api/user', getData, { onError, onSuccess })

// trigger it manually, args will be passed to the fetcher (after the key arg/args)
trigger('myToken', myOptions)

// wait until it's done
await trigger('myToken', myOptions)

The trigger() call will still reflect the hook-returned data and error with a re-render, but that's more declarative.

To-dos

• Finalize the name of the hook.
• Sometimes, mutation APIs (POST, PUT, DELETE) return different payload from the GET API. It might be an issue if we write back to the cache with the same key. This behavior needs to be reconsidered.
• If the mutation APIs' results cannot be cached, that normally means that we need to revalidate those keys again if there's a useSWR hook with the same key. This can be another option to consider.
• Ensure callbacks and isValidating state are working as expected.
• Ensure with a test case that under trigger mode there's no deduping.
• Ensure with a test case that trigger prevents race conditions with normal GET requests.
• (docs) Have a specific list of options, that can be used in useSWRTrigger and ignore the others.

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit be647cc:

Sandbox	Source
SWR-Basic	Configuration
SWR-States	Configuration
SWR-Infinite	Configuration
SWR-SSR	Configuration

[giuseppeg]

RE:

Sometimes, mutation APIs (POST, PUT, DELETE) return different payload from the GET API. It might be an issue if we write back to the cache with the same key. This behavior needs to be reconsidered.

When the user is not interested in updating the global cache for key they can use the fetcher right away i.e. they won't need useSWRTrigger right?

[shuding]

Yes. But I'm also thinking about an option to prevent updating the cache, but then useSWRTrigger will have nothing "SWR". Haven’t decided yet.

[shuding]

This API needs more discussions, will keep it on hold for 1.0.

[shuding]

Some thoughts:

• Passive hooks still need to have a key specified, even if it's not used by that request. Remote mutations are associated with normal GET requests, we need the key to avoid race conditions and do cache write back.
• Each passive hook needs to have its own states (data, error, isValidating), which won't be shared with useSWR or other passive hooks with the same key.
• Error retry should be turned off by default as remote mutations will be more likely to get 4xx errors than GET requests, and retrying won't help.
• There should be a way to reset/clear the state as the request can be triggered again, and it is not idempotent like GET requests.
• There should be an option to enable/disable writing back the value into the cache, as well as triggering a revalidation after it ends.

[giuseppeg]

Some thoughts:

• Passive hooks still need to have a key specified, even if it's not used by that request. Remote mutations are associated with normal GET requests, we need the key to avoid race conditions and do cache write back.
• Each passive hook needs to have its own states (data, error, isValidating), which won't be shared with useSWR or other passive hooks with the same key.

The solution that I am currently using (https://twitter.com/giuseppegurgone/status/1427576808204034061) is close to this except that I don't use a key and revalidate but mutate programmatically.

I think that triggering a revalidation (a GET request) when the remote mutation is complete is a good option although it could be redundant work, lead to higher consumption of resources since the mutation could already return the fresh data.

[shuding]

Continuing this feature in #1450.