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.

• 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

Run ID: 676b9861-c632-41a8-b855-9f8e58187ccb

📥 Commits

Reviewing files that changed from the base of the PR and between 0b178a7 and cc6f60b.

📒 Files selected for processing (3)

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

---

📝 Walkthrough

Walkthrough

Adds safeStringify to serialize unsupported and circular values deterministically, tests its behavior, and uses it to derive router loader dependency hashes.

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, with comprehensive tests.
Route match hash integration packages/router-core/src/router.ts	Uses safeStringify(loaderDeps) when computing loaderDepsHash, retaining the empty fallback for falsy dependencies.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• TanStack/router#7818: Changes loader dependency hash serialization in RouterCore.matchRoutesInternal.

Suggested reviewers: sheraff

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR replaces JSON.stringify with safeStringify, but the linked issue required the configured search serializer and a custom-serializer regression test.	Update loader dependency hashing to use the configured search serializer, add the custom-serializer regression test, and verify cache identity changes with serialized value changes.

✅ 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 names the router-core change and the use of safeStringify for loader dependency hash keys.
Out of Scope Changes check	✅ Passed	All changes support the loader-dependency hashing fix and tests, with no clearly unrelated edits in the shown files.
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.}