fix(router-core): preserve parsed location URL access under sharing

Author: Sheraff

docs/router/api/router/ParsedLocationType.md

@@ -15,11 +15,11 @@ interface ParsedLocation {
   hash: string
   maskedLocation?: ParsedLocation
   unmaskOnReload?: boolean
-  url: URL
+  getUrl: () => URL
   origin: string
 }
 ```
 
 > [!NOTE]
-> The `url` property of a `ParsedLocation` is a getter, and the `URL` may be computed
-> on demand. In hot loops, relying on this property may have a negative performance impact.
+> `getUrl()` returns a memoized `URL` that is created on demand. In hot loops,
+> repeatedly calling this method may have a negative performance impact.

packages/router-core/src/location.ts

@@ -53,8 +53,8 @@ export interface ParsedLocation<TSearchObj extends AnySchema = {}> {
    */
   origin: string
   /**
-   * A `URL` object representation of the location. This object is created lazily,
-   * so reading this property is not free.
+   * Returns a memoized `URL` object representation of the location.
+   * The `URL` is created lazily, so calling this method is not free.
    */
-  url: URL
+  getUrl: () => URL
 }

packages/router-core/src/router.ts

@@ -1278,7 +1278,6 @@ export class RouterCore<
         const searchStr = this.options.stringifySearch(parsedSearch)
 
         return initializeParsedLocation({
-          __proto__: parsedLocationPrototype,
           href: pathname + searchStr + hash,
           publicHref: href,
           pathname: decodePath(pathname).path,
@@ -1291,7 +1290,7 @@ export class RouterCore<
           ) as any,
           hash: decodePath(hash.slice(1)).path,
           state: replaceEqualDeep(previousLocation?.state, state),
-        } as ParsedLocationWithoutUrl<FullSearchSchema<TRouteTree>>)
+        })
       }
 
       // Before we do any processing, we need to allow rewrites to modify the URL
@@ -1309,7 +1308,6 @@ export class RouterCore<
       const fullPath = url.href.replace(url.origin, '')
 
       return initializeParsedLocation({
-        __proto__: parsedLocationPrototype,
         href: fullPath,
         publicHref: href,
         pathname: decodePath(url.pathname).path,
@@ -2005,7 +2003,6 @@ export class RouterCore<
 
       return initializeParsedLocation(
         {
-          __proto__: parsedLocationPrototype,
           publicHref,
           href,
           pathname: nextPathname,
@@ -2958,36 +2955,33 @@ function comparePaths(a: string, b: string) {
   return normalize(a) === normalize(b)
 }
 
-type ParsedLocationWithoutUrl<TSearchObj extends AnySchema = {}> = Omit<
+type ParsedLocationWithoutGetUrl<TSearchObj extends AnySchema = {}> = Omit<
   ParsedLocation<TSearchObj>,
-  'url'
-> & { __proto__: typeof parsedLocationPrototype }
+  'getUrl'
+>
 
 const parsedLocationUrls = new WeakMap<ParsedLocation<any>, URL>()
 
-function getParsedLocationUrl(location: ParsedLocation<any>) {
-  let url = parsedLocationUrls.get(location)
+function getParsedLocationUrl(this: ParsedLocation<any>) {
+  let url = parsedLocationUrls.get(this)
 
   if (!url) {
-    url = new URL(location.publicHref, location.origin)
-    parsedLocationUrls.set(location, url)
+    url = new URL(this.publicHref, this.origin)
+    parsedLocationUrls.set(this, url)
   }
 
   return url
 }
 
-const parsedLocationPrototype = {
-  get url() {
-    return getParsedLocationUrl(this as ParsedLocation<any>)
-  },
-}
-
 function initializeParsedLocation<TSearchObj extends AnySchema = {}>(
-  location: ParsedLocationWithoutUrl<TSearchObj>,
+  location: ParsedLocationWithoutGetUrl<TSearchObj>,
   url?: URL | null,
 ): ParsedLocation<TSearchObj> {
-  if (url) parsedLocationUrls.set(location as any, url)
-  return location as any
+  const parsedLocation = location as ParsedLocation<TSearchObj>
+  parsedLocation.getUrl =
+    getParsedLocationUrl as ParsedLocation<TSearchObj>['getUrl']
+  if (url) parsedLocationUrls.set(parsedLocation as any, url)
+  return parsedLocation
 }
 
 /**

packages/router-core/tests/build-location.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test, vi } from 'vitest'
 import { createMemoryHistory } from '@tanstack/history'
 import { BaseRootRoute, BaseRoute } from '../src'
+import { replaceEqualDeep } from '../src/utils'
 import { createTestRouter } from './routerTestUtils'
 
 describe('buildLocation - params function receives parsed params', () => {
@@ -1207,6 +1208,7 @@ describe('buildLocation - location output structure', () => {
     // Verify all expected properties exist
     expect(location).toEqual({
       external: false,
+      getUrl: expect.any(Function),
       hash: 'section',
       href: '/posts?page=1#section',
       origin: 'http://localhost:3000',
@@ -1248,7 +1250,7 @@ describe('buildLocation - location output structure', () => {
     expect(location.href).toBe('/posts')
   })
 
-  test('location should expose a memoized lazy url', async () => {
+  test('location should expose a memoized lazy getUrl method', async () => {
     const rootRoute = new BaseRootRoute({})
     const postsRoute = new BaseRoute({
       getParentRoute: () => rootRoute,
@@ -1270,14 +1272,14 @@ describe('buildLocation - location output structure', () => {
       hash: 'section',
     })
 
-    expect(Object.keys(location)).not.toContain('url')
-    expect(location.url).toBe(location.url)
-    expect(location.url.pathname).toBe('/posts')
-    expect(location.url.search).toBe('?page=1')
-    expect(location.url.hash).toBe('#section')
+    expect(location.getUrl).toBeDefined()
+    expect(location.getUrl()).toBe(location.getUrl())
+    expect(location.getUrl().pathname).toBe('/posts')
+    expect(location.getUrl().search).toBe('?page=1')
+    expect(location.getUrl().hash).toBe('#section')
   })
 
-  test('router state location should expose url after parsing history', async () => {
+  test('router state location should expose getUrl after parsing history', async () => {
     const rootRoute = new BaseRootRoute({})
     const postsRoute = new BaseRoute({
       getParentRoute: () => rootRoute,
@@ -1295,9 +1297,44 @@ describe('buildLocation - location output structure', () => {
 
     await router.load()
 
-    expect(router.state.location.url.pathname).toBe('/posts')
-    expect(router.state.location.url.search).toBe('?page=1')
-    expect(router.state.location.url.hash).toBe('#section')
+    expect(router.state.location.getUrl().pathname).toBe('/posts')
+    expect(router.state.location.getUrl().search).toBe('?page=1')
+    expect(router.state.location.getUrl().hash).toBe('#section')
+  })
+
+  test('replaceEqualDeep should preserve getUrl on structurally shared locations', async () => {
+    const rootRoute = new BaseRootRoute({})
+    const postsRoute = new BaseRoute({
+      getParentRoute: () => rootRoute,
+      path: '/posts',
+    })
+
+    const routeTree = rootRoute.addChildren([postsRoute])
+
+    const router = createTestRouter({
+      routeTree,
+      history: createMemoryHistory({
+        initialEntries: ['/posts?page=1#section'],
+      }),
+    })
+
+    await router.load()
+
+    const prev = router.state.location
+    const next = router.buildLocation({
+      to: '/posts',
+      search: { page: 2 },
+      hash: 'section',
+    })
+
+    const shared = replaceEqualDeep(prev, next)
+
+    expect(shared).not.toBe(prev)
+    expect(shared.getUrl).toBe(prev.getUrl)
+    expect(shared.search).not.toBe(prev.search)
+    expect(shared.getUrl().pathname).toBe('/posts')
+    expect(shared.getUrl().search).toBe('?page=2')
+    expect(shared.getUrl().hash).toBe('#section')
   })
 })
 

packages/router-core/tests/mask.test.ts

@@ -90,8 +90,8 @@ describe('buildLocation - route masks', () => {
     expect(location.maskedLocation).toBeDefined()
     expect(location.maskedLocation!.pathname).toBe('/photos/123')
     expect(location.pathname).toBe('/photos/123/modal')
-    expect(location.maskedLocation!.url.pathname).toBe('/photos/123')
-    expect(location.url.pathname).toBe('/photos/123/modal')
+    expect(location.maskedLocation!.getUrl().pathname).toBe('/photos/123')
+    expect(location.getUrl().pathname).toBe('/photos/123/modal')
   })
 
   test('should set params to {} when maskParams is false', () => {

packages/router-core/tests/rewrite.test.ts

@@ -53,10 +53,12 @@ describe('rewrite origin behavior', () => {
     expect(router.state.location.pathname).toBe('/about')
     expect(router.state.location.href).toBe('/about?lang=en#team')
     expect(router.state.location.publicHref).toBe('/docs/about?lang=en#team')
-    expect(router.state.location.url.href).toBe(
+    expect(router.state.location.getUrl().href).toBe(
       'https://public.example.com/docs/about?lang=en#team',
     )
-    expect(router.state.location.url.origin).toBe('https://public.example.com')
+    expect(router.state.location.getUrl().origin).toBe(
+      'https://public.example.com',
+    )
   })
 
   test('buildLocation exposes the current origin to output rewrites', async () => {
@@ -91,10 +93,10 @@ describe('rewrite origin behavior', () => {
       'https://public.example.com/docs/about?lang=en#team',
     )
     expect(location.external).toBe(true)
-    expect(location.url.href).toBe(
+    expect(location.getUrl().href).toBe(
       'https://public.example.com/docs/about?lang=en#team',
     )
-    expect(location.url.origin).toBe('https://public.example.com')
+    expect(location.getUrl().origin).toBe('https://public.example.com')
   })
 
   test('buildAndCommitLocation uses origin-aware rewrites when href is provided', async () => {
@@ -126,7 +128,7 @@ describe('rewrite origin behavior', () => {
     expect(router.state.location.pathname).toBe('/about')
     expect(router.state.location.href).toBe('/about?lang=en#team')
     expect(router.state.location.publicHref).toBe('/docs/about?lang=en#team')
-    expect(router.state.location.url.href).toBe(
+    expect(router.state.location.getUrl().href).toBe(
       'https://public.example.com/docs/about?lang=en#team',
     )
   })