@tanstack/router-core 1.132.0-alpha.2 → 1.132.0-alpha.20

package/dist/esm/router.d.ts

@@ -1,17 +1,20 @@
 import { Store } from '@tanstack/store';
+import { loadRouteChunk } from './load-matches.js';
 import { ParsePathnameCache } from './path.js';
 import { SearchParser, SearchSerializer } from './searchParams.js';
 import { AnyRedirect, ResolvedRedirect } from './redirect.js';
 import { HistoryLocation, HistoryState, ParsedHistoryState, RouterHistory } from '@tanstack/history';
-import { Awaitable, ControlledPromise, NoInfer, NonNullableUpdater, PickAsRequired, Updater } from './utils.js';
+import { Awaitable, Constrain, ControlledPromise, NoInfer, NonNullableUpdater, PickAsRequired, Updater } from './utils.js';
 import { ParsedLocation } from './location.js';
 import { AnyContext, AnyRoute, AnyRouteWithContext, MakeRemountDepsOptionsUnion, RouteMask } from './route.js';
 import { FullSearchSchema, RouteById, RoutePaths, RoutesById, RoutesByPath } from './routeInfo.js';
-import { AnyRouteMatch, MakeRouteMatch, MakeRouteMatchUnion, MatchRouteOptions } from './Matches.js';
+import { AnyRouteMatch, MakeRouteMatchUnion, MatchRouteOptions } from './Matches.js';
 import { BuildLocationFn, CommitLocationOptions, NavigateFn } from './RouterProvider.js';
 import { Manifest } from './manifest.js';
 import { AnySchema } from './validators.js';
 import { NavigateOptions, ResolveRelativePath, ToOptions } from './link.js';
+import { AnySerializationAdapter, ValidateSerializableInput } from './ssr/serializer/transformer.js';
+import { AnyRouterConfig } from './config.js';
 export type ControllablePromise<T = any> = Promise<T> & {
     resolve: (value: T) => void;
     reject: (value?: any) => void;
@@ -19,6 +22,8 @@ export type ControllablePromise<T = any> = Promise<T> & {
 export type InjectedHtmlEntry = Promise<string>;
 export interface DefaultRegister {
     router: AnyRouter;
+    config: AnyRouterConfig;
+    ssr: SSROption;
 }
 export interface Register extends DefaultRegister {
 }
@@ -28,7 +33,8 @@ export interface DefaultRouterOptionsExtensions {
 }
 export interface RouterOptionsExtensions extends DefaultRouterOptionsExtensions {
 }
-export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption extends TrailingSlashOption, TDefaultStructuralSharingOption extends boolean = false, TRouterHistory extends RouterHistory = RouterHistory, TDehydrated extends Record<string, any> = Record<string, any>> extends RouterOptionsExtensions {
+export type SSROption = boolean | 'data-only';
+export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption extends TrailingSlashOption, TDefaultStructuralSharingOption extends boolean = false, TRouterHistory extends RouterHistory = RouterHistory, TDehydrated = undefined> extends RouterOptionsExtensions {
     /**
      * The history object that will be used to manage the browser history.
      *
@@ -172,6 +178,18 @@ export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption
     /**
      * The basepath for then entire router. This is useful for mounting a router instance at a subpath.
      *
+     * @deprecated - use `rewrite.input` with the new `rewriteBasepath` utility instead:
+     * ```ts
+     * const router = createRouter({
+     *   routeTree,
+     *   rewrite: rewriteBasepath('/basepath')
+     *   // Or wrap existing rewrite functionality
+     *   rewrite: rewriteBasepath('/basepath', {
+     *     output: ({ url }) => {...},
+     *     input: ({ url }) => {...},
+     *   })
+     * })
+     * ```
      * @default '/'
      * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#basepath-property)
      */
@@ -195,7 +213,7 @@ export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption
      * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#dehydrate-method)
      * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/external-data-loading#critical-dehydrationhydration)
      */
-    dehydrate?: () => Awaitable<TDehydrated>;
+    dehydrate?: () => Constrain<TDehydrated, ValidateSerializableInput<Register, TDehydrated>>;
     /**
      * A function that will be called when the router is hydrated.
      *
@@ -261,7 +279,7 @@ export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption
      *
      * @default true
      */
-    defaultSsr?: boolean | 'data-only';
+    defaultSsr?: SSROption;
     search?: {
         /**
          * Configures how unknown search params (= not returned by any `validateSearch`) are treated.
@@ -290,7 +308,9 @@ export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption
      *
      * @default false
      */
-    scrollRestoration?: boolean;
+    scrollRestoration?: boolean | ((opts: {
+        location: ParsedLocation;
+    }) => boolean);
     /**
      * A function that will be called to get the key for the scroll restoration cache.
      *
@@ -319,7 +339,42 @@ export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption
      * @default false
      */
     disableGlobalCatchBoundary?: boolean;
+    serializationAdapters?: ReadonlyArray<AnySerializationAdapter>;
+    /**
+     * Configures how the router will rewrite the location between the actual href and the internal href of the router.
+     *
+     * @default undefined
+     * @description You can provide a custom rewrite pair (in/out) or use the utilities like `rewriteBasepath` as a convenience for common use cases, or even do both!
+     * This is useful for basepath rewriting, shifting data from the origin to the path (for things like )
+     */
+    rewrite?: LocationRewrite;
+    origin?: string;
 }
+export type LocationRewrite = {
+    /**
+     * A function that will be called to rewrite the URL before it is interpreted by the router from the history instance.
+     * Utilities like `rewriteBasepath` are provided as a convenience for common use cases.
+     *
+     * @default undefined
+     */
+    input?: LocationRewriteFunction;
+    /**
+     * A function that will be called to rewrite the URL before it is committed to the actual history instance from the router.
+     * Utilities like `rewriteBasepath` are provided as a convenience for common use cases.
+     *
+     * @default undefined
+     */
+    output?: LocationRewriteFunction;
+};
+/**
+ * A function that will be called to rewrite the URL.
+ *
+ * @param url The URL to rewrite.
+ * @returns The rewritten URL (as a URL instance or full href string) or undefined if no rewrite is needed.
+ */
+export type LocationRewriteFunction = ({ url, }: {
+    url: URL;
+}) => undefined | string | URL;
 export interface RouterState<in out TRouteTree extends AnyRoute = AnyRoute, in out TRouteMatch = MakeRouteMatchUnion> {
     status: 'pending' | 'idle';
     loadedAt: number;
@@ -408,7 +463,7 @@ export type InvalidateFn<TRouter extends AnyRouter> = (opts?: {
     sync?: boolean;
     forcePending?: boolean;
 }) => Promise<void>;
-export type ParseLocationFn<TRouteTree extends AnyRoute> = (previousLocation?: ParsedLocation<FullSearchSchema<TRouteTree>>, locationToParse?: HistoryLocation) => ParsedLocation<FullSearchSchema<TRouteTree>>;
+export type ParseLocationFn<TRouteTree extends AnyRoute> = (locationToParse: HistoryLocation, previousLocation?: ParsedLocation<FullSearchSchema<TRouteTree>>) => ParsedLocation<FullSearchSchema<TRouteTree>>;
 export type GetMatchRoutesFn = (pathname: string, routePathname: string | undefined) => {
     matchedRoutes: Array<AnyRoute>;
     routeParams: Record<string, string>;
@@ -486,6 +541,8 @@ export declare class RouterCore<in out TRouteTree extends AnyRoute, in out TTrai
     __store: Store<RouterState<TRouteTree>>;
     options: PickAsRequired<RouterOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>, 'stringifySearch' | 'parseSearch' | 'context'>;
     history: TRouterHistory;
+    rewrite?: LocationRewrite;
+    origin?: string;
     latestLocation: ParsedLocation<FullSearchSchema<TRouteTree>>;
     basepath: string;
     routeTree: TRouteTree;
@@ -502,7 +559,8 @@ export declare class RouterCore<in out TRouteTree extends AnyRoute, in out TTrai
     isShell(): boolean;
     isPrerendering(): boolean;
     update: UpdateFn<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>;
-    get state(): RouterState<TRouteTree, import('./Matches.js').RouteMatch<any, any, any, any, any, any, any>>;
+    get state(): RouterState<TRouteTree>;
+    updateLatestLocation: () => void;
     buildRouteTree: () => void;
     subscribe: SubscribeFn;
     emit: EmitFn;
@@ -527,41 +585,17 @@ export declare class RouterCore<in out TRouteTree extends AnyRoute, in out TTrai
     startViewTransition: (fn: () => Promise<void>) => void;
     updateMatch: UpdateMatchFn;
     getMatch: GetMatchFn;
-    private triggerOnReady;
-    private resolvePreload;
-    private handleRedirectAndNotFound;
-    private shouldSkipLoader;
-    private handleSerialError;
-    private isBeforeLoadSsr;
-    private setupPendingTimeout;
-    private shouldExecuteBeforeLoad;
-    private executeBeforeLoad;
-    private handleBeforeLoad;
-    private executeHead;
-    private potentialPendingMinPromise;
-    private getLoaderContext;
-    private runLoader;
-    private loadRouteMatch;
-    loadMatches: (baseContext: {
-        location: ParsedLocation;
-        matches: Array<AnyRouteMatch>;
-        preload?: boolean;
-        onReady?: () => Promise<void>;
-        updateMatch?: UpdateMatchFn;
-        sync?: boolean;
-    }) => Promise<Array<MakeRouteMatch>>;
     invalidate: InvalidateFn<RouterCore<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>>;
     resolveRedirect: (redirect: AnyRedirect) => AnyRedirect;
     clearCache: ClearCacheFn<this>;
     clearExpiredCache: () => void;
-    loadRouteChunk: (route: AnyRoute) => Promise<void> | undefined;
+    loadRouteChunk: typeof loadRouteChunk;
     preloadRoute: PreloadRouteFn<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory>;
     matchRoute: MatchRouteFn<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory>;
     ssr?: {
         manifest: Manifest | undefined;
     };
     serverSsr?: ServerSsr;
-    private _handleNotFound;
     hasNotFoundMatch: () => boolean;
 }
 export declare class SearchParamError extends Error {
@@ -570,7 +604,6 @@ export declare class PathParamError extends Error {
 }
 export declare function lazyFn<T extends Record<string, (...args: Array<any>) => any>, TKey extends keyof T = 'default'>(fn: () => Promise<T>, key?: TKey): (...args: Parameters<T[TKey]>) => Promise<Awaited<ReturnType<T[TKey]>>>;
 export declare function getInitialRouterState(location: ParsedLocation): RouterState<any>;
-export declare const componentTypes: readonly ["component", "errorComponent", "pendingComponent", "notFoundComponent"];
 interface RouteLike {
     id: string;
     isRoot?: boolean;
@@ -592,10 +625,9 @@ export declare function processRouteTree<TRouteLike extends RouteLike>({ routeTr
     routeTree: TRouteLike;
     initRoute?: (route: TRouteLike, index: number) => void;
 }): ProcessRouteTreeResult<TRouteLike>;
-export declare function getMatchedRoutes<TRouteLike extends RouteLike>({ pathname, routePathname, basepath, caseSensitive, routesByPath, routesById, flatRoutes, parseCache, }: {
+export declare function getMatchedRoutes<TRouteLike extends RouteLike>({ pathname, routePathname, caseSensitive, routesByPath, routesById, flatRoutes, parseCache, }: {
     pathname: string;
     routePathname?: string;
-    basepath: string;
     caseSensitive?: boolean;
     routesByPath: Record<string, TRouteLike>;
     routesById: Record<string, TRouteLike>;