feat: useNuxtData composable

docs/content/1.docs/3.api/1.composables/use-nuxt-data.md

@@ -0,0 +1,69 @@
+# `useNuxtData`
+
+`useNuxtData` gives you access to the current value of `useAsyncData`, `useLazyAsyncData`, `useFetch` and `useLazyFetch` with explicitly provided key.
+
+## Type
+
+```ts
+useNuxtData<T = any> (key: string): Ref<T>
+```
+
+## Examples
+
+### Show stale data while fetching in the background
+
+The example below shows how you can use cached data as a placeholder while the most recent data is being fetched from the server.
+
+```ts
+// In Archive.vue
+const { data } = await useFetch('/api/posts', {
+  key: 'posts', // You need to set a key to access the data later.
+})
+```
+
+```ts
+// In Single.vue
+const { data } = await useFetch(`/api/posts/${postId}`, {
+  key: `post-${postId}`,
+  default: () => {
+    // Find the individual post from the cache and set it as the default value.
+    return useNuxtData('posts').value.find(post => post.id === postId)
+  }
+})
+```
+
+### Optimistic Updates
+
+We can leverage the cache to update the UI after a mutation, while the data is being invalidated in the background.
+
+```ts
+// In Todos.vue
+const { data } = await useFetch('/api/todos', {
+  key: 'todos'
+})
+```
+
+```ts
+// In AddTodo.vue
+const newTodo = ref('')
+const previousTodos = ref([])
+
+const { data } = await useFetch('/api/addTodo', {
+  key: 'addTodo',
+  method: 'post',
+  body: {
+    todo: newTodo.value
+  },
+  onRequest () {
+    previousTodos.value = useNuxtData('todos').value // Store the previously cached value to restore if fetch fails.
+
+    useNuxtData('todos').value.push(newTodo.value) // Optimistically update the todos.
+  },
+  onRequestError () {
+    useNuxtData('todos').value = previousTodos.value // Rollback the data if the request failed.
+  },
+  async onResponse () {
+    await refreshNuxtData('todos') // Invalidate todos in the background if the request succeeded.
+  }
+})
+```

packages/nuxt/src/app/composables/asyncData.ts

@@ -1,4 +1,4 @@
-import { onBeforeMount, onServerPrefetch, onUnmounted, ref, getCurrentInstance, watch, unref } from 'vue'
+import { onBeforeMount, onServerPrefetch, onUnmounted, ref, getCurrentInstance, watch, unref, toRef } from 'vue'
 import type { Ref, WatchSource } from 'vue'
 import { NuxtApp, useNuxtApp } from '../nuxt'
 import { createError } from './error'
@@ -268,6 +268,17 @@ export function useLazyAsyncData<
   return useAsyncData(key, handler, { ...options, lazy: true }, null)
 }
 
+export function useNuxtData<T = any> (key: string): Ref<T> {
+  const nuxt = useNuxtApp()
+
+  // Initialize value when key is not already set
+  if (nuxt.payload.data[key] === undefined) {
+    nuxt.payload.data[key] = null
+  }
+
+  return toRef(nuxt.payload.data, key)
+}
+
 export async function refreshNuxtData (keys?: string | string[]): Promise<void> {
   if (process.server) {
     return Promise.resolve()

packages/nuxt/src/app/composables/index.ts

@@ -1,5 +1,5 @@
 export { defineNuxtComponent } from './component'
-export { useAsyncData, useLazyAsyncData, refreshNuxtData, clearNuxtData } from './asyncData'
+export { useAsyncData, useLazyAsyncData, useNuxtData, refreshNuxtData, clearNuxtData } from './asyncData'
 export type { AsyncDataOptions, AsyncData } from './asyncData'
 export { useHydration } from './hydrate'
 export { useState } from './state'

packages/nuxt/src/imports/presets.ts

@@ -23,6 +23,7 @@ const appPreset = defineUnimportPreset({
   imports: [
     'useAsyncData',
     'useLazyAsyncData',
+    'useNuxtData',
     'refreshNuxtData',
     'clearNuxtData',
     'defineNuxtComponent',