fix(router-core): use safeStringify for loader dependency hash keys

[gonzoblasco]

Description

Replace JSON.stringify with safeStringify in loaderDepsHash computation to handle types that JSON.stringify cannot serialize (bigint, Set, Map, circular references, functions, symbols, etc.).

Problem

loaderDepsHash was hardcoded to JSON.stringify, which throws on bigint values and cannot handle Set, Map, circular references, or symbols. Users with custom search serializers that support these types would get runtime errors when using them in loaderDeps.

Previous attempt

PR #7818 attempted to use the configured stringifySearch serializer instead. As @schiller-manuel correctly pointed out, loader deps are not necessarily search params and should not be tied to the search stringifier.

This approach

Introduce safeStringify — a zero-dependency utility that safely serializes any value to a deterministic JSON string:

• bigint → "123n" (string representation)
• Set → sorted array of serialized values
• Map → array of [key, value] entry arrays
• undefined → empty string
• Circular references → "[Circular]" (detected via WeakSet)
• Functions → "[Function]"
• Symbols → description string
• Date → ISO string
• Plain objects → keys sorted for deterministic output

No API changes. No new dependencies. No coupling between loader deps and search params.

Tests

Added 12 unit tests covering all edge cases above.

Verification

• ✅ tests/utils.test.ts — 127 passed, 3 expected fail (pre-existing)
• ✅ tests/searchParams.test.ts — all passed
• ✅ Only 3 files changed (utils.ts, router.ts, utils.test.ts)

Fixes #7787

Summary by CodeRabbit

• Bug Fixes

  • Improved route matching reliability when loader dependencies contain complex values such as dates, maps, sets, bigints, functions, symbols, or circular references.
  • Ensured equivalent dependency data produces stable route identifiers, reducing unnecessary rematches and improving navigation consistency.
  • Improved navigation stability when dependency values are nested or supplied in different property orders.

• Tests

  • Added coverage for safe serialization across supported value types, nested structures, circular references, and differing object key order.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: eec205b3-abd7-4ae7-863b-126e91c4b699

📥 Commits

Reviewing files that changed from the base of the PR and between af8dcb8 and 8cd0c7b.

📒 Files selected for processing (3)

• packages/router-core/src/router.ts
• packages/router-core/src/utils.ts
• packages/router-core/tests/utils.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/router-core/tests/utils.test.ts
• packages/router-core/src/router.ts
• packages/router-core/src/utils.ts

---

📝 Walkthrough

Walkthrough

Adds safeStringify for deterministic serialization of unsupported and circular values. Tests cover its behavior. Router loader dependency hashes now use this utility.

Changes

Loader dependency serialization

Layer / File(s)	Summary
Safe serialization utility and coverage packages/router-core/src/utils.ts, packages/router-core/tests/utils.test.ts	Adds recursive serialization for special values, collections, circular references, dates, and sorted object keys. Tests cover these representations.
Route match hash integration packages/router-core/src/router.ts	Uses safeStringify(loaderDeps) to compute loaderDepsHash and retains the empty fallback for falsy dependencies.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• TanStack/router#7805: Both changes modify loader dependency handling in packages/router-core/src/router.ts.

Suggested labels: package: router-core

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR adds safeStringify coverage but does not use the configured search serializer or add the required custom-serializer and cache-identity tests [#7787].	Use the configured search serializer for loader dependency keys, then add tests for custom serialization and distinct cache identities when serialized values change.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: using safeStringify for loader dependency hash keys.
Out of Scope Changes check	✅ Passed	The changes remain focused on loader dependency serialization and related regression coverage, with no unrelated code changes identified.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.