docs(nuxt): add @since annotations to exported composables (#25086)

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

@@ -1,6 +1,7 @@
 // @ts-expect-error withAsyncContext is internal API
 import { getCurrentInstance, withAsyncContext as withVueAsyncContext } from 'vue'
 
+/** @since 3.8.0 */
 export function withAsyncContext (fn: () => PromiseLike<unknown>) {
   return withVueAsyncContext(() => {
     const nuxtApp = getCurrentInstance()?.appContext.app.$nuxt

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

@@ -121,6 +121,7 @@ const isDefer = (dedupe?: boolean | 'cancel' | 'defer') => dedupe === 'defer' ||
 /**
  * Provides access to data that resolves asynchronously in an SSR-friendly composable.
  * See {@link https://nuxt.com/docs/api/composables/use-async-data}
+ * @since 3.0.0
  * @param handler An asynchronous function that must return a truthy value (for example, it should not be `undefined` or `null`) or the request may be duplicated on the client side.
  * @param options customize the behavior of useAsyncData
  */
@@ -378,6 +379,7 @@ export function useAsyncData<
 
   return asyncDataPromise as AsyncData<PickFrom<DataT, PickKeys>, (NuxtErrorDataT extends Error | NuxtError ? NuxtErrorDataT : NuxtError<NuxtErrorDataT>)>
 }
+/** @since 3.0.0 */
 export function useLazyAsyncData<
   ResT,
   DataE = Error,
@@ -441,6 +443,7 @@ export function useLazyAsyncData<
   return useAsyncData(key, handler, { ...options, lazy: true }, null)
 }
 
+/** @since 3.1.0 */
 export function useNuxtData<DataT = any> (key: string): { data: Ref<DataT | null> } {
   const nuxt = useNuxtApp()
 
@@ -454,6 +457,7 @@ export function useNuxtData<DataT = any> (key: string): { data: Ref<DataT | null
   }
 }
 
+/** @since 3.0.0 */
 export async function refreshNuxtData (keys?: string | string[]): Promise<void> {
   if (import.meta.server) {
     return Promise.resolve()
@@ -465,6 +469,7 @@ export async function refreshNuxtData (keys?: string | string[]): Promise<void>
   await useNuxtApp().hooks.callHookParallel('app:data:refresh', _keys)
 }
 
+/** @since 3.0.0 */
 export function clearNuxtData (keys?: string | string[] | ((key: string) => boolean)): void {
   const nuxtApp = useNuxtApp()
   const _allKeys = Object.keys(nuxtApp.payload.data)

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

@@ -25,6 +25,7 @@ export interface ReloadNuxtAppOptions {
   path?: string
 }
 
+/** @since 3.3.0 */
 export function reloadNuxtApp (options: ReloadNuxtAppOptions = {}) {
   if (import.meta.server) { return }
   const path = options.path || window.location.pathname

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

@@ -27,6 +27,7 @@ async function runLegacyAsyncData (res: Record<string, any> | Promise<Record<str
   }
 }
 
+/** @since 3.0.0 */
 /*@__NO_SIDE_EFFECTS__*/
 export const defineNuxtComponent: typeof defineComponent =
   function defineNuxtComponent (...args: any[]): any {

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

@@ -29,6 +29,7 @@ const CookieDefaults = {
   encode: val => encodeURIComponent(typeof val === 'string' ? val : JSON.stringify(val))
 } satisfies CookieOptions<any>
 
+/** @since 3.0.0 */
 export function useCookie<T = string | null | undefined> (name: string, _opts?: CookieOptions<T> & { readonly?: false }): CookieRef<T>
 export function useCookie<T = string | null | undefined> (name: string, _opts: CookieOptions<T> & { readonly: true }): Readonly<CookieRef<T>>
 export function useCookie<T = string | null | undefined> (name: string, _opts?: CookieOptions<T>): CookieRef<T> {

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

@@ -6,10 +6,12 @@ import { useRouter } from './router'
 
 export const NUXT_ERROR_SIGNATURE = '__nuxt_error'
 
+/** @since 3.0.0 */
 export const useError = () => toRef(useNuxtApp().payload, 'error')
 
 export interface NuxtError<DataT = unknown> extends H3Error<DataT> {}
 
+/** @since 3.0.0 */
 export const showError = <DataT = unknown>(
     error: string | Error | Partial<NuxtError<DataT>>
 ) => {
@@ -31,6 +33,7 @@ export const showError = <DataT = unknown>(
   return nuxtError
 }
 
+/** @since 3.0.0 */
 export const clearError = async (options: { redirect?: string } = {}) => {
   const nuxtApp = useNuxtApp()
   const error = useError()
@@ -44,12 +47,14 @@ export const clearError = async (options: { redirect?: string } = {}) => {
   error.value = null
 }
 
+/** @since 3.0.0 */
 export const isNuxtError = <DataT = unknown>(
     error?: string | object
 ): error is NuxtError<DataT> => (
   !!error && typeof error === 'object' && NUXT_ERROR_SIGNATURE in error
 )
 
+/** @since 3.0.0 */
 export const createError = <DataT = unknown>(
     error: string | Partial<NuxtError<DataT>>
 ) => {

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

@@ -42,6 +42,7 @@ export interface UseFetchOptions<
 /**
  * Fetch data from an API endpoint with an SSR-friendly composable.
  * See {@link https://nuxt.com/docs/api/composables/use-fetch}
+ * @since 3.0.0
  * @param request The URL to fetch
  * @param opts extends $fetch options and useAsyncData options
  */
@@ -184,6 +185,7 @@ export function useFetch<
   return asyncData
 }
 
+/** @since 3.0.0 */
 export function useLazyFetch<
   ResT = void,
   ErrorT = FetchError,

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

@@ -6,6 +6,7 @@ import type { NuxtPayload } from '../nuxt'
  * @param key a unique key to identify the data in the Nuxt payload
  * @param get a function that returns the value to set the initial data
  * @param set a function that will receive the data on the client-side
+ * @since 3.0.0
  */
 export const useHydration = <K extends keyof NuxtPayload, T = NuxtPayload[K]> (key: K, get: () => T, set: (value: T) => void) => {
   const nuxt = useNuxtApp()

packages/nuxt/src/app/composables/loading-indicator.ts

@@ -112,6 +112,7 @@ function createLoadingIndicator (opts: Partial<LoadingIndicatorOpts> = {}) {
 
 /**
  * composable to handle the loading state of the page
+ * @since 3.9.0
  */
 export function useLoadingIndicator (opts: Partial<LoadingIndicatorOpts> = {}): Omit<LoadingIndicator, '_cleanup'> {
   const nuxtApp = useNuxtApp()

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

@@ -33,6 +33,7 @@ function fetchManifest () {
   return manifest
 }
 
+/** @since 3.7.4 */
 export function getAppManifest (): Promise<NuxtAppManifest> {
   if (!isAppManifestEnabled) {
     throw new Error('[nuxt] app manifest should be enabled with `experimental.appManifest`')
@@ -40,6 +41,7 @@ export function getAppManifest (): Promise<NuxtAppManifest> {
   return manifest || fetchManifest()
 }
 
+/** @since 3.7.4 */
 export async function getRouteRules (url: string) {
   await getAppManifest()
   return defu({} as Record<string, any>, ...matcher.matchAll(url).reverse())

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

@@ -5,6 +5,7 @@ import { useNuxtApp } from '../nuxt'
  * @param key a unique key ensuring the function can be properly de-duplicated across requests
  * @param fn a function to call
  * @see https://nuxt.com/docs/api/utils/call-once
+ * @since 3.9.0
  */
 export function callOnce (key?: string, fn?: (() => any | Promise<any>)): Promise<void>
 export function callOnce (fn?: (() => any | Promise<any>)): Promise<void>

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

@@ -15,6 +15,7 @@ interface LoadPayloadOptions {
   hash?: string
 }
 
+/** @since 3.0.0 */
 export function loadPayload (url: string, opts: LoadPayloadOptions = {}): Record<string, any> | Promise<Record<string, any>> | null {
   if (import.meta.server || !payloadExtraction) { return null }
   const payloadURL = _getPayloadURL(url, opts)
@@ -37,7 +38,7 @@ export function loadPayload (url: string, opts: LoadPayloadOptions = {}): Record
   })
   return cache[payloadURL]
 }
-
+/** @since 3.0.0 */
 export function preloadPayload (url: string, opts: LoadPayloadOptions = {}) {
   const payloadURL = _getPayloadURL(url, opts)
   useHead({
@@ -75,7 +76,7 @@ async function _importPayload (payloadURL: string) {
   }
   return null
 }
-
+/** @since 3.0.0 */
 export async function isPrerendered (url = useRoute().path) {
   // Note: Alternative for server is checking x-nitro-prerender header
   if (!appManifest) { return !!useNuxtApp().payload.prerenderedAt }
@@ -89,6 +90,7 @@ export async function isPrerendered (url = useRoute().path) {
 }
 
 let payloadCache: any = null
+/** @since 3.4.0 */
 export async function getNuxtClientPayload () {
   if (import.meta.server) {
     return
@@ -121,6 +123,7 @@ export async function parsePayload (payload: string) {
 
 /**
  * This is an experimental function for configuring passing rich data from server -> client.
+ * @since 3.4.0
  */
 export function definePayloadReducer (
   name: string,
@@ -135,6 +138,7 @@ export function definePayloadReducer (
  * This is an experimental function for configuring passing rich data from server -> client.
  *
  * This function _must_ be called in a Nuxt plugin that is `unshift`ed to the beginning of the Nuxt plugins array.
+ * @since 3.4.0
  */
 export function definePayloadReviver (
   name: string,

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

@@ -7,6 +7,7 @@ import { useRouter } from './router'
 /**
  * Preload a component or components that have been globally registered.
  * @param components Pascal-cased name or names of components to prefetch
+ * @since 3.0.0
  */
 export const preloadComponents = async (components: string | string[]) => {
   if (import.meta.server) { return }
@@ -19,6 +20,7 @@ export const preloadComponents = async (components: string | string[]) => {
 /**
  * Prefetch a component or components that have been globally registered.
  * @param components Pascal-cased name or names of components to prefetch
+ * @since 3.0.0
  */
 export const prefetchComponents = (components: string | string[]) => {
   // TODO
@@ -33,6 +35,7 @@ function _loadAsyncComponent (component: Component) {
   }
 }
 
+/** @since 3.0.0 */
 export async function preloadRouteComponents (to: RouteLocationRaw, router: Router & { _routePreloaded?: Set<string>; _preloadPromises?: Array<Promise<any>> } = useRouter()): Promise<void> {
   if (import.meta.server) { return }
 

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

@@ -1,6 +1,7 @@
 import { useNuxtApp } from '../nuxt'
 import { requestIdleCallback } from '../compat/idle-callback'
 
+/** @since 3.1.0 */
 export const onNuxtReady = (callback: () => any) => {
   if (import.meta.server) { return }
 

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

@@ -12,10 +12,12 @@ import { PageRouteSymbol } from '../components/injections'
 import type { NuxtError } from './error'
 import { createError, showError } from './error'
 
+/** @since 3.0.0 */
 export const useRouter: typeof _useRouter = () => {
   return useNuxtApp()?.$router as Router
 }
 
+/** @since 3.0.0 */
 export const useRoute: typeof _useRoute = () => {
   if (import.meta.dev && isProcessingMiddleware()) {
     console.warn('[nuxt] Calling `useRoute` within middleware may lead to misleading results. Instead, use the (to, from) arguments passed to the middleware to access the new and old routes.')
@@ -26,6 +28,7 @@ export const useRoute: typeof _useRoute = () => {
   return useNuxtApp()._route
 }
 
+/** @since 3.0.0 */
 export const onBeforeRouteLeave = (guard: NavigationGuard) => {
   const unsubscribe = useRouter().beforeEach((to, from, next) => {
     if (to === from) { return }
@@ -34,6 +37,7 @@ export const onBeforeRouteLeave = (guard: NavigationGuard) => {
   onScopeDispose(unsubscribe)
 }
 
+/** @since 3.0.0 */
 export const onBeforeRouteUpdate = (guard: NavigationGuard) => {
   const unsubscribe = useRouter().beforeEach(guard)
   onScopeDispose(unsubscribe)
@@ -43,6 +47,7 @@ export interface RouteMiddleware {
   (to: RouteLocationNormalized, from: RouteLocationNormalized): ReturnType<NavigationGuard>
 }
 
+/** @since 3.0.0 */
 /*@__NO_SIDE_EFFECTS__*/
 export function defineNuxtRouteMiddleware (middleware: RouteMiddleware) {
   return middleware
@@ -57,6 +62,7 @@ interface AddRouteMiddleware {
   (middleware: RouteMiddleware): void
 }
 
+/** @since 3.0.0 */
 export const addRouteMiddleware: AddRouteMiddleware = (name: string | RouteMiddleware, middleware?: RouteMiddleware, options: AddRouteMiddlewareOptions = {}) => {
   const nuxtApp = useNuxtApp()
   const global = options.global || typeof name !== 'string'
@@ -72,6 +78,7 @@ export const addRouteMiddleware: AddRouteMiddleware = (name: string | RouteMiddl
   }
 }
 
+/** @since 3.0.0 */
 const isProcessingMiddleware = () => {
   try {
     if (useNuxtApp()._processingMiddleware) {
@@ -109,6 +116,7 @@ export interface NavigateToOptions {
   open?: OpenOptions
 }
 
+/** @since 3.0.0 */
 export const navigateTo = (to: RouteLocationRaw | undefined | null, options?: NavigateToOptions): Promise<void | NavigationFailure | false> | false | void | RouteLocationRaw => {
   if (!to) {
     to = '/'
@@ -206,7 +214,10 @@ export const navigateTo = (to: RouteLocationRaw | undefined | null, options?: Na
   return options?.replace ? router.replace(to) : router.push(to)
 }
 
-/** This will abort navigation within a Nuxt route middleware handler. */
+/** 
+ * This will abort navigation within a Nuxt route middleware handler. 
+ * @since 3.0.0
+ */
 export const abortNavigation = (err?: string | Partial<NuxtError>) => {
   if (import.meta.dev && !isProcessingMiddleware()) {
     throw new Error('abortNavigation() is only usable inside a route middleware handler.')
@@ -223,6 +234,7 @@ export const abortNavigation = (err?: string | Partial<NuxtError>) => {
   throw err
 }
 
+/** @since 3.0.0 */
 export const setPageLayout = (layout: unknown extends PageMeta['layout'] ? string : PageMeta['layout']) => {
   const nuxtApp = useNuxtApp()
   if (import.meta.server) {

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

@@ -4,10 +4,12 @@ import type { NuxtApp } from '../nuxt'
 import { useNuxtApp } from '../nuxt'
 import { toArray } from '../utils'
 
+/** @since 3.0.0 */
 export function useRequestEvent (nuxtApp: NuxtApp = useNuxtApp()): H3Event {
   return nuxtApp.ssrContext?.event as H3Event
 }
 
+/** @since 3.0.0 */
 export function useRequestHeaders<K extends string = string> (include: K[]): { [key in Lowercase<K>]?: string }
 export function useRequestHeaders (): Readonly<Record<string, string>>
 export function useRequestHeaders (include?: any[]) {
@@ -26,12 +28,14 @@ export function useRequestHeaders (include?: any[]) {
   return headers
 }
 
+/** @since 3.9.0 */
 export function useRequestHeader(header: string) {
   if (import.meta.client) { return undefined }
   const event = useRequestEvent()
   return event ? getRequestHeader(event, header) : undefined
 }
 
+/** @since 3.2.0 */
 export function useRequestFetch (): typeof global.$fetch {
   if (import.meta.client) {
     return globalThis.$fetch
@@ -39,6 +43,7 @@ export function useRequestFetch (): typeof global.$fetch {
   return useRequestEvent()?.$fetch as typeof globalThis.$fetch || globalThis.$fetch
 }
 
+/** @since 3.0.0 */
 export function setResponseStatus (event: H3Event, code?: number, message?: string): void
 /** @deprecated Pass `event` as first option. */
 export function setResponseStatus (code: number, message?: string): void
@@ -50,6 +55,7 @@ export function setResponseStatus (arg1: H3Event | number | undefined, arg2?: nu
   return _setResponseStatus(useRequestEvent(), arg1, arg2 as string | undefined)
 }
 
+/** @since 3.8.0 */
 export function prerenderRoutes (path: string | string[]) {
   if (!import.meta.server || !import.meta.prerender) { return }
 

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

@@ -6,6 +6,7 @@ import { toArray } from '../utils'
 const useStateKeyPrefix = '$s'
 /**
  * Create a global reactive ref that will be hydrated but not shared across ssr requests
+ * @since 3.0.0
  * @param key a unique key ensuring that data fetching can be properly de-duplicated across requests
  * @param init a function that provides initial value for the state when it's not initiated
  */
@@ -37,6 +38,7 @@ export function useState <T> (...args: any): Ref<T> {
   return state
 }
 
+/** @since 3.6.0 */
 export function clearNuxtState (
   keys?: string | string[] | ((key: string) => boolean)
 ): void {

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

@@ -3,6 +3,7 @@ import { joinURL } from 'ufo'
 import { useRuntimeConfig } from '../nuxt'
 import { useRequestEvent } from './ssr'
 
+/** @since 3.5.0 */
 export function useRequestURL () {
   if (import.meta.server) {
     const url = getRequestURL(useRequestEvent())