diff --git a/packages/nuxt/src/app/composables/asyncContext.ts b/packages/nuxt/src/app/composables/asyncContext.ts index 5fa88df529..a0ce9d57dd 100644 --- a/packages/nuxt/src/app/composables/asyncContext.ts +++ b/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) { return withVueAsyncContext(() => { const nuxtApp = getCurrentInstance()?.appContext.app.$nuxt diff --git a/packages/nuxt/src/app/composables/asyncData.ts b/packages/nuxt/src/app/composables/asyncData.ts index ee40a814c7..71a236a28c 100644 --- a/packages/nuxt/src/app/composables/asyncData.ts +++ b/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, (NuxtErrorDataT extends Error | NuxtError ? NuxtErrorDataT : NuxtError)> } +/** @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 (key: string): { data: Ref } { const nuxt = useNuxtApp() @@ -454,6 +457,7 @@ export function useNuxtData (key: string): { data: Ref { if (import.meta.server) { return Promise.resolve() @@ -465,6 +469,7 @@ export async function refreshNuxtData (keys?: string | string[]): Promise 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) diff --git a/packages/nuxt/src/app/composables/chunk.ts b/packages/nuxt/src/app/composables/chunk.ts index f620170410..182c7ec743 100644 --- a/packages/nuxt/src/app/composables/chunk.ts +++ b/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 diff --git a/packages/nuxt/src/app/composables/component.ts b/packages/nuxt/src/app/composables/component.ts index 31e43f8c6e..e23436decf 100644 --- a/packages/nuxt/src/app/composables/component.ts +++ b/packages/nuxt/src/app/composables/component.ts @@ -27,6 +27,7 @@ async function runLegacyAsyncData (res: Record | Promise encodeURIComponent(typeof val === 'string' ? val : JSON.stringify(val)) } satisfies CookieOptions +/** @since 3.0.0 */ export function useCookie (name: string, _opts?: CookieOptions & { readonly?: false }): CookieRef export function useCookie (name: string, _opts: CookieOptions & { readonly: true }): Readonly> export function useCookie (name: string, _opts?: CookieOptions): CookieRef { diff --git a/packages/nuxt/src/app/composables/error.ts b/packages/nuxt/src/app/composables/error.ts index 4ba972de71..2f6a748a08 100644 --- a/packages/nuxt/src/app/composables/error.ts +++ b/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 extends H3Error {} +/** @since 3.0.0 */ export const showError = ( error: string | Error | Partial> ) => { @@ -31,6 +33,7 @@ export const showError = ( 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 = ( error?: string | object ): error is NuxtError => ( !!error && typeof error === 'object' && NUXT_ERROR_SIGNATURE in error ) +/** @since 3.0.0 */ export const createError = ( error: string | Partial> ) => { diff --git a/packages/nuxt/src/app/composables/fetch.ts b/packages/nuxt/src/app/composables/fetch.ts index 2961f19732..5ac5216698 100644 --- a/packages/nuxt/src/app/composables/fetch.ts +++ b/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, diff --git a/packages/nuxt/src/app/composables/hydrate.ts b/packages/nuxt/src/app/composables/hydrate.ts index bab7f398fb..91d358a8a5 100644 --- a/packages/nuxt/src/app/composables/hydrate.ts +++ b/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 = (key: K, get: () => T, set: (value: T) => void) => { const nuxt = useNuxtApp() diff --git a/packages/nuxt/src/app/composables/loading-indicator.ts b/packages/nuxt/src/app/composables/loading-indicator.ts index b9290ba123..4a882c1c5d 100644 --- a/packages/nuxt/src/app/composables/loading-indicator.ts +++ b/packages/nuxt/src/app/composables/loading-indicator.ts @@ -112,6 +112,7 @@ function createLoadingIndicator (opts: Partial = {}) { /** * composable to handle the loading state of the page + * @since 3.9.0 */ export function useLoadingIndicator (opts: Partial = {}): Omit { const nuxtApp = useNuxtApp() diff --git a/packages/nuxt/src/app/composables/manifest.ts b/packages/nuxt/src/app/composables/manifest.ts index 2899924e57..cc7ff41480 100644 --- a/packages/nuxt/src/app/composables/manifest.ts +++ b/packages/nuxt/src/app/composables/manifest.ts @@ -33,6 +33,7 @@ function fetchManifest () { return manifest } +/** @since 3.7.4 */ export function getAppManifest (): Promise { if (!isAppManifestEnabled) { throw new Error('[nuxt] app manifest should be enabled with `experimental.appManifest`') @@ -40,6 +41,7 @@ export function getAppManifest (): Promise { return manifest || fetchManifest() } +/** @since 3.7.4 */ export async function getRouteRules (url: string) { await getAppManifest() return defu({} as Record, ...matcher.matchAll(url).reverse()) diff --git a/packages/nuxt/src/app/composables/once.ts b/packages/nuxt/src/app/composables/once.ts index 52ece887c4..c8c664826d 100644 --- a/packages/nuxt/src/app/composables/once.ts +++ b/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)): Promise export function callOnce (fn?: (() => any | Promise)): Promise diff --git a/packages/nuxt/src/app/composables/payload.ts b/packages/nuxt/src/app/composables/payload.ts index 510ec8733d..680cd295f3 100644 --- a/packages/nuxt/src/app/composables/payload.ts +++ b/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 | Promise> | 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, diff --git a/packages/nuxt/src/app/composables/preload.ts b/packages/nuxt/src/app/composables/preload.ts index e928300d2d..ac94bbede6 100644 --- a/packages/nuxt/src/app/composables/preload.ts +++ b/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; _preloadPromises?: Array> } = useRouter()): Promise { if (import.meta.server) { return } diff --git a/packages/nuxt/src/app/composables/ready.ts b/packages/nuxt/src/app/composables/ready.ts index a30d0d7caf..2360bc002d 100644 --- a/packages/nuxt/src/app/composables/ready.ts +++ b/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 } diff --git a/packages/nuxt/src/app/composables/router.ts b/packages/nuxt/src/app/composables/router.ts index 9366ddf1b1..83501f96f3 100644 --- a/packages/nuxt/src/app/composables/router.ts +++ b/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 } +/** @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 | 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) => { 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) => { throw err } +/** @since 3.0.0 */ export const setPageLayout = (layout: unknown extends PageMeta['layout'] ? string : PageMeta['layout']) => { const nuxtApp = useNuxtApp() if (import.meta.server) { diff --git a/packages/nuxt/src/app/composables/ssr.ts b/packages/nuxt/src/app/composables/ssr.ts index 0cfcba0488..398138660f 100644 --- a/packages/nuxt/src/app/composables/ssr.ts +++ b/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 (include: K[]): { [key in Lowercase]?: string } export function useRequestHeaders (): Readonly> 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 } diff --git a/packages/nuxt/src/app/composables/state.ts b/packages/nuxt/src/app/composables/state.ts index 38c2b17ff2..bb528c60c9 100644 --- a/packages/nuxt/src/app/composables/state.ts +++ b/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 (...args: any): Ref { return state } +/** @since 3.6.0 */ export function clearNuxtState ( keys?: string | string[] | ((key: string) => boolean) ): void { diff --git a/packages/nuxt/src/app/composables/url.ts b/packages/nuxt/src/app/composables/url.ts index 4c6f1222a2..6503c29b65 100644 --- a/packages/nuxt/src/app/composables/url.ts +++ b/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())