@nuxt/docs-nightly 4.2.1-29360990.b3040970 → 4.2.1-29362163.2a087817

package/1.getting-started/10.data-fetching.md

@@ -194,10 +194,10 @@ The `useAsyncData` composable is a great way to wrap and wait for multiple `$fet
 
 ```vue
 <script setup lang="ts">
-const { data: discounts, status } = await useAsyncData('cart-discount', async () => {
+const { data: discounts, status } = await useAsyncData('cart-discount', async (_nuxtApp, { signal }) => {
   const [coupons, offers] = await Promise.all([
-    $fetch('/cart/coupons'),
-    $fetch('/cart/offers'),
+    $fetch('/cart/coupons', { signal }),
+    $fetch('/cart/offers', { signal }),
   ])
 
   return { coupons, offers }
@@ -372,8 +372,8 @@ The following options **must be consistent** across all calls with the same key:
 
 ```ts
 // ❌ This will trigger a development warning
-const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
-const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
+const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: false })
+const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: true })
 ```
 
 The following options **can safely differ** without triggering warnings:
@@ -385,16 +385,16 @@ The following options **can safely differ** without triggering warnings:
 
 ```ts
 // ✅ This is allowed
-const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
-const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })
+const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: true })
+const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: false })
 ```
 
 If you need independent instances, use different keys:
 
 ```ts
 // These are completely independent instances
-const { data: users1 } = useAsyncData('users-1', () => $fetch('/api/users'))
-const { data: users2 } = useAsyncData('users-2', () => $fetch('/api/users'))
+const { data: users1 } = useAsyncData('users-1', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }))
+const { data: users2 } = useAsyncData('users-2', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }))
 ```
 
 #### Reactive Keys
@@ -804,10 +804,10 @@ while (true) {
 When requests don't rely on each other, you can make them in parallel with `Promise.all()` to boost performance.
 
 ```ts
-const { data } = await useAsyncData(() => {
+const { data } = await useAsyncData((_nuxtApp, { signal }) => {
   return Promise.all([
-    $fetch('/api/comments/'),
-    $fetch('/api/author/12'),
+    $fetch('/api/comments/', { signal }),
+    $fetch('/api/author/12', { signal }),
   ])
 })
 

package/2.guide/3.going-further/1.experimental-features.md

@@ -405,12 +405,12 @@ should do this automatically for you.)
 // This would be unsafe in a dynamic page (e.g. `[slug].vue`) because the route slug makes a difference
 // to the data fetched, but Nuxt can't know that because it's not reflected in the key.
 const route = useRoute()
-const { data } = await useAsyncData(async () => {
-  return await $fetch(`/api/my-page/${route.params.slug}`)
+const { data } = await useAsyncData(async (_nuxtApp, { signal }) => {
+  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
 })
 // Instead, you should use a key that uniquely identifies the data fetched.
-const { data } = await useAsyncData(route.params.slug, async () => {
-  return await $fetch(`/api/my-page/${route.params.slug}`)
+const { data } = await useAsyncData(route.params.slug, async (_nuxtApp, { signal }) => {
+  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
 })
 ```
 

package/3.api/2.composables/use-async-data.md

@@ -18,9 +18,9 @@ Within your pages, components, and plugins you can use useAsyncData to get acces
 
 ```vue [app/pages/index.vue]
 <script setup lang="ts">
-const { data, status, error, refresh, clear } = await useAsyncData(
+const { data, status, pending, error, refresh, clear } = await useAsyncData(
   'mountains',
-  () => $fetch('https://api.nuxtjs.dev/mountains'),
+  (_nuxtApp, { signal }) => $fetch('https://api.nuxtjs.dev/mountains', { signal }),
 )
 </script>
 ```
@@ -30,7 +30,7 @@ If you're using a custom useAsyncData wrapper, do not await it in the composable
 ::
 
 ::note
-`data`, `status` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.
+`data`, `status`, `pending` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.
 ::
 
 ### Watch Params
@@ -42,10 +42,11 @@ The built-in `watch` option allows automatically rerunning the fetcher function
 const page = ref(1)
 const { data: posts } = await useAsyncData(
   'posts',
-  () => $fetch('https://fakeApi.com/posts', {
+  (_nuxtApp, { signal }) => $fetch('https://fakeApi.com/posts', {
     params: {
       page: page.value,
     },
+    signal,
   }), {
     watch: [page],
   },
@@ -70,6 +71,64 @@ const { data: user } = useAsyncData(
 </script>
 ```
 
+### Make your `handler` abortable
+
+You can make your `handler` function abortable by using the `signal` provided in the second argument. This is useful for cancelling requests when they are no longer needed, such as when a user navigates away from a page. `$fetch` natively supports abort signals.
+
+```ts
+const { data, error } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
+)
+
+refresh() // will actually cancel the $fetch request (if dedupe: cancel)
+refresh() // will actually cancel the $fetch request (if dedupe: cancel)
+refresh()
+
+clear() // will cancel the latest pending handler
+```
+
+You can also pass an `AbortSignal` to the `refresh`/`execute` function to cancel individual requests manually.
+
+```ts
+const { refresh } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
+)
+let abortController: AbortController | undefined
+
+function handleUserAction () {
+  abortController = new AbortController()
+  refresh({ signal: abortController.signal })
+}
+
+function handleCancel () {
+  abortController?.abort() // aborts the ongoing refresh request
+}
+```
+
+If your `handler` function does not support abort signals, you can implement your own abort logic using the `signal` provided.
+
+```ts
+const { data, error } = await useAsyncData(
+  'users',
+  (_nuxtApp, { signal }) => {
+    return new Promise((resolve, reject) => {
+      signal?.addEventListener('abort', () => {
+        reject(new Error('Request aborted'))
+      })
+      return Promise.resolve(callback.call(this, yourHandler)).then(resolve, reject)
+    })
+  },
+)
+```
+
+The handler signal will be aborted when:
+
+- A new request is made with `dedupe: 'cancel'`
+- The `clear` function is called
+- The `options.timeout` duration is exceeded
+
 ::warning
 [`useAsyncData`](/docs/4.x/api/composables/use-async-data) is a reserved function name transformed by the compiler, so you should not name your own function [`useAsyncData`](/docs/4.x/api/composables/use-async-data).
 ::
@@ -116,7 +175,7 @@ You can use `useLazyAsyncData` to have the same behavior as `lazy: true` with `u
 
 ### Shared State and Option Consistency
 
-When using the same key for multiple `useAsyncData` calls, they will share the same `data`, `error` and `status` refs. This ensures consistency across components but requires option consistency.
+When using the same key for multiple `useAsyncData` calls, they will share the same `data`, `error`, `status` and `pending` refs. This ensures consistency across components but requires option consistency.
 
 The following options **must be consistent** across all calls with the same key:
 - `handler` function
@@ -135,12 +194,12 @@ The following options **can differ** without triggering warnings:
 
 ```ts
 // ❌ This will trigger a development warning
-const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
-const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
+const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: false })
+const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: true })
 
 // ✅ This is allowed
-const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: true })
-const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { immediate: false })
+const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: true })
+const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: false })
 ```
 
 ::tip
@@ -159,6 +218,7 @@ Keyed state created using `useAsyncData` can be retrieved across your Nuxt appli
   - `pending`: the request is in progress
   - `success`: the request has completed successfully
   - `error`: the request has failed
+- `pending`: a `Ref<boolean>` that is `true` while the request is in progress (that is, while `status.value === 'pending'`).
 - `clear`: a function that can be used to set `data` to `undefined` (or the value of `options.default()` if provided), set `error` to `undefined`, set `status` to `idle`, and mark any currently pending requests as cancelled.
 
 By default, Nuxt waits until a `refresh` is finished before it can be executed again.
@@ -170,13 +230,15 @@ If you have not fetched data on the server (for example, with `server: false`),
 ## Type
 
 ```ts [Signature]
+export type AsyncDataHandler<ResT> = (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<ResT>
+
 export function useAsyncData<DataT, DataE> (
-  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
+  handler: AsyncDataHandler<DataT>,
   options?: AsyncDataOptions<DataT>
 ): AsyncData<DataT, DataE>
 export function useAsyncData<DataT, DataE> (
   key: MaybeRefOrGetter<string>,
-  handler: (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<DataT>,
+  handler: AsyncDataHandler<DataT>,
   options?: AsyncDataOptions<DataT>
 ): Promise<AsyncData<DataT, DataE>>
 
@@ -206,6 +268,7 @@ type AsyncData<DataT, ErrorT> = {
   clear: () => void
   error: Ref<ErrorT | undefined>
   status: Ref<AsyncDataRequestStatus>
+  pending: Ref<boolean>
 }
 
 interface AsyncDataExecuteOptions {

package/3.api/2.composables/use-nuxt-app.md

@@ -108,7 +108,7 @@ Nuxt exposes the following properties through `ssrContext`:
   ::code-group
   ```vue [app/app.vue]
   <script setup lang="ts">
-  const { data } = await useAsyncData('count', () => $fetch('/api/count'))
+  const { data } = await useAsyncData('count', (_nuxtApp, { signal }) => $fetch('/api/count', { signal }))
   </script>
   ```
   ```ts [server/api/count.ts]

package/3.api/2.composables/use-nuxt-data.md

@@ -67,7 +67,7 @@ Optimistic Updates is a technique where the user interface is updated immediatel
 ```vue [app/pages/todos.vue]
 <script setup lang="ts">
 // We can access same data later using 'todos' key
-const { data } = await useAsyncData('todos', () => $fetch('/api/todos'))
+const { data } = await useAsyncData('todos', (_nuxtApp, { signal }) => $fetch('/api/todos', { signal }))
 </script>
 ```
 

package/3.api/2.composables/use-request-fetch.md

@@ -33,7 +33,7 @@ const { data: forwarded } = await useAsyncData(() => requestFetch('/api/cookies'
 
 // This will NOT forward anything
 // Result: { cookies: {} }
-const { data: notForwarded } = await useAsyncData(() => $fetch('/api/cookies'))
+const { data: notForwarded } = await useAsyncData((_nuxtApp, { signal }) => $fetch('/api/cookies', { signal }))
 </script>
 ```
 

package/3.api/3.utils/refresh-cookie.md

@@ -36,7 +36,7 @@ const loggedIn = computed(() => !!tokenCookie.value)
 ```
 
 ::note{to="/docs/4.x/guide/going-further/experimental-features#cookiestore"}
-You can enable experimental `cookieStore` option to automatically refresh `useCookie` value when cookie changes in the browser.
+Since [Nuxt v3.12.0](https://github.com/nuxt/nuxt/releases/tag/v3.12.0), the experimental `cookieStore` option is enabled by default. It automatically refreshes the `useCookie` value when cookies change in the browser.
 ::
 
 ## Type

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.2.1-29360990.b3040970",
+  "version": "4.2.1-29362163.2a087817",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",