Open History to see the last commit
1/**
2 * ReplayableStream is used for React Server Components (RSC) / Flight streams.
3 *
4 * In this package the same Flight payload may need to be:
5 * - decoded for SSR (render path), and/or
6 * - serialized for transport to the client for client-side decoding.
7 *
8 * Call sites:
9 * - `src/createServerComponent.ts`: wraps the produced Flight stream once.
10 * - `src/serialization.ts`: uses `createReplayStream()` to transport a fresh stream
11 * to the client via `RawStream`.
12 *
13 * Constraints:
14 * - Consumption order isn't fixed: SSR decode might start first or transport might
15 * start first depending on the request path.
16 * - Sometimes only one happens (e.g. when client calls server function directly).
17 *
18 * Why not just `ReadableStream.tee()`?
19 * - tee() must be called up-front before the stream is consumed/locked and only
20 * creates two live branches (no late "replay from byte 0").
21 * - If one branch is slower or never consumed, the runtime may buffer internally
22 * to keep branches consistent, which can retain large Flight payloads longer
23 * than intended and makes cleanup less explicit.
24 *
25 * ReplayableStream reads once, buffers explicitly, can mint replay streams on
26 * demand, and centralizes cancellation so aborting can stop upstream work and
27 * free buffered data deterministically.
28 *
29 * Memory Management:
30 * - Memory is released when the abort signal fires (request cancelled)
31 * - Call `release()` to force immediate cleanup if no more replays are needed
32 * - No automatic release: replays can be created at unpredictable times (SSR decode
33 * finishes before serialization starts), so we can't safely auto-release
34 */
35β
36export interface ReplayableStreamOptions {
37 signal?: AbortSignal
38}
39β
40// Use Symbol.for to ensure the same symbol across different module instances
41export const REPLAYABLE_STREAM_MARKER = Symbol.for(
42 'tanstack.rsc.ReplayableStream',
43)
44β
45export class ReplayableStream<T = Uint8Array> {
46 // Marker for cross-environment instance checking
47 readonly [REPLAYABLE_STREAM_MARKER] = true
48β
49 private chunks: Array<T> = []
50 private done = false
51 private error: unknown = null
52 private waiter: PromiseWithResolvers<void> | null = null
53 private aborted = false
54 private released = false
55β
56 private sourceReader: ReadableStreamDefaultReader<T> | null = null
57 private abortSignal: AbortSignal | undefined
58 private abortListener: (() => void) | null = null
59β
60 constructor(
61 private source: ReadableStream<T>,
62 private options: ReplayableStreamOptions = {},
63 ) {
64 this.abortSignal = options.signal
65 this.start()
66 }
67β
68 private start(): void {
69 const signal = this.abortSignal
70β
71 if (signal?.aborted) {
72 this.handleAbort()
73 return
74 }
75β
76 const onAbort = () => this.handleAbort()
77 this.abortListener = onAbort
78 signal?.addEventListener('abort', onAbort, { once: true })
79β
80 const reader = this.source.getReader()
81 this.sourceReader = reader
82β
83 const pump = async () => {
84 try {
85 // Keep reading until upstream ends or we are stopped.
86 while (!this.aborted && !this.released) {
87 const { done, value } = await reader.read()
88 if (done) break
89 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
90 if (this.aborted || this.released) break
91 this.chunks.push(value)
92 this.notify()
93 }
94 this.done = true
95 } catch (err) {
96 if (!this.aborted && !this.released) {
97 this.error = err
98 }
99 this.done = true
100 } finally {
101 this.detachAbortListener()
102 try {
103 reader.releaseLock()
104 } catch {
105 // Ignore
106 }
107 if (this.sourceReader === reader) {
108 this.sourceReader = null
109 }
110 this.notify()
111 }
112 }
113β
114 pump()
115 }
116β
117 private detachAbortListener(): void {
118 const signal = this.abortSignal
119 const listener = this.abortListener
120 if (signal && listener) {
121 signal.removeEventListener('abort', listener)
122 }
123 this.abortListener = null
124 }
125β
126 private cancelSource(reason: unknown): void {
127 const reader = this.sourceReader
128 this.sourceReader = null
129β
130 try {
131 reader?.cancel(reason).catch(() => {})
132 } catch {
133 // Ignore
134 }
135 }
136β
137 private handleAbort(): void {
138 if (this.aborted) return
139 this.aborted = true
140 this.done = true
141β
142 // Try to stop upstream work immediately.
143 // Cancellation during an abort can throw synchronously in some runtimes
144 // (eg when the underlying cancel algorithm throws). Never let that escape
145 // an AbortSignal event handler.
146 const reason =
147 this.abortSignal?.reason ?? new Error('ReplayableStream aborted')
148β
149 this.detachAbortListener()
150 this.abortSignal = undefined
151 this.cancelSource(reason)
152β
153 this.chunks = [] // Free memory immediately on abort
154 this.released = true
155 this.notify()
156 }
157β
158 private notify(): void {
159 if (this.waiter) {
160 this.waiter.resolve()
161 this.waiter = null
162 }
163 }
164β
165 private wait(): Promise<void> {
166 if (this.done || this.released) return Promise.resolve()
167 if (!this.waiter) {
168 this.waiter = Promise.withResolvers<void>()
169 }
170 return this.waiter.promise
171 }
172β
173 /**
174 * Explicitly release buffered chunks.
175 * Call this when you know no more replay streams will be created.
176 * After calling release(), createReplayStream() will return empty streams.
177 */
178 release(): void {
179 if (this.released) return
180β
181 this.released = true
182 this.chunks = []
183β
184 // Release should also stop upstream work and wake any waiters.
185 // This is important when a Flight payload is never consumed again
186 // (eg. cached loader data that evicts) to avoid retaining upstream resources.
187 this.detachAbortListener()
188 this.abortSignal = undefined
189 this.cancelSource(new Error('ReplayableStream released'))
190 this.notify()
191 }
192β
193 /**
194 * Check if the stream data has been released
195 */
196 isReleased(): boolean {
197 return this.released
198 }
199β
200 /**
201 * Create an independent replay stream. Each call returns a fresh reader
202 * that starts from the beginning of the buffered data.
203 *
204 * If the stream has been released, returns a stream that closes immediately.
205 */
206 createReplayStream(): ReadableStream<T> {
207 if (this.released) {
208 return new ReadableStream<T>({
209 start(controller) {
210 controller.close()
211 },
212 })
213 }
214β
215 let index = 0
216β
217 return new ReadableStream<T>({
218 pull: async (controller) => {
219 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
220 while (true) {
221 if (this.released) {
222 controller.close()
223 return
224 }
225β
226 if (index < this.chunks.length) {
227 controller.enqueue(this.chunks[index++] as T)
228 return
229 }
230β
231 if (this.done) {
232 if (this.error && !this.aborted) {
233 controller.error(this.error)
234 } else {
235 controller.close()
236 }
237 return
238 }
239β
240 await this.wait()
241 }
242 },
243 cancel: () => {
244 // No-op: consumers canceling a replay should not cancel upstream.
245 // Upstream cancellation is controlled by abort/release.
246 },
247 })
248 }
249}