Open History to see the last commit
1import { createServerFn, RawStream } from '@tanstack/react-start'
2β
3// Helper to create a delayed Uint8Array stream
4function createDelayedStream(
5 chunks: Array<Uint8Array>,
6 delayMs: number,
7): ReadableStream<Uint8Array> {
8 return new ReadableStream<Uint8Array>({
9 async start(controller) {
10 for (const chunk of chunks) {
11 await new Promise((resolve) => setTimeout(resolve, delayMs))
12 controller.enqueue(chunk)
13 }
14 controller.close()
15 },
16 })
17}
18β
19// Helper to create a stream with variable delays per chunk
20// Each entry is [chunk, delayBeforeMs] - delay happens BEFORE enqueueing the chunk
21function createVariableDelayStream(
22 chunksWithDelays: Array<[Uint8Array, number]>,
23): ReadableStream<Uint8Array> {
24 return new ReadableStream<Uint8Array>({
25 async start(controller) {
26 for (const [chunk, delayMs] of chunksWithDelays) {
27 await new Promise((resolve) => setTimeout(resolve, delayMs))
28 controller.enqueue(chunk)
29 }
30 controller.close()
31 },
32 })
33}
34β
35// Helper to encode text to Uint8Array
36function encode(text: string): Uint8Array {
37 return new TextEncoder().encode(text)
38}
39β
40// Export helpers for use in components and SSR routes
41export { encode, createDelayedStream, concatBytes }
42β
43// Expected data for hint tests - defined here for both server and client verification
44// Test 7: Text hint with pure text
45export const TEST7_CHUNKS = [
46 encode('Hello, '),
47 encode('World! '),
48 encode('This is text.'),
49]
50export const TEST7_EXPECTED = concatBytes(TEST7_CHUNKS)
51β
52// Test 8: Text hint with pure binary (invalid UTF-8)
53export const TEST8_CHUNKS = [
54 new Uint8Array([0xff, 0xfe, 0x00, 0x01, 0x80, 0x90]),
55 new Uint8Array([0xa0, 0xb0, 0xc0, 0xd0, 0xe0, 0xf0]),
56]
57export const TEST8_EXPECTED = concatBytes(TEST8_CHUNKS)
58β
59// Test 9: Text hint with mixed content
60export const TEST9_CHUNKS = [
61 encode('Valid UTF-8 text'),
62 new Uint8Array([0xff, 0xfe, 0x80, 0x90]), // Invalid UTF-8
63 encode(' More text'),
64]
65export const TEST9_EXPECTED = concatBytes(TEST9_CHUNKS)
66β
67// Test 10: Binary hint with text data
68export const TEST10_CHUNKS = [encode('This is text but using binary hint')]
69export const TEST10_EXPECTED = concatBytes(TEST10_CHUNKS)
70β
71// Test 11: Binary hint with pure binary
72export const TEST11_CHUNKS = [
73 new Uint8Array([0x00, 0x01, 0x02, 0xff, 0xfe, 0xfd]),
74]
75export const TEST11_EXPECTED = concatBytes(TEST11_CHUNKS)
76β
77// Helper to concatenate byte arrays
78function concatBytes(chunks: Array<Uint8Array>): Uint8Array {
79 const totalLength = chunks.reduce((acc, c) => acc + c.length, 0)
80 const result = new Uint8Array(totalLength)
81 let offset = 0
82 for (const chunk of chunks) {
83 result.set(chunk, offset)
84 offset += chunk.length
85 }
86 return result
87}
88β
89// Test 1: Simple single raw stream
90export const singleRawStreamFn = createServerFn().handler(async () => {
91 const stream = createDelayedStream(
92 [encode('chunk1'), encode('chunk2'), encode('chunk3')],
93 50,
94 )
95 return {
96 message: 'Single stream test',
97 data: new RawStream(stream),
98 }
99})
100β
101// Test 2: Multiple raw streams
102export const multipleRawStreamsFn = createServerFn().handler(async () => {
103 const stream1 = createDelayedStream(
104 [encode('stream1-a'), encode('stream1-b')],
105 30,
106 )
107 const stream2 = createDelayedStream(
108 [encode('stream2-a'), encode('stream2-b')],
109 50,
110 )
111 return {
112 message: 'Multiple streams test',
113 first: new RawStream(stream1),
114 second: new RawStream(stream2),
115 }
116})
117β
118// Test 3: JSON streaming ends before raw stream
119export const jsonEndsFirstFn = createServerFn().handler(async () => {
120 // Slow raw stream (takes 500ms total)
121 const slowStream = createDelayedStream(
122 [encode('slow-1'), encode('slow-2'), encode('slow-3'), encode('slow-4')],
123 125,
124 )
125 return {
126 message: 'JSON ends first test',
127 timestamp: Date.now(),
128 slowData: new RawStream(slowStream),
129 }
130})
131β
132// Test 4: Raw stream ends before JSON streaming (fast stream, deferred JSON)
133export const rawEndsFirstFn = createServerFn().handler(async () => {
134 // Fast raw stream (completes quickly)
135 const fastStream = createDelayedStream([encode('fast-done')], 10)
136β
137 // Deferred promise - NOT awaited, so it streams as deferred JSON
138 const deferredData = new Promise<string>((resolve) =>
139 setTimeout(() => resolve('deferred-json-data'), 200),
140 )
141β
142 return {
143 message: 'Raw ends first test',
144 deferredData,
145 fastData: new RawStream(fastStream),
146 }
147})
148β
149// Test 5: Large binary data
150export const largeBinaryFn = createServerFn().handler(async () => {
151 // Create 1KB chunks
152 const chunk = new Uint8Array(1024)
153 for (let i = 0; i < chunk.length; i++) {
154 chunk[i] = i % 256
155 }
156β
157 const stream = createDelayedStream([chunk, chunk, chunk], 20)
158β
159 return {
160 message: 'Large binary test',
161 size: 3072,
162 binary: new RawStream(stream),
163 }
164})
165β
166// Test 6: Mixed streaming (promise + raw stream)
167export const mixedStreamingFn = createServerFn().handler(async () => {
168 const rawStream = createDelayedStream(
169 [encode('mixed-raw-1'), encode('mixed-raw-2')],
170 50,
171 )
172β
173 return {
174 immediate: 'immediate-value',
175 deferred: new Promise<string>((resolve) =>
176 setTimeout(() => resolve('deferred-value'), 100),
177 ),
178 raw: new RawStream(rawStream),
179 }
180})
181β
182// Test 7: Text hint with pure text data (should use UTF-8 encoding)
183export const textHintPureTextFn = createServerFn().handler(async () => {
184 const stream = createDelayedStream(TEST7_CHUNKS, 30)
185 return {
186 message: 'Text hint with pure text',
187 data: new RawStream(stream, { hint: 'text' }),
188 }
189})
190β
191// Test 8: Text hint with pure binary data (should fallback to base64)
192export const textHintPureBinaryFn = createServerFn().handler(async () => {
193 const stream = createDelayedStream(TEST8_CHUNKS, 30)
194 return {
195 message: 'Text hint with pure binary',
196 data: new RawStream(stream, { hint: 'text' }),
197 }
198})
199β
200// Test 9: Text hint with mixed content (some UTF-8, some binary)
201export const textHintMixedFn = createServerFn().handler(async () => {
202 const stream = createDelayedStream(TEST9_CHUNKS, 30)
203 return {
204 message: 'Text hint with mixed content',
205 data: new RawStream(stream, { hint: 'text' }),
206 }
207})
208β
209// Test 10: Binary hint with text data (should still use base64)
210export const binaryHintTextFn = createServerFn().handler(async () => {
211 const stream = createDelayedStream(TEST10_CHUNKS, 30)
212 return {
213 message: 'Binary hint with text data',
214 data: new RawStream(stream, { hint: 'binary' }),
215 }
216})
217β
218// Test 11: Binary hint with pure binary data
219export const binaryHintBinaryFn = createServerFn().handler(async () => {
220 const stream = createDelayedStream(TEST11_CHUNKS, 30)
221 return {
222 message: 'Binary hint with binary data',
223 data: new RawStream(stream, { hint: 'binary' }),
224 }
225})
226β
227// ============================================================================
228// MULTIPLEXING TESTS - Verify correct interleaving of multiple streams
229// ============================================================================
230β
231// Expected data for multiplexing tests
232// Test 12: Two streams with interleaved timing
233// Stream A: sends at 0ms, 150ms, 200ms (3 chunks with pauses)
234// Stream B: sends at 50ms, 100ms, 250ms (3 chunks, different rhythm)
235export const TEST12_STREAM_A_CHUNKS: Array<[Uint8Array, number]> = [
236 [encode('A1-first'), 0], // immediate
237 [encode('A2-after-pause'), 150], // 150ms pause
238 [encode('A3-quick'), 50], // 50ms after A2
239]
240export const TEST12_STREAM_B_CHUNKS: Array<[Uint8Array, number]> = [
241 [encode('B1-start'), 50], // 50ms after start
242 [encode('B2-continue'), 50], // 50ms after B1
243 [encode('B3-final'), 150], // 150ms pause then final
244]
245export const TEST12_STREAM_A_EXPECTED = concatBytes(
246 TEST12_STREAM_A_CHUNKS.map(([chunk]) => chunk),
247)
248export const TEST12_STREAM_B_EXPECTED = concatBytes(
249 TEST12_STREAM_B_CHUNKS.map(([chunk]) => chunk),
250)
251β
252// Test 13: Burst-pause-burst pattern (single stream)
253// 3 chunks quickly, long pause, 3 more chunks quickly
254export const TEST13_CHUNKS: Array<[Uint8Array, number]> = [
255 [encode('burst1-a'), 10],
256 [encode('burst1-b'), 10],
257 [encode('burst1-c'), 10],
258 [encode('pause-then-burst2-a'), 200], // long pause
259 [encode('burst2-b'), 10],
260 [encode('burst2-c'), 10],
261]
262export const TEST13_EXPECTED = concatBytes(
263 TEST13_CHUNKS.map(([chunk]) => chunk),
264)
265β
266// Test 14: Three concurrent streams with different patterns
267// Stream A: fast steady (every 30ms)
268// Stream B: slow steady (every 100ms)
269// Stream C: burst pattern (quick-pause-quick)
270export const TEST14_STREAM_A_CHUNKS: Array<[Uint8Array, number]> = [
271 [encode('A1'), 30],
272 [encode('A2'), 30],
273 [encode('A3'), 30],
274 [encode('A4'), 30],
275]
276export const TEST14_STREAM_B_CHUNKS: Array<[Uint8Array, number]> = [
277 [encode('B1-slow'), 100],
278 [encode('B2-slow'), 100],
279]
280export const TEST14_STREAM_C_CHUNKS: Array<[Uint8Array, number]> = [
281 [encode('C1-burst'), 20],
282 [encode('C2-burst'), 20],
283 [encode('C3-after-pause'), 150],
284]
285export const TEST14_STREAM_A_EXPECTED = concatBytes(
286 TEST14_STREAM_A_CHUNKS.map(([chunk]) => chunk),
287)
288export const TEST14_STREAM_B_EXPECTED = concatBytes(
289 TEST14_STREAM_B_CHUNKS.map(([chunk]) => chunk),
290)
291export const TEST14_STREAM_C_EXPECTED = concatBytes(
292 TEST14_STREAM_C_CHUNKS.map(([chunk]) => chunk),
293)
294β
295// Test 12: Interleaved multiplexing - two streams with variable delays
296export const interleavedStreamsFn = createServerFn().handler(async () => {
297 const streamA = createVariableDelayStream(TEST12_STREAM_A_CHUNKS)
298 const streamB = createVariableDelayStream(TEST12_STREAM_B_CHUNKS)
299β
300 return {
301 message: 'Interleaved streams test',
302 streamA: new RawStream(streamA),
303 streamB: new RawStream(streamB),
304 }
305})
306β
307// Test 13: Burst-pause-burst pattern
308export const burstPauseBurstFn = createServerFn().handler(async () => {
309 const stream = createVariableDelayStream(TEST13_CHUNKS)
310β
311 return {
312 message: 'Burst-pause-burst test',
313 data: new RawStream(stream),
314 }
315})
316β
317// Test 14: Three concurrent streams
318export const threeStreamsFn = createServerFn().handler(async () => {
319 const streamA = createVariableDelayStream(TEST14_STREAM_A_CHUNKS)
320 const streamB = createVariableDelayStream(TEST14_STREAM_B_CHUNKS)
321 const streamC = createVariableDelayStream(TEST14_STREAM_C_CHUNKS)
322β
323 return {
324 message: 'Three concurrent streams test',
325 fast: new RawStream(streamA),
326 slow: new RawStream(streamB),
327 burst: new RawStream(streamC),
328 }
329})
330β
331// ============================================================================
332// EDGE CASE TESTS
333// ============================================================================
334β
335// Test 15: Empty stream (zero bytes)
336export const emptyStreamFn = createServerFn().handler(async () => {
337 // Stream that immediately closes with no data
338 const stream = new ReadableStream<Uint8Array>({
339 start(controller) {
340 controller.close()
341 },
342 })
343β
344 return {
345 message: 'Empty stream test',
346 data: new RawStream(stream),
347 }
348})
349β
350// Test 16: Stream that errors mid-flight
351export const errorStreamFn = createServerFn().handler(async () => {
352 // Stream that sends some data then errors
353 const stream = new ReadableStream<Uint8Array>({
354 async start(controller) {
355 controller.enqueue(encode('chunk-before-error'))
356 await new Promise((resolve) => setTimeout(resolve, 50))
357 controller.error(new Error('Intentional stream error'))
358 },
359 })
360β
361 return {
362 message: 'Error stream test',
363 data: new RawStream(stream),
364 }
365})
366β
367// ============================================================================
368// LATE RAWSTREAM TESTS - RawStream inside Promise (discovered after initial serialization)
369// ============================================================================
370β
371// Expected data for late stream tests
372export const LATE_STREAM_CHUNKS = [
373 encode('late-1'),
374 encode('late-2'),
375 encode('late-3'),
376]
377export const LATE_STREAM_EXPECTED = concatBytes(LATE_STREAM_CHUNKS)
378β
379export const LATE_STREAM_A_CHUNKS = [encode('lateA-1'), encode('lateA-2')]
380export const LATE_STREAM_A_EXPECTED = concatBytes(LATE_STREAM_A_CHUNKS)
381β
382export const LATE_STREAM_B_CHUNKS = [encode('lateB-1'), encode('lateB-2')]
383export const LATE_STREAM_B_EXPECTED = concatBytes(LATE_STREAM_B_CHUNKS)
384β
385export const IMMEDIATE_STREAM_CHUNKS = [
386 encode('immediate-1'),
387 encode('immediate-2'),
388]
389export const IMMEDIATE_STREAM_EXPECTED = concatBytes(IMMEDIATE_STREAM_CHUNKS)
390β
391// Test 17: Single late RawStream (Promise<RawStream>)
392// The RawStream is wrapped in a Promise, so it's not discovered during initial serialization
393export const lateRawStreamFn = createServerFn().handler(async () => {
394 // Promise that resolves to a RawStream after a delay
395 const lateStream = new Promise<RawStream>((resolve) => {
396 setTimeout(() => {
397 const stream = createDelayedStream(LATE_STREAM_CHUNKS, 30)
398 resolve(new RawStream(stream))
399 }, 100)
400 })
401β
402 return {
403 message: 'Late stream test',
404 lateData: lateStream,
405 }
406})
407β
408// Test 18: Multiple late RawStreams with different delays
409export const multipleLateStreamsFn = createServerFn().handler(async () => {
410 // Two Promises resolving to RawStreams at different times
411 const lateStreamA = new Promise<RawStream>((resolve) => {
412 setTimeout(() => {
413 const stream = createDelayedStream(LATE_STREAM_A_CHUNKS, 20)
414 resolve(new RawStream(stream))
415 }, 50)
416 })
417β
418 const lateStreamB = new Promise<RawStream>((resolve) => {
419 setTimeout(() => {
420 const stream = createDelayedStream(LATE_STREAM_B_CHUNKS, 20)
421 resolve(new RawStream(stream))
422 }, 150)
423 })
424β
425 return {
426 message: 'Multiple late streams test',
427 streamA: lateStreamA,
428 streamB: lateStreamB,
429 }
430})
431β
432// Test 19: Mixed immediate and late RawStreams
433// One RawStream is immediate (discovered during initial serialization)
434// One is wrapped in Promise (discovered after initial serialization)
435export const mixedImmediateLateFn = createServerFn().handler(async () => {
436 // Immediate RawStream - discovered during initial serialization
437 const immediateStream = createDelayedStream(IMMEDIATE_STREAM_CHUNKS, 30)
438β
439 // Late RawStream - wrapped in Promise, discovered after initial serialization
440 const lateStream = new Promise<RawStream>((resolve) => {
441 setTimeout(() => {
442 const stream = createDelayedStream(LATE_STREAM_CHUNKS, 30)
443 resolve(new RawStream(stream))
444 }, 100)
445 })
446β
447 return {
448 message: 'Mixed immediate and late test',
449 immediate: new RawStream(immediateStream),
450 late: lateStream,
451 }
452})
453β
454// Helpers for consuming streams (exported for use in components)
455// Note: RawStream is the marker class used in loaders/server functions,
456// but after SSR deserialization it becomes ReadableStream<Uint8Array>.
457// We accept both types to handle the TypeScript mismatch.
458export function createStreamConsumer() {
459 const decoder = new TextDecoder()
460β
461 return async function consumeStream(
462 stream: ReadableStream<Uint8Array> | RawStream,
463 ): Promise<string> {
464 // Handle both RawStream (from type system) and ReadableStream (runtime)
465 const actualStream =
466 stream instanceof RawStream
467 ? stream.stream
468 : (stream as ReadableStream<Uint8Array>)
469 const reader = actualStream.getReader()
470 const chunks: Array<string> = []
471β
472 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
473 while (true) {
474 const { done, value } = await reader.read()
475 if (done) break
476 chunks.push(decoder.decode(value, { stream: true }))
477 }
478β
479 return chunks.join('')
480 }
481}
482β
483export async function consumeBinaryStream(
484 stream: ReadableStream<Uint8Array> | RawStream,
485): Promise<number> {
486 // Handle both RawStream (from type system) and ReadableStream (runtime)
487 const actualStream =
488 stream instanceof RawStream
489 ? stream.stream
490 : (stream as ReadableStream<Uint8Array>)
491 const reader = actualStream.getReader()
492 let totalBytes = 0
493β
494 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
495 while (true) {
496 const { done, value } = await reader.read()
497 if (done) break
498 totalBytes += value.length
499 }
500β
501 return totalBytes
502}
503β
504// Helper to collect all bytes from a stream
505export async function collectBytes(
506 stream: ReadableStream<Uint8Array> | RawStream,
507): Promise<Uint8Array> {
508 const actualStream =
509 stream instanceof RawStream
510 ? stream.stream
511 : (stream as ReadableStream<Uint8Array>)
512 const reader = actualStream.getReader()
513 const chunks: Array<Uint8Array> = []
514 let totalLength = 0
515β
516 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
517 while (true) {
518 const { done, value } = await reader.read()
519 if (done) break
520 chunks.push(value)
521 totalLength += value.length
522 }
523β
524 const result = new Uint8Array(totalLength)
525 let pos = 0
526 for (const chunk of chunks) {
527 result.set(chunk, pos)
528 pos += chunk.length
529 }
530 return result
531}
532β
533// Compare two Uint8Arrays byte-by-byte
534export function compareBytes(
535 actual: Uint8Array,
536 expected: Uint8Array,
537): {
538 match: boolean
539 mismatchIndex: number | null
540 actualLength: number
541 expectedLength: number
542} {
543 if (actual.length !== expected.length) {
544 return {
545 match: false,
546 mismatchIndex: -1, // -1 indicates length mismatch
547 actualLength: actual.length,
548 expectedLength: expected.length,
549 }
550 }
551 for (let i = 0; i < actual.length; i++) {
552 if (actual[i] !== expected[i]) {
553 return {
554 match: false,
555 mismatchIndex: i,
556 actualLength: actual.length,
557 expectedLength: expected.length,
558 }
559 }
560 }
561 return {
562 match: true,
563 mismatchIndex: null,
564 actualLength: actual.length,
565 expectedLength: expected.length,
566 }
567}