Add a guide about streaming

Author: fulopkovacs

docs/router/framework/react/guide/streaming-data-from-server-functions.md

@@ -0,0 +1,102 @@
+---
+title: Streaming Data from Server Functions
+---
+
+Streaming data from the server has become very popular thanks to the rise of AI apps. Luckily, it's a pretty easy task with TanStack Start, and what's even better: the streamed data is typed!
+
+The two most popular ways of streaming data from server functions are using `ReadableStream`-s or async generators.
+
+You can see how to implement both in the [Streaming Data From Server Functions example](https://github.com/TanStack/router/tree/main/examples/react/start-streaming-data-from-server-functions).
+
+## Typed Readable Streams
+
+Here's an example for a server function that streams an array of messages to the client in a type-safe manner:
+
+```ts
+type Message = {
+  content: string;
+};
+
+/**
+  This server function returns a `ReadableStream`
+  that streams `Message` chunks to the client.
+*/
+const streamingResponseFn = createServerFn({
+  method: "GET",
+}).handler(async () => {
+  // These are the messages that you want to send as chunks to the client
+  const messages: Message[] = generateMessages();
+
+  // This `ReadableStream` is typed, so each
+  // will be of type `Message`.
+  const stream = new ReadableStream<Message>({
+    async start(controller) {
+      for (const message of messages) {
+        // Send the message
+        controller.enqueue(message);
+      }
+      controller.close();
+    },
+  });
+
+  return stream;
+});
+```
+
+When you consume this stream from the client, the streamed chunks will be properly typed:
+
+```ts
+const [message, setMessage] = useState("");
+
+const getTypedReadableStreamResponse = useCallback(async () => {
+  const response = await streamingResponseFn();
+
+  if (!response) {
+    return;
+  }
+
+  const reader = response.getReader();
+  let done = false;
+  while (!done) {
+    const { value, done: doneReading } = await reader.read();
+    done = doneReading;
+    if (value) {
+      // Notice how we know the value of `chunk` (`Message | undefined`)
+      // here, because it's coming from the typed `ReadableStream`
+      const chunk = value.content;
+      setMessage((prev) => prev + chunk);
+    }
+  }
+}, []);
+```
+
+## Async Generators in Server Functions
+
+A much cleaner approach with the same results is to use an async generator function:
+
+```ts
+const streamingWithAnAsyncGeneratorFn = createServerFn().handler(
+  async function* () {
+    const messages = generateMessages();
+    for (const msg of messages) {
+      // Notice how we defined the type of the streamed chunks
+      // in the generic passed down the Promise constructor
+      yield new Promise<Message>(async (r) => {
+        // Send the message
+        return r(msg);
+      });
+    }
+  }
+);
+```
+
+The client side code will also be leaner:
+
+```ts
+const getResponseFromTheAsyncGenerator = useCallback(async () => {
+  for await (const msg of await streamingWithAnAsyncGeneratorFn()) {
+    const chunk = msg.content;
+    setMessages((prev) => prev + chunk);
+  }
+}, []);
+```

docs/start/framework/react/server-functions.md

@@ -8,15 +8,15 @@ title: Server Functions
 Server functions let you define server-only logic that can be called from anywhere in your application - loaders, components, hooks, or other server functions. They run on the server but can be invoked from client code seamlessly.
 
 ```tsx
-import { createServerFn } from '@tanstack/react-start'
+import { createServerFn } from "@tanstack/react-start";
 
 export const getServerTime = createServerFn().handler(async () => {
   // This runs only on the server
-  return new Date().toISOString()
-})
+  return new Date().toISOString();
+});
 
 // Call from anywhere - components, loaders, hooks, etc.
-const time = await getServerTime()
+const time = await getServerTime();
 ```
 
 Server functions provide server capabilities (database access, environment variables, file system) while maintaining type safety across the network boundary.
@@ -26,18 +26,18 @@ Server functions provide server capabilities (database access, environment varia
 Server functions are created with `createServerFn()` and can specify HTTP method:
 
 ```tsx
-import { createServerFn } from '@tanstack/react-start'
+import { createServerFn } from "@tanstack/react-start";
 
 // GET request (default)
 export const getData = createServerFn().handler(async () => {
-  return { message: 'Hello from server!' }
-})
+  return { message: "Hello from server!" };
+});
 
 // POST request
-export const saveData = createServerFn({ method: 'POST' }).handler(async () => {
+export const saveData = createServerFn({ method: "POST" }).handler(async () => {
   // Server-only logic
-  return { success: true }
-})
+  return { success: true };
+});
 ```
 
 ## Where to Call Server Functions
@@ -51,18 +51,18 @@ Call server functions from:
 
 ```tsx
 // In a route loader
-export const Route = createFileRoute('/posts')({
+export const Route = createFileRoute("/posts")({
   loader: () => getPosts(),
-})
+});
 
 // In a component
 function PostList() {
-  const getPosts = useServerFn(getServerPosts)
+  const getPosts = useServerFn(getServerPosts);
 
   const { data } = useQuery({
-    queryKey: ['posts'],
+    queryKey: ["posts"],
     queryFn: () => getPosts(),
-  })
+  });
 }
 ```
 
@@ -73,58 +73,58 @@ Server functions accept a single `data` parameter. Since they cross the network
 ### Basic Parameters
 
 ```tsx
-import { createServerFn } from '@tanstack/react-start'
+import { createServerFn } from "@tanstack/react-start";
 
-export const greetUser = createServerFn({ method: 'GET' })
+export const greetUser = createServerFn({ method: "GET" })
   .inputValidator((data: { name: string }) => data)
   .handler(async ({ data }) => {
-    return `Hello, ${data.name}!`
-  })
+    return `Hello, ${data.name}!`;
+  });
 
-await greetUser({ data: { name: 'John' } })
+await greetUser({ data: { name: "John" } });
 ```
 
 ### Validation with Zod
 
 For robust validation, use schema libraries like Zod:
 
 ```tsx
-import { createServerFn } from '@tanstack/react-start'
-import { z } from 'zod'
+import { createServerFn } from "@tanstack/react-start";
+import { z } from "zod";
 
 const UserSchema = z.object({
   name: z.string().min(1),
   age: z.number().min(0),
-})
+});
 
-export const createUser = createServerFn({ method: 'POST' })
+export const createUser = createServerFn({ method: "POST" })
   .inputValidator(UserSchema)
   .handler(async ({ data }) => {
     // data is fully typed and validated
-    return `Created user: ${data.name}, age ${data.age}`
-  })
+    return `Created user: ${data.name}, age ${data.age}`;
+  });
 ```
 
 ### Form Data
 
 Handle form submissions with FormData:
 
 ```tsx
-export const submitForm = createServerFn({ method: 'POST' })
+export const submitForm = createServerFn({ method: "POST" })
   .inputValidator((data) => {
     if (!(data instanceof FormData)) {
-      throw new Error('Expected FormData')
+      throw new Error("Expected FormData");
     }
 
     return {
-      name: data.get('name')?.toString() || '',
-      email: data.get('email')?.toString() || '',
-    }
+      name: data.get("name")?.toString() || "",
+      email: data.get("email")?.toString() || "",
+    };
   })
   .handler(async ({ data }) => {
     // Process form data
-    return { success: true }
-  })
+    return { success: true };
+  });
 ```
 
 ## Error Handling & Redirects
@@ -134,20 +134,20 @@ Server functions can throw errors, redirects, and not-found responses that are h
 ### Basic Errors
 
 ```tsx
-import { createServerFn } from '@tanstack/react-start'
+import { createServerFn } from "@tanstack/react-start";
 
 export const riskyFunction = createServerFn().handler(async () => {
   if (Math.random() > 0.5) {
-    throw new Error('Something went wrong!')
+    throw new Error("Something went wrong!");
   }
-  return { success: true }
-})
+  return { success: true };
+});
 
 // Errors are serialized to the client
 try {
-  await riskyFunction()
+  await riskyFunction();
 } catch (error) {
-  console.log(error.message) // "Something went wrong!"
+  console.log(error.message); // "Something went wrong!"
 }
 ```
 
@@ -156,39 +156,39 @@ try {
 Use redirects for authentication, navigation, etc:
 
 ```tsx
-import { createServerFn } from '@tanstack/react-start'
-import { redirect } from '@tanstack/react-router'
+import { createServerFn } from "@tanstack/react-start";
+import { redirect } from "@tanstack/react-router";
 
 export const requireAuth = createServerFn().handler(async () => {
-  const user = await getCurrentUser()
+  const user = await getCurrentUser();
 
   if (!user) {
-    throw redirect({ to: '/login' })
+    throw redirect({ to: "/login" });
   }
 
-  return user
-})
+  return user;
+});
 ```
 
 ### Not Found
 
 Throw not-found errors for missing resources:
 
 ```tsx
-import { createServerFn } from '@tanstack/react-start'
-import { notFound } from '@tanstack/react-router'
+import { createServerFn } from "@tanstack/react-start";
+import { notFound } from "@tanstack/react-router";
 
 export const getPost = createServerFn()
   .inputValidator((data: { id: string }) => data)
   .handler(async ({ data }) => {
-    const post = await db.findPost(data.id)
+    const post = await db.findPost(data.id);
 
     if (!post) {
-      throw notFound()
+      throw notFound();
     }
 
-    return post
-  })
+    return post;
+  });
 ```
 
 ## Advanced Topics
@@ -204,9 +204,13 @@ Access request headers, cookies, and response customization:
 - `setResponseHeader()` - Set custom response headers
 - `setResponseStatus()` - Custom status codes
 
-### Streaming & Raw Responses
+### Streaming
+
+Stream typed data from server functions to the client. See the [Streaming Data from Server Functions guide ](../guide/streaming-data-from-server-functions).
+
+### Raw Responses
 
-Return `Response` objects for streaming, binary data, or custom content types.
+Return `Response` objects binary data, or custom content types.
 
 ### Progressive Enhancement