feat(data-loaders): allow default type for errors

BREAKING CHANGE: The default type for `error` is now `Error`.

Author: posva

docs/data-loaders/error-handling.md

@@ -148,3 +148,29 @@ When you use both, global and local error handling, the local error handling has
 - if local `errors` is `false`: abort the navigation -> `data` is not `undefined`
 - if local `errors` is `true`: rely on the globally defined `errors` option -> `data` is possibly `undefined`
 - else: rely on the local `errors` option -> `data` is possibly `undefined`
+
+## TypeScript
+
+You will notice that the type of `error` is `Error | null` even when you specify the `errors` option. This is because if we call the `reload()` method (meaning we are outside of a navigation), the error isn't discarded, it appears in the `error` property **without being filtered** by the `errors` option.
+
+In practice, depending on how you handle the error, you will add a [type guard](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards) inside the component responsible for displaying an error or directly in a `v-if` in the template.
+
+```vue-html
+<template>
+  <!-- ... -->
+  <p v-if="isMyError(error)">{{ error.message }}</p>
+</template>
+```
+
+If you want to be even stricter, you can override the default `Error` type with `unknown` (or anything else) by augmenting the `TypesConfig` interface.
+
+```ts
+// types-extension.d.ts
+import 'unplugin-vue-router/data-loaders'
+export {}
+declare module 'unplugin-vue-router/data-loaders' {
+  interface TypesConfig {
+    Error: unknown
+  }
+}
+```

src/data-loaders/createDataLoader.ts

@@ -18,7 +18,7 @@ export interface DataLoaderEntryBase<Data = unknown, TError = unknown> {
   /**
    * Error if there was an error.
    */
-  error: ShallowRef<TError | null> // any is simply more convenient for errors
+  error: ShallowRef<TError | null>
 
   /**
    * Location the data was loaded for or `null` if the data is not loaded.
@@ -128,7 +128,7 @@ export interface _DefineDataLoaderOptionsBase_Common {
  * Options for a data loader that returns a data that is possibly `undefined`. Available for data loaders
  * implementations so they can be used in `defineLoader()` overloads.
  */
-export interface DefineDataLoaderOptionsBase_LaxData<TError = any>
+export interface DefineDataLoaderOptionsBase_LaxData
   extends _DefineDataLoaderOptionsBase_Common {
   lazy?:
     | boolean
@@ -143,36 +143,12 @@ export interface DefineDataLoaderOptionsBase_LaxData<TError = any>
 
   errors?:
     | boolean
-  // NOTE:
-    // | (any extends TError ? any[] : readonly (new (...args: any[]) => TError)[])
-    | Array<new (...args: any[]) => TError>
-    | (any extends TError
-        ? (reason?: unknown) => boolean
-        : (reason?: unknown) => reason is TError)
+    // array of constructors
+    | Array<new (...args: any[]) => any>
+    // custom type guard
+    | ((reason?: unknown) => boolean)
 }
 
-export function errorsFromArray<
-  const T extends readonly (new (...args: any) => any)[],
->(
-  errorConstructorsArray: T
-): (reason?: unknown) => reason is _UnionFromConstructorsArray<T> {
-  return (r: unknown): r is _UnionFromConstructorsArray<T> =>
-    errorConstructorsArray.some((ErrConstructor) => r instanceof ErrConstructor)
-}
-
-/**
- * Extracts the union of the constructors from an array of constructors.
- * @internal
- */
-export type _UnionFromConstructorsArray<T extends readonly any[]> = T extends readonly [
-  new (...args: any[]) => infer R,
-  ...infer Rest,
-]
-  ? Rest extends readonly [any, ...any[]]
-    ? R | _UnionFromConstructorsArray<Rest>
-    : R
-  : never
-
 /**
  * Options for a data loader making the data defined without it being possibly `undefined`. Available for data loaders
  * implementations so they can be used in `defineLoader()` overloads.
@@ -256,7 +232,7 @@ export interface UseDataLoader<Data = unknown, TError = unknown> {
    * Internals of the data loader.
    * @internal
    */
-  _: UseDataLoaderInternals<Exclude<Data, NavigationResult | undefined>>
+  _: UseDataLoaderInternals<Exclude<Data, NavigationResult | undefined>, TError>
 }
 
 /**
@@ -310,7 +286,7 @@ export interface UseDataLoaderResult<Data = unknown, TError = ErrorDefault> {
   /**
    * Error if there was an error.
    */
-  error: ShallowRef<TError | null> // any is simply more convenient for errors
+  error: ShallowRef<TError | null>
 
   /**
    * Reload the data using the current route location. Returns a promise that resolves when the data is reloaded. This

src/data-loaders/defineColadaLoader.test-d.ts

@@ -107,19 +107,23 @@ describe('defineBasicLoader', () => {
       defineColadaLoader({ key, query, errors: [] })().data.value
     ).toEqualTypeOf<UserData | undefined>()
     expectTypeOf(
-      defineColadaLoader({ key, query, errors: (e) => e instanceof Error })().data.value
+      defineColadaLoader({ key, query, errors: (e) => e instanceof Error })()
+        .data.value
     ).toEqualTypeOf<UserData | undefined>()
     expectTypeOf(
-      defineColadaLoader({ key, query, errors: (e) => typeof e == 'object' && e != null })().data.value
+      defineColadaLoader({
+        key,
+        query,
+        errors: (e) => typeof e == 'object' && e != null,
+      })().data.value
     ).toEqualTypeOf<UserData | undefined>()
   })
 
-  it('can type the error with a type guard', () => {
+  it('error is typed to Error by default', () => {
     expectTypeOf(
       defineColadaLoader({
         key,
         query,
-        errors: (e): e is Error => e instanceof Error,
       })().error.value
     ).toEqualTypeOf<Error | null>()
   })

src/data-loaders/defineColadaLoader.ts

@@ -15,6 +15,7 @@ import {
   type UseDataLoaderResult,
   type _DefineLoaderEntryMap,
   type _PromiseMerged,
+  type ErrorDefault,
   ABORT_CONTROLLER_KEY,
   APP_KEY,
   IS_USE_DATA_LOADER_KEY,
@@ -381,7 +382,9 @@ export function defineColadaLoader<Data>(
     const entries = router[
       LOADER_ENTRIES_KEY
     ]! as unknown as _DefineLoaderEntryMap<DataLoaderColadaEntry<unknown>>
-    let entry = entries.get(loader) as DataLoaderColadaEntry<Data> | undefined
+    let entry = entries.get(loader) as
+      | DataLoaderColadaEntry<Data, ErrorDefault>
+      | undefined
 
     if (
       // if the entry doesn't exist, create it with load and ensure it's loading
@@ -400,7 +403,7 @@ export function defineColadaLoader<Data>(
       )
     }
 
-    entry = entries.get(loader)! as DataLoaderColadaEntry<Data>
+    entry = entries.get(loader)! as DataLoaderColadaEntry<Data, ErrorDefault>
 
     // add ourselves to the parent entry children
     if (parentEntry) {
@@ -558,7 +561,7 @@ export type DefineDataColadaLoaderOptions<
 export interface DataColadaLoaderContext extends DataLoaderContextBase {}
 
 export interface UseDataLoaderColadaResult<Data>
-  extends UseDataLoaderResult<Data>,
+  extends UseDataLoaderResult<Data, ErrorDefault>,
     Pick<
       UseQueryReturn<Data, any>,
       'isPending' | 'refetch' | 'refresh' | 'status' | 'asyncStatus' | 'state'
@@ -568,7 +571,7 @@ export interface UseDataLoaderColadaResult<Data>
  * Data Loader composable returned by `defineColadaLoader()`.
  */
 export interface UseDataLoaderColada_LaxData<Data>
-  extends UseDataLoader<Data | undefined> {
+  extends UseDataLoader<Data | undefined, ErrorDefault> {
   /**
    * Data Loader composable returned by `defineColadaLoader()`.
    *
@@ -603,7 +606,7 @@ export interface UseDataLoaderColada_LaxData<Data>
  * Data Loader composable returned by `defineColadaLoader()`.
  */
 export interface UseDataLoaderColada_DefinedData<Data>
-  extends UseDataLoader<Data> {
+  extends UseDataLoader<Data, ErrorDefault> {
   /**
    * Data Loader composable returned by `defineColadaLoader()`.
    *
@@ -634,7 +637,8 @@ export interface UseDataLoaderColada_DefinedData<Data>
   >
 }
 
-export interface DataLoaderColadaEntry<Data> extends DataLoaderEntryBase<Data> {
+export interface DataLoaderColadaEntry<Data, TError = unknown>
+  extends DataLoaderEntryBase<Data, TError> {
   /**
    * Reactive route passed to pinia colada so it automatically refetch
    */
@@ -648,7 +652,7 @@ export interface DataLoaderColadaEntry<Data> extends DataLoaderEntryBase<Data> {
   /**
    * Extended options for pinia colada
    */
-  ext: UseQueryReturn<Data> | null
+  ext: UseQueryReturn<Data, TError> | null
 }
 
 interface TrackedRoute {

src/data-loaders/defineLoader.test-d.ts

@@ -2,7 +2,6 @@ import { describe, it, expectTypeOf } from 'vitest'
 import { defineBasicLoader } from './defineLoader'
 import type { Ref } from 'vue'
 import { NavigationResult } from './navigation-guard'
-import { errorsFromArray, type _UnionFromConstructorsArray } from './createDataLoader'
 
 describe('defineBasicLoader', () => {
   interface UserData {
@@ -113,69 +112,10 @@ describe('defineBasicLoader', () => {
     p2: string = 'p2'
   }
 
-  it('can type the error with a type guard', () => {
+  it('uses a default type of Error | null', () => {
     expectTypeOf(
-      defineBasicLoader(loaderUser, {
-        errors: (e) => e instanceof Error,
-      })().error.value
+      defineBasicLoader(loaderUser, {})().error.value
     ).toEqualTypeOf<Error | null>()
-
-    expectTypeOf(
-      defineBasicLoader(loaderUser, {
-        errors: (e) => e instanceof MyError1 || e instanceof MyError2,
-      })().error.value
-    ).toEqualTypeOf<MyError1 | MyError2 | null>()
-  })
-
-  it('errorsFromArray fails on non constructors', () => {
-    errorsFromArray([
-      // @ts-expect-error: no constructor
-      2,
-      // @ts-expect-error: no constructor
-      {},
-    ])
-  })
-
-  it('errorsFromArray narrows down types', () => {
-    let e: unknown
-    if (errorsFromArray([MyError1])(e)) {
-      expectTypeOf(e).toEqualTypeOf<MyError1>()
-    }
-  })
-
-  it('errorsFromArray works with multiple types', () => {
-    let e: unknown
-    if (errorsFromArray([MyError1, MyError2])(e)) {
-      expectTypeOf(e).toEqualTypeOf<MyError1 | MyError2>()
-    }
-  })
-
-  it('errorsFromArray works with multiple incompatible types', () => {
-    const e1 = [MyError1] as const
-    const e2 = [MyError1, MyError2] as const
-    const e3 = [MyError1, Error] as const
-    expectTypeOf({} as _UnionFromConstructorsArray<typeof e1>).toEqualTypeOf<MyError1>()
-    expectTypeOf({} as _UnionFromConstructorsArray<typeof e2>).toEqualTypeOf<MyError1 | MyError2>()
-    expectTypeOf({} as _UnionFromConstructorsArray<typeof e3>).toEqualTypeOf<MyError1 | Error>()
-
-
-    let e: unknown
-    if (errorsFromArray([MyError1, Error])(e)) {
-      expectTypeOf(e).toEqualTypeOf<MyError1 | Error>()
-    }
-  })
-
-  it('can type the error with an array', () => {
-    expectTypeOf(
-      defineBasicLoader(loaderUser, {
-        errors: errorsFromArray([MyError1, MyError2]),
-      })().error.value
-    ).toEqualTypeOf<MyError1 | MyError2 | null>()
-    expectTypeOf(
-      defineBasicLoader(loaderUser, {
-        errors: [MyError1, MyError2],
-      })().error.value
-    ).toEqualTypeOf<MyError1 | MyError2 | null>()
   })
 
   it('makes data possibly undefined when server is not true', () => {