Open History to see the last commit
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})