@xeito/router/dist/index.d.ts

Router for Xeito | Framework for building web applications

import { XeitoPlugin, XeitoComponent } from '@xeito/core';
import { ReadStore, WriteStore } from '@xeito/store';
import { Update, Location } from 'history';
export { Listener, Location, Update } from 'history';
import * as uhtml from 'uhtml';

interface Route {
    path: string;
    component: any;
    children?: Route[];
    redirectTo?: string;
    guards?: any[];
}

interface RouterOptions {
    routes: Route[];
    strategy?: 'hash' | 'browser' | 'memory';
}

/**
 * Parameters of a route.
 * eg: /user/:id/:name -> { id: '1', name: 'John' }
 */
interface RouteParams {
    [key: string]: string;
}

interface XeitoRouter {
    routeUpdate: ReadStore<Update>;
    routeParams: ReadStore<RouteParams>;
    location: ReadStore<Location>;
    push: (path: string, state?: any) => void;
    replace: (path: string, state?: any) => void;
    go: (n: number) => void;
    back: () => void;
    forward: () => void;
    createHref: (path: string) => string;
}

interface RouterInternal {
    routeUpdate: WriteStore<any>;
    routes: Route[];
    params: WriteStore<any>;
    previousRoute: WriteStore<Route>;
    pathAccumulator: WriteStore<string>;
    history: any;
}

declare class XeitoRouterPlugin extends XeitoPlugin {
    private history;
    private $routeUpdate;
    private $location;
    private $params;
    private routes;
    /**
     * Install the router plugin
     * This method is called by the Xeito framework when the plugin is registered
     * @param options The router options
     */
    install(options: RouterOptions): void;
    /**
     * Create the history instance based on the strategy supplied by the user
     * @param strategy The strategy to use
     */
    initializeHistory(strategy: 'hash' | 'browser' | 'memory'): void;
    /**
     * Return the router instance
     * This is exposed to the user and can be used to navigate between routes
     * It can be used in the components using the '@Global' decorator
     * eg: @Global() router: XeitoRouter;
     * @returns The router instance
     */
    getRouterInstance(): XeitoRouter;
    /**
     * Router internal instance used in the router-slot component to render the active route
     * This is not exposed to the user and is only used internally
     * @returns The router internal instance
     */
    getRouterInternalInstance(): RouterInternal;
    /**
     * Register the components for the routes as global components
     * This is done to allow components declared in the routes to use the '@Global' decorator
     * @param routes List of routes
     */
    registerRouteComponentsAsGlobal(routes: Route[]): void;
    /**
     * Moves the root route to the end of the array to ensure that it is always the last route to be matched
     * Prevents infinite loops when the root route is matched
     * @param routes List of routes
     * @returns routes with the root route at the end of the array
     */
    formatRoutes(routes: Route[]): Route[];
    isRootRoute(route: Route): boolean;
}

declare class RouterSlot extends XeitoComponent {
    router: XeitoRouter;
    routerInternal: RouterInternal;
    component: XeitoComponent;
    historySubscription: any;
    onWillMount(): void;
    handleRouteUpdate(): Promise<void>;
    handleRoute(route: Route | null): void;
    onUnmount(): void;
    render(): uhtml.Hole;
}

declare class RouterLink extends XeitoComponent {
    router: XeitoRouter;
    to: string;
    state: Record<any, any>;
    handleClick(event: Event): void;
    render(): uhtml.Hole;
}

/**
 * A guard is a function that can be run before a route is rendered.
 * It can be used to check if a user is logged in, for example.
 * If the guard returns false, the route will not be rendered.
 * If it returns a string, the user will be redirected to that path.
 * If it returns a promise, the route will wait for the promise to resolve
 * before deciding what to do.
 */
interface RouterGuard {
    (path: string): boolean | string | Promise<boolean | string>;
}

export { Route, RouteParams, RouterGuard, RouterLink, RouterOptions, RouterSlot, XeitoRouter, XeitoRouterPlugin };