refactor: improve function type safety (#3024)

* refactor: improve function type safety

* refactor: restructure and improve types

* refactor: restructure into compatibility file

* refactor: add comments and reorder imports

* refactor: rename method and reorder imports

* refactor: improve messages function types

* refactor: improve server plugin types

src/runtime/compatibility.ts

@@ -0,0 +1,116 @@
+/**
+ * Utility functions to support both VueI18n and Composer instances
+ */
+
+import { isRef, unref } from 'vue'
+
+import type { NuxtApp } from '#app'
+import type { LocaleObject } from '#build/i18n.options.mjs'
+import type { Composer, I18n, Locale, VueI18n } from 'vue-i18n'
+import type { UnwrapRef } from 'vue'
+
+function isI18nInstance(i18n: I18n | VueI18n | Composer): i18n is I18n {
+  return i18n != null && 'global' in i18n && 'mode' in i18n
+}
+
+function isComposer(target: I18n | VueI18n | Composer): target is Composer {
+  return target != null && !('__composer' in target) && 'locale' in target && isRef(target.locale)
+}
+
+export function isVueI18n(target: I18n | VueI18n | Composer): target is VueI18n {
+  return target != null && '__composer' in target
+}
+
+export function getI18nTarget(i18n: I18n | VueI18n | Composer) {
+  return isI18nInstance(i18n) ? i18n.global : i18n
+}
+
+export function getComposer(i18n: I18n | VueI18n | Composer): Composer {
+  const target = getI18nTarget(i18n)
+
+  if (isComposer(target)) return target
+  if (isVueI18n(target)) return target.__composer
+
+  return target
+}
+
+/**
+ * Extract the value of a property on a VueI18n or Composer instance
+ */
+function extractI18nProperty<T extends ReturnType<typeof getI18nTarget>, K extends keyof T>(
+  i18n: T,
+  key: K
+): UnwrapRef<T[K]> {
+  return unref(i18n[key]) as UnwrapRef<T[K]>
+}
+
+/**
+ * Typesafe access to property of a VueI18n or Composer instance
+ */
+export function getI18nProperty<K extends keyof ReturnType<typeof getI18nTarget>>(i18n: I18n, property: K) {
+  return extractI18nProperty(getI18nTarget(i18n), property)
+}
+
+/**
+ * Sets the value of the locale property on VueI18n or Composer instance
+ *
+ * This differs from the instance `setLocale` method in that it sets the
+ * locale property directly without triggering other side effects
+ */
+export function setLocaleProperty(i18n: I18n, locale: Locale): void {
+  const target = getI18nTarget(i18n)
+  if (isRef(target.locale)) {
+    target.locale.value = locale
+  } else {
+    target.locale = locale
+  }
+}
+
+export function getLocale(i18n: I18n): Locale {
+  return getI18nProperty(i18n, 'locale')
+}
+
+export function getLocales(i18n: I18n): string[] | LocaleObject[] {
+  return getI18nProperty(i18n, 'locales')
+}
+
+export function getLocaleCodes(i18n: I18n): string[] {
+  return getI18nProperty(i18n, 'localeCodes')
+}
+
+export function setLocale(i18n: I18n, locale: Locale) {
+  return getI18nTarget(i18n).setLocale(locale)
+}
+
+export function setLocaleCookie(i18n: I18n, locale: Locale) {
+  return getI18nTarget(i18n).setLocaleCookie(locale)
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function mergeLocaleMessage(i18n: I18n, locale: Locale, messages: Record<string, any>) {
+  return getI18nTarget(i18n).mergeLocaleMessage(locale, messages)
+}
+
+export async function onBeforeLanguageSwitch(
+  i18n: I18n,
+  oldLocale: string,
+  newLocale: string,
+  initial: boolean,
+  context: NuxtApp
+) {
+  return getI18nTarget(i18n).onBeforeLanguageSwitch(oldLocale, newLocale, initial, context)
+}
+
+export function onLanguageSwitched(i18n: I18n, oldLocale: string, newLocale: string) {
+  return getI18nTarget(i18n).onLanguageSwitched(oldLocale, newLocale)
+}
+
+declare module 'vue-i18n' {
+  interface VueI18n {
+    /**
+     * This is not exposed in VueI18n's types, but it's used internally
+     * @internal
+     */
+    __composer: Composer
+  }
+}

src/runtime/composables/index.ts

@@ -17,7 +17,8 @@ import {
   localeRoute,
   switchLocalePath
 } from '../routing/compatibles'
-import { findBrowserLocale, getComposer, getLocale, getLocales } from '../routing/utils'
+import { findBrowserLocale } from '../routing/utils'
+import { getLocale, getLocales, getComposer } from '../compatibility'
 
 import type { Ref } from 'vue'
 import type { Locale } from 'vue-i18n'
@@ -44,8 +45,8 @@ export function useSetI18nParams(seoAttributes?: SeoAttributesOptions): SetI18nP
   const i18n = getComposer(common.i18n)
   const router = common.router
 
-  const locale = getLocale(i18n)
-  const locales = getNormalizedLocales(getLocales(i18n))
+  const locale = getLocale(common.i18n)
+  const locales = getNormalizedLocales(getLocales(common.i18n))
   const _i18nParams = ref({})
   const experimentalSSR = common.runtimeConfig.public.i18n.experimental.switchLocalePathLinkSSR
 

src/runtime/internal.ts

@@ -3,19 +3,12 @@
 import { isArray, isString, isObject } from '@intlify/shared'
 import { hasProtocol } from 'ufo'
 import isHTTPS from 'is-https'
-import {
-  useRequestHeaders,
-  useRequestEvent,
-  useCookie as useNuxtCookie,
-  useRuntimeConfig,
-  useNuxtApp,
-  unref
-} from '#imports'
+import { useRequestHeaders, useRequestEvent, useCookie as useNuxtCookie, useRuntimeConfig, useNuxtApp } from '#imports'
 import { NUXT_I18N_MODULE_ID, DEFAULT_COOKIE_KEY, isSSG, localeCodes, normalizedLocales } from '#build/i18n.options.mjs'
-import { findBrowserLocale, getLocalesRegex, getI18nTarget } from './routing/utils'
+import { findBrowserLocale, getLocalesRegex } from './routing/utils'
 import { initCommonComposableOptions, type CommonComposableOptions } from './utils'
 
-import type { Locale, I18n } from 'vue-i18n'
+import type { Locale } from 'vue-i18n'
 import type { DetectBrowserLanguageOptions, LocaleObject } from '#build/i18n.options.mjs'
 import type { RouteLocationNormalized, RouteLocationNormalizedLoaded } from 'vue-router'
 import type { CookieRef } from 'nuxt/app'
@@ -25,21 +18,6 @@ export function formatMessage(message: string) {
   return NUXT_I18N_MODULE_ID + ' ' + message
 }
 
-export function callVueI18nInterfaces<Return = any>(i18n: any, name: string, ...args: any[]): Return {
-  const target = getI18nTarget(i18n as unknown as I18n)
-  // prettier-ignore
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/ban-types
-  const [obj, method] = [target, (target as any)[name] as Function]
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-  return Reflect.apply(method, obj, [...args]) as Return
-}
-
-export function getVueI18nPropertyValue<Return = any>(i18n: any, name: string): Return {
-  const target = getI18nTarget(i18n as unknown as I18n)
-  // @ts-expect-error name should be typed instead of string
-  return unref(target[name]) as Return
-}
-
 export function defineGetter<K extends string | number | symbol, V>(obj: Record<K, V>, key: K, val: V) {
   Object.defineProperty(obj, key, { get: () => val })
 }

src/runtime/messages.ts

@@ -6,9 +6,14 @@ import type { DeepRequired } from 'ts-essentials'
 import type { VueI18nConfig, NuxtI18nOptions } from '../types'
 import type { CoreContext } from '@intlify/h3'
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type LocaleLoader = { key: string; load: () => Promise<any>; cache: boolean }
+type MessageLoaderFunction<T = DefineLocaleMessage> = (locale: Locale) => Promise<LocaleMessages<T>>
+type MessageLoaderResult<T, Result = MessageLoaderFunction<T> | LocaleMessages<T>> = { default: Result } | Result
 
+export type LocaleLoader<T = LocaleMessages<DefineLocaleMessage>> = {
+  key: string
+  load: () => Promise<MessageLoaderResult<T>>
+  cache: boolean
+}
 const cacheMessages = new Map<string, LocaleMessages<DefineLocaleMessage>>()
 
 export async function loadVueI18nOptions(
@@ -73,21 +78,18 @@ async function loadMessage(locale: Locale, { key, load }: LocaleLoader) {
   let message: LocaleMessages<DefineLocaleMessage> | null = null
   try {
     __DEBUG__ && console.log('loadMessage: (locale) -', locale)
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access -- FIXME
-    const getter = await load().then(r => r.default || r)
+    const getter = await load().then(r => ('default' in r ? r.default : r))
     if (isFunction(getter)) {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call -- FIXME
       message = await getter(locale)
       __DEBUG__ && console.log('loadMessage: dynamic load', message)
     } else {
-      message = getter as LocaleMessages<DefineLocaleMessage>
+      message = getter
       if (message != null && cacheMessages) {
         cacheMessages.set(key, message)
       }
       __DEBUG__ && console.log('loadMessage: load', message)
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  } catch (e: any) {
+  } catch (e: unknown) {
     console.error('Failed locale loading: ' + (e as Error).message)
   }
   return message
@@ -126,20 +128,17 @@ export async function loadLocale(
   setter(locale, targetMessage)
 }
 
-type LocaleLoaderMessages = CoreContext['messages'] | LocaleMessages<DefineLocaleMessage>
+type LocaleLoaderMessages =
+  | CoreContext<Locale, DefineLocaleMessage>['messages']
+  | LocaleMessages<DefineLocaleMessage, Locale>
 export async function loadAndSetLocaleMessages(
   locale: Locale,
   localeLoaders: Record<Locale, LocaleLoader[]>,
   messages: LocaleLoaderMessages
 ) {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const setter = (locale: Locale, message: Record<string, any>) => {
-    // @ts-expect-error should be able to use `locale` as index
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- FIXME
+  const setter = (locale: Locale, message: LocaleMessages<DefineLocaleMessage, Locale>) => {
     const base = messages[locale] || {}
     deepCopy(message, base)
-    // @ts-expect-error should be able to use `locale` as index
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- FIXME
     messages[locale] = base
   }
 

src/runtime/plugins/i18n.ts

@@ -10,27 +10,19 @@ import {
   normalizedLocales
 } from '#build/i18n.options.mjs'
 import { loadVueI18nOptions, loadInitialMessages, loadLocale } from '../messages'
+import { loadAndSetLocale, detectLocale, detectRedirect, navigate, injectNuxtHelpers, extendBaseUrl } from '../utils'
 import {
-  loadAndSetLocale,
-  detectLocale,
-  detectRedirect,
-  navigate,
-  injectNuxtHelpers,
-  extendBaseUrl,
-  _setLocale,
-  mergeLocaleMessage
-} from '../utils'
-import {
-  getBrowserLocale as _getBrowserLocale,
-  getLocaleCookie as _getLocaleCookie,
-  setLocaleCookie as _setLocaleCookie,
+  getBrowserLocale,
+  getLocaleCookie,
+  setLocaleCookie,
   detectBrowserLanguage,
   DefaultDetectBrowserLanguageFromResult,
   getI18nCookie,
   runtimeDetectBrowserLanguage
 } from '../internal'
-import { getLocale, inBrowser, resolveBaseUrl, setLocale } from '../routing/utils'
+import { inBrowser, resolveBaseUrl } from '../routing/utils'
 import { extendI18n, createLocaleFromRouteGetter } from '../routing/extends'
+import { setLocale, getLocale, mergeLocaleMessage, setLocaleProperty } from '../compatibility'
 
 import type { LocaleObject } from '#build/i18n.options.mjs'
 import type { Locale, I18nOptions } from 'vue-i18n'
@@ -81,7 +73,7 @@ export default defineNuxtPlugin({
         ssg: isSSG && runtimeI18n.strategy === 'no_prefix' ? 'ssg_ignore' : 'normal',
         callType: 'setup',
         firstAccess: true,
-        localeCookie: _getLocaleCookie(localeCookie, _detectBrowserLanguage, runtimeI18n.defaultLocale)
+        localeCookie: getLocaleCookie(localeCookie, _detectBrowserLanguage, runtimeI18n.defaultLocale)
       },
       runtimeI18n
     )
@@ -118,7 +110,7 @@ export default defineNuxtPlugin({
      *  avoid hydration mismatch for SSG mode
      */
     if (isSSGModeInitialSetup() && runtimeI18n.strategy === 'no_prefix' && import.meta.client) {
-      nuxt.hook('app:mounted', () => {
+      nuxt.hook('app:mounted', async () => {
         __DEBUG__ && console.log('hook app:mounted')
         const {
           locale: browserLocale,
@@ -133,7 +125,7 @@ export default defineNuxtPlugin({
                 ssg: 'ssg_setup',
                 callType: 'setup',
                 firstAccess: true,
-                localeCookie: _getLocaleCookie(localeCookie, _detectBrowserLanguage, runtimeI18n.defaultLocale)
+                localeCookie: getLocaleCookie(localeCookie, _detectBrowserLanguage, runtimeI18n.defaultLocale)
               },
               initialLocale
             )
@@ -146,7 +138,7 @@ export default defineNuxtPlugin({
             reason,
             from
           )
-        _setLocale(i18n, browserLocale)
+        await setLocale(i18n, browserLocale)
         ssgModeInitialSetup = false
       })
     }
@@ -211,16 +203,15 @@ export default defineNuxtPlugin({
           )
         }
         composer.loadLocaleMessages = async (locale: string) => {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          const setter = (locale: Locale, message: Record<string, any>) => mergeLocaleMessage(i18n, locale, message)
+          const setter = mergeLocaleMessage.bind(null, i18n)
           await loadLocale(locale, localeLoaders, setter)
         }
         composer.differentDomains = runtimeI18n.differentDomains
         composer.defaultLocale = runtimeI18n.defaultLocale
-        composer.getBrowserLocale = () => _getBrowserLocale()
+        composer.getBrowserLocale = () => getBrowserLocale()
         composer.getLocaleCookie = () =>
-          _getLocaleCookie(localeCookie, _detectBrowserLanguage, runtimeI18n.defaultLocale)
-        composer.setLocaleCookie = (locale: string) => _setLocaleCookie(localeCookie, locale, _detectBrowserLanguage)
+          getLocaleCookie(localeCookie, _detectBrowserLanguage, runtimeI18n.defaultLocale)
+        composer.setLocaleCookie = (locale: string) => setLocaleCookie(localeCookie, locale, _detectBrowserLanguage)
 
         composer.onBeforeLanguageSwitch = (oldLocale, newLocale, initialSetup, context) =>
           nuxt.callHook('i18n:beforeLocaleSwitch', { oldLocale, newLocale, initialSetup, context }) as Promise<void>
@@ -231,7 +222,7 @@ export default defineNuxtPlugin({
           if (!i18n.__pendingLocale) {
             return
           }
-          setLocale(i18n, i18n.__pendingLocale)
+          setLocaleProperty(i18n, i18n.__pendingLocale)
           if (i18n.__resolvePendingLocalePromise) {
             // eslint-disable-next-line @typescript-eslint/await-thenable -- FIXME: `__resolvePendingLocalePromise` should be `Promise<void>`
             await i18n.__resolvePendingLocalePromise()
@@ -330,7 +321,7 @@ export default defineNuxtPlugin({
             ssg: isSSGModeInitialSetup() && runtimeI18n.strategy === 'no_prefix' ? 'ssg_ignore' : 'normal',
             callType: 'routing',
             firstAccess: routeChangeCount === 0,
-            localeCookie: _getLocaleCookie(localeCookie, _detectBrowserLanguage, runtimeI18n.defaultLocale)
+            localeCookie: getLocaleCookie(localeCookie, _detectBrowserLanguage, runtimeI18n.defaultLocale)
           },
           runtimeI18n
         )

src/runtime/routing/compatibles/head.ts

@@ -1,9 +1,10 @@
+import { joinURL } from 'ufo'
+import { isArray, isObject } from '@intlify/shared'
 import { unref, useNuxtApp, useRuntimeConfig } from '#imports'
 
-import { getComposer, getLocale, getLocales, getNormalizedLocales } from '../utils'
+import { getNormalizedLocales } from '../utils'
 import { getRouteBaseName, localeRoute, switchLocalePath } from './routing'
-import { isArray, isObject } from '@intlify/shared'
-import { joinURL } from 'ufo'
+import { getComposer, getLocale, getLocales } from '../../compatibility'
 
 import type { I18n } from 'vue-i18n'
 import type { I18nHeadMetaInfo, MetaAttrs, LocaleObject, I18nHeadOptions } from '#build/i18n.options.mjs'

src/runtime/routing/compatibles/routing.ts

@@ -4,8 +4,9 @@ import { hasProtocol, parsePath, parseQuery, withTrailingSlash, withoutTrailingS
 import { DEFAULT_DYNAMIC_PARAMS_KEY } from '#build/i18n.options.mjs'
 import { unref } from '#imports'
 
+import { getLocale } from '../../compatibility'
 import { resolve, routeToObject } from './utils'
-import { getLocale, getLocaleRouteName, getRouteName } from '../utils'
+import { getLocaleRouteName, getRouteName } from '../utils'
 import { extendPrefixable, extendSwitchLocalePathIntercepter, type CommonComposableOptions } from '../../utils'
 
 import type { Strategies, PrefixableOptions, SwitchLocalePathIntercepter } from '#build/i18n.options.mjs'

src/runtime/routing/extends/i18n.ts

@@ -1,5 +1,5 @@
 import { effectScope } from '#imports'
-import { isVueI18n, getComposer } from '../utils'
+import { isVueI18n, getComposer } from '../../compatibility'
 import {
   getRouteBaseName,
   localeHead,