@falcondev-oss/nuxt-layers-base 0.36.1 → 0.37.1

package/app/composables/useToast.ts

@@ -16,11 +16,11 @@ const presets = {
   },
 } as const satisfies Record<string, Partial<Toast>>
 
-interface ToastOptions extends Partial<Toast> {
+export interface ToastOptions extends Partial<Toast> {
   preset?: keyof typeof presets
 }
 
-export const useToast = createGlobalState(() => {
+function createToast() {
   const toast = useNuxtUiToast()
 
   return {
@@ -37,4 +37,18 @@ export const useToast = createGlobalState(() => {
       )
     },
   }
-})
+}
+
+let clientToast: ReturnType<typeof createToast> | undefined
+
+/**
+ * Cached on the client only, since `useNuxtUiToast()` needs Nuxt's async context that
+ * cache callbacks have left, while caching it on the server would hand one request's
+ * instance to every later request.
+ */
+export function useToast() {
+  if (import.meta.server) return createToast()
+
+  // eslint-disable-next-line unicorn/no-top-level-assignment-in-function
+  return (clientToast ??= createToast())
+}

package/app/utils/plugins.ts

@@ -1,18 +1,23 @@
 import type { DehydratedState, QueryClientConfig, VueQueryPluginOptions } from '@tanstack/vue-query'
-import type { AnyTRPCRouter } from '@trpc/server'
+import type { OperationLink, TRPCClientError, TRPCLink } from '@trpc/client'
+import type { AnyTRPCRouter, TRPC_ERROR_CODE_KEY, TRPCDefaultErrorData } from '@trpc/server'
+import type { FetchOptions } from 'ofetch'
 import type { ObjectPlugin } from '#app'
+import type { ToastOptions } from '../composables/useToast'
 import { typedFormDataLink } from '@falcondev-oss/trpc-typed-form-data/client'
-import { createTRPCVueQueryClient } from '@falcondev-oss/trpc-vue-query'
+import { createTRPCVueQueryClient, vueQueryContext } from '@falcondev-oss/trpc-vue-query'
 import {
   dehydrate,
   hydrate,
   MutationCache,
+  QueryCache,
   QueryClient,
   useIsFetching,
   useQueryClient,
   VueQueryPlugin,
 } from '@tanstack/vue-query'
-import { httpSubscriptionLink, isTRPCClientError, splitLink, TRPCClientError } from '@trpc/client'
+import { httpSubscriptionLink, isTRPCClientError, splitLink } from '@trpc/client'
+import { observable } from '@trpc/server/observable'
 import defu from 'defu'
 import superjson from 'superjson'
 import { httpBatchLink, httpLink } from 'trpc-nuxt/client'
@@ -29,6 +34,11 @@ interface ToastOpts {
 }
 
 export interface CustomMeta {
+  queryMeta: {
+    toast?: {
+      error?: ToastOpts
+    }
+  }
   mutationMeta: {
     toast?: {
       success?: ToastOpts
@@ -41,37 +51,108 @@ declare module '@tanstack/vue-query' {
   interface Register extends CustomMeta {}
 }
 
+/** a request that never got a response, i.e. `fetch` itself failed (offline, DNS, CORS, …) */
+function isNetworkError(err: unknown) {
+  return isTRPCClientError<AnyTRPCRouter>(err) && !err.meta?.response
+}
+
+/** `AnyTRPCRouter` widens the error shape to `any` */
+function errorData(err: TRPCClientError<AnyTRPCRouter>) {
+  return err.data as TRPCDefaultErrorData | undefined
+}
+
+const retryableHttpStatuses = new Set([408, 425, 429, 502, 503, 504])
+
+function isRetryableError(err: unknown) {
+  // unknown errors are usually a bug in the query fn, which a retry won't fix
+  if (!isTRPCClientError<AnyTRPCRouter>(err)) return false
+
+  return isNetworkError(err) || retryableHttpStatuses.has(errorData(err)?.httpStatus ?? 0)
+}
+
+/** zod reports its issues as a JSON-encoded list in the error message */
+function isSchemaIssueList(message: string) {
+  if (!message.startsWith('[')) return false
+
+  try {
+    const issues = JSON.parse(message) as unknown[]
+    return (
+      issues.length > 0 &&
+      issues.every((issue) => typeof (issue as { message?: unknown }).message === 'string')
+    )
+  } catch {
+    return false
+  }
+}
+
+const errorTitles: Partial<Record<TRPC_ERROR_CODE_KEY, string>> = {
+  BAD_REQUEST: 'Ungültige Eingabe',
+  UNAUTHORIZED: 'Nicht angemeldet',
+  FORBIDDEN: 'Kein Zugriff',
+  NOT_FOUND: 'Nicht vorhanden',
+}
+
+function requestErrorToast(err: unknown): ToastOpts {
+  if (isNetworkError(err))
+    return { title: 'Keine Verbindung', description: 'Der Server ist nicht erreichbar.' }
+
+  if (!isTRPCClientError<AnyTRPCRouter>(err)) return { title: 'Unbekannter Fehler' }
+
+  // internal errors leak implementation details and mean nothing to the user
+  if (errorData(err)?.httpStatus === 500) return { title: 'Server-Fehler' }
+
+  const code = errorData(err)?.code
+
+  return {
+    title: (code && errorTitles[code]) ?? 'Anfrage-Fehler',
+    description: isSchemaIssueList(err.message) ? 'Bitte Eingaben überprüfen.' : err.message,
+  }
+}
+
+/** during SSR a toast would be serialized into the payload and pop up after hydration */
+function toastAdd(opts: ToastOptions) {
+  if (import.meta.server) return
+
+  useToast().add({ duration: 5000, ...opts })
+}
+
+/** toasts a failed request, using `opts` if given, otherwise a generic message */
+function toastRequestError(err: unknown, opts?: ToastOpts) {
+  toastAdd({
+    preset: 'error',
+    ...(opts ?? requestErrorToast(err)),
+  })
+}
+
 export function vueQueryPlugin(opts?: VueQueryNuxtPluginOptions) {
   return {
     name: 'vue-query',
     setup(nuxt) {
-      const toast = useToast()
-      const vueQueryState = useState<Partial<DehydratedState>>('vue-query')
+      const vueQueryState = useState<Partial<DehydratedState>>('vue-query', () => ({}))
 
       const queryClient = new QueryClient(
         defu<QueryClientConfig, QueryClientConfig[]>(opts?.queryClientOptions, {
           defaultOptions: {
             queries: {
               retry(failureCount, error) {
-                if (
-                  isTRPCClientError<AnyTRPCRouter>(error) &&
-                  error.data &&
-                  // eslint-disable-next-line ts/no-unsafe-member-access
-                  error.data.httpStatus >= 400 &&
-                  // eslint-disable-next-line ts/no-unsafe-member-access
-                  error.data.httpStatus < 500
-                )
-                  return false
+                if (!isRetryableError(error)) return false
+
                 return failureCount < 3
               },
             },
           },
+          queryCache: new QueryCache({
+            onError(err, query) {
+              console.error(err)
+
+              toastRequestError(err, query.meta?.toast?.error)
+            },
+          }),
           mutationCache: new MutationCache({
             onSuccess(_res, _input, _onMutateRes, mutation) {
               if (mutation.meta?.toast?.success) {
-                toast.add({
+                toastAdd({
                   preset: 'success',
-                  duration: 5000,
                   ...mutation.meta.toast.success,
                 })
               }
@@ -79,42 +160,32 @@ export function vueQueryPlugin(opts?: VueQueryNuxtPluginOptions) {
             onError(err, _input, __onMutateRes, mutation) {
               console.error(err)
 
-              if (mutation.meta?.toast?.error) {
-                toast.add({
-                  preset: 'error',
-                  duration: 5000,
-                  ...mutation.meta.toast.error,
-                })
-              } else if (err instanceof TRPCClientError)
-                toast.add({
-                  preset: 'error',
-                  title: 'Request Error',
-                  description: err.message,
-                  duration: 5000,
-                })
-              else
-                toast.add({
-                  preset: 'error',
-                  title: 'An unknown error occurred',
-                  duration: 5000,
-                })
+              toastRequestError(err, mutation.meta?.toast?.error)
             },
           }),
         }),
       )
-      const options: VueQueryPluginOptions = { queryClient, ...opts?.vuePluginOptions }
 
+      const options: VueQueryPluginOptions = { queryClient, ...opts?.vuePluginOptions }
       nuxt.vueApp.use(VueQueryPlugin, options)
 
       if (import.meta.server) {
         nuxt.hooks.hook('app:rendered', () => {
-          vueQueryState.value = dehydrate(queryClient)
+          try {
+            vueQueryState.value = dehydrate(queryClient)
+          } catch (err) {
+            console.error('[vue-query] dehydrating state failed:', err)
+          }
         })
       }
 
       if (import.meta.client) {
         nuxt.hooks.hook('app:created', () => {
-          hydrate(queryClient, vueQueryState.value)
+          try {
+            hydrate(queryClient, vueQueryState.value)
+          } catch (err) {
+            console.error('[vue-query] hydrating state failed:', err)
+          }
         })
       }
 
@@ -138,8 +209,39 @@ export function vueQueryPlugin(opts?: VueQueryNuxtPluginOptions) {
   } satisfies ObjectPlugin
 }
 
+/**
+ * Toasts errors of requests that vue-query doesn't handle itself, i.e. plain
+ * `.query()` / `.mutate()` calls. Requests made through vue-query get their toast
+ * from the query/mutation cache instead.
+ */
+const toastRequestErrors: OperationLink<AnyTRPCRouter> = ({ op, next }) =>
+  observable((observer) => {
+    const subscription = next(op).subscribe({
+      next: (value) => observer.next(value),
+      complete: () => observer.complete(),
+      error(err) {
+        if (!op.context[vueQueryContext] && op.type !== 'subscription') {
+          console.error(err)
+          toastRequestError(err)
+        }
+
+        observer.error(err)
+      },
+    })
+
+    return () => {
+      subscription.unsubscribe()
+    }
+  })
+export const requestErrorToastLink: TRPCLink<AnyTRPCRouter> = () => toastRequestErrors
+
 interface TrpcNuxtPluginOptions {
   url: string
+  /**
+   * ofetch options passed to the HTTP links.
+   * @see https://github.com/unjs/ofetch
+   */
+  fetchOptions?: FetchOptions
 }
 export function trpcPlugin<Router extends AnyTRPCRouter>(opts: TrpcNuxtPluginOptions) {
   return {
@@ -153,6 +255,7 @@ export function trpcPlugin<Router extends AnyTRPCRouter>(opts: TrpcNuxtPluginOpt
         queryClient,
         trpc: {
           links: [
+            requestErrorToastLink,
             splitLink({
               condition: (op) => op.type === 'subscription',
               true: httpSubscriptionLink({
@@ -168,12 +271,14 @@ export function trpcPlugin<Router extends AnyTRPCRouter>(opts: TrpcNuxtPluginOpt
                   httpLink({
                     transformer: superjson,
                     url: opts.url,
+                    fetchOptions: opts.fetchOptions,
                   }),
                 ],
                 false: httpBatchLink({
                   transformer: superjson,
                   url: opts.url,
                   maxURLLength: 2000,
+                  fetchOptions: opts.fetchOptions,
                 }),
               }),
             }),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@falcondev-oss/nuxt-layers-base",
   "type": "module",
-  "version": "0.36.1",
+  "version": "0.37.1",
   "description": "Nuxt layer with lots of useful helpers and @nuxt/ui components",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
   },
   "dependencies": {
     "@falcondev-oss/trpc-typed-form-data": "^0.5.3",
-    "@falcondev-oss/trpc-vue-query": "^0.5.4",
+    "@falcondev-oss/trpc-vue-query": "^0.6.1",
     "@iconify-json/lucide": "^1.2.125",
     "@nuxt/icon": "^2.5.0",
     "@nuxtjs/color-mode": "^4.0.1",