What does mutate do?

[rwb196884]

The documentation suggests that it's something to do with marking the cache entry as dirty (which, bizarrely, is also called validation).

What I need is to make changes to the data -- while the user is editing it -- before sending it back.
Does it do that or do I need to get a separate useState to put the data in while it's being edited?

[ver1fy]

In scenarios like this, the boundary between client and server state becomes blurred. I often conceptualise mutate as committing data to the server. You'll have some client state which is responsible for maintaining user edits (i.e. the dirty data). Once it’s ready to submit, you'll call mutate to update your server state and invalidate cache.

Whilst this does theoretically raise a red flag for duplicating state, I believe the scenario you have described is a valid exception to this rule. Just take extra care to ensure you derive the correct state on success, error etc.

Tl;dr: useState for local edits, mutate for 'committing' data to the server/cache.

[rwb196884]

OK, so I still need to useState, that's helpful, ta.

Does it just assume to PUT to whatever path it used for GET? I expect there's some carefully boobytrapped and undocumented naming convention going on somewhere?

[ver1fy]

mutate will only invalidate the cache unless you specify how to perform the mutation. You can achieve this by using the second argument: data.

data to update the client cache, or an async function for the remote mutation

[rwb196884]

So mutate() will trigger a GET to get the data again?

What does mutaate(something) do?

I could imagine using mutate instead of separate state, but I don't understand how this can send data back to the API.
Indeed, you really wouldn't want it PUTting every single user keystroke (that sort of thing is web socket territory) -- you need to wait until the user clicks the save button.

    let apiItem: SwrResponse<any> = useGenericGetById(params.datasetId!, params.type!, params.modelKey!, swrConfig(!isNewItem && api, setMessages, 'Error getting item data.'));
    useSwrResponse(
        apiItem,
        (data: any) => {
            setModel({ key: null, value: data }); // set state for user to do edits
        }
    );

function onUserClicksSaveButton() {
  // need to PUT the updated `model` to the server.
  // can this be done with `apiItem.mutate(model) ? How?
  // orval has generated a method that does the PUT and returns a Promise
  // genericPut(params.datasetId!, params.type!, model).then(...

[ver1fy]

Correct, calling a bounded mutate with no arguments will trigger a refetch. This might be useful if you have a button to allow users to manually refresh a news feed or something. You certainly wouldn’t want to be calling mutate on every keystroke. As before, mutate should be called when you want to 'commit' the client state. There is an example of this in the docs:

try {
  const user = await mutate('/api/user', updateUser(newUser))
} catch (error) {
  // Handle an error while updating the user here
}

updateUser is the API call to modify server state. When dealing with forms, you'll want to maintain state separately (either controlled or uncontrolled) and then mutate in your onSubmit handler using data extracted from local state (useState or useReducer).