vue-router/dist/vue-router.d.ts

## Status: Alpha

import { App } from 'vue';
import { ComponentOptions } from 'vue';
import { ComponentPublicInstance } from 'vue';
import { ComputedRef } from 'vue';
import { Ref } from 'vue';

/**
 * Creates a 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.
 * @param base - Base applied to all urls, defaults to '/'
 * @returns a history object that can be passed to the router constructor
 */
export declare function createMemoryHistory(base?: string): RouterHistory;

export declare function createRouter({ history, routes, scrollBehavior, parseQuery, stringifyQuery, }: RouterOptions): Router;

export declare function createWebHashHistory(base?: string): RouterHistory;

export declare function createWebHistory(base?: string): RouterHistory;

/**
 * Internal type to define an ErrorHandler
 * @internal
 */
export declare type ErrorHandler = (error: any) => any;

declare interface HistoryLocation {
    fullPath: string;
    state?: HistoryState;
}

declare type HistoryLocationNormalized = Pick<HistoryLocation, 'fullPath'>;

declare interface HistoryState {
    [x: number]: HistoryStateValue;
    [x: string]: HistoryStateValue;
}

declare interface HistoryStateArray extends Array<HistoryStateValue> {
}

declare type HistoryStateValue = string | number | boolean | null | HistoryState | HistoryStateArray;

declare type Lazy<T> = () => Promise<T>;

export declare const Link: new () => import("vue").ComponentPublicInstance<{
    to: RouteLocation;
} & {}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement>, unknown, {}, {}, import("vue").VNodeProps & {
    to: RouteLocation;
} & {}>;

declare interface LinkProps {
    to: RouteLocation;
    replace?: boolean;
}

declare interface LocationAsName {
    name: string;
    params?: RouteParamsRaw;
}

declare interface LocationAsPath {
    path: string;
}

declare interface LocationAsRelative {
    params?: RouteParamsRaw;
}

/**
 * Normalized query object that appears in {@link RouteLocationNormalized}
 *
 * @public
 */
export declare 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 RouteLocation}
 *
 * @public
 */
export declare type LocationQueryRaw = Record<string | number, LocationQueryValueRaw | LocationQueryValueRaw[]>;

/**
 * Possible values in normalized {@link LocationQuery}
 *
 * @internal
 */
export declare type LocationQueryValue = string | null;

/**
 * Possible values when definining a query
 *
 * @internal
 */
declare type LocationQueryValueRaw = LocationQueryValue | number | undefined;

declare interface NavigationCallback {
    (to: HistoryLocationNormalized, from: HistoryLocationNormalized, information: NavigationInformation): void;
}

declare enum NavigationDirection {
    back = "back",
    forward = "forward",
    unknown = ""
}

export declare interface NavigationGuard<V = ComponentPublicInstance> {
    (this: V, to: RouteLocationNormalized, from: RouteLocationNormalized, next: NavigationGuardCallback): any;
}

declare interface NavigationGuardCallback {
    (): void;
    (location: RouteLocation): void;
    (valid: boolean): void;
    (cb: (vm: any) => void): void;
}

declare interface NavigationInformation {
    type: NavigationType;
    direction: NavigationDirection;
    distance: number;
}

declare enum NavigationType {
    pop = "pop",
    push = "push"
}

export declare function onBeforeRouteLeave(leaveGuard: NavigationGuard): void;

/**
 * Transforms a queryString into a {@link LocationQuery} object. Accept both, a
 * version with the leading `?` and without Should work as URLSearchParams
 *
 * @param search - search string to parse
 * @returns a query object
 */
export declare function parseQuery(search: string): LocationQuery;

declare interface PathParserOptions {
    /**
     * Makes the RegExp case sensitive. Defaults to false
     */
    sensitive?: boolean;
    /**
     * Should we allow a trailing slash. Defaults to true
     */
    strict?: boolean;
    /**
     * Should the RegExp match from the beginning by prepending a ^. Defaults to true
     */
    start?: boolean;
    /**
     * Should the RegExp match until the end by appending a $. Defaults to true
     */
    end?: boolean;
}

export declare interface PostNavigationGuard {
    (to: RouteLocationNormalized, from: RouteLocationNormalized): any;
}

declare type RawHistoryLocation = HistoryLocation | string;

declare type RawRouteComponent = RouteComponent | Lazy<RouteComponent>;

declare type RouteComponent = ComponentOptions & RouteComponentInterface;

declare interface RouteComponentInterface {
    beforeRouteEnter?: NavigationGuard<undefined>;
    /**
     * Guard called when the router is navigating away from the current route
     * that is rendering this component.
     * @param to - RouteLocation we are navigating to
     * @param from - RouteLocation we are navigating from
     * @param next - function to validate, cancel or modify (by redirectering) the navigation
     */
    beforeRouteLeave?: NavigationGuard;
    /**
     * Guard called whenever the route that renders this component has changed but
     * it is reused for the new route. This allows you to guard for changes in params,
     * the query or the hash.
     * @param to - RouteLocation we are navigating to
     * @param from - RouteLocation we are navigating from
     * @param next - function to validate, cancel or modify (by redirectering) the navigation
     */
    beforeRouteUpdate?: NavigationGuard;
}

export declare type RouteLocation = string | (RouteQueryAndHash & LocationAsPath & RouteLocationOptions) | (RouteQueryAndHash & LocationAsName & RouteLocationOptions) | (RouteQueryAndHash & LocationAsRelative & RouteLocationOptions);

export declare interface RouteLocationMatched extends RouteRecordNormalized {
    components: Record<string, RouteComponent>;
}

export declare interface RouteLocationNormalized {
    path: string;
    fullPath: string;
    query: LocationQuery;
    hash: string;
    name: string | null | undefined;
    params: RouteParams;
    matched: RouteRecordNormalized[];
    redirectedFrom: RouteLocationNormalized | undefined;
    meta: Record<string | number | symbol, any>;
}

export declare interface RouteLocationNormalizedResolved {
    path: string;
    fullPath: string;
    query: LocationQuery;
    hash: string;
    name: string | null | undefined;
    params: RouteParams;
    matched: RouteLocationMatched[];
    redirectedFrom: RouteLocationNormalized | undefined;
    meta: Record<string | number | symbol, any>;
}

export declare 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
     */
    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 TODO: link mdn
     */
    state?: HistoryState;
}

export declare type RouteParams = Record<string, RouteParamValue | RouteParamValue[]>;

declare type RouteParamsRaw = RouteParams;

declare type RouteParamValue = string;

declare interface RouteQueryAndHash {
    query?: LocationQueryRaw;
    hash?: string;
}

export declare interface Router {
    history: RouterHistory;
    currentRoute: Ref<RouteLocationNormalizedResolved>;
    addRoute(parentName: string, route: RouteRecord): () => void;
    addRoute(route: RouteRecord): () => void;
    removeRoute(name: string): void;
    getRoutes(): RouteRecordNormalized[];
    resolve(to: RouteLocation): RouteLocationNormalized;
    createHref(to: RouteLocationNormalized): string;
    push(to: RouteLocation): Promise<RouteLocationNormalizedResolved>;
    replace(to: RouteLocation): Promise<RouteLocationNormalizedResolved>;
    beforeEach(guard: NavigationGuard<undefined>): () => void;
    afterEach(guard: PostNavigationGuard): () => void;
    onError(handler: ErrorHandler): () => void;
    isReady(): Promise<void>;
    install(app: App): void;
}

export declare type RouteRecord = RouteRecordSingleView | RouteRecordMultipleViews | RouteRecordRedirect;

declare interface RouteRecordCommon {
    path: string;
    alias?: string | string[];
    name?: string;
    props?: boolean | Record<string, any> | ((to: RouteLocationNormalized) => Record<string, any>);
    beforeEnter?: NavigationGuard<undefined> | NavigationGuard<undefined>[];
    meta?: Record<string | number | symbol, any>;
    options?: PathParserOptions;
}

declare interface RouteRecordMultipleViews extends RouteRecordCommon {
    components: Record<string, RawRouteComponent>;
    children?: RouteRecord[];
}

export declare interface RouteRecordNormalized {
    path: RouteRecordMultipleViews['path'];
    name: RouteRecordMultipleViews['name'];
    components: RouteRecordMultipleViews['components'];
    children: Exclude<RouteRecordMultipleViews['children'], void>;
    meta: Exclude<RouteRecordMultipleViews['meta'], void>;
    props: Exclude<RouteRecordCommon['props'], void>;
    beforeEnter: RouteRecordMultipleViews['beforeEnter'];
    leaveGuards: NavigationGuard<undefined>[];
    instances: Record<string, {} | undefined | null>;
    aliasOf: RouteRecordNormalized | undefined;
}

declare interface RouteRecordRedirect extends RouteRecordCommon {
    redirect: RouteRecordRedirectOption;
    beforeEnter?: never;
    component?: never;
    components?: never;
}

declare type RouteRecordRedirectOption = RouteLocation | ((to: RouteLocationNormalized) => RouteLocation);

declare interface RouteRecordSingleView extends RouteRecordCommon {
    component: RawRouteComponent;
    children?: RouteRecord[];
}

export declare interface RouterHistory {
    readonly base: string;
    readonly location: HistoryLocationNormalized;
    readonly state: HistoryState;
    push(to: RawHistoryLocation, data?: HistoryState): void;
    replace(to: RawHistoryLocation, data?: HistoryState): void;
    back(triggerListeners?: boolean): void;
    forward(triggerListeners?: boolean): void;
    go(distance: number, triggerListeners?: boolean): void;
    listen(callback: NavigationCallback): () => void;
    destroy(): void;
}

export declare interface RouterOptions {
    history: RouterHistory;
    routes: RouteRecord[];
    scrollBehavior?: ScrollBehavior;
    parseQuery?: typeof parseQuery;
    stringifyQuery?: typeof stringifyQuery;
}

declare interface ScrollBehavior {
    (to: RouteLocationNormalized, from: RouteLocationNormalizedResolved, savedPosition: ScrollToPosition | null): ScrollPosition | Promise<ScrollPosition>;
}

declare type ScrollPosition = ScrollToPosition | ScrollToElement;

declare interface ScrollToElement {
    selector: string;
    offset?: ScrollToPosition;
}

declare type ScrollToPosition = {
    x: number;
    y: number;
};

export declare const START_LOCATION: RouteLocationNormalizedResolved;

/**
 * Stringifies a {@link LocationQueryRaw} object. Like `URLSearchParams`, it
 * doesn't prepend a `?`
 *
 * @param query - query object to stringify
 * @returns string verion of the query without the leading `?`
 */
export declare function stringifyQuery(query: LocationQueryRaw): string;

export declare function useLink(props: UseLinkOptions): {
    route: import("vue").ComputedRef<RouteLocationNormalized>;
    href: import("vue").ComputedRef<string>;
    isActive: import("vue").ComputedRef<boolean>;
    isExactActive: import("vue").ComputedRef<boolean>;
    navigate: (e?: MouseEvent) => void;
};

declare type UseLinkOptions = VueUseOptions<LinkProps>;

export declare function useRoute(): import("./types").RouteLocationNormalizedResolved;

export declare function useRouter(): import("./router").Router;

export declare function useView(options: UseViewOptions): (attrs: {
    [key: string]: unknown;
}) => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement> | null;

declare type UseViewOptions = VueUseOptions<ViewProps>;

export declare const View: new () => ComponentPublicInstance<{
    name: string;
} & {}, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement> | null, unknown, {}, {}, import("vue").VNodeProps & {} & {
    name?: string | undefined;
}>;

declare interface ViewProps {
    route: RouteLocationNormalizedResolved;
    name: string;
}

declare type VueUseOptions<T> = {
    [k in keyof T]: Ref<T[k]> | T[k] | ComputedRef<T[k]>;
};

export { }