From 595c1dafa82a794efa4bdcbf886c108f3d278350 Mon Sep 17 00:00:00 2001
From: pawelblaszczyk5 <internal@pawelblaszczyk.dev>
Date: Wed, 5 Aug 2026 10:38:17 +0200
Subject: [PATCH] fix(router-core): properly handle serialization of readonly
 maps/sets at type level

---
 .changeset/full-flowers-carry.md              |  5 +++
 .../src/ssr/serializer/transformer.ts         | 19 ++++++----
 .../router-core/tests/serializer.test-d.ts    | 35 +++++++++++++++++++
 3 files changed, 53 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/full-flowers-carry.md

diff --git a/.changeset/full-flowers-carry.md b/.changeset/full-flowers-carry.md
new file mode 100644
index 0000000000..06bbc16e46
--- /dev/null
+++ b/.changeset/full-flowers-carry.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/router-core': patch
+---
+
+fix(router-core): properly handle serialization of readonly maps/sets at type level
diff --git a/packages/router-core/src/ssr/serializer/transformer.ts b/packages/router-core/src/ssr/serializer/transformer.ts
index 6eeed9b6e6..d818e52b44 100644
--- a/packages/router-core/src/ssr/serializer/transformer.ts
+++ b/packages/router-core/src/ssr/serializer/transformer.ts
@@ -86,10 +86,10 @@ export type ValidateSerializable<T, TSerializable> = T extends TSerializable
           ? ValidateSerializablePromise<T, TSerializable>
           : T extends ReadableStream<any>
             ? ValidateReadableStream<T, TSerializable>
-            : T extends Set<any>
-              ? ValidateSerializableSet<T, TSerializable>
-              : T extends Map<any, any>
-                ? ValidateSerializableMap<T, TSerializable>
+            : T extends ReadonlyMap<any, any>
+              ? ValidateSerializableMap<T, TSerializable>
+              : T extends ReadonlySet<any>
+                ? ValidateSerializableSet<T, TSerializable>
                 : T extends AsyncGenerator<any, any>
                   ? ValidateSerializableAsyncGenerator<T, TSerializable>
                   : T extends object
@@ -118,7 +118,9 @@ export type ValidateReadableStream<T, TSerializable> =
 export type ValidateSerializableSet<T, TSerializable> =
   T extends Set<infer TItem>
     ? Set<ValidateSerializable<TItem, TSerializable>>
-    : never
+    : T extends ReadonlySet<infer TItem>
+      ? ReadonlySet<ValidateSerializable<TItem, TSerializable>>
+      : never
 
 export type ValidateSerializableMap<T, TSerializable> =
   T extends Map<infer TKey, infer TValue>
@@ -126,7 +128,12 @@ export type ValidateSerializableMap<T, TSerializable> =
         ValidateSerializable<TKey, TSerializable>,
         ValidateSerializable<TValue, TSerializable>
       >
-    : never
+    : T extends ReadonlyMap<infer TKey, infer TValue>
+      ? ReadonlyMap<
+          ValidateSerializable<TKey, TSerializable>,
+          ValidateSerializable<TValue, TSerializable>
+        >
+      : never
 
 export type ValidateSerializableArray<T, TSerializable> = T extends readonly [
   any,
diff --git a/packages/router-core/tests/serializer.test-d.ts b/packages/router-core/tests/serializer.test-d.ts
index 5ef3e3964b..b54e6f8f48 100644
--- a/packages/router-core/tests/serializer.test-d.ts
+++ b/packages/router-core/tests/serializer.test-d.ts
@@ -21,4 +21,39 @@ describe('Serializer', () => {
       ValidateSerializable<MyCustomType, Serializable>
     >().toEqualTypeOf<MyCustomType>()
   })
+
+  it('works for readonly sets containing serializable values', () => {
+    type Value = ReadonlySet<string>
+
+    expectTypeOf<
+      ValidateSerializable<Value, Serializable>
+    >().toEqualTypeOf<Value>()
+  })
+
+  it('fails for readonly sets containing unserializable values', () => {
+    type Value = ReadonlySet<() => void>
+
+    expectTypeOf<ValidateSerializable<Value, Serializable>>().toEqualTypeOf<
+      ReadonlySet<SerializationError<'Function may not be serializable'>>
+    >()
+  })
+
+  it('works for readonly maps containing serializable values', () => {
+    type Value = ReadonlyMap<string, number>
+
+    expectTypeOf<
+      ValidateSerializable<Value, Serializable>
+    >().toEqualTypeOf<Value>()
+  })
+
+  it('fails for readonly maps containing unserializable values', () => {
+    type Value = ReadonlyMap<string, () => void>
+
+    expectTypeOf<ValidateSerializable<Value, Serializable>>().toEqualTypeOf<
+      ReadonlyMap<
+        string,
+        SerializationError<'Function may not be serializable'>
+      >
+    >()
+  })
 })