Open History to see the last commit
1'use client'
2β
3import { createElement } from 'react'
4import { RscNodeRenderer } from './RscNodeRenderer'
5import {
6 RENDERABLE_RSC,
7 RSC_PROXY_GET_TREE,
8 RSC_PROXY_PATH,
9 RSC_SLOT_USAGES,
10 RSC_SLOT_USAGES_STREAM,
11 SERVER_COMPONENT_CSS_HREFS,
12 SERVER_COMPONENT_JS_PRELOADS,
13 SERVER_COMPONENT_STREAM,
14} from './ServerComponentTypes'
15import type { RscSlotUsageEvent } from './ServerComponentTypes'
16β
17export interface RscProxyOptions {
18 stream?: unknown // The stream to attach for serialization
19 cssHrefs?: ReadonlySet<string> // CSS hrefs collected from the RSC stream
20 jsPreloads?: ReadonlySet<string> // JS hrefs collected from the RSC stream
21 renderable?: boolean // If true, proxy masquerades as React element
22 slotUsagesStream?: ReadableStream<RscSlotUsageEvent> // Dev only: slot usage event stream
23}
24β
25/**
26 * Creates a recursive Proxy for RSC data.
27 *
28 * If `renderable: true`, returns a React element that can be rendered as `{data}`.
29 * The element also has proxy-like behavior for nested access like `data.foo.bar`.
30 *
31 * If `renderable: false` (default), the proxy is NOT directly renderable and
32 * must be used with `<CompositeComponent src={...} />`.
33 */
34export function createRscProxy<T>(
35 getTree: () => T,
36 options: RscProxyOptions = {},
37): any {
38 if (options.renderable) {
39 // For renderable mode, create a real React element with proxy access
40 return createRenderableElement(
41 getTree,
42 [],
43 options.stream,
44 options.cssHrefs,
45 options.jsPreloads,
46 )
47 }
48 let slotUsages: Array<RscSlotUsageEvent> | undefined = undefined
49β
50 if (
51 process.env.NODE_ENV === 'development' &&
52 typeof window !== 'undefined' &&
53 options.slotUsagesStream
54 ) {
55 slotUsages = []
56 void consumeSlotUsages(options.slotUsagesStream, slotUsages)
57 }
58β
59 // Non-renderable mode: plain proxy
60 return createRscProxyWithPath(
61 getTree,
62 [],
63 options.stream,
64 options.cssHrefs,
65 options.jsPreloads,
66 slotUsages,
67 options.slotUsagesStream,
68 )
69}
70β
71/**
72 * Creates a React element that's also a Proxy for nested access.
73 * This is used by renderable RSCs so they work as both {data} and {data.foo.bar}.
74 */
75type CreateProxyOptions = {
76 getTree: () => unknown
77 path: Array<string>
78 stream: unknown | undefined
79 cssHrefs: ReadonlySet<string> | undefined
80 jsPreloads: ReadonlySet<string> | undefined
81 renderable: boolean
82 slotUsages: Array<RscSlotUsageEvent> | undefined
83 slotUsagesStream: ReadableStream<RscSlotUsageEvent> | undefined
84}
85β
86const UNHANDLED = Symbol('tanstack.rsc.proxy.unhandled')
87β
88function handleProxyTrap(
89 kind: 'get' | 'has',
90 prop: PropertyKey,
91 options: CreateProxyOptions,
92): unknown | boolean | typeof UNHANDLED {
93 switch (prop) {
94 // Seroval (>=1.5) uses string sentinels and `in` checks for internal types.
95 // These proxies must never look like streams/sequences.
96 case '__SEROVAL_STREAM__':
97 case '__SEROVAL_SEQUENCE__':
98 return kind === 'get' ? undefined : false
99β
100 // Seroval >=1.5 also checks iterability via `Symbol.iterator in value`.
101 case Symbol.iterator:
102 case Symbol.asyncIterator:
103 return kind === 'get' ? undefined : false
104β
105 // Our proxy branding/properties
106 case SERVER_COMPONENT_STREAM:
107 return kind === 'get' ? options.stream : options.stream !== undefined
108 case SERVER_COMPONENT_CSS_HREFS:
109 return kind === 'get' ? options.cssHrefs : options.cssHrefs !== undefined
110 case SERVER_COMPONENT_JS_PRELOADS:
111 return kind === 'get'
112 ? options.jsPreloads
113 : options.jsPreloads !== undefined
114 case RSC_PROXY_GET_TREE:
115 return kind === 'get' ? options.getTree : true
116 case RSC_PROXY_PATH:
117 return kind === 'get' ? options.path : true
118 case RENDERABLE_RSC:
119 return kind === 'get' ? options.renderable : true
120 case RSC_SLOT_USAGES:
121 return kind === 'get'
122 ? options.slotUsages
123 : options.slotUsages !== undefined
124β
125 case RSC_SLOT_USAGES_STREAM:
126 return kind === 'get'
127 ? options.slotUsagesStream
128 : options.slotUsagesStream !== undefined
129β
130 // Avoid promise-like checks
131 case 'then':
132 return kind === 'get' ? undefined : UNHANDLED
133β
134 // Avoid breaking primitive coercion (eg String(proxy)).
135 // Without these, nested-selection proxies can shadow these keys and
136 // cause `Cannot convert object to primitive value` errors.
137 case 'toString':
138 return kind === 'get' ? Object.prototype.toString : UNHANDLED
139 case 'valueOf':
140 return kind === 'get' ? Object.prototype.valueOf : UNHANDLED
141 case 'constructor':
142 return kind === 'get' ? Object : UNHANDLED
143 }
144β
145 // Non-renderable proxies claim all string keys exist for nested selection,
146 // but symbol presence checks should be accurate.
147 if (typeof prop === 'symbol') {
148 return kind === 'get' ? undefined : false
149 }
150β
151 return UNHANDLED
152}
153β
154function createRscProxyInternal(options: CreateProxyOptions): any {
155 // Per-proxy cache so repeated property access is referentially stable.
156 const childCache = new Map<string, any>()
157β
158 const getChild = (key: string) => {
159 const cached = childCache.get(key)
160 if (cached) return cached
161β
162 const next = createRscProxyInternal({
163 ...options,
164 path: [...options.path, key],
165 })
166 childCache.set(key, next)
167 return next
168 }
169β
170 const dataProxy = options.renderable
171 ? createRscProxyInternal({ ...options, renderable: false })
172 : undefined
173β
174 // Use a React element (renderable) or plain object (non-renderable) as Proxy target.
175 const proxyTarget = options.renderable
176 ? createElement(RscNodeRenderer, { data: dataProxy })
177 : ({} as any)
178β
179 return new Proxy(proxyTarget, {
180 get(target, prop) {
181 const handled = handleProxyTrap('get', prop, options)
182 if (handled !== UNHANDLED) return handled
183β
184 if (options.renderable) {
185 // Proxy invariants: if target has a non-configurable, read-only property,
186 // we must return the *exact* value for that property.
187 if (prop === 'props') {
188 return target.props
189 }
190β
191 if (prop === 'data') {
192 return dataProxy
193 }
194β
195 if (prop in target) {
196 return target[prop]
197 }
198 }
199β
200 return getChild(String(prop))
201 },
202β
203 has(target, prop) {
204 const handled = handleProxyTrap('has', prop, options)
205 if (handled !== UNHANDLED) return handled as boolean
206β
207 if (options.renderable) {
208 if (prop in target) return true
209 if (typeof prop === 'string') return true
210 return false
211 }
212β
213 // Allow any property access for nested selection.
214 return true
215 },
216β
217 getPrototypeOf(target) {
218 return options.renderable
219 ? Object.getPrototypeOf(target)
220 : Object.prototype
221 },
222β
223 getOwnPropertyDescriptor(target, prop) {
224 return options.renderable
225 ? Object.getOwnPropertyDescriptor(target, prop)
226 : undefined
227 },
228β
229 ownKeys(target) {
230 return options.renderable ? Reflect.ownKeys(target) : []
231 },
232 })
233}
234β
235/**
236 * Creates a React element that's also a Proxy for nested access.
237 * This is used by renderable RSCs so they work as both {data} and {data.foo.bar}.
238 */
239function createRenderableElement(
240 getTree: () => unknown,
241 path: Array<string>,
242 stream: unknown | undefined,
243 cssHrefs: ReadonlySet<string> | undefined,
244 jsPreloads: ReadonlySet<string> | undefined,
245): any {
246 return createRscProxyInternal({
247 getTree,
248 path,
249 stream,
250 cssHrefs,
251 jsPreloads,
252 renderable: true,
253 slotUsages: undefined,
254 slotUsagesStream: undefined,
255 })
256}
257β
258function createRscProxyWithPath(
259 getTree: () => unknown,
260 path: Array<string>,
261 stream: unknown | undefined,
262 cssHrefs: ReadonlySet<string> | undefined,
263 jsPreloads: ReadonlySet<string> | undefined,
264 slotUsages: Array<RscSlotUsageEvent> | undefined,
265 slotUsagesStream: ReadableStream<RscSlotUsageEvent> | undefined,
266): any {
267 return createRscProxyInternal({
268 getTree,
269 path,
270 stream,
271 cssHrefs,
272 jsPreloads,
273 renderable: false,
274 slotUsages,
275 slotUsagesStream,
276 })
277}
278β
279async function consumeSlotUsages(
280 stream: ReadableStream<RscSlotUsageEvent>,
281 slotUsages: Array<RscSlotUsageEvent>,
282): Promise<void> {
283 try {
284 const reader = stream.getReader()
285 for (;;) {
286 const { value, done } = await reader.read()
287 if (done) break
288 if (!value.slot) continue
289 slotUsages.push(value)
290 }
291 } catch {
292 // Ignore - dev-only best effort
293 }
294}