Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

raw-stream-fns.ts

480 lines14.3 KB

1import { RawStream, createServerFn } from '@tanstack/solid-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 })
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 })
34​
35// Helper to encode text to Uint8Array
36function encode(text: string): Uint8Array {
37 return new TextEncoder().encode(text)
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.'),
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]),
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'),
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]),
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
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
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
245export const TEST12_STREAM_A_EXPECTED = concatBytes(
246 TEST12_STREAM_A_CHUNKS.map(([chunk]) => chunk),
248export const TEST12_STREAM_B_EXPECTED = concatBytes(
249 TEST12_STREAM_B_CHUNKS.map(([chunk]) => chunk),
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],
262export const TEST13_EXPECTED = concatBytes(
263 TEST13_CHUNKS.map(([chunk]) => chunk),
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],
276export const TEST14_STREAM_B_CHUNKS: Array<[Uint8Array, number]> = [
277 [encode('B1-slow'), 100],
278 [encode('B2-slow'), 100],
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],
285export const TEST14_STREAM_A_EXPECTED = concatBytes(
286 TEST14_STREAM_A_CHUNKS.map(([chunk]) => chunk),
288export const TEST14_STREAM_B_EXPECTED = concatBytes(
289 TEST14_STREAM_B_CHUNKS.map(([chunk]) => chunk),
291export const TEST14_STREAM_C_EXPECTED = concatBytes(
292 TEST14_STREAM_C_CHUNKS.map(([chunk]) => chunk),
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// Helpers for consuming streams (exported for use in components)
368// Note: RawStream is the marker class used in loaders/server functions,
369// but after SSR deserialization it becomes ReadableStream<Uint8Array>.
370// We accept both types to handle the TypeScript mismatch.
371export function createStreamConsumer() {
372 const decoder = new TextDecoder()
373​
374 return async function consumeStream(
375 stream: ReadableStream<Uint8Array> | RawStream,
376 ): Promise<string> {
377 // Handle both RawStream (from type system) and ReadableStream (runtime)
378 const actualStream =
379 stream instanceof RawStream
380 ? stream.stream
381 : (stream as ReadableStream<Uint8Array>)
382 const reader = actualStream.getReader()
383 const chunks: Array<string> = []
384​
385 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
386 while (true) {
387 const { done, value } = await reader.read()
388 if (done) break
389 chunks.push(decoder.decode(value, { stream: true }))
390 }
391​
392 return chunks.join('')
393 }
395​
396export async function consumeBinaryStream(
397 stream: ReadableStream<Uint8Array> | RawStream,
398): Promise<number> {
399 // Handle both RawStream (from type system) and ReadableStream (runtime)
400 const actualStream =
401 stream instanceof RawStream
402 ? stream.stream
403 : (stream as ReadableStream<Uint8Array>)
404 const reader = actualStream.getReader()
405 let totalBytes = 0
406​
407 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
408 while (true) {
409 const { done, value } = await reader.read()
410 if (done) break
411 totalBytes += value.length
412 }
413​
414 return totalBytes
416​
417// Helper to collect all bytes from a stream
418export async function collectBytes(
419 stream: ReadableStream<Uint8Array> | RawStream,
420): Promise<Uint8Array> {
421 const actualStream =
422 stream instanceof RawStream
423 ? stream.stream
424 : (stream as ReadableStream<Uint8Array>)
425 const reader = actualStream.getReader()
426 const chunks: Array<Uint8Array> = []
427 let totalLength = 0
428​
429 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
430 while (true) {
431 const { done, value } = await reader.read()
432 if (done) break
433 chunks.push(value)
434 totalLength += value.length
435 }
436​
437 const result = new Uint8Array(totalLength)
438 let pos = 0
439 for (const chunk of chunks) {
440 result.set(chunk, pos)
441 pos += chunk.length
442 }
443 return result
445​
446// Compare two Uint8Arrays byte-by-byte
447export function compareBytes(
448 actual: Uint8Array,
449 expected: Uint8Array,
450): {
451 match: boolean
452 mismatchIndex: number | null
453 actualLength: number
454 expectedLength: number
455} {
456 if (actual.length !== expected.length) {
457 return {
458 match: false,
459 mismatchIndex: -1, // -1 indicates length mismatch
460 actualLength: actual.length,
461 expectedLength: expected.length,
462 }
463 }
464 for (let i = 0; i < actual.length; i++) {
465 if (actual[i] !== expected[i]) {
466 return {
467 match: false,
468 mismatchIndex: i,
469 actualLength: actual.length,
470 expectedLength: expected.length,
471 }
472 }
473 }
474 return {
475 match: true,
476 mismatchIndex: null,
477 actualLength: actual.length,
478 expectedLength: expected.length,
479 }