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

ReplayableStream.test.ts

536 lines16.0 KB

1import { describe, expect, it } from 'vitest'
2import {
3 ReplayableStream,
4 REPLAYABLE_STREAM_MARKER,
5} from '../src/ReplayableStream'
6​
7describe('ReplayableStream', () => {
8 describe('basic functionality', () => {
9 it('should buffer and replay chunks to single consumer', async () => {
10 const source = new ReadableStream<Uint8Array>({
11 start(controller) {
12 controller.enqueue(new Uint8Array([1, 2, 3]))
13 controller.enqueue(new Uint8Array([4, 5, 6]))
14 controller.close()
15 },
16 })
17​
18 const replayable = new ReplayableStream(source)
19 const replay = replayable.createReplayStream()
20 const reader = replay.getReader()
21​
22 const chunks: Array<Uint8Array> = []
23 while (true) {
24 const { done, value } = await reader.read()
25 if (done) break
26 chunks.push(value)
27 }
28​
29 expect(chunks).toHaveLength(2)
30 expect(chunks[0]).toEqual(new Uint8Array([1, 2, 3]))
31 expect(chunks[1]).toEqual(new Uint8Array([4, 5, 6]))
32 })
33​
34 it('should allow multiple independent consumers', async () => {
35 const source = new ReadableStream<Uint8Array>({
36 start(controller) {
37 controller.enqueue(new Uint8Array([10, 20]))
38 controller.enqueue(new Uint8Array([30, 40]))
39 controller.close()
40 },
41 })
42​
43 const replayable = new ReplayableStream(source)
44​
45 // Create two independent replay streams
46 const replay1 = replayable.createReplayStream()
47 const replay2 = replayable.createReplayStream()
48​
49 const reader1 = replay1.getReader()
50 const reader2 = replay2.getReader()
51​
52 // Read from both independently
53 const chunks1: Array<Uint8Array> = []
54 const chunks2: Array<Uint8Array> = []
55​
56 // Read first chunk from both
57 const r1c1 = await reader1.read()
58 const r2c1 = await reader2.read()
59 if (!r1c1.done) chunks1.push(r1c1.value)
60 if (!r2c1.done) chunks2.push(r2c1.value)
61​
62 // Read remaining from both
63 while (true) {
64 const { done, value } = await reader1.read()
65 if (done) break
66 chunks1.push(value)
67 }
68 while (true) {
69 const { done, value } = await reader2.read()
70 if (done) break
71 chunks2.push(value)
72 }
73​
74 // Both should have same data
75 expect(chunks1).toHaveLength(2)
76 expect(chunks2).toHaveLength(2)
77 expect(chunks1[0]).toEqual(new Uint8Array([10, 20]))
78 expect(chunks2[0]).toEqual(new Uint8Array([10, 20]))
79 })
80​
81 it('should support late subscribers (replay from beginning)', async () => {
82 let closeController: () => void = () => {}
83 const source = new ReadableStream<Uint8Array>({
84 start(controller) {
85 controller.enqueue(new Uint8Array([1]))
86 controller.enqueue(new Uint8Array([2]))
87 closeController = () => controller.close()
88 },
89 })
90​
91 const replayable = new ReplayableStream(source)
92​
93 // First consumer reads immediately
94 const replay1 = replayable.createReplayStream()
95 const reader1 = replay1.getReader()
96 await reader1.read() // Read first chunk
97​
98 // Wait a bit for buffering
99 await new Promise((r) => setTimeout(r, 10))
100​
101 // Close the source
102 closeController()
103​
104 // Late subscriber should still get all data from beginning
105 const replay2 = replayable.createReplayStream()
106 const reader2 = replay2.getReader()
107​
108 const chunks: Array<Uint8Array> = []
109 while (true) {
110 const { done, value } = await reader2.read()
111 if (done) break
112 chunks.push(value)
113 }
114​
115 expect(chunks).toHaveLength(2)
116 expect(chunks[0]).toEqual(new Uint8Array([1]))
117 expect(chunks[1]).toEqual(new Uint8Array([2]))
118 })
119​
120 it('should have REPLAYABLE_STREAM_MARKER', () => {
121 const source = new ReadableStream<Uint8Array>({
122 start(controller) {
123 controller.close()
124 },
125 })
126​
127 const replayable = new ReplayableStream(source)
128 expect(replayable[REPLAYABLE_STREAM_MARKER]).toBe(true)
129 })
130 })
131​
132 describe('abort handling', () => {
133 it('should abort immediately if signal already aborted', async () => {
134 const controller = new AbortController()
135 controller.abort()
136​
137 const source = new ReadableStream<Uint8Array>({
138 start(ctrl) {
139 ctrl.enqueue(new Uint8Array([1, 2, 3]))
140 ctrl.close()
141 },
142 })
143​
144 const replayable = new ReplayableStream(source, {
145 signal: controller.signal,
146 })
147 const replay = replayable.createReplayStream()
148 const reader = replay.getReader()
149​
150 // Should close immediately due to abort
151 const { done } = await reader.read()
152 expect(done).toBe(true)
153 })
154​
155 it('should close streams when abort signal fires', async () => {
156 const abortController = new AbortController()
157​
158 let enqueueFn: (chunk: Uint8Array) => void = () => {}
159 const source = new ReadableStream<Uint8Array>({
160 start(controller) {
161 enqueueFn = (chunk) => controller.enqueue(chunk)
162 },
163 })
164​
165 const replayable = new ReplayableStream(source, {
166 signal: abortController.signal,
167 })
168 const replay = replayable.createReplayStream()
169 const reader = replay.getReader()
170​
171 // Enqueue one chunk
172 enqueueFn(new Uint8Array([1]))
173​
174 // Read it
175 const { value, done } = await reader.read()
176 expect(done).toBe(false)
177 expect(value).toEqual(new Uint8Array([1]))
178​
179 // Abort
180 abortController.abort()
181​
182 // Next read should close (not error)
183 const result = await reader.read()
184 expect(result.done).toBe(true)
185 })
186​
187 it('should free memory on abort', async () => {
188 const abortController = new AbortController()
189​
190 const source = new ReadableStream<Uint8Array>({
191 start(controller) {
192 controller.enqueue(new Uint8Array(1000))
193 controller.enqueue(new Uint8Array(1000))
194 },
195 })
196​
197 const replayable = new ReplayableStream(source, {
198 signal: abortController.signal,
199 })
200​
201 // Wait for buffering
202 await new Promise((r) => setTimeout(r, 10))
203​
204 // Abort - should clear internal buffer
205 abortController.abort()
206​
207 // Creating new replay should return empty/closed stream
208 const replay = replayable.createReplayStream()
209 const reader = replay.getReader()
210 const { done } = await reader.read()
211 expect(done).toBe(true)
212 })
213 })
214​
215 describe('error handling', () => {
216 it('should propagate source stream errors to consumers', async () => {
217 let errorController: (err: Error) => void = () => {}
218​
219 const source = new ReadableStream<Uint8Array>({
220 start(controller) {
221 controller.enqueue(new Uint8Array([1]))
222 // Store error function to call later
223 errorController = (err) => controller.error(err)
224 },
225 })
226​
227 const replayable = new ReplayableStream(source)
228 const replay = replayable.createReplayStream()
229 const reader = replay.getReader()
230​
231 // First read succeeds
232 const { value, done } = await reader.read()
233 expect(done).toBe(false)
234 expect(value).toEqual(new Uint8Array([1]))
235​
236 // Now trigger the error
237 errorController(new Error('Source stream failed'))
238​
239 // Wait for error to propagate
240 await new Promise((r) => setTimeout(r, 10))
241​
242 // Next read should error
243 await expect(reader.read()).rejects.toThrow('Source stream failed')
244 })
245 })
246​
247 describe('async streaming', () => {
248 it('should handle slow source streams', async () => {
249 const source = new ReadableStream<Uint8Array>({
250 async pull(controller) {
251 await new Promise((r) => setTimeout(r, 10))
252 controller.enqueue(new Uint8Array([42]))
253 controller.close()
254 },
255 })
256​
257 const replayable = new ReplayableStream(source)
258 const replay = replayable.createReplayStream()
259 const reader = replay.getReader()
260​
261 const { value, done } = await reader.read()
262 expect(done).toBe(false)
263 expect(value).toEqual(new Uint8Array([42]))
264​
265 const { done: finalDone } = await reader.read()
266 expect(finalDone).toBe(true)
267 })
268​
269 it('should allow consumer to read faster than producer', async () => {
270 let enqueueCount = 0
271 const source = new ReadableStream<Uint8Array>({
272 start(controller) {
273 // Enqueue chunks slowly
274 const interval = setInterval(() => {
275 if (enqueueCount < 3) {
276 controller.enqueue(new Uint8Array([enqueueCount]))
277 enqueueCount++
278 } else {
279 clearInterval(interval)
280 controller.close()
281 }
282 }, 5)
283 },
284 })
285​
286 const replayable = new ReplayableStream(source)
287 const replay = replayable.createReplayStream()
288 const reader = replay.getReader()
289​
290 const chunks: Array<Uint8Array> = []
291 while (true) {
292 const { done, value } = await reader.read()
293 if (done) break
294 chunks.push(value)
295 }
296​
297 expect(chunks).toHaveLength(3)
298 expect(chunks[0]).toEqual(new Uint8Array([0]))
299 expect(chunks[1]).toEqual(new Uint8Array([1]))
300 expect(chunks[2]).toEqual(new Uint8Array([2]))
301 })
302 })
303​
304 describe('edge cases', () => {
305 it('should handle empty source stream', async () => {
306 const source = new ReadableStream<Uint8Array>({
307 start(controller) {
308 controller.close()
309 },
310 })
311​
312 const replayable = new ReplayableStream(source)
313 const replay = replayable.createReplayStream()
314 const reader = replay.getReader()
315​
316 const { done } = await reader.read()
317 expect(done).toBe(true)
318 })
319​
320 it('should handle large number of chunks', async () => {
321 const numChunks = 100
322​
323 const source = new ReadableStream<Uint8Array>({
324 start(controller) {
325 for (let i = 0; i < numChunks; i++) {
326 controller.enqueue(new Uint8Array([i % 256]))
327 }
328 controller.close()
329 },
330 })
331​
332 const replayable = new ReplayableStream(source)
333 const replay = replayable.createReplayStream()
334 const reader = replay.getReader()
335​
336 const chunks: Array<Uint8Array> = []
337 while (true) {
338 const { done, value } = await reader.read()
339 if (done) break
340 chunks.push(value)
341 }
342​
343 expect(chunks).toHaveLength(numChunks)
344 })
345​
346 it('should create multiple replay streams from same source', async () => {
347 const source = new ReadableStream<Uint8Array>({
348 start(controller) {
349 controller.enqueue(new Uint8Array([1, 2, 3]))
350 controller.close()
351 },
352 })
353​
354 const replayable = new ReplayableStream(source)
355​
356 // Create 5 replay streams
357 const replays = Array.from({ length: 5 }, () =>
358 replayable.createReplayStream(),
359 )
360​
361 // All should get same data
362 for (const replay of replays) {
363 const reader = replay.getReader()
364 const { value, done } = await reader.read()
365 expect(done).toBe(false)
366 expect(value).toEqual(new Uint8Array([1, 2, 3]))
367​
368 const { done: finalDone } = await reader.read()
369 expect(finalDone).toBe(true)
370 }
371 })
372 })
373​
374 describe('memory cleanup', () => {
375 it('should not auto-release (replays can come at unpredictable times)', async () => {
376 const source = new ReadableStream<Uint8Array>({
377 start(controller) {
378 controller.enqueue(new Uint8Array([1, 2, 3]))
379 controller.close()
380 },
381 })
382​
383 const replayable = new ReplayableStream(source)
384 expect(replayable.isReleased()).toBe(false)
385​
386 // Create and fully consume a replay stream
387 const replay = replayable.createReplayStream()
388 const reader = replay.getReader()
389 await reader.read() // Read chunk
390 await reader.read() // Read close
391​
392 // Wait for async operations
393 await new Promise((r) => setTimeout(r, 10))
394​
395 // Should NOT be auto-released (another replay might come later)
396 expect(replayable.isReleased()).toBe(false)
397​
398 // Can still create another replay
399 const replay2 = replayable.createReplayStream()
400 const reader2 = replay2.getReader()
401 const { value } = await reader2.read()
402 expect(value).toEqual(new Uint8Array([1, 2, 3]))
403 })
404​
405 it('should allow explicit release()', async () => {
406 const source = new ReadableStream<Uint8Array>({
407 start(controller) {
408 controller.enqueue(new Uint8Array([1, 2, 3]))
409 controller.close()
410 },
411 })
412​
413 const replayable = new ReplayableStream(source)
414 await new Promise((r) => setTimeout(r, 10)) // Wait for buffering
415​
416 expect(replayable.isReleased()).toBe(false)
417​
418 replayable.release()
419​
420 expect(replayable.isReleased()).toBe(true)
421 })
422​
423 it('should return empty stream after release()', async () => {
424 const source = new ReadableStream<Uint8Array>({
425 start(controller) {
426 controller.enqueue(new Uint8Array([1, 2, 3]))
427 controller.close()
428 },
429 })
430​
431 const replayable = new ReplayableStream(source)
432 await new Promise((r) => setTimeout(r, 10))
433​
434 // Release explicitly
435 replayable.release()
436​
437 // New replay should return empty/closed stream
438 const replay = replayable.createReplayStream()
439 const reader = replay.getReader()
440 const { done } = await reader.read()
441 expect(done).toBe(true)
442 })
443​
444 it('should cancel upstream when release() is called', async () => {
445 let canceledReason: unknown
446 let resolveCancel: () => void
447 const cancelCalled = new Promise<void>((resolve) => {
448 resolveCancel = resolve
449 })
450​
451 const source = new ReadableStream<Uint8Array>({
452 start(controller) {
453 controller.enqueue(new Uint8Array([1]))
454 },
455 cancel(reason) {
456 canceledReason = reason
457 resolveCancel()
458 },
459 })
460​
461 const replayable = new ReplayableStream(source)
462​
463 // Ensure the pump reads at least one chunk.
464 const replay = replayable.createReplayStream()
465 const replayReader = replay.getReader()
466 await replayReader.read()
467​
468 replayable.release()
469 await cancelCalled
470​
471 expect(canceledReason).toBeInstanceOf(Error)
472 })
473​
474 it('should close active replay stream when release() is called mid-stream', async () => {
475 const source = new ReadableStream<Uint8Array>({
476 start(controller) {
477 controller.enqueue(new Uint8Array([1]))
478 controller.enqueue(new Uint8Array([2]))
479 controller.close()
480 },
481 })
482​
483 const replayable = new ReplayableStream(source)
484 await new Promise((r) => setTimeout(r, 10))
485​
486 // Create replay and read first chunk
487 const replay = replayable.createReplayStream()
488 const reader = replay.getReader()
489 await reader.read() // Read first chunk
490​
491 // Release mid-stream
492 replayable.release()
493​
494 // Next read should get close (stream closed early)
495 const { done } = await reader.read()
496 expect(done).toBe(true)
497​
498 expect(replayable.isReleased()).toBe(true)
499 })
500​
501 it('should support multiple sequential replays before release', async () => {
502 const source = new ReadableStream<Uint8Array>({
503 start(controller) {
504 controller.enqueue(new Uint8Array([1]))
505 controller.close()
506 },
507 })
508​
509 const replayable = new ReplayableStream(source)
510 await new Promise((r) => setTimeout(r, 10))
511​
512 // First replay - full read
513 const replay1 = replayable.createReplayStream()
514 const reader1 = replay1.getReader()
515 await reader1.read()
516 await reader1.read()
517​
518 // Should not be released
519 expect(replayable.isReleased()).toBe(false)
520​
521 // Second replay - full read
522 const replay2 = replayable.createReplayStream()
523 const reader2 = replay2.getReader()
524 const { value } = await reader2.read()
525 expect(value).toEqual(new Uint8Array([1]))
526 await reader2.read()
527​
528 // Still not released
529 expect(replayable.isReleased()).toBe(false)
530​
531 // Now release
532 replayable.release()
533 expect(replayable.isReleased()).toBe(true)
534 })
535 })
536})