@timber-js/app 0.2.0-alpha.240 → 0.2.0-alpha.242

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (408) hide show
  1. package/dist/_chunks/{actions-DIgnvDrG.js → actions-BkwgRwCl.js} +146 -12
  2. package/dist/_chunks/actions-BkwgRwCl.js.map +1 -0
  3. package/dist/_chunks/{als-registry-PPYstxK0.js → als-registry-C-iwbtvI.js} +4 -3
  4. package/dist/_chunks/{als-registry-PPYstxK0.js.map → als-registry-C-iwbtvI.js.map} +1 -1
  5. package/dist/_chunks/{als-slots-kbQrHTzm.js → als-slots-CVTF-AMz.js} +3 -3
  6. package/dist/_chunks/als-slots-CVTF-AMz.js.map +1 -0
  7. package/dist/_chunks/{cache-api-uWQwuxWb.js → cache-api-BGA7c5qJ.js} +5 -5
  8. package/dist/_chunks/{cache-api-uWQwuxWb.js.map → cache-api-BGA7c5qJ.js.map} +1 -1
  9. package/dist/_chunks/{chains-C7CExrUI.js → chains-Cuwwjv6T.js} +2 -2
  10. package/dist/_chunks/{chains-C7CExrUI.js.map → chains-Cuwwjv6T.js.map} +1 -1
  11. package/dist/_chunks/chains-LGjBHfSN.js +1 -0
  12. package/dist/_chunks/{classify-Cj9EeZoL.js → classify-Y8S9C0Na.js} +2 -2
  13. package/dist/_chunks/{classify-Cj9EeZoL.js.map → classify-Y8S9C0Na.js.map} +1 -1
  14. package/dist/_chunks/{cli-check-C3QOAru7.js → cli-check-KeE1QaIx.js} +7 -6
  15. package/dist/_chunks/cli-check-KeE1QaIx.js.map +1 -0
  16. package/dist/_chunks/{cli-schema-sync-DQUS_o3V.js → cli-schema-sync-DZEF31wd.js} +2 -2
  17. package/dist/_chunks/{cli-schema-sync-DQUS_o3V.js.map → cli-schema-sync-DZEF31wd.js.map} +1 -1
  18. package/dist/_chunks/{cli-schema-sync-BRxZz66D.js → cli-schema-sync-_y5O6MIg.js} +1 -1
  19. package/dist/_chunks/{client-dep-entries-ZETBdLgv.js → client-dep-entries-DpiwvoDi.js} +2 -2
  20. package/dist/_chunks/{client-dep-entries-ZETBdLgv.js.map → client-dep-entries-DpiwvoDi.js.map} +1 -1
  21. package/dist/_chunks/{cloudflare-Dk5Hqo-O.js → cloudflare-9dbhVOxS.js} +2 -2
  22. package/dist/_chunks/{cloudflare-Dk5Hqo-O.js.map → cloudflare-9dbhVOxS.js.map} +1 -1
  23. package/dist/_chunks/{convention-lint-BoVISNS6.js → convention-lint-0AEsPK2T.js} +378 -10
  24. package/dist/_chunks/convention-lint-0AEsPK2T.js.map +1 -0
  25. package/dist/_chunks/dev-server-CboXr8zX.js +1 -0
  26. package/dist/_chunks/{dev-server-C5R6jx8Q.js → dev-server-DYDr8KIc.js} +9 -3
  27. package/dist/_chunks/dev-server-DYDr8KIc.js.map +1 -0
  28. package/dist/_chunks/{dist-C1Rjlo6s.js → dist-GyaJm4GA.js} +18 -2
  29. package/dist/_chunks/dist-GyaJm4GA.js.map +1 -0
  30. package/dist/_chunks/{error-boundary-DB51f9ih.js → error-boundary-wuNvAJ4n.js} +11 -14
  31. package/dist/_chunks/error-boundary-wuNvAJ4n.js.map +1 -0
  32. package/dist/_chunks/{flight-source-node-D9cHBhjP.js → flight-source-node-KQsX_OhS.js} +4 -7
  33. package/dist/_chunks/flight-source-node-KQsX_OhS.js.map +1 -0
  34. package/dist/_chunks/{json-lossy-check-Y1GxqVX_.js → json-lossy-check-BVDALqMf.js} +2 -2
  35. package/dist/_chunks/{json-lossy-check-Y1GxqVX_.js.map → json-lossy-check-BVDALqMf.js.map} +1 -1
  36. package/dist/_chunks/key-headers-uIig1_mU.js +40 -0
  37. package/dist/_chunks/key-headers-uIig1_mU.js.map +1 -0
  38. package/dist/_chunks/{live-graph-BDQWvnMm.js → live-graph-VhzO7Ol9.js} +4 -4
  39. package/dist/_chunks/{live-graph-BDQWvnMm.js.map → live-graph-VhzO7Ol9.js.map} +1 -1
  40. package/dist/_chunks/{logger-DmRR9tmZ.js → logger-C4m8rfMy.js} +2 -2
  41. package/dist/_chunks/{logger-DmRR9tmZ.js.map → logger-C4m8rfMy.js.map} +1 -1
  42. package/dist/_chunks/metadata-routes-MXNjWOt5.js.map +1 -1
  43. package/dist/_chunks/{node-response-yp8zdyRp.js → node-response-8Vz29cGS.js} +2 -2
  44. package/dist/_chunks/{node-response-yp8zdyRp.js.map → node-response-8Vz29cGS.js.map} +1 -1
  45. package/dist/_chunks/{poison-scan-WQgUydF_.js → poison-scan-Dpl3ibG-.js} +2 -2
  46. package/dist/_chunks/{poison-scan-WQgUydF_.js.map → poison-scan-Dpl3ibG-.js.map} +1 -1
  47. package/dist/_chunks/{rsc-cache-key-D0cb0Gmc.js → rsc-cache-key-BGvUtMtN.js} +40 -4
  48. package/dist/_chunks/{rsc-cache-key-D0cb0Gmc.js.map → rsc-cache-key-BGvUtMtN.js.map} +1 -1
  49. package/dist/_chunks/{scanner-C9Lrf77z.js → scanner-CCEHN9Jg.js} +14 -81
  50. package/dist/_chunks/scanner-CCEHN9Jg.js.map +1 -0
  51. package/dist/_chunks/{sizeof-BISkSaU0.js → sizeof-CIF7fwSJ.js} +2 -2
  52. package/dist/_chunks/{sizeof-BISkSaU0.js.map → sizeof-CIF7fwSJ.js.map} +1 -1
  53. package/dist/_chunks/{walkers-Bxv4v7tX.js → walkers-BbotBhNG.js} +3 -3
  54. package/dist/_chunks/{walkers-Bxv4v7tX.js.map → walkers-BbotBhNG.js.map} +1 -1
  55. package/dist/adapters/cloudflare-dev.js +1 -1
  56. package/dist/adapters/cloudflare-kv-cache.js +2 -2
  57. package/dist/adapters/cloudflare.js +1 -1
  58. package/dist/analyze/crawl-entry.js +3 -3
  59. package/dist/analyze/graph-command.js +2 -2
  60. package/dist/cache/index.js +2 -2
  61. package/dist/cache/stores/memory.js +1 -1
  62. package/dist/cdn/workers-cache-purge.js +1 -1
  63. package/dist/cli-check.d.ts +3 -0
  64. package/dist/cli-check.d.ts.map +1 -1
  65. package/dist/cli.js +3 -3
  66. package/dist/client/browser-entry/router-init.d.ts +0 -1
  67. package/dist/client/browser-entry/router-init.d.ts.map +1 -1
  68. package/dist/client/error-boundary.js +1 -1
  69. package/dist/client/index.js +2 -2
  70. package/dist/client/index.js.map +1 -1
  71. package/dist/client/internal.js +4 -5
  72. package/dist/client/internal.js.map +1 -1
  73. package/dist/client/navigation-commit.d.ts +3 -5
  74. package/dist/client/navigation-commit.d.ts.map +1 -1
  75. package/dist/client/outlet-content-cache.d.ts +25 -30
  76. package/dist/client/outlet-content-cache.d.ts.map +1 -1
  77. package/dist/client/outlet-scope-context.d.ts +4 -4
  78. package/dist/client/outlet-scope-context.d.ts.map +1 -1
  79. package/dist/client/params-context.d.ts +1 -1
  80. package/dist/client/router-types.d.ts +3 -13
  81. package/dist/client/router-types.d.ts.map +1 -1
  82. package/dist/client/router.d.ts.map +1 -1
  83. package/dist/client/segment-cache.d.ts +2 -2
  84. package/dist/client/segment-outlet.d.ts +12 -13
  85. package/dist/client/segment-outlet.d.ts.map +1 -1
  86. package/dist/client/stale-segment.d.ts +2 -2
  87. package/dist/config-types.d.ts +22 -15
  88. package/dist/config-types.d.ts.map +1 -1
  89. package/dist/config-validation.d.ts.map +1 -1
  90. package/dist/cookies/define-cookie.d.ts.map +1 -1
  91. package/dist/cookies/index.js +5 -2
  92. package/dist/cookies/index.js.map +1 -1
  93. package/dist/index.d.ts +1 -0
  94. package/dist/index.d.ts.map +1 -1
  95. package/dist/index.js +109 -26
  96. package/dist/index.js.map +1 -1
  97. package/dist/native/rsc/cookies/define-cookie.js +6 -2
  98. package/dist/native/rsc/cookies/define-cookie.js.map +1 -1
  99. package/dist/native/rsc/manifest.json +12 -4
  100. package/dist/native/rsc/routing/segment-keys.js +11 -1
  101. package/dist/native/rsc/routing/segment-keys.js.map +1 -1
  102. package/dist/native/rsc/search-params/define.js +4 -1
  103. package/dist/native/rsc/search-params/define.js.map +1 -1
  104. package/dist/native/rsc/server/als-registry.js +2 -2
  105. package/dist/native/rsc/server/als-registry.js.map +1 -1
  106. package/dist/native/rsc/server/client-state-tree.js +13 -12
  107. package/dist/native/rsc/server/client-state-tree.js.map +1 -1
  108. package/dist/native/rsc/server/cookie-context.js +12 -0
  109. package/dist/native/rsc/server/cookie-context.js.map +1 -1
  110. package/dist/native/rsc/server/flight-source-node.js +2 -5
  111. package/dist/native/rsc/server/flight-source-node.js.map +1 -1
  112. package/dist/native/rsc/server/flight-source.js +8 -40
  113. package/dist/native/rsc/server/flight-source.js.map +1 -1
  114. package/dist/native/rsc/server/framework-stack-frames.js +18 -0
  115. package/dist/native/rsc/server/framework-stack-frames.js.map +1 -0
  116. package/dist/native/rsc/server/prebuilt-builder.js +15 -1
  117. package/dist/native/rsc/server/prebuilt-builder.js.map +1 -1
  118. package/dist/native/rsc/server/request-context.js +11 -5
  119. package/dist/native/rsc/server/request-context.js.map +1 -1
  120. package/dist/native/rsc/server/route-element-builder.js +29 -11
  121. package/dist/native/rsc/server/route-element-builder.js.map +1 -1
  122. package/dist/native/rsc/server/route-module-loader.js +14 -6
  123. package/dist/native/rsc/server/route-module-loader.js.map +1 -1
  124. package/dist/native/rsc/server/rsc-cache-key-guard.js +5 -1
  125. package/dist/native/rsc/server/rsc-cache-key-guard.js.map +1 -1
  126. package/dist/native/rsc/server/rsc-entry/render-route.js +10 -29
  127. package/dist/native/rsc/server/rsc-entry/render-route.js.map +1 -1
  128. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js +7 -2
  129. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js.map +1 -1
  130. package/dist/native/rsc/server/rsc-entry/rsc-stream.js +2 -5
  131. package/dist/native/rsc/server/rsc-entry/rsc-stream.js.map +1 -1
  132. package/dist/native/rsc/server/segment-lifetime/document-outlet.js +24 -0
  133. package/dist/native/rsc/server/segment-lifetime/document-outlet.js.map +1 -0
  134. package/dist/native/rsc/server/segment-lifetime/key-digest.js +74 -0
  135. package/dist/native/rsc/server/segment-lifetime/key-digest.js.map +1 -0
  136. package/dist/native/rsc/server/segment-lifetime/outlet-gate.js +44 -0
  137. package/dist/native/rsc/server/segment-lifetime/outlet-gate.js.map +1 -0
  138. package/dist/native/rsc/server/segment-lifetime/read-rule.js +78 -0
  139. package/dist/native/rsc/server/segment-lifetime/read-rule.js.map +1 -0
  140. package/dist/native/rsc/server/segment-lifetime/read-scope.js +41 -0
  141. package/dist/native/rsc/server/segment-lifetime/read-scope.js.map +1 -0
  142. package/dist/native/rsc/server/segment-lifetime/segment-key.js +64 -0
  143. package/dist/native/rsc/server/segment-lifetime/segment-key.js.map +1 -0
  144. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js +72 -0
  145. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js.map +1 -0
  146. package/dist/native/rsc/server/slot-resolver.js +51 -27
  147. package/dist/native/rsc/server/slot-resolver.js.map +1 -1
  148. package/dist/native/rsc/server/slot-subtree-contain.js +17 -89
  149. package/dist/native/rsc/server/slot-subtree-contain.js.map +1 -1
  150. package/dist/native/rsc/server/subtree-walk.js +140 -0
  151. package/dist/native/rsc/server/subtree-walk.js.map +1 -0
  152. package/dist/native/rsc/server/vite-handoff-rsc.js.map +1 -1
  153. package/dist/native/rsc/shared/als-slots.js +2 -2
  154. package/dist/native/rsc/shared/als-slots.js.map +1 -1
  155. package/dist/native/rsc/shared/cookie-read-through.js +5 -0
  156. package/dist/native/rsc/shared/cookie-read-through.js.map +1 -0
  157. package/dist/native/rsc/shared/key-headers.js +20 -0
  158. package/dist/native/rsc/shared/key-headers.js.map +1 -0
  159. package/dist/native/rsc/shared/outlet-decision.js.map +1 -1
  160. package/dist/native/rsc/shared/route-options-export.js +8 -0
  161. package/dist/native/rsc/shared/route-options-export.js.map +1 -0
  162. package/dist/native/rsc/shared/rsc-cache-key.js +19 -3
  163. package/dist/native/rsc/shared/rsc-cache-key.js.map +1 -1
  164. package/dist/native/rsc/shims/headers.js +3 -4
  165. package/dist/native/rsc/shims/headers.js.map +1 -1
  166. package/dist/native/ssr/client/outlet-content-cache.js +12 -18
  167. package/dist/native/ssr/client/outlet-content-cache.js.map +1 -1
  168. package/dist/native/ssr/client/outlet-scope-context.js.map +1 -1
  169. package/dist/native/ssr/client/segment-outlet.js +6 -19
  170. package/dist/native/ssr/client/segment-outlet.js.map +1 -1
  171. package/dist/native/ssr/cookies/define-cookie.js +6 -2
  172. package/dist/native/ssr/cookies/define-cookie.js.map +1 -1
  173. package/dist/native/ssr/manifest.json +5 -1
  174. package/dist/native/ssr/search-params/define.js +4 -1
  175. package/dist/native/ssr/search-params/define.js.map +1 -1
  176. package/dist/native/ssr/server/als-registry.js +2 -2
  177. package/dist/native/ssr/server/als-registry.js.map +1 -1
  178. package/dist/native/ssr/server/client-state-tree.js +13 -12
  179. package/dist/native/ssr/server/client-state-tree.js.map +1 -1
  180. package/dist/native/ssr/server/cookie-context.js +12 -0
  181. package/dist/native/ssr/server/cookie-context.js.map +1 -1
  182. package/dist/native/ssr/server/flight-source-node.js +2 -5
  183. package/dist/native/ssr/server/flight-source-node.js.map +1 -1
  184. package/dist/native/ssr/server/flight-source.js +1 -1
  185. package/dist/native/ssr/server/flight-source.js.map +1 -1
  186. package/dist/native/ssr/server/framework-stack-frames.js +18 -0
  187. package/dist/native/ssr/server/framework-stack-frames.js.map +1 -0
  188. package/dist/native/ssr/server/request-context.js +11 -5
  189. package/dist/native/ssr/server/request-context.js.map +1 -1
  190. package/dist/native/ssr/server/rsc-cache-key-guard.js +5 -1
  191. package/dist/native/ssr/server/rsc-cache-key-guard.js.map +1 -1
  192. package/dist/native/ssr/server/segment-lifetime/key-digest.js +6 -0
  193. package/dist/native/ssr/server/segment-lifetime/key-digest.js.map +1 -0
  194. package/dist/native/ssr/server/segment-lifetime/read-rule.js +78 -0
  195. package/dist/native/ssr/server/segment-lifetime/read-rule.js.map +1 -0
  196. package/dist/native/ssr/server/vite-handoff-rsc.js.map +1 -1
  197. package/dist/native/ssr/shared/als-slots.js +2 -2
  198. package/dist/native/ssr/shared/als-slots.js.map +1 -1
  199. package/dist/native/ssr/shared/cookie-read-through.js +5 -0
  200. package/dist/native/ssr/shared/cookie-read-through.js.map +1 -0
  201. package/dist/native/ssr/shared/key-headers.js +13 -0
  202. package/dist/native/ssr/shared/key-headers.js.map +1 -0
  203. package/dist/native/ssr/shared/rsc-cache-key.js +19 -3
  204. package/dist/native/ssr/shared/rsc-cache-key.js.map +1 -1
  205. package/dist/native/ssr/shims/headers.js +3 -4
  206. package/dist/native/ssr/shims/headers.js.map +1 -1
  207. package/dist/plugins/callsite-jsx.d.ts +8 -1
  208. package/dist/plugins/callsite-jsx.d.ts.map +1 -1
  209. package/dist/plugins/entries.d.ts.map +1 -1
  210. package/dist/plugins/prerender-sugar.d.ts +9 -8
  211. package/dist/plugins/prerender-sugar.d.ts.map +1 -1
  212. package/dist/plugins/routing.d.ts.map +1 -1
  213. package/dist/routing/convention-lint.d.ts +11 -3
  214. package/dist/routing/convention-lint.d.ts.map +1 -1
  215. package/dist/routing/export-detect.d.ts +50 -23
  216. package/dist/routing/export-detect.d.ts.map +1 -1
  217. package/dist/routing/index.js +2 -2
  218. package/dist/routing/route-options-lint.d.ts +36 -0
  219. package/dist/routing/route-options-lint.d.ts.map +1 -0
  220. package/dist/routing/route-options.d.ts +55 -0
  221. package/dist/routing/route-options.d.ts.map +1 -0
  222. package/dist/routing/segment-keys.d.ts +38 -4
  223. package/dist/routing/segment-keys.d.ts.map +1 -1
  224. package/dist/search-params/index.js +5 -2
  225. package/dist/search-params/index.js.map +1 -1
  226. package/dist/server/als-registry.d.ts +22 -13
  227. package/dist/server/als-registry.d.ts.map +1 -1
  228. package/dist/server/client-state-tree.d.ts +11 -10
  229. package/dist/server/client-state-tree.d.ts.map +1 -1
  230. package/dist/server/cookie-context.d.ts +3 -0
  231. package/dist/server/cookie-context.d.ts.map +1 -1
  232. package/dist/server/flight-source-node.d.ts +1 -6
  233. package/dist/server/flight-source-node.d.ts.map +1 -1
  234. package/dist/server/flight-source.d.ts +4 -28
  235. package/dist/server/flight-source.d.ts.map +1 -1
  236. package/dist/server/framework-stack-frames.d.ts +20 -0
  237. package/dist/server/framework-stack-frames.d.ts.map +1 -0
  238. package/dist/server/index.d.ts +1 -0
  239. package/dist/server/index.d.ts.map +1 -1
  240. package/dist/server/index.js +2 -2
  241. package/dist/server/internal.js +102 -28
  242. package/dist/server/internal.js.map +1 -1
  243. package/dist/server/prebuilt/capture-routes.d.ts +1 -1
  244. package/dist/server/prebuilt-builder.d.ts.map +1 -1
  245. package/dist/server/request-context.d.ts +6 -1
  246. package/dist/server/request-context.d.ts.map +1 -1
  247. package/dist/server/route-element-builder.d.ts +2 -2
  248. package/dist/server/route-element-builder.d.ts.map +1 -1
  249. package/dist/server/route-module-loader.d.ts +10 -2
  250. package/dist/server/route-module-loader.d.ts.map +1 -1
  251. package/dist/server/rsc-cache-key-guard.d.ts +3 -1
  252. package/dist/server/rsc-cache-key-guard.d.ts.map +1 -1
  253. package/dist/server/rsc-entry/helpers.d.ts +1 -1
  254. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  255. package/dist/server/rsc-entry/render-route.d.ts +10 -1
  256. package/dist/server/rsc-entry/render-route.d.ts.map +1 -1
  257. package/dist/server/rsc-entry/revalidate-renderer.d.ts +12 -0
  258. package/dist/server/rsc-entry/revalidate-renderer.d.ts.map +1 -1
  259. package/dist/server/rsc-entry/rsc-stream.d.ts +2 -11
  260. package/dist/server/rsc-entry/rsc-stream.d.ts.map +1 -1
  261. package/dist/server/segment-lifetime/document-outlet.d.ts +66 -0
  262. package/dist/server/segment-lifetime/document-outlet.d.ts.map +1 -0
  263. package/dist/server/segment-lifetime/key-digest.d.ts +46 -0
  264. package/dist/server/segment-lifetime/key-digest.d.ts.map +1 -0
  265. package/dist/server/segment-lifetime/outlet-gate.d.ts +58 -0
  266. package/dist/server/segment-lifetime/outlet-gate.d.ts.map +1 -0
  267. package/dist/server/segment-lifetime/read-rule.d.ts +53 -0
  268. package/dist/server/segment-lifetime/read-rule.d.ts.map +1 -0
  269. package/dist/server/segment-lifetime/read-scope.d.ts +40 -0
  270. package/dist/server/segment-lifetime/read-scope.d.ts.map +1 -0
  271. package/dist/server/segment-lifetime/segment-key.d.ts +63 -0
  272. package/dist/server/segment-lifetime/segment-key.d.ts.map +1 -0
  273. package/dist/server/segment-lifetime/slot-outlets.d.ts +81 -0
  274. package/dist/server/segment-lifetime/slot-outlets.d.ts.map +1 -0
  275. package/dist/server/slot-resolver.d.ts +10 -5
  276. package/dist/server/slot-resolver.d.ts.map +1 -1
  277. package/dist/server/slot-subtree-contain.d.ts +2 -6
  278. package/dist/server/slot-subtree-contain.d.ts.map +1 -1
  279. package/dist/server/subtree-walk.d.ts +56 -0
  280. package/dist/server/subtree-walk.d.ts.map +1 -0
  281. package/dist/server/types.d.ts +75 -0
  282. package/dist/server/types.d.ts.map +1 -1
  283. package/dist/server/vite-handoff-rsc.d.ts +1 -10
  284. package/dist/server/vite-handoff-rsc.d.ts.map +1 -1
  285. package/dist/shared/als-slots.d.ts +12 -2
  286. package/dist/shared/als-slots.d.ts.map +1 -1
  287. package/dist/shared/cookie-read-through.d.ts +18 -0
  288. package/dist/shared/cookie-read-through.d.ts.map +1 -0
  289. package/dist/shared/key-headers.d.ts +13 -0
  290. package/dist/shared/key-headers.d.ts.map +1 -0
  291. package/dist/shared/outlet-decision.d.ts +16 -28
  292. package/dist/shared/outlet-decision.d.ts.map +1 -1
  293. package/dist/shared/payload-root.d.ts +1 -1
  294. package/dist/shared/route-options-export.d.ts +13 -0
  295. package/dist/shared/route-options-export.d.ts.map +1 -0
  296. package/dist/shared/rsc-cache-key.d.ts +22 -0
  297. package/dist/shared/rsc-cache-key.d.ts.map +1 -1
  298. package/dist/shared/segment-info.d.ts +7 -5
  299. package/dist/shared/segment-info.d.ts.map +1 -1
  300. package/dist/shims/headers.d.ts.map +1 -1
  301. package/docs/api/30-api-server.mdx +29 -0
  302. package/docs/api/32-api-cache.mdx +10 -4
  303. package/docs/api/34-api-config.mdx +5 -0
  304. package/docs/learn/09-streaming.mdx +6 -2
  305. package/docs/learn/10-caching.mdx +10 -4
  306. package/package.json +1 -1
  307. package/src/cli-check.ts +11 -3
  308. package/src/client/browser-entry/index.ts +0 -2
  309. package/src/client/browser-entry/router-init.ts +2 -4
  310. package/src/client/error-boundary.tsx +1 -1
  311. package/src/client/navigation-commit.ts +9 -14
  312. package/src/client/outlet-content-cache.ts +36 -42
  313. package/src/client/outlet-scope-context.ts +5 -5
  314. package/src/client/params-context.ts +1 -1
  315. package/src/client/router-types.ts +3 -14
  316. package/src/client/router.ts +1 -2
  317. package/src/client/rsc-fetch.ts +1 -1
  318. package/src/client/segment-cache.ts +2 -2
  319. package/src/client/segment-outlet.tsx +19 -45
  320. package/src/client/stale-segment.ts +2 -2
  321. package/src/config-types.ts +23 -15
  322. package/src/config-validation.ts +17 -1
  323. package/src/cookies/define-cookie.ts +5 -1
  324. package/src/index.ts +2 -1
  325. package/src/plugins/callsite-jsx.ts +104 -6
  326. package/src/plugins/entries.ts +3 -1
  327. package/src/plugins/prerender-sugar.ts +34 -18
  328. package/src/plugins/routing.ts +3 -1
  329. package/src/routing/convention-lint.ts +18 -7
  330. package/src/routing/export-detect.ts +14 -117
  331. package/src/routing/route-options-lint.ts +153 -0
  332. package/src/routing/route-options.ts +439 -0
  333. package/src/routing/scanner.ts +1 -1
  334. package/src/routing/segment-keys.ts +53 -4
  335. package/src/rsc-runtime/vendor-types.d.ts +5 -1
  336. package/src/search-params/define.ts +1 -1
  337. package/src/server/als-registry.ts +25 -17
  338. package/src/server/client-state-tree.ts +30 -27
  339. package/src/server/cookie-context.ts +17 -0
  340. package/src/server/flight-source-node.ts +1 -5
  341. package/src/server/flight-source.ts +8 -82
  342. package/src/server/framework-stack-frames.ts +41 -0
  343. package/src/server/index.ts +7 -0
  344. package/src/server/prebuilt/capture-routes.ts +1 -1
  345. package/src/server/prebuilt-builder.ts +30 -2
  346. package/src/server/request-context.ts +31 -6
  347. package/src/server/route-element-builder.ts +92 -18
  348. package/src/server/route-module-loader.ts +43 -10
  349. package/src/server/rsc-cache-key-guard.ts +17 -2
  350. package/src/server/rsc-entry/helpers.ts +1 -1
  351. package/src/server/rsc-entry/index.ts +16 -3
  352. package/src/server/rsc-entry/render-route.ts +22 -51
  353. package/src/server/rsc-entry/revalidate-renderer.ts +16 -2
  354. package/src/server/rsc-entry/rsc-stream.ts +3 -23
  355. package/src/server/segment-lifetime/document-outlet.ts +98 -0
  356. package/src/server/segment-lifetime/key-digest.ts +139 -0
  357. package/src/server/segment-lifetime/outlet-gate.ts +102 -0
  358. package/src/server/segment-lifetime/read-rule.ts +193 -0
  359. package/src/server/segment-lifetime/read-scope.ts +101 -0
  360. package/src/server/segment-lifetime/segment-key.ts +168 -0
  361. package/src/server/segment-lifetime/slot-outlets.ts +180 -0
  362. package/src/server/slot-resolver.ts +103 -60
  363. package/src/server/slot-subtree-contain.ts +35 -182
  364. package/src/server/subtree-walk.ts +316 -0
  365. package/src/server/types.ts +91 -0
  366. package/src/server/vite-handoff-rsc.ts +1 -12
  367. package/src/shared/als-slots.ts +19 -8
  368. package/src/shared/cookie-read-through.ts +18 -0
  369. package/src/shared/key-headers.ts +42 -0
  370. package/src/shared/outlet-decision.ts +16 -30
  371. package/src/shared/payload-root.ts +1 -1
  372. package/src/shared/route-options-export.ts +14 -0
  373. package/src/shared/rsc-cache-key.ts +41 -2
  374. package/src/shared/segment-info.ts +7 -5
  375. package/src/shims/headers.ts +5 -4
  376. package/dist/_chunks/actions-DIgnvDrG.js.map +0 -1
  377. package/dist/_chunks/als-slots-kbQrHTzm.js.map +0 -1
  378. package/dist/_chunks/chains-CSslTUdI.js +0 -1
  379. package/dist/_chunks/cli-check-C3QOAru7.js.map +0 -1
  380. package/dist/_chunks/convention-lint-BoVISNS6.js.map +0 -1
  381. package/dist/_chunks/dev-server-B8roKA3Q.js +0 -1
  382. package/dist/_chunks/dev-server-C5R6jx8Q.js.map +0 -1
  383. package/dist/_chunks/dist-C1Rjlo6s.js.map +0 -1
  384. package/dist/_chunks/error-boundary-DB51f9ih.js.map +0 -1
  385. package/dist/_chunks/flight-source-node-D9cHBhjP.js.map +0 -1
  386. package/dist/_chunks/scanner-C9Lrf77z.js.map +0 -1
  387. package/dist/native/rsc/server/segment-hash/capture.js +0 -107
  388. package/dist/native/rsc/server/segment-hash/capture.js.map +0 -1
  389. package/dist/native/rsc/server/segment-hash/outlet.js +0 -81
  390. package/dist/native/rsc/server/segment-hash/outlet.js.map +0 -1
  391. package/dist/native/rsc/server/segment-hash/stream-tap.js +0 -139
  392. package/dist/native/rsc/server/segment-hash/stream-tap.js.map +0 -1
  393. package/dist/native/rsc/server/segment-hash/value-hash.js +0 -171
  394. package/dist/native/rsc/server/segment-hash/value-hash.js.map +0 -1
  395. package/dist/native/ssr/server/segment-hash/value-hash.js +0 -162
  396. package/dist/native/ssr/server/segment-hash/value-hash.js.map +0 -1
  397. package/dist/server/segment-hash/capture.d.ts +0 -77
  398. package/dist/server/segment-hash/capture.d.ts.map +0 -1
  399. package/dist/server/segment-hash/outlet.d.ts +0 -65
  400. package/dist/server/segment-hash/outlet.d.ts.map +0 -1
  401. package/dist/server/segment-hash/stream-tap.d.ts +0 -49
  402. package/dist/server/segment-hash/stream-tap.d.ts.map +0 -1
  403. package/dist/server/segment-hash/value-hash.d.ts +0 -70
  404. package/dist/server/segment-hash/value-hash.d.ts.map +0 -1
  405. package/src/server/segment-hash/capture.ts +0 -232
  406. package/src/server/segment-hash/outlet.ts +0 -185
  407. package/src/server/segment-hash/stream-tap.ts +0 -244
  408. package/src/server/segment-hash/value-hash.ts +0 -338
@@ -1,232 +0,0 @@
1
- /**
2
- * The capture: a segment rendered on its own Flight stream, inside the current
3
- * request — the segment's one and only render.
4
- *
5
- * The outlet gate captures a segment when the client advertised a hash for it.
6
- * The capture is decoded as it streams by React's own Flight client in the
7
- * RSC environment, and the decoded value graph is hashed (value-hash.ts):
8
- *
9
- * - its hash equals the client's → a skip, and the decoded tree is dropped;
10
- * - it differs → the decoded tree is emitted as the segment's live content.
11
- * Nothing is rendered a second time: server components already ran, and the
12
- * main render only serializes what they produced.
13
- *
14
- * A capture that reaches a Suspense boundary or a promise prop still pending
15
- * is not waited on (the shell rule is not built): its decoded tree is emitted
16
- * live at once and the pending content streams when it would have anyway.
17
- *
18
- * Nested outlets are holes. Each renders as a `SegmentOutlet` whose decision is
19
- * an opaque marker, written as a Flight temporary reference. Decoding
20
- * replaces it with a lazy decision for the nested segment, made only if the
21
- * decoded tree is sent — a skip decides the nested segments itself.
22
- *
23
- * Because the capture is the render, it writes request state (metadata
24
- * entries, deny status) directly, and reports errors through the main
25
- * render's error handler. An error decoded into the live content keeps its
26
- * digest: the main render passes it through rather than reporting it again.
27
- *
28
- * See design/52-segment-hash-dedupe.md §"Capture".
29
- */
30
-
31
- import { createHash } from 'node:crypto';
32
- import { createElement, type ReactNode } from 'react';
33
- import { segmentCaptureAls } from '../als-registry.ts';
34
- import { flightChunkBytes, openFlightReader } from '../flight-source.ts';
35
- import { withTimeout } from '../render-timeout.ts';
36
- import { createFromReadableStream, renderFlight } from '../vite-handoff-rsc.ts';
37
- import type {
38
- CaptureHole,
39
- OutletDecision,
40
- OutletDecisionValue,
41
- } from '../../shared/outlet-decision.ts';
42
- import { hashValue } from './value-hash.ts';
43
-
44
- /**
45
- * Inside a capture render, the marker a nested outlet renders with in place of
46
- * its decision; undefined outside one.
47
- */
48
- export function captureHoleMarker(segmentPath: string): CaptureHole | undefined {
49
- return segmentCaptureAls.getStore()?.hole(segmentPath);
50
- }
51
-
52
- /** A short, stable `useId()` prefix for the capture of `segmentPath`. */
53
- function captureIdPrefix(segmentPath: string): string {
54
- return 's' + createHash('sha256').update(segmentPath).digest('base64url').slice(0, 8) + '-';
55
- }
56
-
57
- export interface CaptureOptions {
58
- /** The segment captured — its `useId()` prefix derives from it. */
59
- segmentPath: string;
60
- /** Upper bound on the whole capture stream. */
61
- timeoutMs: number;
62
- /** The request's signal — a disconnect abandons the capture. */
63
- signal?: AbortSignal;
64
- /** Subscribes to the main render's end — a capture never outlives it. */
65
- onRenderEnd?: (cancel: () => void) => () => void;
66
- /** The main render's error handler: its digests, signals and reports. */
67
- onError?: (error: unknown) => string | void;
68
- /** Whether a decoded element type is timber's `SegmentOutlet`. */
69
- isOutlet: (type: unknown) => boolean;
70
- /** The decision for a nested outlet, made only if the capture is sent live. */
71
- decideHole: (segmentPath: string) => OutletDecisionValue | undefined;
72
- }
73
-
74
- /** What a capture found, as soon as it can say. */
75
- export type SegmentCapture =
76
- /** Everything the segment reaches settled: its hash is known. */
77
- | {
78
- kind: 'complete';
79
- hash: string;
80
- /**
81
- * The nested outlets that rendered as holes. One missing here was not
82
- * rendered — an access gate above it denied — and a skip must not decide
83
- * it: deciding renders its content.
84
- */
85
- holes: ReadonlySet<string>;
86
- /** The decoded content, to send if the segment is not skipped. */
87
- content: ReactNode;
88
- /** The segment is skipped: stop reading the capture. */
89
- discard(): void;
90
- }
91
- /** Not waited for — still streaming, or not hashable. Send it live. */
92
- | { kind: 'live'; content: ReactNode };
93
-
94
- /**
95
- * A decision made the first time something asks for it. The main render asks
96
- * when it serializes the decoded tree (Flight awaits any thenable prop); a
97
- * skip never does.
98
- */
99
- function lazyDecision(decide: () => OutletDecisionValue | undefined): PromiseLike<OutletDecision> {
100
- let decided: Promise<OutletDecision> | undefined;
101
- return {
102
- then(onFulfilled, onRejected) {
103
- decided ??= Promise.resolve(decide()).then((d) => {
104
- // The client refuses an outlet without a decision rather than show
105
- // stale content (client/segment-outlet.tsx).
106
- if (d === undefined) throw new Error('[timber] a capture hole has no segment to decide');
107
- return d;
108
- });
109
- return decided.then(onFulfilled, onRejected);
110
- },
111
- };
112
- }
113
-
114
- /** Render `content` as a capture. Settles once its hash is known or not waited for. */
115
- export async function captureSegment(
116
- content: ReactNode,
117
- options: CaptureOptions
118
- ): Promise<SegmentCapture> {
119
- // Hole markers, by temporary-reference id, and the paths they stand for.
120
- const temporaryReferences = new WeakMap<object, string>();
121
- const holePaths = new Map<string, string>();
122
- const source = segmentCaptureAls.run(
123
- {
124
- hole(segmentPath) {
125
- const id = String(holePaths.size);
126
- const marker: CaptureHole = { captureHole: true };
127
- holePaths.set(id, segmentPath);
128
- temporaryReferences.set(marker, id);
129
- return marker;
130
- },
131
- },
132
- () =>
133
- renderFlight(content, {
134
- signal: options.signal,
135
- timeoutMs: options.timeoutMs,
136
- onError: options.onError,
137
- temporaryReferences,
138
- // The capture counts `useId()` from zero like the main render does;
139
- // a prefix of its own, stable per segment, keeps their ids apart in
140
- // one document and keeps the hash the same from render to render.
141
- identifierPrefix: captureIdPrefix(options.segmentPath),
142
- })
143
- );
144
-
145
- const reader = openFlightReader(source);
146
- // Cancelling the reader aborts the capture's render. Unsubscribed when the
147
- // capture's stream ends.
148
- let ended = false;
149
- const unsubscribe = options.onRenderEnd?.(() => {
150
- ended = true;
151
- reader.cancel();
152
- });
153
-
154
- // Pump the capture into the decoder, every read under the deadline.
155
- const deadline = Date.now() + options.timeoutMs;
156
- const bytes = new ReadableStream<Uint8Array>({
157
- async pull(controller) {
158
- try {
159
- const result = await withTimeout(
160
- reader.read(),
161
- Math.max(0, deadline - Date.now()),
162
- 'segment capture'
163
- );
164
- if (result.done) {
165
- unsubscribe?.();
166
- controller.close();
167
- } else {
168
- controller.enqueue(flightChunkBytes(result.value));
169
- }
170
- } catch (error) {
171
- // Failed, cancelled, or out of time: release the render. Sent live,
172
- // the decoded content fails at the same point — the main render
173
- // answers it.
174
- unsubscribe?.();
175
- reader.cancel();
176
- controller.error(error);
177
- }
178
- },
179
- cancel() {
180
- unsubscribe?.();
181
- reader.cancel();
182
- },
183
- });
184
-
185
- const decisions = new Map<string, PromiseLike<OutletDecision>>();
186
- const root = createFromReadableStream(bytes, {
187
- temporaryReferences: {
188
- get(key: string) {
189
- // Flight's client asks for `$<id>`; each hole is decided once, lazily.
190
- const id = key.slice(1);
191
- const path = holePaths.get(id);
192
- if (path === undefined) return undefined;
193
- let decision = decisions.get(id);
194
- if (!decision) {
195
- decision = lazyDecision(() => options.decideHole(path));
196
- decisions.set(id, decision);
197
- }
198
- return decision;
199
- },
200
- },
201
- });
202
- let decoded: ReactNode;
203
- try {
204
- decoded = (await root) as ReactNode;
205
- } catch {
206
- // The capture's root errored (or never arrived). Sent live as the
207
- // rejected root, the main render writes that error where the segment
208
- // would be — once, with the digest the capture already reported.
209
- // A server component that only awaits the decoded root: no app code runs.
210
- const DecodedCaptureRoot = async (): Promise<ReactNode> => (await root) as ReactNode;
211
- return { kind: 'live', content: createElement(DecodedCaptureRoot) };
212
- }
213
-
214
- for (;;) {
215
- const outcome = hashValue(decoded, { isOutlet: options.isOutlet });
216
- if (outcome.status === 'complete') {
217
- return {
218
- kind: 'complete',
219
- hash: outcome.hash,
220
- holes: new Set(holePaths.values()),
221
- content: decoded,
222
- discard: () => reader.cancel(),
223
- };
224
- }
225
- if (outcome.status === 'unhashable' || outcome.streaming || ended) {
226
- return { kind: 'live', content: decoded };
227
- }
228
- // Pending async work outside any Suspense boundary: the client cannot
229
- // commit before it arrives either, so waiting for it is invisible.
230
- await Promise.allSettled(outcome.waitFor.map((t) => Promise.resolve(t)));
231
- }
232
- }
@@ -1,185 +0,0 @@
1
- /**
2
- * The outlet gate: renders one segment as a `SegmentOutlet` whose decision is
3
- * either its live content or a skip.
4
- *
5
- * Every segment renders on every navigation; access runs for every one. What
6
- * hash dedupe saves is bytes: when the client advertised a hash for a segment,
7
- * the gate captures the segment (capture.ts), and if the capture's hash
8
- * equals the client's, the segment is sent as a skip — the client keeps the
9
- * content it holds. Otherwise the live content is sent with a hash the client
10
- * stores beside it (stream-tap.ts). Nothing is predicted: a skip happens only
11
- * when a render the server just ran produced exactly what the client holds.
12
- *
13
- * A skip carries the decisions of the segments nested directly inside it —
14
- * only those the capture rendered as holes. Their access gates ran in the
15
- * capture; a nested gate that denied rendered its deny page instead of the
16
- * hole, so its segment is never decided, never rendered, never sent.
17
- *
18
- * See design/52-segment-hash-dedupe.md §"Mechanism".
19
- */
20
-
21
- import { createElement, type ReactElement, type ReactNode } from 'react';
22
- import type { OutletDecision, OutletDecisionValue } from '../../shared/outlet-decision.ts';
23
- import { clientComponents } from '../vite-handoff-rsc.ts';
24
- import { stripReferenceCacheTag } from './value-hash.ts';
25
- import { captureHoleMarker, captureSegment, type SegmentCapture } from './capture.ts';
26
- import type { SegmentHashTap } from './stream-tap.ts';
27
-
28
- /** One outlet in the element tree, and the outlets directly inside it. */
29
- export interface OutletSpec {
30
- segmentPath: string;
31
- content: ReactNode;
32
- nested: OutletSpec[];
33
- }
34
-
35
- /** Per-request inputs to every gate in one render. */
36
- export interface SegmentHashRender {
37
- /** The hashes the client advertised (`X-Timber-State-Tree`), by path. */
38
- clientHashes: ReadonlyMap<string, string> | null;
39
- /** Hashes the outgoing stream; null when `clientSegmentCache` is off. */
40
- tap: SegmentHashTap | null;
41
- /**
42
- * Bounds each capture's stream. A capture also ends with the main render
43
- * (`tap.onEnd`), which usually comes first.
44
- */
45
- captureTimeoutMs: number;
46
- /**
47
- * The main render's error handler. A capture is a segment's render, so its
48
- * errors are the render's: reported, digested and signalled once, there.
49
- */
50
- onCaptureError?: (error: unknown) => string | void;
51
- signal?: AbortSignal;
52
- }
53
-
54
- /** A render with dedupe off: every segment live, no hashes. */
55
- export const NO_SEGMENT_HASHING: SegmentHashRender = {
56
- clientHashes: null,
57
- tap: null,
58
- captureTimeoutMs: 0,
59
- };
60
-
61
- /**
62
- * Whether a decoded element type is timber's `SegmentOutlet` client
63
- * reference. Matched by reference id — module and export — so an app
64
- * component that happened to be exported as `SegmentOutlet` is not read as a
65
- * hole, which would keep changes inside it out of its segment's hash.
66
- */
67
- export function isOutletType(type: unknown): boolean {
68
- if (typeof type !== 'function' && (typeof type !== 'object' || type === null)) return false;
69
- const id = (type as { $$id?: unknown }).$$id;
70
- const outlet = (clientComponents().SegmentOutlet as { $$id?: unknown }).$$id;
71
- return (
72
- typeof id === 'string' &&
73
- typeof outlet === 'string' &&
74
- stripReferenceCacheTag(id) === stripReferenceCacheTag(outlet)
75
- );
76
- }
77
-
78
- /**
79
- * The element for an outlet: a server component that decides when it renders
80
- * — after every access gate above it — and inside a capture renders a bare
81
- * hole, since the nested segment's content belongs to its own hash.
82
- *
83
- * A closure with no props rather than a component taking `{ spec, render }`:
84
- * dev Flight serializes a server component's props as debug info, and these
85
- * would repeat the whole subtree in every dev payload.
86
- */
87
- export function outletGate(spec: OutletSpec, render: SegmentHashRender): ReactElement {
88
- function OutletGate(): ReactElement {
89
- const { SegmentOutlet } = clientComponents();
90
- const marker = captureHoleMarker(spec.segmentPath);
91
- if (marker)
92
- return createElement(SegmentOutlet, { segmentPath: spec.segmentPath, decision: marker });
93
- return createElement(SegmentOutlet, {
94
- segmentPath: spec.segmentPath,
95
- decision: decide(spec, render),
96
- });
97
- }
98
- return createElement(OutletGate);
99
- }
100
-
101
- function decide(spec: OutletSpec, render: SegmentHashRender): OutletDecisionValue {
102
- const clientHash = render.clientHashes?.get(spec.segmentPath);
103
- if (clientHash === undefined) return live(spec, render, spec.content);
104
- return detached(compare(spec, render, clientHash));
105
- }
106
-
107
- /**
108
- * The decision as a promise of its own, created here and settled from the
109
- * capture's callback — not a link in the capture's promise chain.
110
- *
111
- * Development Flight follows the async chain of every promise it serializes
112
- * (async_hooks in the Node build, and each awaited promise's `_debugInfo`) and
113
- * writes what it finds as debug rows, awaited values included. The chain
114
- * through a capture ends at its decoded root, so a decision chained to it
115
- * would carry a skipped segment's content into the payload as debug info —
116
- * whenever the timing made those reads count as I/O.
117
- */
118
- function detached<T>(source: Promise<T>): Promise<T> {
119
- return new Promise<T>((resolve, reject) => {
120
- source.then(resolve, reject);
121
- });
122
- }
123
-
124
- function compare(
125
- spec: OutletSpec,
126
- render: SegmentHashRender,
127
- clientHash: string
128
- ): Promise<OutletDecision> {
129
- return captureSegment(spec.content, {
130
- segmentPath: spec.segmentPath,
131
- timeoutMs: render.captureTimeoutMs,
132
- signal: render.signal,
133
- onRenderEnd: render.tap?.onEnd,
134
- onError: render.onCaptureError,
135
- isOutlet: isOutletType,
136
- decideHole: (path) => decideNested(spec, path, render),
137
- }).then(
138
- (capture) => {
139
- if (capture.kind === 'complete' && capture.hash === clientHash) {
140
- capture.discard();
141
- return skip(spec, render, capture);
142
- }
143
- // Sent live: the capture's own elements, decoded — not a second render.
144
- return live(spec, render, capture.content);
145
- },
146
- // The capture could not be started at all (renderFlight threw before
147
- // rendering anything): render the segment inline, as without a hash.
148
- () => live(spec, render, spec.content)
149
- );
150
- }
151
-
152
- /** The decision for the nested outlet at `path`, which rendered as a hole. */
153
- function decideNested(
154
- spec: OutletSpec,
155
- path: string,
156
- render: SegmentHashRender
157
- ): OutletDecisionValue | undefined {
158
- const nested = spec.nested.find((n) => n.segmentPath === path);
159
- // A hole the builder did not record under this segment cannot be decided;
160
- // the client refuses an outlet without a decision rather than show it stale.
161
- return nested ? decide(nested, render) : undefined;
162
- }
163
-
164
- function live(spec: OutletSpec, render: SegmentHashRender, children: ReactNode): OutletDecision {
165
- if (!render.tap) return { children };
166
- return { hash: render.tap.advertise(spec.segmentPath), children };
167
- }
168
-
169
- /**
170
- * A skip decides exactly the nested outlets its capture rendered as holes —
171
- * the ones whose access gates passed. Those are also exactly the outlets in
172
- * the client's cached copy, since the hashes matched. A nested outlet whose
173
- * gate denied is not decided at all: deciding it would render its content.
174
- */
175
- function skip(
176
- spec: OutletSpec,
177
- render: SegmentHashRender,
178
- capture: Extract<SegmentCapture, { kind: 'complete' }>
179
- ): OutletDecision {
180
- const outlets: Record<string, OutletDecisionValue> = {};
181
- for (const nested of spec.nested) {
182
- if (capture.holes.has(nested.segmentPath)) outlets[nested.segmentPath] = decide(nested, render);
183
- }
184
- return { skip: true, hash: capture.hash, outlets };
185
- }
@@ -1,244 +0,0 @@
1
- /**
2
- * The advertised hash: each live segment's hash, computed from what the main
3
- * Flight stream actually sent.
4
- *
5
- * A live `SegmentOutlet` carries `decision.hash` as a promise. The tap feeds
6
- * the outgoing stream to React's own Flight client in the RSC environment,
7
- * finds each live outlet in the decoded tree, and once everything the
8
- * decision's `children` reach has settled, resolves that promise with the
9
- * hash of those decoded values (value-hash.ts). Flight then writes the hash
10
- * as one more row. The client stores it beside the content it committed, so
11
- * the hash it later advertises describes exactly what it received
12
- * (design/52 §"Two hashes, two jobs").
13
- *
14
- * Nothing about this can stall the response: a hash the tap cannot compute
15
- * resolves to null once the decoded payload has been explored without
16
- * finding its outlet, or when the stream ends, and every pending hash
17
- * resolves to null once `timeoutMs` passes — a pending promise would otherwise hold the
18
- * Flight stream open.
19
- *
20
- * See design/52-segment-hash-dedupe.md §"Wire format".
21
- */
22
-
23
- import { hashSettledValue } from './value-hash.ts';
24
-
25
- export interface SegmentHashTap {
26
- /**
27
- * The hash of live segment `segmentPath`'s content in this stream, once it
28
- * has all arrived. Null when it cannot be computed.
29
- */
30
- advertise(segmentPath: string): Promise<string | null>;
31
- /** Feed one chunk of the outgoing stream. */
32
- observe(chunk: Uint8Array): void;
33
- /** The stream ended or was cancelled: give up on everything pending. */
34
- end(): void;
35
- /**
36
- * Run `cancel` once the stream ends, however it ends; returns the
37
- * unsubscribe. Captures started for this render stop with it (capture.ts) —
38
- * nothing waits on them any more. A callback list rather than an
39
- * AbortSignal: aborting a signal from the stream's teardown kept every
40
- * finished request reachable in dev (tests/e2e/dev-request-retention.test.ts).
41
- */
42
- onEnd(cancel: () => void): () => void;
43
- }
44
-
45
- export interface SegmentHashTapOptions {
46
- timeoutMs: number;
47
- /** Whether a decoded element type is timber's `SegmentOutlet`. */
48
- isOutlet: (type: unknown) => boolean;
49
- /** React's Flight client in the RSC environment. */
50
- decode: (stream: ReadableStream<Uint8Array>) => PromiseLike<unknown>;
51
- }
52
-
53
- const LAZY = Symbol.for('react.lazy');
54
- const ELEMENT = new Set([Symbol.for('react.transitional.element'), Symbol.for('react.element')]);
55
-
56
- function isThenable(value: unknown): value is PromiseLike<unknown> {
57
- return (
58
- typeof value === 'object' &&
59
- value !== null &&
60
- typeof (value as { then?: unknown }).then === 'function'
61
- );
62
- }
63
-
64
- /** Await a decoded promise; a rejection settles to undefined. */
65
- async function settled(value: PromiseLike<unknown>): Promise<unknown> {
66
- try {
67
- return await value;
68
- } catch {
69
- return undefined;
70
- }
71
- }
72
-
73
- export function createSegmentHashTap(options: SegmentHashTapOptions): SegmentHashTap {
74
- const pending = new Map<string, (hash: string | null) => void>();
75
- const computed = new Map<string, Promise<string | null>>();
76
- const ambiguous = new Set<string>();
77
- const onEnd = new Set<() => void>();
78
- const state = { aborted: false };
79
- let explored = false;
80
- let timer: ReturnType<typeof setTimeout> | undefined;
81
- let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
82
-
83
- const stream = new ReadableStream<Uint8Array>({
84
- start(c) {
85
- controller = c;
86
- },
87
- });
88
-
89
- function settle(path: string, hash: string | null): void {
90
- const resolve = pending.get(path);
91
- if (!resolve) return;
92
- pending.delete(path);
93
- resolve(hash);
94
- if (pending.size === 0 && timer !== undefined) {
95
- clearTimeout(timer);
96
- timer = undefined;
97
- }
98
- }
99
-
100
- function deliver(path: string): void {
101
- const hash = computed.get(path);
102
- if (!hash || !pending.has(path)) return;
103
- // A hash that cannot be computed is no hash — never a rejection left to
104
- // crash the process.
105
- void hash.then(
106
- (h) => settle(path, ambiguous.has(path) ? null : h),
107
- () => settle(path, null)
108
- );
109
- }
110
-
111
- // ─── Finding the outlets in the decoded tree ─────────────────────────────
112
-
113
- const visited = new WeakSet<object>();
114
-
115
- /** Walk a decoded value for outlet elements, waiting on what is pending. */
116
- async function explore(value: unknown): Promise<void> {
117
- if (state.aborted || value === null || typeof value !== 'object') return;
118
- if (visited.has(value)) return;
119
- visited.add(value);
120
- const tagged = value as { $$typeof?: unknown; _payload?: unknown };
121
- if (tagged.$$typeof === LAZY) {
122
- if (isThenable(tagged._payload)) await explore(await settled(tagged._payload));
123
- return;
124
- }
125
- if (tagged.$$typeof !== undefined && ELEMENT.has(tagged.$$typeof as symbol)) {
126
- const { props } = value as { props: Record<string, unknown> | null };
127
- // A client component's type arrives as a lazy reference to its module.
128
- let type = (value as { type: unknown }).type;
129
- const lazyType = type as { $$typeof?: unknown; _payload?: unknown } | null;
130
- if (lazyType && typeof lazyType === 'object' && lazyType.$$typeof === LAZY) {
131
- type = isThenable(lazyType._payload) ? await settled(lazyType._payload) : undefined;
132
- }
133
- if (options.isOutlet(type) && props) {
134
- await outlet(props.segmentPath, props.decision);
135
- return;
136
- }
137
- await explore(props);
138
- return;
139
- }
140
- if (isThenable(value)) {
141
- await explore(await settled(value));
142
- return;
143
- }
144
- const children: unknown[] = Array.isArray(value)
145
- ? value
146
- : value instanceof Map
147
- ? [...value.keys(), ...value.values()]
148
- : value instanceof Set
149
- ? [...value]
150
- : Object.getPrototypeOf(value) === Object.prototype ||
151
- Object.getPrototypeOf(value) === null
152
- ? Object.values(value)
153
- : [];
154
- await Promise.all(children.map(explore));
155
- }
156
-
157
- /** One outlet: hash it if live, and find the outlets inside it. */
158
- async function outlet(segmentPath: unknown, decisionValue: unknown): Promise<void> {
159
- if (typeof segmentPath !== 'string') return;
160
- const decision = isThenable(decisionValue) ? await settled(decisionValue) : decisionValue;
161
- if (!decision || typeof decision !== 'object') return;
162
- const d = decision as { skip?: unknown; children?: unknown; outlets?: unknown };
163
- if (d.skip === true) {
164
- // A skip carries its nested segments' decisions.
165
- const outlets = d.outlets && typeof d.outlets === 'object' ? d.outlets : {};
166
- await Promise.all(Object.entries(outlets).map(([path, nested]) => outlet(path, nested)));
167
- return;
168
- }
169
- if (computed.has(segmentPath)) ambiguous.add(segmentPath);
170
- computed.set(segmentPath, hashSettledValue(d.children, { isOutlet: options.isOutlet }, state));
171
- deliver(segmentPath);
172
- await explore(d.children);
173
- }
174
-
175
- /**
176
- * Everything the payload reaches has been explored: an outlet whose hash is
177
- * still pending is one the walk did not find (a value kind it does not
178
- * descend into). Its hash is none — it must not hold the stream open until
179
- * the deadline.
180
- */
181
- function exploredAll(): void {
182
- explored = true;
183
- for (const path of [...pending.keys()]) if (!computed.has(path)) settle(path, null);
184
- }
185
-
186
- // Decoding starts at once and reads whatever `observe` feeds it. A decoder
187
- // that throws — even synchronously — ends hashing, never the response.
188
- void new Promise<unknown>((resolve) => resolve(options.decode(stream)))
189
- .then((root) => explore(root))
190
- .then(exploredAll)
191
- .catch(() => end());
192
-
193
- function end(): void {
194
- if (state.aborted) return;
195
- state.aborted = true;
196
- for (const cancel of [...onEnd]) cancel();
197
- onEnd.clear();
198
- if (timer !== undefined) clearTimeout(timer);
199
- timer = undefined;
200
- try {
201
- controller?.close();
202
- } catch {
203
- // Already closed or errored.
204
- }
205
- controller = null;
206
- for (const path of [...pending.keys()]) settle(path, null);
207
- computed.clear();
208
- }
209
-
210
- return {
211
- advertise(segmentPath) {
212
- if (state.aborted) return Promise.resolve(null);
213
- if (pending.has(segmentPath)) {
214
- // Two live outlets claimed one path: neither hash is trustworthy.
215
- ambiguous.add(segmentPath);
216
- settle(segmentPath, null);
217
- return Promise.resolve(null);
218
- }
219
- if (explored && !computed.has(segmentPath)) return Promise.resolve(null);
220
- const promise = new Promise<string | null>((resolve) => pending.set(segmentPath, resolve));
221
- timer ??= setTimeout(end, options.timeoutMs);
222
- deliver(segmentPath);
223
- return promise;
224
- },
225
- observe(chunk) {
226
- // The tap runs inside the response's stream: nothing it does may break
227
- // that stream. A chunk it cannot hand on ends hashing for this response.
228
- try {
229
- controller?.enqueue(chunk);
230
- } catch {
231
- end();
232
- }
233
- },
234
- end,
235
- onEnd(cancel) {
236
- if (state.aborted) {
237
- cancel();
238
- return () => {};
239
- }
240
- onEnd.add(cancel);
241
- return () => onEnd.delete(cancel);
242
- },
243
- };
244
- }