@tanstack/react-router 1.20.0 → 1.20.3-alpha.1

package/dist/esm/router.d.ts

@@ -1,240 +1,72 @@
-import * as React from 'react';
-import { HistoryState, RouterHistory } from '@tanstack/history';
-import { Store } from '@tanstack/react-store';
-import { AnySearchSchema, AnyRoute, AnyContext, RouteMask, NotFoundRouteComponent } from './route.js';
-import { FullSearchSchema, RouteById, RoutePaths, RoutesById, RoutesByPath } from './routeInfo.js';
-import { PickAsRequired, Updater, NonNullableUpdater, Timeout } from './utils.js';
-import { RouteComponent } from './route.js';
-import { AnyRouteMatch, MatchRouteOptions, RouteMatch } from './Matches.js';
-import { ParsedLocation } from './location.js';
-import { SearchSerializer, SearchParser } from './searchParams.js';
-import { BuildLocationFn, CommitLocationOptions, InjectedHtmlEntry, NavigateFn } from './RouterProvider.js';
-import { AnyRedirect, ResolvedRedirect } from './redirects.js';
-import { NotFoundError } from './not-found.js';
-import { NavigateOptions, ResolveRelativePath, ToOptions } from './link.js';
-import { NoInfer } from '@tanstack/react-store';
-import { DeferredPromiseState } from './defer.js';
-declare global {
-    interface Window {
-        __TSR_DEHYDRATED__?: {
-            data: string;
-        };
-        __TSR_ROUTER_CONTEXT__?: React.Context<Router<any>>;
+import { RouterCore, AnyRoute, CreateRouterFn, RouterConstructorOptions, TrailingSlashOption } from '@tanstack/router-core';
+import { RouterHistory } from '@tanstack/history';
+import { ErrorRouteComponent, NotFoundRouteComponent, RouteComponent } from './route.js';
+declare module '@tanstack/router-core' {
+    interface RouterOptionsExtensions {
+        /**
+         * The default `component` a route should use if no component is provided.
+         *
+         * @default Outlet
+         * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultcomponent-property)
+         */
+        defaultComponent?: RouteComponent;
+        /**
+         * The default `errorComponent` a route should use if no error component is provided.
+         *
+         * @default ErrorComponent
+         * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaulterrorcomponent-property)
+         * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#handling-errors-with-routeoptionserrorcomponent)
+         */
+        defaultErrorComponent?: ErrorRouteComponent;
+        /**
+         * The default `pendingComponent` a route should use if no pending component is provided.
+         *
+         * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpendingcomponent-property)
+         * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#showing-a-pending-component)
+         */
+        defaultPendingComponent?: RouteComponent;
+        /**
+         * The default `notFoundComponent` a route should use if no notFound component is provided.
+         *
+         * @default NotFound
+         * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultnotfoundcomponent-property)
+         * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/not-found-errors#default-router-wide-not-found-handling)
+         */
+        defaultNotFoundComponent?: NotFoundRouteComponent;
+        /**
+         * A component that will be used to wrap the entire router.
+         *
+         * This is useful for providing a context to the entire router.
+         *
+         * Only non-DOM-rendering components like providers should be used, anything else will cause a hydration error.
+         *
+         * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#wrap-property)
+         */
+        Wrap?: (props: {
+            children: any;
+        }) => React.JSX.Element;
+        /**
+         * A component that will be used to wrap the inner contents of the router.
+         *
+         * This is useful for providing a context to the inner contents of the router where you also need access to the router context and hooks.
+         *
+         * Only non-DOM-rendering components like providers should be used, anything else will cause a hydration error.
+         *
+         * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#innerwrap-property)
+         */
+        InnerWrap?: (props: {
+            children: any;
+        }) => React.JSX.Element;
+        /**
+         * The default `onCatch` handler for errors caught by the Router ErrorBoundary
+         *
+         * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultoncatch-property)
+         * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#handling-errors-with-routeoptionsoncatch)
+         */
+        defaultOnCatch?: (error: Error, errorInfo: React.ErrorInfo) => void;
     }
 }
-export interface Register {
+export declare const createRouter: CreateRouterFn;
+export declare class Router<in out TRouteTree extends AnyRoute, in out TTrailingSlashOption extends TrailingSlashOption = 'never', in out TDefaultStructuralSharingOption extends boolean = false, in out TRouterHistory extends RouterHistory = RouterHistory, in out TDehydrated extends Record<string, any> = Record<string, any>> extends RouterCore<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated> {
+    constructor(options: RouterConstructorOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>);
 }
-export type AnyRouter = Router<AnyRoute, any, any>;
-export type RegisteredRouter = Register extends {
-    router: infer TRouter extends AnyRouter;
-} ? TRouter : AnyRouter;
-export type HydrationCtx = {
-    router: DehydratedRouter;
-    payload: Record<string, any>;
-};
-export type RouterContextOptions<TRouteTree extends AnyRoute> = AnyContext extends TRouteTree['types']['routerContext'] ? {
-    context?: TRouteTree['types']['routerContext'];
-} : {
-    context: TRouteTree['types']['routerContext'];
-};
-export interface RouterOptions<TRouteTree extends AnyRoute, TDehydrated extends Record<string, any> = Record<string, any>, TSerializedError extends Record<string, any> = Record<string, any>> {
-    history?: RouterHistory;
-    stringifySearch?: SearchSerializer;
-    parseSearch?: SearchParser;
-    defaultPreload?: false | 'intent';
-    defaultPreloadDelay?: number;
-    defaultComponent?: RouteComponent;
-    defaultErrorComponent?: RouteComponent;
-    defaultPendingComponent?: RouteComponent;
-    defaultPendingMs?: number;
-    defaultPendingMinMs?: number;
-    defaultStaleTime?: number;
-    defaultPreloadStaleTime?: number;
-    defaultPreloadGcTime?: number;
-    notFoundMode?: 'root' | 'fuzzy';
-    defaultGcTime?: number;
-    caseSensitive?: boolean;
-    routeTree?: TRouteTree;
-    basepath?: string;
-    context?: TRouteTree['types']['routerContext'];
-    dehydrate?: () => TDehydrated;
-    hydrate?: (dehydrated: TDehydrated) => void;
-    routeMasks?: RouteMask<TRouteTree>[];
-    unmaskOnReload?: boolean;
-    Wrap?: (props: {
-        children: any;
-    }) => React.ReactNode;
-    InnerWrap?: (props: {
-        children: any;
-    }) => React.ReactNode;
-    /**
-     * @deprecated
-     * Use `notFoundComponent` instead.
-     * See https://tanstack.com/router/v1/docs/guide/not-found-errors#migrating-from-notfoundroute for more info.
-     */
-    notFoundRoute?: AnyRoute;
-    defaultNotFoundComponent?: NotFoundRouteComponent;
-    transformer?: RouterTransformer;
-    errorSerializer?: RouterErrorSerializer<TSerializedError>;
-}
-export interface RouterTransformer {
-    stringify: (obj: unknown) => string;
-    parse: (str: string) => unknown;
-}
-export interface RouterErrorSerializer<TSerializedError> {
-    serialize: (err: unknown) => TSerializedError;
-    deserialize: (err: TSerializedError) => unknown;
-}
-export interface RouterState<TRouteTree extends AnyRoute = AnyRoute> {
-    status: 'pending' | 'idle';
-    isLoading: boolean;
-    isTransitioning: boolean;
-    matches: RouteMatch<TRouteTree>[];
-    pendingMatches?: RouteMatch<TRouteTree>[];
-    cachedMatches: RouteMatch<TRouteTree>[];
-    location: ParsedLocation<FullSearchSchema<TRouteTree>>;
-    resolvedLocation: ParsedLocation<FullSearchSchema<TRouteTree>>;
-    lastUpdated: number;
-    statusCode: number;
-    redirect?: ResolvedRedirect;
-}
-export type ListenerFn<TEvent extends RouterEvent> = (event: TEvent) => void;
-export interface BuildNextOptions {
-    to?: string | number | null;
-    params?: true | Updater<unknown>;
-    search?: true | Updater<unknown>;
-    hash?: true | Updater<string>;
-    state?: true | NonNullableUpdater<HistoryState>;
-    mask?: {
-        to?: string | number | null;
-        params?: true | Updater<unknown>;
-        search?: true | Updater<unknown>;
-        hash?: true | Updater<string>;
-        state?: true | NonNullableUpdater<HistoryState>;
-        unmaskOnReload?: boolean;
-    };
-    from?: string;
-}
-export interface DehydratedRouterState {
-    dehydratedMatches: DehydratedRouteMatch[];
-}
-export type DehydratedRouteMatch = Pick<RouteMatch, 'id' | 'status' | 'updatedAt' | 'loaderData'>;
-export interface DehydratedRouter {
-    state: DehydratedRouterState;
-}
-export type RouterConstructorOptions<TRouteTree extends AnyRoute, TDehydrated extends Record<string, any>, TSerializedError extends Record<string, any>> = Omit<RouterOptions<TRouteTree, TDehydrated, TSerializedError>, 'context'> & RouterContextOptions<TRouteTree>;
-export declare const componentTypes: readonly ["component", "errorComponent", "pendingComponent", "notFoundComponent"];
-export type RouterEvents = {
-    onBeforeLoad: {
-        type: 'onBeforeLoad';
-        fromLocation: ParsedLocation;
-        toLocation: ParsedLocation;
-        pathChanged: boolean;
-    };
-    onLoad: {
-        type: 'onLoad';
-        fromLocation: ParsedLocation;
-        toLocation: ParsedLocation;
-        pathChanged: boolean;
-    };
-    onResolved: {
-        type: 'onResolved';
-        fromLocation: ParsedLocation;
-        toLocation: ParsedLocation;
-        pathChanged: boolean;
-    };
-};
-export type RouterEvent = RouterEvents[keyof RouterEvents];
-export type RouterListener<TRouterEvent extends RouterEvent> = {
-    eventType: TRouterEvent['type'];
-    fn: ListenerFn<TRouterEvent>;
-};
-export declare function createRouter<TRouteTree extends AnyRoute = AnyRoute, TDehydrated extends Record<string, any> = Record<string, any>, TSerializedError extends Record<string, any> = Record<string, any>>(options: RouterConstructorOptions<TRouteTree, TDehydrated, TSerializedError>): Router<TRouteTree, TDehydrated, TSerializedError>;
-export declare class Router<TRouteTree extends AnyRoute = AnyRoute, TDehydrated extends Record<string, any> = Record<string, any>, TSerializedError extends Record<string, any> = Record<string, any>> {
-    tempLocationKey: string | undefined;
-    resetNextScroll: boolean;
-    navigateTimeout: Timeout | null;
-    latestLoadPromise: Promise<void>;
-    subscribers: Set<RouterListener<RouterEvent>>;
-    injectedHtml: InjectedHtmlEntry[];
-    dehydratedData?: TDehydrated;
-    __store: Store<RouterState<TRouteTree>>;
-    options: PickAsRequired<Omit<RouterOptions<TRouteTree, TDehydrated, TSerializedError>, 'transformer'> & {
-        transformer: RouterTransformer;
-    }, 'stringifySearch' | 'parseSearch' | 'context'>;
-    history: RouterHistory;
-    latestLocation: ParsedLocation;
-    basepath: string;
-    routeTree: TRouteTree;
-    routesById: RoutesById<TRouteTree>;
-    routesByPath: RoutesByPath<TRouteTree>;
-    flatRoutes: AnyRoute[];
-    /**
-     * @deprecated Use the `createRouter` function instead
-     */
-    constructor(options: RouterConstructorOptions<TRouteTree, TDehydrated, TSerializedError>);
-    startReactTransition: (fn: () => void) => void;
-    update: (newOptions: RouterConstructorOptions<TRouteTree, TDehydrated, TSerializedError>) => void;
-    get state(): RouterState<TRouteTree>;
-    buildRouteTree: () => void;
-    subscribe: <TType extends keyof RouterEvents>(eventType: TType, fn: ListenerFn<RouterEvents[TType]>) => () => void;
-    emit: (routerEvent: RouterEvent) => void;
-    checkLatest: (promise: Promise<void>) => undefined | Promise<void>;
-    parseLocation: (previousLocation?: ParsedLocation) => ParsedLocation<FullSearchSchema<TRouteTree>>;
-    resolvePathWithBase: (from: string, path: string) => string;
-    get looseRoutesById(): Record<string, AnyRoute>;
-    matchRoutes: <TRouteTree_1 extends AnyRoute>(pathname: string, locationSearch: AnySearchSchema, opts?: {
-        preload?: boolean;
-        throwOnError?: boolean;
-        debug?: boolean;
-    }) => RouteMatch<TRouteTree_1, import("./routeInfo").ParseRoute<TRouteTree_1, TRouteTree_1>["id"], false>[];
-    cancelMatch: (id: string) => void;
-    cancelMatches: () => void;
-    buildLocation: BuildLocationFn<TRouteTree>;
-    commitLocation: ({ startTransition, ...next }: ParsedLocation & CommitLocationOptions) => Promise<void>;
-    buildAndCommitLocation: ({ replace, resetScroll, startTransition, ...rest }?: BuildNextOptions & CommitLocationOptions) => Promise<void>;
-    navigate: NavigateFn;
-    loadMatches: ({ checkLatest, location, matches, preload, }: {
-        checkLatest: () => Promise<void> | undefined;
-        location: ParsedLocation;
-        matches: AnyRouteMatch[];
-        preload?: boolean | undefined;
-    }) => Promise<RouteMatch[]>;
-    invalidate: () => void;
-    load: () => Promise<void>;
-    resolveRedirect: (err: AnyRedirect) => ResolvedRedirect;
-    cleanCache: () => void;
-    preloadRoute: <TFrom extends string | import("./routeInfo").ParseRoute<TRouteTree, TRouteTree>["fullPath"] = string, TTo extends string = "", TMaskFrom extends string | import("./routeInfo").ParseRoute<TRouteTree, TRouteTree>["fullPath"] = TFrom, TMaskTo extends string = "">(opts: NavigateOptions<TRouteTree, TFrom, TTo, TMaskFrom, TMaskTo>) => Promise<AnyRouteMatch[] | undefined>;
-    matchRoute: <TFrom extends RoutePaths<TRouteTree> = "/", TTo extends string = "", TResolved = ResolveRelativePath<TFrom, NoInfer<TTo>>>(location: ToOptions<TRouteTree, TFrom, TTo>, opts?: MatchRouteOptions) => false | RouteById<TRouteTree, TResolved>["types"]["allParams"];
-    injectHtml: (html: string | (() => Promise<string> | string)) => Promise<void>;
-    registeredDeferredsIds: Map<string, {}>;
-    registeredDeferreds: WeakMap<{}, DeferredPromiseState<any>>;
-    getDeferred: (uid: string) => DeferredPromiseState<any> | undefined;
-    /**
-     * @deprecated Please inject your own html using the `injectHtml` method
-     */
-    dehydrateData: <T>(key: any, getData: T | (() => T | Promise<T>)) => () => T | undefined;
-    /**
-     * @deprecated Please extract your own data from scripts injected using the `injectHtml` method
-     */
-    hydrateData: <T extends unknown = unknown>(key: any) => T | undefined;
-    dehydrate: () => DehydratedRouter;
-    hydrate: (__do_not_use_server_ctx?: string) => Promise<void>;
-    handleNotFound: (matches: AnyRouteMatch[], err: NotFoundError) => void;
-    hasNotFoundMatch: () => boolean;
-}
-export declare function lazyFn<T extends Record<string, (...args: any[]) => any>, TKey extends keyof T = 'default'>(fn: () => Promise<T>, key?: TKey): (...args: Parameters<T[TKey]>) => Promise<Awaited<ReturnType<T[TKey]>>>;
-export declare class SearchParamError extends Error {
-}
-export declare class PathParamError extends Error {
-}
-export declare function getInitialRouterState(location: ParsedLocation): RouterState<any>;
-export declare function defaultSerializeError(err: unknown): {
-    name: string;
-    message: string;
-    data?: undefined;
-} | {
-    data: unknown;
-    name?: undefined;
-    message?: undefined;
-};