Questions about data fetching

[jongmin4943]

I've been reading docs and making small project to understand Nuxt3. It was working good until data-fetching.
I've got two questions.

First, what is difference between refresh and execute method? I read UseAsyncData docs and I don't really understand the reason why execute and refresh method exist together. The docs says refresh/execute: a function that can be used to refresh the data returned by the handler function

type AsyncData<DataT, ErrorT> = {
  data: Ref<DataT | null>
  pending: Ref<boolean>
  execute: () => Promise<void>
  refresh: (opts?: RefreshOptions) => Promise<void>
  error: Ref<ErrorT | null>
}

and asyncData.d.ts says

export interface _AsyncData<DataT, ErrorT> {
    data: Ref<DataT | null>;
    pending: Ref<boolean>;
    refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>;
    execute: (opts?: AsyncDataExecuteOptions) => Promise<void>;
    error: Ref<ErrorT | null>;
}

It looks like the same method. I tried to use them in many cases, I couldn't find any differences. My conclusion was those are the same and interchangeable. Is there any differences?

Second, I made a reproduction.
When useAsyncData with immediate: false option and fetch data by clicking button, it loads data on client-side.
However, when I move to other page and come back, the data is still alive because it's cached so useAsyncData doesn't make api call. I expected that if I move to other page, data variable is undefined.
I read docs about data-fetching and refreshNuxtData. UseAsyncData docs says

key: a unique key to ensure that data fetching can be properly de-duplicated across requests. If you do not provide a key, then a key that is unique to the file name and line number of the instance of useAsyncData will be generated for you.

I understood that it is just for de-duplicated across requests between server and client but I guess I'm wrong.
The question is that if I want to get new data whenever client-side navigation occurs and data fetching key is just same like board/list and board/detail/1, I always have to clear the data manually for all components? is there any option for that?

[Tummerhore]

I can really second that. Nuxt's data fetching part in general is really confusing at this time and not intuitive at all (even though Nuxt claims to be the "The Intuitive Web Framework" )...

In addition to your 2 points I want to point out the following:

• Why does useAsyncData return a promise if this promise is not really connected to the fetch state and instead the ref pending is used. Seems like a weird design decision to me.
  I guess the promise is only used to determine whether the page is ready to be displayed (so for lazy option it resolves immediately). But if that's really the case then this should also be described better in the docs and the useLazy... variants shouldn't return a promise.
• In the docs useAsyncData is shown as an overloaded function.
  Why does the first function without key parameter not return a promise while the second function with it return a promise?

function useAsyncData(
  handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
  options?: AsyncDataOptions<DataT>
): AsyncData<DataT>
function useAsyncData(
  key: string,
  handler: (nuxtApp?: NuxtApp) => Promise<DataT>,
  options?: AsyncDataOptions<DataT>
): Promise<AsyncData<DataT>>

• Also the docs are simply wrong about the caching part.

  useFetch and useAsyncData use keys to prevent refetching the same data (for example when navigating back to a page previously rendered).

  Nuxt will refetch when navigating back, at least with the standard parameters immediate: true)

[maou-shonen]

The lack of a promise return may indicate an error.

I couldn't find the reloading error you mentioned in the documentation.
there doesn't seem to be an error in the source code. It's also possible that this error has been fixed.

I also agree that excessive information in the documentation can make it difficult to understand the differences. In reality,
I believe that $fetch and useAsyncData can fulfill 99% of the requirements.

[jongmin4943]

useFetch and useAsyncData use keys to prevent refetching the same data (for example when navigating back to a page previously rendered).
This one will be removed from docs in v3.5.2 (#21197)

[maou-shonen]

1. execute and refresh are exactly the same,
   They exist at the same time, probably because they make it easier for you to choose different semantics.

2. immediate option determines whether the component will execute refresh once each time it is loaded.
   Typically, you rarely set it to false.
   one example is when you fetch multiple sets of data within the same page or component,
   but you need to use the content of the previous set as a parameter.