feat(react-router): add SerializesTo brand type (#12264)

* Add `SerializesTo` brand type.

* sign CLA

* Update .changeset/sour-avocados-lick.md

Co-authored-by: Michaël De Boey <[email protected]>

* change `__RR_SerializesTo` to `__ReactRouter_SerializesTo`

* mark `SerializesTo` as unstable

---------

Co-authored-by: Michaël De Boey <[email protected]>
Co-authored-by: Tim Dorr <[email protected]>
Co-authored-by: Pedro Cattori <[email protected]>

Author: 4 people

.changeset/sour-avocados-lick.md

@@ -0,0 +1,5 @@
+---
+"react-router": patch
+---
+
+Add `unstable_SerializesTo` brand type for library authors to register types serializable by React Router's streaming format (`turbo-stream`)

contributors.yml

@@ -246,6 +246,7 @@
 - pavsoldatov
 - pcattori
 - petersendidit
+- phryneas
 - phildl
 - pierophp
 - printfn

packages/react-router/index.ts

@@ -263,6 +263,7 @@ export type {
   FlashSessionData,
 } from "./lib/server-runtime/sessions";
 
+export type { unstable_SerializesTo } from "./lib/types/serializes-to.ts";
 export type { Register } from "./lib/types/register";
 export { href } from "./lib/href";
 

packages/react-router/lib/types/route-data.ts

@@ -4,11 +4,15 @@ import type {
 } from "../dom/ssr/routeModules";
 import type { DataWithResponseInit } from "../router/utils";
 import type { Serializable } from "../server-runtime/single-fetch";
+import type { unstable_SerializesTo } from "./serializes-to";
 import type { Equal, Expect, Func, IsAny, Pretty } from "./utils";
 
 // prettier-ignore
 type Serialize<T> =
-  // First, let type stay as-is if its already serializable...
+  // If type has a `SerializesTo` brand, use that type
+  T extends unstable_SerializesTo<infer To> ? To :
+
+  // Then, let type stay as-is if its already serializable...
   T extends Serializable ? T :
 
   // ...then don't allow functions to be serialized...
@@ -69,21 +73,38 @@ type __tests = [
   Expect<Equal<ServerDataFrom<any>, undefined>>,
   Expect<
     Equal<
-      ServerDataFrom<() => { a: string; b: Date; c: () => boolean }>,
-      { a: string; b: Date; c: undefined }
+      ServerDataFrom<
+        () => {
+          a: string;
+          b: Date;
+          c: () => boolean;
+          d: unstable_SerializesTo<number>;
+        }
+      >,
+      { a: string; b: Date; c: undefined; d: number }
     >
   >,
   Expect<
     Equal<
       Pretty<
         ServerDataFrom<
           () =>
-            | { json: string; b: Date; c: () => boolean }
-            | DataWithResponseInit<{ data: string; b: Date; c: () => boolean }>
+            | {
+                json: string;
+                b: Date;
+                c: () => boolean;
+                d: unstable_SerializesTo<number>;
+              }
+            | DataWithResponseInit<{
+                data: string;
+                b: Date;
+                c: () => boolean;
+                d: unstable_SerializesTo<number>;
+              }>
         >
       >,
-      | { json: string; b: Date; c: undefined }
-      | { data: string; b: Date; c: undefined }
+      | { json: string; b: Date; c: undefined; d: number }
+      | { data: string; b: Date; c: undefined; d: number }
     >
   >,
   Expect<Equal<ServerDataFrom<() => { a: string } | Response>, { a: string }>>,

packages/react-router/lib/types/serializes-to.ts

@@ -0,0 +1,9 @@
+/**
+ * A brand that can be applied to a type to indicate that it will serialize
+ * to a specific type when transported to the client from a loader.
+ * Only use this if you have additional serialization/deserialization logic
+ * in your application.
+ */
+export type unstable_SerializesTo<T> = {
+  unstable__ReactRouter_SerializesTo?: [T];
+};