@tanstack/router-core 1.132.0-alpha.4 → 1.132.0

package/dist/esm/router.d.ts

@@ -4,32 +4,38 @@ 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 { AnyContext, AnyRoute, AnyRouteWithContext, MakeRemountDepsOptionsUnion, RouteLike, RouteMask } from './route.js';
 import { FullSearchSchema, RouteById, RoutePaths, RoutesById, RoutesByPath } from './routeInfo.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';
 export type ControllablePromise<T = any> = Promise<T> & {
     resolve: (value: T) => void;
     reject: (value?: any) => void;
 };
 export type InjectedHtmlEntry = Promise<string>;
-export interface DefaultRegister {
-    router: AnyRouter;
+export interface Register {
 }
-export interface Register extends DefaultRegister {
-}
-export type RegisteredRouter = Register['router'];
+export type RegisteredRouter<TRegister = Register> = TRegister extends {
+    router: infer TRouter;
+} ? TRouter : AnyRouter;
+export type RegisteredConfigType<TRegister, TKey> = TRegister extends {
+    config: infer TConfig;
+} ? TConfig extends {
+    '~types': infer TTypes;
+} ? TKey extends keyof TTypes ? TTypes[TKey] : unknown : unknown : unknown;
 export type DefaultRemountDepsFn<TRouteTree extends AnyRoute> = (opts: MakeRemountDepsOptionsUnion<TRouteTree>) => any;
 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>, TTransformerConfig = 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.
      *
@@ -173,6 +179,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)
      */
@@ -188,6 +206,7 @@ export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption
      * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/router-context)
      */
     context?: InferRouterContext<TRouteTree>;
+    additionalContext?: any;
     /**
      * A function that will be called when the router is dehydrated.
      *
@@ -196,7 +215,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.
      *
@@ -262,7 +281,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.
@@ -322,8 +341,45 @@ export interface RouterOptions<TRouteTree extends AnyRoute, TTrailingSlashOption
      * @default false
      */
     disableGlobalCatchBoundary?: boolean;
-    serializationAdapters?: TTransformerConfig;
+    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;
+    ssr?: {
+        nonce?: 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;
@@ -403,16 +459,16 @@ export type RouterContextOptions<TRouteTree extends AnyRoute> = AnyContext exten
 } : {
     context: InferRouterContext<TRouteTree>;
 };
-export type RouterConstructorOptions<TRouteTree extends AnyRoute, TTrailingSlashOption extends TrailingSlashOption, TDefaultStructuralSharingOption extends boolean, TRouterHistory extends RouterHistory, TDehydrated extends Record<string, any>, TTransformerConfig> = Omit<RouterOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated, TTransformerConfig>, 'context'> & RouterContextOptions<TRouteTree>;
+export type RouterConstructorOptions<TRouteTree extends AnyRoute, TTrailingSlashOption extends TrailingSlashOption, TDefaultStructuralSharingOption extends boolean, TRouterHistory extends RouterHistory, TDehydrated extends Record<string, any>> = Omit<RouterOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>, 'context' | 'serializationAdapters' | 'defaultSsr'> & RouterContextOptions<TRouteTree>;
 export type PreloadRouteFn<TRouteTree extends AnyRoute, TTrailingSlashOption extends TrailingSlashOption, TDefaultStructuralSharingOption extends boolean, TRouterHistory extends RouterHistory> = <TFrom extends RoutePaths<TRouteTree> | string = string, TTo extends string | undefined = undefined, TMaskFrom extends RoutePaths<TRouteTree> | string = TFrom, TMaskTo extends string = ''>(opts: NavigateOptions<RouterCore<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory>, TFrom, TTo, TMaskFrom, TMaskTo>) => Promise<Array<AnyRouteMatch> | undefined>;
 export type MatchRouteFn<TRouteTree extends AnyRoute, TTrailingSlashOption extends TrailingSlashOption, TDefaultStructuralSharingOption extends boolean, TRouterHistory extends RouterHistory> = <TFrom extends RoutePaths<TRouteTree> = '/', TTo extends string | undefined = undefined, TResolved = ResolveRelativePath<TFrom, NoInfer<TTo>>>(location: ToOptions<RouterCore<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory>, TFrom, TTo>, opts?: MatchRouteOptions) => false | RouteById<TRouteTree, TResolved>['types']['allParams'];
-export type UpdateFn<TRouteTree extends AnyRoute, TTrailingSlashOption extends TrailingSlashOption, TDefaultStructuralSharingOption extends boolean, TRouterHistory extends RouterHistory, TDehydrated extends Record<string, any>, TTransformerConfig extends any> = (newOptions: RouterConstructorOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated, TTransformerConfig>) => void;
+export type UpdateFn<TRouteTree extends AnyRoute, TTrailingSlashOption extends TrailingSlashOption, TDefaultStructuralSharingOption extends boolean, TRouterHistory extends RouterHistory, TDehydrated extends Record<string, any>> = (newOptions: RouterConstructorOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>) => void;
 export type InvalidateFn<TRouter extends AnyRouter> = (opts?: {
     filter?: (d: MakeRouteMatchUnion<TRouter>) => boolean;
     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>;
@@ -449,8 +505,8 @@ export interface ServerSsr {
     onRenderFinished: (listener: () => void) => void;
     dehydrate: () => Promise<void>;
 }
-export type AnyRouterWithContext<TContext> = RouterCore<AnyRouteWithContext<TContext>, any, any, any, any, any>;
-export type AnyRouter = RouterCore<any, any, any, any, any, any>;
+export type AnyRouterWithContext<TContext> = RouterCore<AnyRouteWithContext<TContext>, any, any, any, any>;
+export type AnyRouter = RouterCore<any, any, any, any, any>;
 export interface ViewTransitionOptions {
     types: Array<string> | ((locationChangeInfo: {
         fromLocation?: ParsedLocation;
@@ -477,8 +533,8 @@ export declare function getLocationChangeInfo(routerState: {
     hrefChanged: boolean;
     hashChanged: boolean;
 };
-export type CreateRouterFn = <TRouteTree extends AnyRoute, TTrailingSlashOption extends TrailingSlashOption = 'never', TDefaultStructuralSharingOption extends boolean = false, TRouterHistory extends RouterHistory = RouterHistory, TDehydrated extends Record<string, any> = Record<string, any>, TTransformerConfig = any>(options: undefined extends number ? 'strictNullChecks must be enabled in tsconfig.json' : RouterConstructorOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated, TTransformerConfig>) => RouterCore<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated, TTransformerConfig>;
-export declare class RouterCore<in out TRouteTree extends AnyRoute, in out TTrailingSlashOption extends TrailingSlashOption, in out TDefaultStructuralSharingOption extends boolean, in out TRouterHistory extends RouterHistory = RouterHistory, in out TDehydrated extends Record<string, any> = Record<string, any>, in out TTransformerConfig = any> {
+export type CreateRouterFn = <TRouteTree extends AnyRoute, TTrailingSlashOption extends TrailingSlashOption = 'never', TDefaultStructuralSharingOption extends boolean = false, TRouterHistory extends RouterHistory = RouterHistory, TDehydrated extends Record<string, any> = Record<string, any>>(options: undefined extends number ? 'strictNullChecks must be enabled in tsconfig.json' : RouterConstructorOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>) => RouterCore<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>;
+export declare class RouterCore<in out TRouteTree extends AnyRoute, in out TTrailingSlashOption extends TrailingSlashOption, in out TDefaultStructuralSharingOption extends boolean, in out TRouterHistory extends RouterHistory = RouterHistory, in out TDehydrated extends Record<string, any> = Record<string, any>> {
     tempLocationKey: string | undefined;
     resetNextScroll: boolean;
     shouldViewTransition?: boolean | ViewTransitionOptions;
@@ -488,8 +544,10 @@ export declare class RouterCore<in out TRouteTree extends AnyRoute, in out TTrai
     isScrollRestoring: boolean;
     isScrollRestorationSetup: boolean;
     __store: Store<RouterState<TRouteTree>>;
-    options: PickAsRequired<RouterOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated, TTransformerConfig>, 'stringifySearch' | 'parseSearch' | 'context'>;
+    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;
@@ -501,12 +559,13 @@ export declare class RouterCore<in out TRouteTree extends AnyRoute, in out TTrai
     /**
      * @deprecated Use the `createRouter` function instead
      */
-    constructor(options: RouterConstructorOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated, TTransformerConfig>);
+    constructor(options: RouterConstructorOptions<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>);
     startTransition: StartTransitionFn;
     isShell(): boolean;
     isPrerendering(): boolean;
-    update: UpdateFn<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated, TTransformerConfig>;
+    update: UpdateFn<TRouteTree, TTrailingSlashOption, TDefaultStructuralSharingOption, TRouterHistory, TDehydrated>;
     get state(): RouterState<TRouteTree>;
+    updateLatestLocation: () => void;
     buildRouteTree: () => void;
     subscribe: SubscribeFn;
     emit: EmitFn;
@@ -550,31 +609,9 @@ 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>;
-interface RouteLike {
-    id: string;
-    isRoot?: boolean;
-    path?: string;
-    fullPath: string;
-    rank?: number;
-    parentRoute?: RouteLike;
-    children?: Array<RouteLike>;
-    options?: {
-        caseSensitive?: boolean;
-    };
-}
-export type ProcessRouteTreeResult<TRouteLike extends RouteLike> = {
-    routesById: Record<string, TRouteLike>;
-    routesByPath: Record<string, TRouteLike>;
-    flatRoutes: Array<TRouteLike>;
-};
-export declare function processRouteTree<TRouteLike extends RouteLike>({ routeTree, initRoute, }: {
-    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>;