UNPKG

vue-router

Version:

> - This is the repository for Vue Router 4 (for Vue 3) > - For Vue Router 3 (for Vue 2) see [vuejs/vue-router](https://github.com/vuejs/vue-router). > To see what versions are currently supported, please refer to the [Security Policy](./packages/router

1,413 lines (1,408 loc) 90.4 kB
/*! * vue-router v5.0.6 * (c) 2026 Eduardo San Martin Morote * @license MIT */ import { AllowedComponentProps, AnchorHTMLAttributes, App, Component as Component$1, ComponentCustomProps, ComponentPublicInstance, ComputedRef, DefineComponent, InjectionKey, MaybeRef, Ref, ShallowRef, UnwrapRef, VNode, VNodeProps } from "vue"; //#region src/config.d.ts /** * Allows customizing existing types of the router that are used globally like `$router`, `<RouterLink>`, etc. **ONLY FOR INTERNAL USAGE**. * * - `$router` - the router instance * - `$route` - the current route location * - `beforeRouteEnter` - Page component option * - `beforeRouteUpdate` - Page component option * - `beforeRouteLeave` - Page component option * - `RouterLink` - RouterLink Component * - `RouterView` - RouterView Component * * @internal */ interface TypesConfig {} //#endregion //#region src/query.d.ts /** * Possible values in normalized {@link LocationQuery}. `null` renders the query * param but without an `=`. * * @example * ``` * ?isNull&isEmpty=&other=other * gives * `{ isNull: null, isEmpty: '', other: 'other' }`. * ``` * * @internal */ type LocationQueryValue = string | null; /** * Possible values when defining a query. `undefined` allows to remove a value. * * @internal */ type LocationQueryValueRaw = LocationQueryValue | number | undefined; /** * Normalized query object that appears in {@link RouteLocationNormalized} * * @public */ type LocationQuery = Record<string, LocationQueryValue | LocationQueryValue[]>; /** * Loose {@link LocationQuery} object that can be passed to functions like * {@link Router.push} and {@link Router.replace} or anywhere when creating a * {@link RouteLocationRaw} * * @public */ type LocationQueryRaw = Record<string | number, LocationQueryValueRaw | LocationQueryValueRaw[]>; /** * Transforms a queryString into a {@link LocationQuery} object. Accept both, a * version with the leading `?` and without Should work as URLSearchParams * @internal * * @param search - search string to parse * @returns a query object */ declare function parseQuery(search: string): LocationQuery; /** * Stringifies a {@link LocationQueryRaw} object. Like `URLSearchParams`, it * doesn't prepend a `?` * * @internal * * @param query - query object to stringify * @returns string version of the query without the leading `?` */ declare function stringifyQuery(query: LocationQueryRaw | undefined): string; //#endregion //#region src/matcher/types.d.ts /** * Normalized version of a {@link RouteRecord | route record}. */ interface RouteRecordNormalized { /** * {@inheritDoc _RouteRecordBase.path} */ path: _RouteRecordBase['path']; /** * {@inheritDoc _RouteRecordBase.redirect} */ redirect: _RouteRecordBase['redirect'] | undefined; /** * {@inheritDoc _RouteRecordBase.name} */ name: _RouteRecordBase['name']; /** * {@inheritDoc RouteRecordMultipleViews.components} */ components: RouteRecordMultipleViews['components'] | null | undefined; /** * Contains the original modules for lazy loaded components. * @internal */ mods: Record<string, unknown>; /** * Nested route records. */ children: RouteRecordRaw[]; /** * {@inheritDoc _RouteRecordBase.meta} */ meta: Exclude<_RouteRecordBase['meta'], void>; /** * {@inheritDoc RouteRecordMultipleViews.props} */ props: Record<string, _RouteRecordProps>; /** * Registered beforeEnter guards */ beforeEnter: _RouteRecordBase['beforeEnter']; /** * Registered leave guards * * @internal */ leaveGuards: Set<NavigationGuard>; /** * Registered update guards * * @internal */ updateGuards: Set<NavigationGuard>; /** * Registered beforeRouteEnter callbacks passed to `next` or returned in guards * * @internal */ enterCallbacks: Record<string, NavigationGuardNextCallback[]>; /** * Mounted route component instances * Having the instances on the record mean beforeRouteUpdate and * beforeRouteLeave guards can only be invoked with the latest mounted app * instance if there are multiple application instances rendering the same * view, basically duplicating the content on the page, which shouldn't happen * in practice. It will work if multiple apps are rendering different named * views. */ instances: Record<string, ComponentPublicInstance | undefined | null>; /** * Defines if this record is the alias of another one. This property is * `undefined` if the record is the original one. */ aliasOf: RouteRecordNormalized | undefined; } /** * {@inheritDoc RouteRecordNormalized} */ type RouteRecord = RouteRecordNormalized; //#endregion //#region src/matcher/pathParserRanker.d.ts type PathParams = Record<string, string | string[]>; /** * A param in a url like `/users/:id` */ interface PathParserParamKey { name: string; repeatable: boolean; optional: boolean; } interface PathParser { /** * The regexp used to match a url */ re: RegExp; /** * The score of the parser */ score: Array<number[]>; /** * Keys that appeared in the path */ keys: PathParserParamKey[]; /** * Parses a url and returns the matched params or null if it doesn't match. An * optional param that isn't preset will be an empty string. A repeatable * param will be an array if there is at least one value. * * @param path - url to parse * @returns a Params object, empty if there are no params. `null` if there is * no match */ parse(path: string): PathParams | null; /** * Creates a string version of the url * * @param params - object of params * @returns a url */ stringify(params: PathParams): string; } /** * @internal */ interface _PathParserOptions { /** * Makes the RegExp case-sensitive. * * @defaultValue `false` */ sensitive?: boolean; /** * Whether to disallow a trailing slash or not. * * @defaultValue `false` */ strict?: boolean; /** * Should the RegExp match from the beginning by prepending a `^` to it. * @internal * * @defaultValue `true` */ start?: boolean; /** * Should the RegExp match until the end by appending a `$` to it. * * @deprecated this option will alsways be `true` in the future. Open a discussion in vuejs/router if you need this to be `false` * * @defaultValue `true` */ end?: boolean; } type PathParserOptions = Pick<_PathParserOptions, 'end' | 'sensitive' | 'strict'>; //#endregion //#region src/matcher/pathMatcher.d.ts interface RouteRecordMatcher extends PathParser { record: RouteRecord; parent: RouteRecordMatcher | undefined; children: RouteRecordMatcher[]; alias: RouteRecordMatcher[]; } //#endregion //#region src/matcher/index.d.ts /** * Internal RouterMatcher * * @internal */ interface RouterMatcher { addRoute: (record: RouteRecordRaw, parent?: RouteRecordMatcher) => () => void; removeRoute(matcher: RouteRecordMatcher): void; removeRoute(name: NonNullable<RouteRecordNameGeneric>): void; clearRoutes: () => void; getRoutes: () => RouteRecordMatcher[]; getRecordMatcher: (name: NonNullable<RouteRecordNameGeneric>) => RouteRecordMatcher | undefined; /** * Resolves a location. Gives access to the route record that corresponds to the actual path as well as filling the corresponding params objects * * @param location - MatcherLocationRaw to resolve to a url * @param currentLocation - MatcherLocation of the current location */ resolve: (location: MatcherLocationRaw, currentLocation: MatcherLocation) => MatcherLocation; } /** * Creates a Router Matcher. * * @internal * @param routes - array of initial routes * @param globalOptions - global route options */ declare function createRouterMatcher(routes: Readonly<RouteRecordRaw[]>, globalOptions: PathParserOptions): RouterMatcher; //#endregion //#region src/history/common.d.ts type HistoryLocation = string; /** * Allowed variables in HTML5 history state. Note that pushState clones the state * passed and does not accept everything: e.g.: it doesn't accept symbols, nor * functions as values. It also ignores Symbols as keys. * * @internal */ type HistoryStateValue = string | number | boolean | null | undefined | HistoryState | HistoryStateArray; /** * Allowed HTML history.state */ interface HistoryState { [x: number]: HistoryStateValue; [x: string]: HistoryStateValue; } /** * Allowed arrays for history.state. * * @internal */ interface HistoryStateArray extends Array<HistoryStateValue> {} declare enum NavigationType { pop = "pop", push = "push" } declare enum NavigationDirection { back = "back", forward = "forward", unknown = "" } interface NavigationInformation { type: NavigationType; direction: NavigationDirection; delta: number; } interface NavigationCallback { (to: HistoryLocation, from: HistoryLocation, information: NavigationInformation): void; } /** * Interface implemented by History implementations that can be passed to the * router as {@link Router.history} * * @alpha */ interface RouterHistory { /** * Base path that is prepended to every url. This allows hosting an SPA at a * sub-folder of a domain like `example.com/sub-folder` by having a `base` of * `/sub-folder` */ readonly base: string; /** * Current History location */ readonly location: HistoryLocation; /** * Current History state */ readonly state: HistoryState; /** * Navigates to a location. In the case of an HTML5 History implementation, * this will call `history.pushState` to effectively change the URL. * * @param to - location to push * @param data - optional {@link HistoryState} to be associated with the * navigation entry */ push(to: HistoryLocation, data?: HistoryState): void; /** * Same as {@link RouterHistory.push} but performs a `history.replaceState` * instead of `history.pushState` * * @param to - location to set * @param data - optional {@link HistoryState} to be associated with the * navigation entry */ replace(to: HistoryLocation, data?: HistoryState): void; /** * Traverses history in a given direction. * * @example * ```js * myHistory.go(-1) // equivalent to window.history.back() * myHistory.go(1) // equivalent to window.history.forward() * ``` * * @param delta - distance to travel. If delta is \< 0, it will go back, * if it's \> 0, it will go forward by that amount of entries. * @param triggerListeners - whether this should trigger listeners attached to * the history */ go(delta: number, triggerListeners?: boolean): void; /** * Attach a listener to the History implementation that is triggered when the * navigation is triggered from outside (like the Browser back and forward * buttons) or when passing `true` to {@link RouterHistory.back} and * {@link RouterHistory.forward} * * @param callback - listener to attach * @returns a callback to remove the listener */ listen(callback: NavigationCallback): () => void; /** * Generates the corresponding href to be used in an anchor tag. * * @param location - history location that should create an href */ createHref(location: HistoryLocation): string; /** * Clears any event listener attached by the history implementation. */ destroy(): void; } //#endregion //#region src/types/index.d.ts type Lazy<T> = () => Promise<T>; /** * @internal */ type RouteParamValue = string; /** * @internal */ type RouteParamValueRaw = RouteParamValue | number | null | undefined; type RouteParamsGeneric = Record<string, RouteParamValue | RouteParamValue[]>; type RouteParamsRawGeneric = Record<string, RouteParamValueRaw | Exclude<RouteParamValueRaw, null | undefined>[]>; /** * @internal */ interface RouteQueryAndHash { query?: LocationQueryRaw; hash?: string; } /** * @internal */ interface MatcherLocationAsPath { path: string; } /** * @internal */ interface MatcherLocationAsName { name: RouteRecordNameGeneric; /** * Ignored path property since we are dealing with a relative location. Only `undefined` is allowed. */ path?: undefined; params?: RouteParamsGeneric; } /** * @internal */ interface MatcherLocationAsRelative { /** * Ignored path property since we are dealing with a relative location. Only `undefined` is allowed. */ path?: undefined; params?: RouteParamsGeneric; } /** * @internal */ interface LocationAsRelativeRaw { name?: RouteRecordNameGeneric; /** * Ignored path property since we are dealing with a relative location. Only `undefined` is allowed. */ path?: undefined; params?: RouteParamsRawGeneric; } /** * Common options for all navigation methods. */ interface RouteLocationOptions { /** * Replace the entry in the history instead of pushing a new entry */ replace?: boolean; /** * Triggers the navigation even if the location is the same as the current one. * Note this will also add a new entry to the history unless `replace: true` * is passed. */ force?: boolean; /** * State to save using the History API. This cannot contain any reactive * values and some primitives like Symbols are forbidden. More info at * https://developer.mozilla.org/en-US/docs/Web/API/History/state */ state?: HistoryState; } /** * Route Location that can infer the necessary params based on the name. * * @internal */ interface RouteLocationNamedRaw extends RouteQueryAndHash, LocationAsRelativeRaw, RouteLocationOptions {} /** * Route Location that can infer the possible paths. * * @internal */ interface RouteLocationPathRaw extends RouteQueryAndHash, MatcherLocationAsPath, RouteLocationOptions {} interface RouteLocationMatched extends RouteRecordNormalized { components: Record<string, RouteComponent> | null | undefined; } /** * Base properties for a normalized route location. * * @internal */ interface _RouteLocationBase extends Pick<MatcherLocation, 'name' | 'path' | 'params' | 'meta'> { /** * The whole location including the `search` and `hash`. This string is * percentage encoded. */ fullPath: string; /** * Object representation of the `search` property of the current location. */ query: LocationQuery; /** * Hash of the current location. If present, starts with a `#`. */ hash: string; /** * Contains the location we were initially trying to access before ending up * on the current location. */ redirectedFrom: RouteLocation | undefined; } /** * Allowed Component in {@link RouteLocationMatched} */ type RouteComponent = Component$1 | DefineComponent; /** * Allowed Component definitions in route records provided by the user */ type RawRouteComponent = RouteComponent | Lazy<RouteComponent>; /** * Internal type for common properties among all kind of {@link RouteRecordRaw}. */ interface _RouteRecordBase extends PathParserOptions { /** * Path of the record. Should start with `/` unless the record is the child of * another record. * * @example `/users/:id` matches `/users/1` as well as `/users/posva`. */ path: string; /** * Where to redirect if the route is directly matched. The redirection happens * before any navigation guard and triggers a new navigation with the new * target location. */ redirect?: RouteRecordRedirectOption; /** * Aliases for the record. Allows defining extra paths that will behave like a * copy of the record. Allows having paths shorthands like `/users/:id` and * `/u/:id`. All `alias` and `path` values must share the same params. */ alias?: string | string[]; /** * Name for the route record. Must be unique. */ name?: RouteRecordNameGeneric; /** * Before Enter guard specific to this record. Note `beforeEnter` has no * effect if the record has a `redirect` property. */ beforeEnter?: NavigationGuardWithThis<undefined> | NavigationGuardWithThis<undefined>[]; /** * Arbitrary data attached to the record. */ meta?: RouteMeta; /** * Array of nested routes. */ children?: RouteRecordRaw[]; /** * Allow passing down params as props to the component rendered by `router-view`. */ props?: _RouteRecordProps | Record<string, _RouteRecordProps>; } /** * Interface to type `meta` fields in route records. * * @example * * ```ts * // typings.d.ts or router.ts * import 'vue-router'; * * declare module 'vue-router' { * interface RouteMeta { * requiresAuth?: boolean * } * } * ``` */ interface RouteMeta extends Record<PropertyKey, unknown> {} /** * Route Record defining one single component with the `component` option. */ interface RouteRecordSingleView extends _RouteRecordBase { /** * Component to display when the URL matches this route. */ component: RawRouteComponent; components?: never; children?: never; redirect?: never; /** * Allow passing down params as props to the component rendered by `router-view`. */ props?: _RouteRecordProps; } /** * Route Record defining one single component with a nested view. Differently * from {@link RouteRecordSingleView}, this record has children and allows a * `redirect` option. */ interface RouteRecordSingleViewWithChildren extends _RouteRecordBase { /** * Component to display when the URL matches this route. */ component?: RawRouteComponent | null | undefined; components?: never; children: RouteRecordRaw[]; /** * Allow passing down params as props to the component rendered by `router-view`. */ props?: _RouteRecordProps; } /** * Route Record defining multiple named components with the `components` option. */ interface RouteRecordMultipleViews extends _RouteRecordBase { /** * Components to display when the URL matches this route. Allow using named views. */ components: Record<string, RawRouteComponent>; component?: never; children?: never; redirect?: never; /** * Allow passing down params as props to the component rendered by * `router-view`. Should be an object with the same keys as `components` or a * boolean to be applied to every component. */ props?: Record<string, _RouteRecordProps> | boolean; } /** * Route Record defining multiple named components with the `components` option and children. */ interface RouteRecordMultipleViewsWithChildren extends _RouteRecordBase { /** * Components to display when the URL matches this route. Allow using named views. */ components?: Record<string, RawRouteComponent> | null | undefined; component?: never; children: RouteRecordRaw[]; /** * Allow passing down params as props to the component rendered by * `router-view`. Should be an object with the same keys as `components` or a * boolean to be applied to every component. */ props?: Record<string, _RouteRecordProps> | boolean; } /** * Route Record that defines a redirect. Cannot have `component` or `components` * as it is never rendered. */ interface RouteRecordRedirect extends _RouteRecordBase { redirect: RouteRecordRedirectOption; component?: never; components?: never; props?: never; } type RouteRecordRaw = RouteRecordSingleView | RouteRecordSingleViewWithChildren | RouteRecordMultipleViews | RouteRecordMultipleViewsWithChildren | RouteRecordRedirect; /** * Route location that can be passed to the matcher. */ type MatcherLocationRaw = MatcherLocationAsPath | MatcherLocationAsName | MatcherLocationAsRelative; /** * Normalized/resolved Route location that returned by the matcher. */ interface MatcherLocation { /** * Name of the matched record */ name: RouteRecordNameGeneric | null | undefined; /** * Percentage encoded pathname section of the URL. */ path: string; /** * Object of decoded params extracted from the `path`. */ params: RouteParamsGeneric; /** * Merged `meta` properties from all the matched route records. */ meta: RouteMeta; /** * Array of {@link RouteRecord} containing components as they were * passed when adding records. It can also contain redirect records. This * can't be used directly */ matched: RouteRecord[]; } //#endregion //#region src/typed-routes/route-map.d.ts /** * Helper type to define a Typed `RouteRecord` * @see {@link RouteRecord} */ interface RouteRecordInfo<Name extends string | symbol = string, Path extends string = string, ParamsRaw extends RouteParamsRawGeneric = RouteParamsRawGeneric, Params extends RouteParamsGeneric = RouteParamsGeneric, ChildrenNames extends string | symbol = never> { name: Name; path: Path; paramsRaw: ParamsRaw; params: Params; childrenNames: ChildrenNames; } type RouteRecordInfoGeneric = RouteRecordInfo<string | symbol, string, RouteParamsRawGeneric, RouteParamsGeneric, string | symbol>; /** * Convenience type to get the typed RouteMap or a generic one if not provided. * It is extracted from the {@link TypesConfig} if it exists, it becomes * {@link RouteMapGeneric} otherwise. */ type RouteMap = TypesConfig extends Record<'RouteNamedMap', infer RouteNamedMap> ? RouteNamedMap : RouteMapGeneric; /** * Generic version of the `RouteMap`. */ type RouteMapGeneric = Record<string | symbol, RouteRecordInfoGeneric>; //#endregion //#region src/typed-routes/params.d.ts /** * Utility type for raw and non raw params like :id+ * */ type ParamValueOneOrMore<isRaw extends boolean> = [ParamValue<isRaw>, ...ParamValue<isRaw>[]]; /** * Utility type for raw and non raw params like :id* * */ type ParamValueZeroOrMore<isRaw extends boolean> = true extends isRaw ? ParamValue<isRaw>[] | undefined | null : ParamValue<isRaw>[] | undefined; /** * Utility type for raw and non raw params like :id? * */ type ParamValueZeroOrOne<isRaw extends boolean> = true extends isRaw ? string | number | null | undefined : string; /** * Utility type for raw and non raw params like :id * */ type ParamValue<isRaw extends boolean> = true extends isRaw ? string | number : string; /** * Generate a type safe params for a route location. Requires the name of the route to be passed as a generic. * @see {@link RouteParamsGeneric} */ type RouteParams<Name extends keyof RouteMap = keyof RouteMap> = RouteMap[Name]['params']; /** * Generate a type safe raw params for a route location. Requires the name of the route to be passed as a generic. * @see {@link RouteParamsRaw} */ type RouteParamsRaw<Name extends keyof RouteMap = keyof RouteMap> = RouteMap[Name]['paramsRaw']; //#endregion //#region src/types/utils.d.ts /** * Creates a union type that still allows autocompletion for strings. * @internal */ type _LiteralUnion<LiteralType, BaseType extends string = string> = LiteralType | (BaseType & Record<never, never>); /** * Maybe a promise maybe not * @internal */ type _Awaitable<T> = T | PromiseLike<T>; /** * @internal */ type Simplify<T> = { [K in keyof T]: T[K] } & {}; //#endregion //#region src/typed-routes/route-records.d.ts /** * @internal */ type RouteRecordRedirectOption = RouteLocationRaw | ((to: RouteLocation, from: RouteLocationNormalizedLoaded) => RouteLocationRaw); /** * Generic version of {@link RouteRecordName}. */ type RouteRecordNameGeneric = string | symbol | undefined; /** * Possible values for a route record **after normalization** * * NOTE: since `RouteRecordName` is a type, it evaluates too early and it's often the generic version {@link RouteRecordNameGeneric}. If you need a typed version of all of the names of routes, use {@link RouteMap | `keyof RouteMap`} */ type RouteRecordName = RouteMapGeneric extends RouteMap ? RouteRecordNameGeneric : keyof RouteMap; /** * @internal */ type _RouteRecordProps<Name extends keyof RouteMap = keyof RouteMap> = boolean | Record<string, any> | ((to: RouteLocationNormalized<Name>) => Record<string, any>); //#endregion //#region src/typed-routes/route-location.d.ts /** * Generic version of {@link RouteLocation}. It is used when no {@link RouteMap} is provided. */ interface RouteLocationGeneric extends _RouteLocationBase, RouteLocationOptions { /** * Array of {@link RouteRecord} containing components as they were * passed when adding records. It can also contain redirect records. This * can't be used directly. **This property is non-enumerable**. */ matched: RouteRecord[]; } /** * Helper to generate a type safe version of the {@link RouteLocation} type. */ interface RouteLocationTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric }, Name extends keyof RouteMap> extends RouteLocationGeneric { name: Extract<Name, string | symbol>; params: RouteMap[Name]['params']; } /** * List of all possible {@link RouteLocation} indexed by the route name. * @internal */ type RouteLocationTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationTyped<RouteMap, N> }; /** * Generic version of {@link RouteLocationNormalized} that is used when no {@link RouteMap} is provided. */ interface RouteLocationNormalizedGeneric extends _RouteLocationBase { name: RouteRecordNameGeneric; /** * Array of {@link RouteRecordNormalized} */ matched: RouteRecordNormalized[]; } /** * Helper to generate a type safe version of the {@link RouteLocationNormalized} type. */ interface RouteLocationNormalizedTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric, Name extends keyof RouteMap = keyof RouteMap> extends RouteLocationNormalizedGeneric { name: Extract<Name, string | symbol>; params: RouteMap[Name]['params']; /** * Array of {@link RouteRecordNormalized} */ matched: RouteRecordNormalized[]; } /** * List of all possible {@link RouteLocationNormalized} indexed by the route name. * @internal */ type RouteLocationNormalizedTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationNormalizedTyped<RouteMap, N> }; /** * Generic version of {@link RouteLocationNormalizedLoaded} that is used when no {@link RouteMap} is provided. */ interface RouteLocationNormalizedLoadedGeneric extends RouteLocationNormalizedGeneric { /** * Array of {@link RouteLocationMatched} containing only plain components (any * lazy-loaded components have been loaded and were replaced inside the * `components` object) so it can be directly used to display routes. It * cannot contain redirect records either. **This property is non-enumerable**. */ matched: RouteLocationMatched[]; } /** * Helper to generate a type safe version of the {@link RouteLocationNormalizedLoaded} type. */ interface RouteLocationNormalizedLoadedTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric, Name extends keyof RouteMap = keyof RouteMap> extends RouteLocationNormalizedLoadedGeneric { name: Extract<Name, string | symbol>; params: RouteMap[Name]['params']; } /** * List of all possible {@link RouteLocationNormalizedLoaded} indexed by the route name. * @internal */ type RouteLocationNormalizedLoadedTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationNormalizedLoadedTyped<RouteMap, N> }; /** * Generic version of {@link RouteLocationAsRelative}. It is used when no {@link RouteMap} is provided. */ interface RouteLocationAsRelativeGeneric extends RouteQueryAndHash, RouteLocationOptions { name?: RouteRecordNameGeneric; params?: RouteParamsRawGeneric; /** * A relative path to the current location. This property should be removed */ path?: undefined; } /** * Helper to generate a type safe version of the {@link RouteLocationAsRelative} type. */ interface RouteLocationAsRelativeTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric, Name extends keyof RouteMap = keyof RouteMap> extends RouteLocationAsRelativeGeneric { name?: Extract<Name, string | symbol>; params?: RouteMap[Name]['paramsRaw']; } /** * List of all possible {@link RouteLocationAsRelative} indexed by the route name. * @internal */ type RouteLocationAsRelativeTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationAsRelativeTyped<RouteMap, N> }; /** * Generic version of {@link RouteLocationAsPath}. It is used when no {@link RouteMap} is provided. */ interface RouteLocationAsPathGeneric extends RouteQueryAndHash, RouteLocationOptions { /** * Percentage encoded pathname section of the URL. */ path: string; } /** * Helper to generate a type safe version of the {@link RouteLocationAsPath} type. */ interface RouteLocationAsPathTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric, Name extends keyof RouteMap = keyof RouteMap> extends RouteLocationAsPathGeneric { path: _LiteralUnion<RouteMap[Name]['path']>; } /** * List of all possible {@link RouteLocationAsPath} indexed by the route name. * @internal */ type RouteLocationAsPathTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationAsPathTyped<RouteMap, N> }; /** * Helper to generate a type safe version of the {@link RouteLocationAsString} type. */ type RouteLocationAsStringTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric, Name extends keyof RouteMap = keyof RouteMap> = RouteMap[Name]['path']; /** * List of all possible {@link RouteLocationAsString} indexed by the route name. * @internal */ type RouteLocationAsStringTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationAsStringTyped<RouteMap, N> }; /** * Generic version of {@link RouteLocationResolved}. It is used when no {@link RouteMap} is provided. */ interface RouteLocationResolvedGeneric extends RouteLocationGeneric { /** * Resolved `href` for the route location that will be set on the `<a href="...">`. */ href: string; } /** * Helper to generate a type safe version of the {@link RouteLocationResolved} type. */ interface RouteLocationResolvedTyped<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric }, Name extends keyof RouteMap> extends RouteLocationTyped<RouteMap, Name> { /** * Resolved `href` for the route location that will be set on the `<a href="...">`. */ href: string; } /** * List of all possible {@link RouteLocationResolved} indexed by the route name. * @internal */ type RouteLocationResolvedTypedList<RouteMap extends { [K in keyof RouteMap]: RouteRecordInfoGeneric } = RouteMapGeneric> = { [N in keyof RouteMap]: RouteLocationResolvedTyped<RouteMap, N> }; /** * Type safe versions of types that are exposed by vue-router. We have to use a generic check to allow for names to be `undefined` when no `RouteMap` is provided. */ /** * {@link RouteLocationRaw} resolved using the matcher */ type RouteLocation<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationGeneric : RouteLocationTypedList<RouteMap>[Name]; /** * Similar to {@link RouteLocation} but its * {@link RouteLocationNormalizedTyped.matched | `matched` property} cannot contain redirect records */ type RouteLocationNormalized<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationNormalizedGeneric : RouteLocationNormalizedTypedList<RouteMap>[Name]; /** * Similar to {@link RouteLocationNormalized} but its `components` do not contain any function to lazy load components. * In other words, it's ready to be rendered by `<RouterView>`. */ type RouteLocationNormalizedLoaded<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationNormalizedLoadedGeneric : RouteLocationNormalizedLoadedTypedList<RouteMap>[Name]; /** * Route location relative to the current location. It accepts other properties than `path` like `params`, `query` and * `hash` to conveniently change them. */ type RouteLocationAsRelative<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationAsRelativeGeneric : RouteLocationAsRelativeTypedList<RouteMap>[Name]; /** * Route location resolved with {@link Router | `router.resolve()`}. */ type RouteLocationResolved<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationResolvedGeneric : RouteLocationResolvedTypedList<RouteMap>[Name]; /** * Same as {@link RouteLocationAsPath} but as a string literal. */ type RouteLocationAsString<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? string : _LiteralUnion<RouteLocationAsStringTypedList<RouteMap>[Name], string>; /** * Route location as an object with a `path` property. */ type RouteLocationAsPath<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationAsPathGeneric : RouteLocationAsPathTypedList<RouteMap>[Name]; /** * Route location that can be passed to `router.push()` and other user-facing APIs. */ type RouteLocationRaw<Name extends keyof RouteMap = keyof RouteMap> = RouteMapGeneric extends RouteMap ? RouteLocationAsString | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric : _LiteralUnion<RouteLocationAsStringTypedList<RouteMap>[Name], string> | RouteLocationAsRelativeTypedList<RouteMap>[Name] | RouteLocationAsPathTypedList<RouteMap>[Name]; //#endregion //#region src/errors.d.ts /** * Flags so we can combine them when checking for multiple errors. This is the internal version of * {@link NavigationFailureType}. * * @internal */ declare const enum ErrorTypes { MATCHER_NOT_FOUND = 1, NAVIGATION_GUARD_REDIRECT = 2, NAVIGATION_ABORTED = 4, NAVIGATION_CANCELLED = 8, NAVIGATION_DUPLICATED = 16 } /** * Enumeration with all possible types for navigation failures. Can be passed to * {@link isNavigationFailure} to check for specific failures. */ declare enum NavigationFailureType { /** * An aborted navigation is a navigation that failed because a navigation * guard returned `false` or called `next(false)` */ aborted = 4, /** * A cancelled navigation is a navigation that failed because a more recent * navigation finished started (not necessarily finished). */ cancelled = 8, /** * A duplicated navigation is a navigation that failed because it was * initiated while already being at the exact same location. */ duplicated = 16 } /** * Extended Error that contains extra information regarding a failed navigation. */ interface NavigationFailure extends Error { /** * Type of the navigation. One of {@link NavigationFailureType} */ type: ErrorTypes.NAVIGATION_CANCELLED | ErrorTypes.NAVIGATION_ABORTED | ErrorTypes.NAVIGATION_DUPLICATED; /** * Route location we were navigating from */ from: RouteLocationNormalized; /** * Route location we were navigating to */ to: RouteLocationNormalized; } /** * Internal error used to detect a redirection. * * @internal */ interface NavigationRedirectError extends Omit<NavigationFailure, 'to' | 'type'> { type: ErrorTypes.NAVIGATION_GUARD_REDIRECT; to: RouteLocationRaw; } /** * Check if an object is a {@link NavigationFailure}. * * @param error - possible {@link NavigationFailure} * @param type - optional types to check for * * @example * ```js * import { isNavigationFailure, NavigationFailureType } from 'vue-router' * * router.afterEach((to, from, failure) => { * // Any kind of navigation failure * if (isNavigationFailure(failure)) { * // ... * } * // Only duplicated navigations * if (isNavigationFailure(failure, NavigationFailureType.duplicated)) { * // ... * } * // Aborted or canceled navigations * if (isNavigationFailure(failure, NavigationFailureType.aborted | NavigationFailureType.cancelled )) { * // ... * } * }) * ``` */ declare function isNavigationFailure(error: any, type?: ErrorTypes.NAVIGATION_GUARD_REDIRECT): error is NavigationRedirectError; declare function isNavigationFailure(error: any, type?: ErrorTypes | NavigationFailureType): error is NavigationFailure; /** * Internal type to define an ErrorHandler * * @param error - error thrown * @param to - location we were navigating to when the error happened * @param from - location we were navigating from when the error happened * @internal */ interface _ErrorListener { (error: any, to: RouteLocationNormalized, from: RouteLocationNormalizedLoaded): any; } //#endregion //#region src/typed-routes/navigation-guards.d.ts /** * Return types for a Navigation Guard. Based on `TypesConfig` * * @see {@link TypesConfig} */ type NavigationGuardReturn = void | Error | boolean | RouteLocationRaw; /** * Navigation Guard with a type parameter for `this`. * @see {@link TypesConfig} */ interface NavigationGuardWithThis<T> { (this: T, to: RouteLocationNormalized, from: RouteLocationNormalizedLoaded, /** * @deprecated Return a value from the guard instead of calling `next(value)`. * The callback will be removed in a future version of Vue Router. */ next: NavigationGuardNext): _Awaitable<NavigationGuardReturn>; } /** * In `router.beforeResolve((to) => {})`, the `to` is typed as `RouteLocationNormalizedLoaded`, not * `RouteLocationNormalized` like in `router.beforeEach()`. In practice it doesn't change much as users do not rely on * the difference between them but if we update the type in vue-router, we will have to update this type too. * @internal */ interface _NavigationGuardResolved { (this: undefined, to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded, /** * @deprecated Return a value from the guard instead of calling `next(value)`. * The callback will be removed in a future version of Vue Router. */ next: NavigationGuardNext): _Awaitable<NavigationGuardReturn>; } /** * Navigation Guard. */ interface NavigationGuard { (to: RouteLocationNormalized, from: RouteLocationNormalizedLoaded, /** * @deprecated Return a value from the guard instead of calling `next(value)`. * The callback will be removed in a future version of Vue Router. */ next: NavigationGuardNext): _Awaitable<NavigationGuardReturn>; } /** * Navigation hook triggered after a navigation is settled. */ interface NavigationHookAfter { (to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded, failure?: NavigationFailure | void): unknown; } /** * Callback passed to navigation guards to continue or abort the navigation. * * @deprecated Prefer returning a value from the guard instead of calling * `next(value)`. The callback will be removed in a future version of Vue Router. */ interface NavigationGuardNext { (): void; (error: Error): void; (location: RouteLocationRaw): void; (valid: boolean | undefined): void; (cb: NavigationGuardNextCallback): void; } /** * Callback that can be passed to `next()` in `beforeRouteEnter()` guards. */ type NavigationGuardNextCallback = (vm: ComponentPublicInstance) => unknown; //#endregion //#region src/history/html5.d.ts /** * Creates an HTML5 history. Most common history for single page applications. * * @param base - */ declare function createWebHistory(base?: string): RouterHistory; //#endregion //#region src/history/memory.d.ts /** * Creates an in-memory based history. The main purpose of this history is to handle SSR. It starts in a special location that is nowhere. * It's up to the user to replace that location with the starter location by either calling `router.push` or `router.replace`. * * @param base - Base applied to all urls, defaults to '/' * @returns a history object that can be passed to the router constructor */ declare function createMemoryHistory(base?: string): RouterHistory; //#endregion //#region src/history/hash.d.ts /** * Creates a hash history. Useful for web applications with no host (e.g. `file://`) or when configuring a server to * handle any URL is not possible. * * @param base - optional base to provide. Defaults to `location.pathname + location.search` If there is a `<base>` tag * in the `head`, its value will be ignored in favor of this parameter **but note it affects all the history.pushState() * calls**, meaning that if you use a `<base>` tag, it's `href` value **has to match this parameter** (ignoring anything * after the `#`). * * @example * ```js * // at https://example.com/folder * createWebHashHistory() // gives a url of `https://example.com/folder#` * createWebHashHistory('/folder/') // gives a url of `https://example.com/folder/#` * // if the `#` is provided in the base, it won't be added by `createWebHashHistory` * createWebHashHistory('/folder/#/app/') // gives a url of `https://example.com/folder/#/app/` * // you should avoid doing this because it changes the original url and breaks copying urls * createWebHashHistory('/other-folder/') // gives a url of `https://example.com/other-folder/#` * * // at file:///usr/etc/folder/index.html * // for locations with no `host`, the base is ignored * createWebHashHistory('/iAmIgnored') // gives a url of `file:///usr/etc/folder/index.html#` * ``` */ declare function createWebHashHistory(base?: string): RouterHistory; //#endregion //#region src/scrollBehavior.d.ts /** * Scroll position similar to * {@link https://developer.mozilla.org/en-US/docs/Web/API/ScrollToOptions | `ScrollToOptions`}. * Note that not all browsers support `behavior`. */ type ScrollPositionCoordinates = { behavior?: ScrollOptions['behavior']; left?: number; top?: number; }; /** * Internal normalized version of {@link ScrollPositionCoordinates} that always * has `left` and `top` coordinates. Must be a type to be assignable to HistoryStateValue. * * @internal */ type _ScrollPositionNormalized = { behavior?: ScrollOptions['behavior']; left: number; top: number; }; /** * Type of the `scrollBehavior` option that can be passed to `createRouter`. */ interface RouterScrollBehavior { /** * @param to - Route location where we are navigating to * @param from - Route location where we are navigating from * @param savedPosition - saved position if it exists, `null` otherwise */ (to: RouteLocationNormalized, from: RouteLocationNormalizedLoaded, savedPosition: _ScrollPositionNormalized | null): Awaitable<ScrollPosition | false | void>; } interface ScrollPositionElement extends ScrollToOptions { /** * A valid CSS selector. Note some characters must be escaped in id selectors (https://mathiasbynens.be/notes/css-escapes). * @example * Here are a few examples: * * - `.title` * - `.content:first-child` * - `#marker` * - `#marker\~with\~symbols` * - `#marker.with.dot`: selects `class="with dot" id="marker"`, not `id="marker.with.dot"` * */ el: string | Element; } type ScrollPosition = ScrollPositionCoordinates | ScrollPositionElement; type Awaitable<T> = T | PromiseLike<T>; //#endregion //#region src/experimental/route-resolver/matchers/param-parsers/types.d.ts /** * Defines a parser that can read a param from the url (string-based) and * transform it into a more complex type, or vice versa. * * @see MatcherPattern */ interface ParamParser<TParam = MatcherQueryParamsValue, TUrlParam = MatcherQueryParamsValue, TParamRaw = TParam> { get?: (value: NoInfer<TUrlParam>) => TParam; set?: (value: TParamRaw) => TUrlParam; } //#endregion //#region src/experimental/route-resolver/matchers/matcher-pattern.d.ts /** * Base interface for matcher patterns that extract params from a URL. * * @template TIn - type of the input value to match against the pattern * @template TParams - type of the output value after matching * @template TParamsRaw - type of the input value to build the input from * * In the case of the `path`, the `TIn` is a `string`, but in the case of the * query, it's the object of query params. `TParamsRaw` allows for a more permissive * type when building the value, for example allowing numbers and strings like * the old params. * * @internal this is the base interface for all matcher patterns, it shouldn't * be used directly */ interface MatcherPattern<TIn = string, TParams extends MatcherParamsFormatted = MatcherParamsFormatted, TParamsRaw extends MatcherParamsFormatted = TParams> { /** * Matches a serialized params value against the pattern. * * @param value - params value to parse * @throws {MatchMiss} if the value doesn't match * @returns parsed params object */ match(value: TIn): TParams; /** * Build a serializable value from parsed params. Should apply encoding if the * returned value is a string (e.g path and hash should be encoded but query * shouldn't). * * @param value - params value to parse * @returns serialized params value */ build(params: TParamsRaw): TIn; } /** * Handles the `path` part of a URL. It can transform a path string into an * object of params and vice versa. */ interface MatcherPatternPath<TParams extends MatcherParamsFormatted = MatcherParamsFormatted, // | null // | undefined // | void // so it might be a bit more convenient TParamsRaw extends MatcherParamsFormatted = TParams> extends MatcherPattern<string, TParams, TParamsRaw> {} /** * Allows matching a static path. * * @example * ```ts * const matcher = new MatcherPatternPathStatic('/team') * matcher.match('/team') // {} * matcher.match('/team/123') // throws MatchMiss * matcher.build() // '/team' * ``` */ declare class MatcherPatternPathStatic implements MatcherPatternPath<EmptyParams> { readonly path: string; /** * lowercase version of the path to match against. * This is used to make the matching case insensitive. */ private pathi; constructor(path: string); match(path: string): EmptyParams; build(): string; } /** * Options for param parsers in {@link MatcherPatternPathDynamic}. */ type MatcherPatternPathDynamic_ParamOptions<TUrlParam extends string | string[] | null = string | string[] | null, TParam = string | string[] | null, TParamRaw = TParam> = readonly [ /** * Param parser to use for this param. */ parser?: ParamParser<TParam, TUrlParam, TParamRaw>, /** * Is tha param a repeatable param and should be converted to an array */ repeatable?: boolean, /** * Can this parameter be omitted or empty (for repeatable params, an empty array). */ optional?: boolean]; /** * Helper type to extract the params from the options object. * * @internal */ type ExtractParamTypeFromOptions<TParamsOptions> = { [K in keyof TParamsOptions]: TParamsOptions[K] extends MatcherPatternPathDynamic_ParamOptions<any, infer TParam, any> ? TParam : never }; /** * Helper type to extract the raw params from the options object. * * @internal */ type ExtractLocationParamTypeFromOptions<TParamsOptions> = { [K in keyof TParamsOptions]: TParamsOptions[K] extends MatcherPatternPathDynamic_ParamOptions<any, any, infer TParamRaw> ? TParamRaw : never }; /** * Handles the `path` part of a URL with dynamic parameters. */ declare class MatcherPatternPathDynamic<TParamsOptions> implements MatcherPatternPath<ExtractParamTypeFromOptions<TParamsOptions>, ExtractLocationParamTypeFromOptions<TParamsOptions>> { readonly re: RegExp; readonly params: TParamsOptions & Record<string, MatcherPatternPathDynamic_ParamOptions<any, any>>; readonly pathParts: Array<string | number | Array<string | number>>; readonly trailingSlash: boolean | null; /** * Cached keys of the {@link params} object. */ private paramsKeys; /** * Creates a new dynamic path matcher. * * @param re - regex to match the path against * @param params - object of param parsers as {@link MatcherPatternPathDynamic_ParamOptions} * @param pathParts - array of path parts, where strings are static parts, 1 are regular params, and 0 are splat params (not encode slash) * @param trailingSlash - whether the path should end with a trailing slash, null means "do not care" (for trailing splat params) */ constructor(re: RegExp, params: TParamsOptions & Record<string, MatcherPatternPathDynamic_ParamOptions<any, any>>, pathParts: Array<string | number | Array<string | number>>, trailingSlash?: boolean | null); match(path: string): Simplify<ExtractParamTypeFromOptions<TParamsOptions>>; build(params: Simplify<ExtractLocationParamTypeFromOptions<TParamsOptions>>): string; } /** * Handles the `hash` part of a URL. It can transform a hash string into an * object of params and vice versa. */ interface MatcherPatternHash<TParams extends MatcherParamsFormatted = MatcherParamsFormatted> extends MatcherPattern<string, TParams> {} /** * Generic object of params that can be passed to a matcher. */ type MatcherParamsFormatted = Record<string, unknown>; /** * Empty object in TS. */ type EmptyParams = Record<PropertyKey, never>; /** * Possible values for query params in a matcher. */ type MatcherQueryParamsValue = string | null | undefined | Array<string | null>; type MatcherQueryParams = Record<string, MatcherQueryParamsValue>; //#endregion //#region src/location.d.ts /** * Location object returned by {@link `parseURL`}. * @internal */ interface LocationNormalized { path: string; fullPath: string; hash: string; query: LocationQuery; } /** * Initial route location where the router is. Can be used in navigation guards * to differentiate the initial navigation. * * @example * ```js * import { START_LOCATION } from 'vue-router' * * router.beforeEach((to, from) => { * if (from === START_LOCATION) { * // initial navigation * } * }) * ``` */ declare const START_LOCATION_NORMALIZED: RouteLocationNormalizedLoaded; //#endregion //#region src/experimental/route-resolver/resolver-abstract.d.ts /** * Allow