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

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 (333) hide show
  1. package/dist/_chunks/{actions-DIgnvDrG.js → actions-BCYVyoFl.js} +117 -11
  2. package/dist/_chunks/actions-BCYVyoFl.js.map +1 -0
  3. package/dist/_chunks/{als-registry-PPYstxK0.js → als-registry-fabsRnPY.js} +4 -2
  4. package/dist/_chunks/{als-registry-PPYstxK0.js.map → als-registry-fabsRnPY.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-n5FL4wFs.js} +5 -5
  8. package/dist/_chunks/{cache-api-uWQwuxWb.js.map → cache-api-n5FL4wFs.js.map} +1 -1
  9. package/dist/_chunks/chains-DPZAMMav.js +1 -0
  10. package/dist/_chunks/{chains-C7CExrUI.js → chains-IswOWMnq.js} +2 -2
  11. package/dist/_chunks/{chains-C7CExrUI.js.map → chains-IswOWMnq.js.map} +1 -1
  12. package/dist/_chunks/{classify-Cj9EeZoL.js → classify-B08RCF6s.js} +2 -2
  13. package/dist/_chunks/{classify-Cj9EeZoL.js.map → classify-B08RCF6s.js.map} +1 -1
  14. package/dist/_chunks/{cli-check-C3QOAru7.js → cli-check-tpFb6pBU.js} +7 -6
  15. package/dist/_chunks/cli-check-tpFb6pBU.js.map +1 -0
  16. package/dist/_chunks/{cli-schema-sync-BRxZz66D.js → cli-schema-sync-C0pXBtzG.js} +1 -1
  17. package/dist/_chunks/{cli-schema-sync-DQUS_o3V.js → cli-schema-sync-DRNJutey.js} +2 -2
  18. package/dist/_chunks/{cli-schema-sync-DQUS_o3V.js.map → cli-schema-sync-DRNJutey.js.map} +1 -1
  19. package/dist/_chunks/{client-dep-entries-ZETBdLgv.js → client-dep-entries-Dw5Dvatr.js} +2 -2
  20. package/dist/_chunks/{client-dep-entries-ZETBdLgv.js.map → client-dep-entries-Dw5Dvatr.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-BfC_dAhZ.js} +364 -10
  24. package/dist/_chunks/convention-lint-BfC_dAhZ.js.map +1 -0
  25. package/dist/_chunks/dev-server-3DNTXQV-.js +1 -0
  26. package/dist/_chunks/{dev-server-C5R6jx8Q.js → dev-server-3R6Bl9_R.js} +9 -2
  27. package/dist/_chunks/dev-server-3R6Bl9_R.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-Dfhxigko.js} +8 -4
  31. package/dist/_chunks/error-boundary-Dfhxigko.js.map +1 -0
  32. package/dist/_chunks/{flight-source-node-D9cHBhjP.js → flight-source-node-QOpWZATb.js} +2 -2
  33. package/dist/_chunks/{flight-source-node-D9cHBhjP.js.map → flight-source-node-QOpWZATb.js.map} +1 -1
  34. package/dist/_chunks/{json-lossy-check-Y1GxqVX_.js → json-lossy-check-5KFcC1yt.js} +2 -2
  35. package/dist/_chunks/{json-lossy-check-Y1GxqVX_.js.map → json-lossy-check-5KFcC1yt.js.map} +1 -1
  36. package/dist/_chunks/{live-graph-BDQWvnMm.js → live-graph-D1dfVqoT.js} +4 -4
  37. package/dist/_chunks/{live-graph-BDQWvnMm.js.map → live-graph-D1dfVqoT.js.map} +1 -1
  38. package/dist/_chunks/{logger-DmRR9tmZ.js → logger-BvGxPd1e.js} +2 -2
  39. package/dist/_chunks/{logger-DmRR9tmZ.js.map → logger-BvGxPd1e.js.map} +1 -1
  40. package/dist/_chunks/metadata-routes-MXNjWOt5.js.map +1 -1
  41. package/dist/_chunks/{node-response-yp8zdyRp.js → node-response-D5cfiyWP.js} +2 -2
  42. package/dist/_chunks/{node-response-yp8zdyRp.js.map → node-response-D5cfiyWP.js.map} +1 -1
  43. package/dist/_chunks/{poison-scan-WQgUydF_.js → poison-scan-CX02ilxN.js} +2 -2
  44. package/dist/_chunks/{poison-scan-WQgUydF_.js.map → poison-scan-CX02ilxN.js.map} +1 -1
  45. package/dist/_chunks/{rsc-cache-key-D0cb0Gmc.js → rsc-cache-key-BGvUtMtN.js} +40 -4
  46. package/dist/_chunks/{rsc-cache-key-D0cb0Gmc.js.map → rsc-cache-key-BGvUtMtN.js.map} +1 -1
  47. package/dist/_chunks/{scanner-C9Lrf77z.js → scanner-DneYxQoY.js} +14 -81
  48. package/dist/_chunks/scanner-DneYxQoY.js.map +1 -0
  49. package/dist/_chunks/{sizeof-BISkSaU0.js → sizeof-BtQ3ErLf.js} +2 -2
  50. package/dist/_chunks/{sizeof-BISkSaU0.js.map → sizeof-BtQ3ErLf.js.map} +1 -1
  51. package/dist/_chunks/{walkers-Bxv4v7tX.js → walkers-C9R2A4jN.js} +3 -3
  52. package/dist/_chunks/{walkers-Bxv4v7tX.js.map → walkers-C9R2A4jN.js.map} +1 -1
  53. package/dist/adapters/cloudflare-dev.js +1 -1
  54. package/dist/adapters/cloudflare-kv-cache.js +2 -2
  55. package/dist/adapters/cloudflare.js +1 -1
  56. package/dist/analyze/crawl-entry.js +3 -3
  57. package/dist/analyze/graph-command.js +2 -2
  58. package/dist/cache/index.js +2 -2
  59. package/dist/cache/stores/memory.js +1 -1
  60. package/dist/cdn/workers-cache-purge.js +1 -1
  61. package/dist/cli-check.d.ts +3 -0
  62. package/dist/cli-check.d.ts.map +1 -1
  63. package/dist/cli.js +3 -3
  64. package/dist/client/error-boundary.js +1 -1
  65. package/dist/client/index.js +1 -1
  66. package/dist/client/internal.js +3 -2
  67. package/dist/client/internal.js.map +1 -1
  68. package/dist/client/navigation-commit.d.ts +5 -0
  69. package/dist/client/navigation-commit.d.ts.map +1 -1
  70. package/dist/client/outlet-content-cache.d.ts +28 -7
  71. package/dist/client/outlet-content-cache.d.ts.map +1 -1
  72. package/dist/client/router.d.ts.map +1 -1
  73. package/dist/client/segment-outlet.d.ts +3 -1
  74. package/dist/client/segment-outlet.d.ts.map +1 -1
  75. package/dist/config-types.d.ts +24 -0
  76. package/dist/config-types.d.ts.map +1 -1
  77. package/dist/config-validation.d.ts.map +1 -1
  78. package/dist/cookies/define-cookie.d.ts.map +1 -1
  79. package/dist/cookies/index.js +5 -2
  80. package/dist/cookies/index.js.map +1 -1
  81. package/dist/index.d.ts +1 -0
  82. package/dist/index.d.ts.map +1 -1
  83. package/dist/index.js +109 -25
  84. package/dist/index.js.map +1 -1
  85. package/dist/native/rsc/cookies/define-cookie.js +6 -2
  86. package/dist/native/rsc/cookies/define-cookie.js.map +1 -1
  87. package/dist/native/rsc/manifest.json +10 -0
  88. package/dist/native/rsc/routing/segment-keys.js +11 -1
  89. package/dist/native/rsc/routing/segment-keys.js.map +1 -1
  90. package/dist/native/rsc/search-params/define.js +4 -1
  91. package/dist/native/rsc/search-params/define.js.map +1 -1
  92. package/dist/native/rsc/server/als-registry.js +2 -1
  93. package/dist/native/rsc/server/als-registry.js.map +1 -1
  94. package/dist/native/rsc/server/client-state-tree.js +14 -9
  95. package/dist/native/rsc/server/client-state-tree.js.map +1 -1
  96. package/dist/native/rsc/server/cookie-context.js +12 -0
  97. package/dist/native/rsc/server/cookie-context.js.map +1 -1
  98. package/dist/native/rsc/server/flight-source.js +5 -2
  99. package/dist/native/rsc/server/flight-source.js.map +1 -1
  100. package/dist/native/rsc/server/framework-stack-frames.js +18 -0
  101. package/dist/native/rsc/server/framework-stack-frames.js.map +1 -0
  102. package/dist/native/rsc/server/prebuilt-builder.js +15 -1
  103. package/dist/native/rsc/server/prebuilt-builder.js.map +1 -1
  104. package/dist/native/rsc/server/request-context.js +10 -4
  105. package/dist/native/rsc/server/request-context.js.map +1 -1
  106. package/dist/native/rsc/server/route-element-builder.js +25 -7
  107. package/dist/native/rsc/server/route-element-builder.js.map +1 -1
  108. package/dist/native/rsc/server/route-module-loader.js +14 -6
  109. package/dist/native/rsc/server/route-module-loader.js.map +1 -1
  110. package/dist/native/rsc/server/rsc-cache-key-guard.js +5 -1
  111. package/dist/native/rsc/server/rsc-cache-key-guard.js.map +1 -1
  112. package/dist/native/rsc/server/rsc-entry/render-route.js +8 -1
  113. package/dist/native/rsc/server/rsc-entry/render-route.js.map +1 -1
  114. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js +8 -1
  115. package/dist/native/rsc/server/rsc-entry/revalidate-renderer.js.map +1 -1
  116. package/dist/native/rsc/server/segment-hash/outlet.js +28 -8
  117. package/dist/native/rsc/server/segment-hash/outlet.js.map +1 -1
  118. package/dist/native/rsc/server/segment-lifetime/document-outlet.js +24 -0
  119. package/dist/native/rsc/server/segment-lifetime/document-outlet.js.map +1 -0
  120. package/dist/native/rsc/server/segment-lifetime/key-digest.js +74 -0
  121. package/dist/native/rsc/server/segment-lifetime/key-digest.js.map +1 -0
  122. package/dist/native/rsc/server/segment-lifetime/read-rule.js +56 -0
  123. package/dist/native/rsc/server/segment-lifetime/read-rule.js.map +1 -0
  124. package/dist/native/rsc/server/segment-lifetime/read-scope.js +40 -0
  125. package/dist/native/rsc/server/segment-lifetime/read-scope.js.map +1 -0
  126. package/dist/native/rsc/server/segment-lifetime/segment-key.js +50 -0
  127. package/dist/native/rsc/server/segment-lifetime/segment-key.js.map +1 -0
  128. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js +72 -0
  129. package/dist/native/rsc/server/segment-lifetime/slot-outlets.js.map +1 -0
  130. package/dist/native/rsc/server/slot-resolver.js +50 -26
  131. package/dist/native/rsc/server/slot-resolver.js.map +1 -1
  132. package/dist/native/rsc/server/slot-subtree-contain.js +17 -89
  133. package/dist/native/rsc/server/slot-subtree-contain.js.map +1 -1
  134. package/dist/native/rsc/server/subtree-walk.js +140 -0
  135. package/dist/native/rsc/server/subtree-walk.js.map +1 -0
  136. package/dist/native/rsc/shared/als-slots.js +2 -2
  137. package/dist/native/rsc/shared/als-slots.js.map +1 -1
  138. package/dist/native/rsc/shared/cookie-read-through.js +5 -0
  139. package/dist/native/rsc/shared/cookie-read-through.js.map +1 -0
  140. package/dist/native/rsc/shared/outlet-decision.js.map +1 -1
  141. package/dist/native/rsc/shared/route-options-export.js +8 -0
  142. package/dist/native/rsc/shared/route-options-export.js.map +1 -0
  143. package/dist/native/rsc/shared/rsc-cache-key.js +19 -3
  144. package/dist/native/rsc/shared/rsc-cache-key.js.map +1 -1
  145. package/dist/native/rsc/shims/headers.js +3 -4
  146. package/dist/native/rsc/shims/headers.js.map +1 -1
  147. package/dist/native/ssr/client/outlet-content-cache.js +17 -3
  148. package/dist/native/ssr/client/outlet-content-cache.js.map +1 -1
  149. package/dist/native/ssr/client/segment-outlet.js +3 -3
  150. package/dist/native/ssr/client/segment-outlet.js.map +1 -1
  151. package/dist/native/ssr/cookies/define-cookie.js +6 -2
  152. package/dist/native/ssr/cookies/define-cookie.js.map +1 -1
  153. package/dist/native/ssr/manifest.json +4 -0
  154. package/dist/native/ssr/search-params/define.js +4 -1
  155. package/dist/native/ssr/search-params/define.js.map +1 -1
  156. package/dist/native/ssr/server/als-registry.js +2 -1
  157. package/dist/native/ssr/server/als-registry.js.map +1 -1
  158. package/dist/native/ssr/server/client-state-tree.js +14 -9
  159. package/dist/native/ssr/server/client-state-tree.js.map +1 -1
  160. package/dist/native/ssr/server/cookie-context.js +12 -0
  161. package/dist/native/ssr/server/cookie-context.js.map +1 -1
  162. package/dist/native/ssr/server/flight-source.js +1 -0
  163. package/dist/native/ssr/server/flight-source.js.map +1 -1
  164. package/dist/native/ssr/server/framework-stack-frames.js +18 -0
  165. package/dist/native/ssr/server/framework-stack-frames.js.map +1 -0
  166. package/dist/native/ssr/server/request-context.js +10 -4
  167. package/dist/native/ssr/server/request-context.js.map +1 -1
  168. package/dist/native/ssr/server/rsc-cache-key-guard.js +5 -1
  169. package/dist/native/ssr/server/rsc-cache-key-guard.js.map +1 -1
  170. package/dist/native/ssr/server/segment-lifetime/key-digest.js +6 -0
  171. package/dist/native/ssr/server/segment-lifetime/key-digest.js.map +1 -0
  172. package/dist/native/ssr/server/segment-lifetime/read-rule.js +56 -0
  173. package/dist/native/ssr/server/segment-lifetime/read-rule.js.map +1 -0
  174. package/dist/native/ssr/shared/als-slots.js +2 -2
  175. package/dist/native/ssr/shared/als-slots.js.map +1 -1
  176. package/dist/native/ssr/shared/cookie-read-through.js +5 -0
  177. package/dist/native/ssr/shared/cookie-read-through.js.map +1 -0
  178. package/dist/native/ssr/shared/rsc-cache-key.js +19 -3
  179. package/dist/native/ssr/shared/rsc-cache-key.js.map +1 -1
  180. package/dist/native/ssr/shims/headers.js +3 -4
  181. package/dist/native/ssr/shims/headers.js.map +1 -1
  182. package/dist/plugins/callsite-jsx.d.ts +8 -1
  183. package/dist/plugins/callsite-jsx.d.ts.map +1 -1
  184. package/dist/plugins/entries.d.ts.map +1 -1
  185. package/dist/plugins/prerender-sugar.d.ts +9 -8
  186. package/dist/plugins/prerender-sugar.d.ts.map +1 -1
  187. package/dist/plugins/routing.d.ts.map +1 -1
  188. package/dist/routing/convention-lint.d.ts +11 -3
  189. package/dist/routing/convention-lint.d.ts.map +1 -1
  190. package/dist/routing/export-detect.d.ts +50 -23
  191. package/dist/routing/export-detect.d.ts.map +1 -1
  192. package/dist/routing/index.js +2 -2
  193. package/dist/routing/route-options-lint.d.ts +36 -0
  194. package/dist/routing/route-options-lint.d.ts.map +1 -0
  195. package/dist/routing/route-options.d.ts +55 -0
  196. package/dist/routing/route-options.d.ts.map +1 -0
  197. package/dist/routing/segment-keys.d.ts +35 -0
  198. package/dist/routing/segment-keys.d.ts.map +1 -1
  199. package/dist/search-params/index.js +5 -2
  200. package/dist/search-params/index.js.map +1 -1
  201. package/dist/server/als-registry.d.ts +23 -0
  202. package/dist/server/als-registry.d.ts.map +1 -1
  203. package/dist/server/client-state-tree.d.ts +10 -3
  204. package/dist/server/client-state-tree.d.ts.map +1 -1
  205. package/dist/server/cookie-context.d.ts +3 -0
  206. package/dist/server/cookie-context.d.ts.map +1 -1
  207. package/dist/server/flight-source.d.ts +4 -1
  208. package/dist/server/flight-source.d.ts.map +1 -1
  209. package/dist/server/framework-stack-frames.d.ts +23 -0
  210. package/dist/server/framework-stack-frames.d.ts.map +1 -0
  211. package/dist/server/index.d.ts +1 -0
  212. package/dist/server/index.d.ts.map +1 -1
  213. package/dist/server/index.js +2 -2
  214. package/dist/server/internal.js +105 -21
  215. package/dist/server/internal.js.map +1 -1
  216. package/dist/server/prebuilt/capture-routes.d.ts +1 -1
  217. package/dist/server/prebuilt-builder.d.ts.map +1 -1
  218. package/dist/server/request-context.d.ts +6 -1
  219. package/dist/server/request-context.d.ts.map +1 -1
  220. package/dist/server/route-element-builder.d.ts.map +1 -1
  221. package/dist/server/route-module-loader.d.ts +10 -2
  222. package/dist/server/route-module-loader.d.ts.map +1 -1
  223. package/dist/server/rsc-cache-key-guard.d.ts +3 -1
  224. package/dist/server/rsc-cache-key-guard.d.ts.map +1 -1
  225. package/dist/server/rsc-entry/index.d.ts.map +1 -1
  226. package/dist/server/rsc-entry/render-route.d.ts +10 -0
  227. package/dist/server/rsc-entry/render-route.d.ts.map +1 -1
  228. package/dist/server/rsc-entry/revalidate-renderer.d.ts +12 -0
  229. package/dist/server/rsc-entry/revalidate-renderer.d.ts.map +1 -1
  230. package/dist/server/segment-hash/outlet.d.ts +28 -0
  231. package/dist/server/segment-hash/outlet.d.ts.map +1 -1
  232. package/dist/server/segment-lifetime/document-outlet.d.ts +66 -0
  233. package/dist/server/segment-lifetime/document-outlet.d.ts.map +1 -0
  234. package/dist/server/segment-lifetime/key-digest.d.ts +46 -0
  235. package/dist/server/segment-lifetime/key-digest.d.ts.map +1 -0
  236. package/dist/server/segment-lifetime/read-rule.d.ts +43 -0
  237. package/dist/server/segment-lifetime/read-rule.d.ts.map +1 -0
  238. package/dist/server/segment-lifetime/read-scope.d.ts +39 -0
  239. package/dist/server/segment-lifetime/read-scope.d.ts.map +1 -0
  240. package/dist/server/segment-lifetime/segment-key.d.ts +60 -0
  241. package/dist/server/segment-lifetime/segment-key.d.ts.map +1 -0
  242. package/dist/server/segment-lifetime/slot-outlets.d.ts +81 -0
  243. package/dist/server/segment-lifetime/slot-outlets.d.ts.map +1 -0
  244. package/dist/server/slot-resolver.d.ts +6 -1
  245. package/dist/server/slot-resolver.d.ts.map +1 -1
  246. package/dist/server/slot-subtree-contain.d.ts +2 -6
  247. package/dist/server/slot-subtree-contain.d.ts.map +1 -1
  248. package/dist/server/subtree-walk.d.ts +56 -0
  249. package/dist/server/subtree-walk.d.ts.map +1 -0
  250. package/dist/server/types.d.ts +69 -0
  251. package/dist/server/types.d.ts.map +1 -1
  252. package/dist/shared/als-slots.d.ts +12 -2
  253. package/dist/shared/als-slots.d.ts.map +1 -1
  254. package/dist/shared/cookie-read-through.d.ts +18 -0
  255. package/dist/shared/cookie-read-through.d.ts.map +1 -0
  256. package/dist/shared/outlet-decision.d.ts +23 -4
  257. package/dist/shared/outlet-decision.d.ts.map +1 -1
  258. package/dist/shared/route-options-export.d.ts +13 -0
  259. package/dist/shared/route-options-export.d.ts.map +1 -0
  260. package/dist/shared/rsc-cache-key.d.ts +22 -0
  261. package/dist/shared/rsc-cache-key.d.ts.map +1 -1
  262. package/dist/shared/segment-info.d.ts +6 -0
  263. package/dist/shared/segment-info.d.ts.map +1 -1
  264. package/dist/shims/headers.d.ts.map +1 -1
  265. package/docs/api/30-api-server.mdx +29 -0
  266. package/docs/api/32-api-cache.mdx +10 -4
  267. package/docs/api/34-api-config.mdx +5 -0
  268. package/docs/learn/09-streaming.mdx +6 -2
  269. package/docs/learn/10-caching.mdx +10 -4
  270. package/package.json +1 -1
  271. package/src/cli-check.ts +11 -3
  272. package/src/client/navigation-commit.ts +11 -2
  273. package/src/client/outlet-content-cache.ts +40 -8
  274. package/src/client/router.ts +1 -0
  275. package/src/client/segment-outlet.tsx +10 -4
  276. package/src/config-types.ts +25 -0
  277. package/src/config-validation.ts +17 -0
  278. package/src/cookies/define-cookie.ts +5 -1
  279. package/src/index.ts +2 -1
  280. package/src/plugins/callsite-jsx.ts +104 -6
  281. package/src/plugins/entries.ts +3 -0
  282. package/src/plugins/prerender-sugar.ts +34 -18
  283. package/src/plugins/routing.ts +3 -1
  284. package/src/routing/convention-lint.ts +18 -7
  285. package/src/routing/export-detect.ts +14 -117
  286. package/src/routing/route-options-lint.ts +153 -0
  287. package/src/routing/route-options.ts +423 -0
  288. package/src/routing/segment-keys.ts +50 -0
  289. package/src/rsc-runtime/vendor-types.d.ts +4 -0
  290. package/src/search-params/define.ts +1 -1
  291. package/src/server/als-registry.ts +29 -0
  292. package/src/server/client-state-tree.ts +30 -16
  293. package/src/server/cookie-context.ts +17 -0
  294. package/src/server/flight-source.ts +7 -1
  295. package/src/server/framework-stack-frames.ts +44 -0
  296. package/src/server/index.ts +7 -0
  297. package/src/server/prebuilt/capture-routes.ts +1 -1
  298. package/src/server/prebuilt-builder.ts +30 -2
  299. package/src/server/request-context.ts +28 -4
  300. package/src/server/route-element-builder.ts +80 -5
  301. package/src/server/route-module-loader.ts +43 -10
  302. package/src/server/rsc-cache-key-guard.ts +17 -2
  303. package/src/server/rsc-entry/index.ts +16 -0
  304. package/src/server/rsc-entry/render-route.ts +19 -1
  305. package/src/server/rsc-entry/revalidate-renderer.ts +17 -1
  306. package/src/server/segment-hash/outlet.ts +62 -18
  307. package/src/server/segment-lifetime/document-outlet.ts +98 -0
  308. package/src/server/segment-lifetime/key-digest.ts +139 -0
  309. package/src/server/segment-lifetime/read-rule.ts +136 -0
  310. package/src/server/segment-lifetime/read-scope.ts +99 -0
  311. package/src/server/segment-lifetime/segment-key.ts +140 -0
  312. package/src/server/segment-lifetime/slot-outlets.ts +180 -0
  313. package/src/server/slot-resolver.ts +99 -56
  314. package/src/server/slot-subtree-contain.ts +35 -182
  315. package/src/server/subtree-walk.ts +316 -0
  316. package/src/server/types.ts +85 -0
  317. package/src/shared/als-slots.ts +19 -8
  318. package/src/shared/cookie-read-through.ts +18 -0
  319. package/src/shared/outlet-decision.ts +25 -4
  320. package/src/shared/route-options-export.ts +14 -0
  321. package/src/shared/rsc-cache-key.ts +41 -2
  322. package/src/shared/segment-info.ts +6 -0
  323. package/src/shims/headers.ts +5 -4
  324. package/dist/_chunks/actions-DIgnvDrG.js.map +0 -1
  325. package/dist/_chunks/als-slots-kbQrHTzm.js.map +0 -1
  326. package/dist/_chunks/chains-CSslTUdI.js +0 -1
  327. package/dist/_chunks/cli-check-C3QOAru7.js.map +0 -1
  328. package/dist/_chunks/convention-lint-BoVISNS6.js.map +0 -1
  329. package/dist/_chunks/dev-server-B8roKA3Q.js +0 -1
  330. package/dist/_chunks/dev-server-C5R6jx8Q.js.map +0 -1
  331. package/dist/_chunks/dist-C1Rjlo6s.js.map +0 -1
  332. package/dist/_chunks/error-boundary-DB51f9ih.js.map +0 -1
  333. package/dist/_chunks/scanner-C9Lrf77z.js.map +0 -1
@@ -1,14 +1,15 @@
1
1
  /**
2
- * timber-prerender-sugar — Vite plugin that desugars `export const prerender`
3
- * on page and layout files into `cache.component(...)` wrappers.
2
+ * timber-prerender-sugar — Vite plugin that desugars `prerender` in a page's
3
+ * `pageOptions` (or an ancestor layout's `layoutOptions`) into a
4
+ * `cache.component(...)` wrapper around the page.
4
5
  *
5
6
  * Design doc: design/45-cache-lifetimes.md §"Route-Level Static" and
6
- * §"Layout Propagation".
7
+ * §"Layout Propagation"; design/53-segment-lifetime.md §"Route-module options".
7
8
  *
8
- * `export const prerender = true` on a page is pure sugar: it desugars to
9
+ * `pageOptions = { prerender: true }` on a page is pure sugar: it desugars to
9
10
  * wrapping the page's default export in `timber.cache.component(Component,
10
11
  * { prerender: true })`. Layout propagation cascades a layout's
11
- * `export const prerender` to descendant pages via most-specific-wins:
12
+ * `layoutOptions.prerender` to descendant pages via most-specific-wins:
12
13
  * walk the segment tree from leaf to root, first explicit value wins.
13
14
  *
14
15
  * Layout declarations are propagation policy only. Layouts receive the real
@@ -22,18 +23,18 @@
22
23
  import type { Plugin } from 'vite';
23
24
  import type { PluginContext } from '../plugin-context.ts';
24
25
  import type { SegmentNode } from '../routing/types.ts';
25
- import { type PrerenderExportValue } from '../routing/export-detect.ts';
26
+ import type { RoutePrerender } from '../server/types.ts';
26
27
  /**
27
28
  * Walk the segment tree and resolve the effective prerender value for
28
29
  * every page. Returns a map from page file path to resolved value.
29
30
  *
30
- * **Pages:** walk from leaf toward root; first explicit `export const prerender`
31
+ * **Pages:** walk from leaf toward root; first explicit `prerender` option
31
32
  * wins (page > nearest layout > ... > root layout). If none, dynamic.
32
33
  *
33
34
  * **Layouts:** declarations propagate to descendant pages but layouts are not
34
35
  * included in the result. Their real React-element `children` preserve secure
35
36
  * containment and deliberately make child-independent layout caching invalid.
36
37
  */
37
- export declare function resolvePagePrerender(root: SegmentNode): Map<string, PrerenderExportValue>;
38
+ export declare function resolvePagePrerender(root: SegmentNode): Map<string, RoutePrerender>;
38
39
  export declare function timberPrerenderSugar(ctx: PluginContext): Plugin;
39
40
  //# sourceMappingURL=prerender-sugar.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"prerender-sugar.d.ts","sourceRoot":"","sources":["../../src/plugins/prerender-sugar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAY5F;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CA2BzF;AAuFD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwL/D"}
1
+ {"version":3,"file":"prerender-sugar.d.ts","sourceRoot":"","sources":["../../src/plugins/prerender-sugar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAazD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CA2BnF;AAoGD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAyL/D"}
@@ -1 +1 @@
1
- {"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAA4B,KAAK,MAAM,EAAsB,MAAM,MAAM,CAAC;AAYjF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAsD1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA4SxD"}
1
+ {"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAA4B,KAAK,MAAM,EAAsB,MAAM,MAAM,CAAC;AAYjF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAsD1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA8SxD"}
@@ -9,14 +9,18 @@
9
9
  * empty pages, confusing React errors).
10
10
  *
11
11
  * A check emits `level: 'error'` only when the misconfiguration is *proven*
12
- * (never inferred from an absence the analysis cannot see through) and fatal
13
- * to rendering. `plugins/routing.ts` turns those into a thrown build error,
12
+ * (never inferred from an absence the analysis cannot see through) and either
13
+ * fatal to rendering or a declaration that provably does nothing — a CSRF
14
+ * exemption the gate never reads, a route option the build cannot read, a
15
+ * middleware.ts in a slot. The developer believes the declaration is in
16
+ * effect, so silence would ship the wrong behavior. `plugins/routing.ts` turns those into a thrown build error,
14
17
  * so a false positive there refuses a working app — see
15
18
  * `classifyClientBoundaryFile` for how that bar is met.
16
19
  *
17
20
  * Design doc: 07-routing.md, 10-error-handling.md
18
21
  */
19
22
  import type { RouteTree } from './types.ts';
23
+ import type { SegmentLifetime } from '../server/types.ts';
20
24
  export interface ConventionWarning {
21
25
  /** Warning ID for deduplication and filtering. */
22
26
  id: string;
@@ -32,7 +36,11 @@ export interface ConventionWarning {
32
36
  *
33
37
  * Returns an array of warnings. Empty array means everything looks good.
34
38
  */
35
- export declare function lintConventions(tree: RouteTree, appDir: string): ConventionWarning[];
39
+ export declare function lintConventions(tree: RouteTree, appDir: string,
40
+ /** The config the checks depend on, as the build resolved it. */
41
+ config: {
42
+ defaultLayoutLifetime: SegmentLifetime | undefined;
43
+ }): ConventionWarning[];
36
44
  /**
37
45
  * Check if the app/ directory exists. Called before scanning.
38
46
  * Returns a warning if missing, or null if the directory exists.
@@ -1 +1 @@
1
- {"version":3,"file":"convention-lint.d.ts","sourceRoot":"","sources":["../../src/routing/convention-lint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAa,SAAS,EAAe,MAAM,YAAY,CAAC;AAcpE,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAyCpF;AA2dD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAe1E;AAUD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAkCR"}
1
+ {"version":3,"file":"convention-lint.d.ts","sourceRoot":"","sources":["../../src/routing/convention-lint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAa,SAAS,EAAe,MAAM,YAAY,CAAC;AAapE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAI1D,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,MAAM;AACd,iEAAiE;AACjE,MAAM,EAAE;IAAE,qBAAqB,EAAE,eAAe,GAAG,SAAS,CAAA;CAAE,GAC7D,iBAAiB,EAAE,CA6CrB;AAudD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAe1E;AAUD,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAkCR"}
@@ -5,6 +5,46 @@
5
5
  * default exports, replacing the regex-based approach that was fragile
6
6
  * with TypeScript syntax (type exports, `as` aliases, comments, etc.).
7
7
  */
8
+ interface AstNode {
9
+ type: string;
10
+ exportKind?: string;
11
+ declaration?: AstNode;
12
+ specifiers?: Array<{
13
+ exported?: {
14
+ name: string;
15
+ };
16
+ local?: {
17
+ name: string;
18
+ };
19
+ exportKind?: string;
20
+ }>;
21
+ id?: {
22
+ name: string;
23
+ };
24
+ declarations?: Array<{
25
+ id?: {
26
+ name: string;
27
+ };
28
+ init?: AstNode;
29
+ }>;
30
+ /** Set on re-exports: `export { X } from './y'`. Absent on local exports. */
31
+ source?: {
32
+ value?: string;
33
+ } | null;
34
+ /** Set on runtime-transparent wrappers: `X as T`, `X satisfies T`, `(X)`, `X!`. */
35
+ expression?: AstNode;
36
+ /** Set on `Identifier` nodes. */
37
+ name?: string;
38
+ }
39
+ interface ProgramNode {
40
+ body: AstNode[];
41
+ }
42
+ /**
43
+ * Parse a module. `lang` defaults to `tsx`; pass `ts` for `.ts` files, where
44
+ * an angle-bracket cast or a generic arrow (`<T>(x: T) => x`) is valid
45
+ * TypeScript but a TSX parse error.
46
+ */
47
+ export declare function tryParse(source: string, lang?: 'ts' | 'tsx'): ProgramNode | null;
8
48
  /**
9
49
  * Check if a file exports a specific named export.
10
50
  * Returns false if the file doesn't exist or can't be parsed.
@@ -20,6 +60,11 @@ export declare function fileHasAnyExport(filePath: string, exportNames: readonly
20
60
  * Returns false if the file doesn't exist or can't be parsed.
21
61
  */
22
62
  export declare function fileHasDefaultExport(filePath: string): boolean;
63
+ /**
64
+ * Expression wrappers that erase at runtime and so cannot change where a value
65
+ * was constructed: `X as T`, `X satisfies T`, `<T>X`, `X!`, `X<T>`, `(X)`.
66
+ */
67
+ export declare const TRANSPARENT_WRAPPERS: ReadonlySet<string>;
23
68
  /**
24
69
  * Whether the default export is *provably* a value constructed by this module:
25
70
  * `export default function/class/() => {}`, or a name bound to a function or
@@ -41,29 +86,6 @@ export declare function fileDefaultExportIsLocalValue(filePath: string): boolean
41
86
  * Returns false if the file doesn't exist or can't be parsed.
42
87
  */
43
88
  export declare function fileHasStarExport(filePath: string): boolean;
44
- /**
45
- * Parsed value of `export const prerender` from a route file.
46
- *
47
- * - `true` / `false` — literal boolean
48
- * - `{ ttl?, tags? }` — ISR options object (prerender: true is implied)
49
- * - `undefined` — no `export const prerender` found
50
- *
51
- * See design/45-cache-lifetimes.md §"Route-Level Static".
52
- */
53
- export type PrerenderExportValue = boolean | {
54
- ttl?: number;
55
- tags?: string[];
56
- };
57
- /**
58
- * Extract the value of `export const prerender` from a file.
59
- * Returns undefined if the file doesn't export `prerender` or can't be parsed.
60
- *
61
- * Supports:
62
- * export const prerender = true;
63
- * export const prerender = false;
64
- * export const prerender = { ttl: 3600, tags: ['docs'] };
65
- */
66
- export declare function getPrerenderExport(filePath: string): PrerenderExportValue | undefined;
67
89
  /**
68
90
  * How a file declares the per-route CSRF exemption.
69
91
  *
@@ -83,9 +105,14 @@ export declare function getPrerenderExport(filePath: string): PrerenderExportVal
83
105
  */
84
106
  export type CsrfExport = 'absent' | 'exempt' | 'invalid';
85
107
  export declare function getCsrfExport(filePath: string): CsrfExport;
108
+ /** Whether a destructuring pattern binds `name` anywhere inside it. */
109
+ export declare function patternBinds(node: unknown, name: string): boolean;
86
110
  /**
87
111
  * Check if a file starts with a specific directive (e.g. "use client").
88
112
  * Directives are string literal expression statements at the top of the file.
89
113
  */
90
114
  export declare function fileHasDirective(filePath: string, directive: string): boolean;
115
+ /** Route files the AST checks can read; `.mdx` and `.json` are skipped. */
116
+ export declare function isScriptExtension(ext: string): boolean;
117
+ export {};
91
118
  //# sourceMappingURL=export-detect.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"export-detect.d.ts","sourceRoot":"","sources":["../../src/routing/export-detect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4HH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAU3E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAc9F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAU9D;AAoED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAiCvE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAU3D;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AA8C/E;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CA+CrF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAsC1D;AA+BD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAgB7E"}
1
+ {"version":3,"file":"export-detect.d.ts","sourceRoot":"","sources":["../../src/routing/export-detect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,UAAU,OAAO;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,QAAQ,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5B,KAAK,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QACzB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;IACH,EAAE,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtB,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAChE,6EAA6E;IAC7E,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnC,mFAAmF;IACnF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,UAAU,WAAW;IACnB,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,GAAG,KAAa,GAAG,WAAW,GAAG,IAAI,CAMvF;AAyFD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAU3E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAc9F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAU9D;AAWD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAOnD,CAAC;AA8CH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAiCvE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAU3D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAsC1D;AAQD,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAoBjE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAgB7E;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtD"}
@@ -1,6 +1,6 @@
1
- import { n as scanRoutes } from "../_chunks/scanner-C9Lrf77z.js";
1
+ import { n as scanRoutes } from "../_chunks/scanner-DneYxQoY.js";
2
2
  import { t as generateRouteMap } from "../_chunks/codegen-vaCyFyVN.js";
3
3
  import { a as INTERCEPTION_MARKERS, i as DEFAULT_PAGE_EXTENSIONS, n as classifyUrlSegment, t as classifySegment } from "../_chunks/segment-classify-Ho8jXWeC.js";
4
4
  import { t as collectInterceptionRewrites } from "../_chunks/interception-CtNt9jPt.js";
5
- import { n as collectDynamicSegmentsFromTree, r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "../_chunks/walkers-Bxv4v7tX.js";
5
+ import { n as collectDynamicSegmentsFromTree, r as validateSchemaAgainstRoutes, t as collectLeafRoutes } from "../_chunks/walkers-C9R2A4jN.js";
6
6
  export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS, classifySegment, classifyUrlSegment, collectDynamicSegmentsFromTree, collectInterceptionRewrites, collectLeafRoutes, generateRouteMap, scanRoutes, validateSchemaAgainstRoutes };
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Convention-lint check for route-module options (design/53 §"Route-module
3
+ * options"): `layoutOptions` / `pageOptions` the build cannot read, and
4
+ * options declared where nothing reads them. Called from
5
+ * `lintConventions` in `convention-lint.ts`.
6
+ */
7
+ import type { ConventionWarning } from './convention-lint.ts';
8
+ import type { SegmentNode } from './types.ts';
9
+ import type { SegmentLifetime } from '../server/types.ts';
10
+ /**
11
+ * Fail the build on a `layoutOptions` / `pageOptions` the build cannot read.
12
+ *
13
+ * Proven from source and fatal in the sense the error level requires: the
14
+ * developer declared an option that would otherwise silently do nothing — a
15
+ * misspelled key, a value the build cannot read, an options object in the
16
+ * wrong file kind, or a floating `export const prerender` that no longer
17
+ * prerenders. See `routing/route-options.ts` for what is accepted.
18
+ */
19
+ export declare function checkRouteOptions(node: SegmentNode, warnings: ConventionWarning[], position: RoutePosition,
20
+ /** The app's `defaultLayoutLifetime` (design/53 §"App-wide default"). */
21
+ defaultLayoutLifetime: SegmentLifetime,
22
+ /** The params named on the path above this segment. */
23
+ ancestorParams?: readonly string[]): void;
24
+ /**
25
+ * Where a segment sits decides which options take effect there.
26
+ * - `main`: the matched route chain. Every option applies.
27
+ * - `slot`: a parallel slot. `prerender` applies to slot pages (the sugar
28
+ * walks slots); `deferSuspenseFor` does not — the hold is read from the
29
+ * main chain's modules only (`server/route-module-loader.ts`).
30
+ * - `intercepting`: an intercepting route and everything under it. It renders
31
+ * only on a soft navigation, through the slot resolver, and the sugar skips
32
+ * it, so no option applies.
33
+ */
34
+ type RoutePosition = 'main' | 'slot' | 'intercepting';
35
+ export {};
36
+ //# sourceMappingURL=route-options-lint.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"route-options-lint.d.ts","sourceRoot":"","sources":["../../src/routing/route-options-lint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,KAAK,EAA8B,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGtF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,QAAQ,EAAE,aAAa;AACvB,yEAAyE;AACzE,qBAAqB,EAAE,eAAe;AACtC,uDAAuD;AACvD,cAAc,GAAE,SAAS,MAAM,EAAO,GACrC,IAAI,CAgDN;AAwCD;;;;;;;;;GASG;AACH,KAAK,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,cAAc,CAAC"}
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Route-module options: `export const layoutOptions = { … }` in a layout and
3
+ * `export const pageOptions = { … }` in a page, read from source.
4
+ *
5
+ * Design doc: design/53-segment-lifetime.md §"Route-module options".
6
+ *
7
+ * `prerender` is read here at build time, before any route module loads:
8
+ * `plugins/prerender-sugar.ts` decides from it which pages to wrap in
9
+ * `cache.component(...)`. Every other option is validated here and read at
10
+ * runtime from the loaded module (`deferSuspenseFor`, in
11
+ * `server/route-module-loader.ts`; `lifetime` and `key`, in
12
+ * `server/segment-lifetime/segment-key.ts`). A key's `searchParams` and
13
+ * `cookies` name definitions, so they are the one place a non-literal value is
14
+ * accepted; `segmentParams` is checked against the segment's path by
15
+ * `routing/route-options-lint.ts`. The whole object follows one rule so that
16
+ * every key is checkable: this reader accepts one spelling —
17
+ * `export const xOptions = { … }` of literal values, optionally behind
18
+ * `satisfies` / `as` — and reports the others it can see as problems.
19
+ * `routing/convention-lint.ts` turns problems into build errors:
20
+ *
21
+ * - a spread, a computed key, a getter or method, or a non-literal value
22
+ * - an unknown key (a misspelled `prerendr`)
23
+ * - `pageOptions` in a layout or `layoutOptions` in a page
24
+ * - options in a `'use client'` file, whose exports the server never sees
25
+ * - the removed floating exports, `export const prerender` and
26
+ * `export const deferSuspenseFor`
27
+ * - `let`, a destructured binding, a specifier or a named re-export
28
+ * (`export { pageOptions } from`, `export * as pageOptions from`)
29
+ *
30
+ * What it cannot see is not reported: `export * from` is not followed, a
31
+ * file that does not parse reads as having no options (the compiler reports
32
+ * it), and MDX pages are not read at all, so `prerender` in an MDX page does
33
+ * nothing and its `deferSuspenseFor` is unvalidated.
34
+ */
35
+ import type { LayoutOptions, PageOptions } from '../server/types.ts';
36
+ import { type RouteOptionsKind } from '../shared/route-options-export.ts';
37
+ export interface RouteOptionsRead {
38
+ /**
39
+ * The declared options. Undefined when the file declares none or when any
40
+ * problem was found — a half-read object is never acted on.
41
+ */
42
+ options: LayoutOptions | PageOptions | undefined;
43
+ /** One line per problem, each naming what to write instead. */
44
+ problems: string[];
45
+ }
46
+ /**
47
+ * Read a layout's `layoutOptions` or a page's `pageOptions` from source.
48
+ *
49
+ * A missing or unparseable file reads as no options and no problems: the
50
+ * compiler reports syntax errors, and guessing at a half-written file would
51
+ * misreport it. `.ts` files are parsed as TypeScript, not TSX, so an
52
+ * angle-bracket cast does not hide a file from this check.
53
+ */
54
+ export declare function readRouteOptions(filePath: string, kind: RouteOptionsKind): RouteOptionsRead;
55
+ //# sourceMappingURL=route-options.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"route-options.d.ts","sourceRoot":"","sources":["../../src/routing/route-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EAIZ,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAOhG,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,OAAO,EAAE,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;IACjD,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA6QD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,CAsE3F"}
@@ -102,4 +102,39 @@ export declare function computeSlotKey(parentSegmentId: string, slotName: string
102
102
  * See design/52-segment-hash-dedupe.md §"The unit is the segment's own output".
103
103
  */
104
104
  export declare function childrenOutletKey(segmentId: string): string;
105
+ /**
106
+ * The outlet keys of `'document'` segments (design/53-segment-lifetime.md
107
+ * §"Skipping"), by the segment's **tree path** — its directory path, route
108
+ * groups and `@slot` directories included. A `'document'` skip is
109
+ * identity-addressed (the client renders what it holds at this key, under a
110
+ * digest bound to it), so the key must name one segment. Segment ids
111
+ * (`computeSegmentKeys`) do not: `(landing)/feed` and `(browse)/feed` both
112
+ * key as `/feed`, which a content-addressed hash skip survives and a digest
113
+ * skip would not.
114
+ *
115
+ * `#` starts a URL fragment, so no routable segment is named with it — the
116
+ * same reason the metadata outlet is `#metadata`. A `'document'` layout's
117
+ * `children` outlet is `childrenOutletKey` of its layout key in a slot; on the
118
+ * main chain it keeps `childrenOutletKey(segmentId)`.
119
+ */
120
+ export declare function pageOutletKey(treePath: string): string;
121
+ /** See `pageOutletKey`. */
122
+ export declare function layoutOutletKey(treePath: string): string;
123
+ /**
124
+ * The full tree path of a slot's matched chain (or a prefix of it) — the key
125
+ * the ALS slot params map, the generated `getSegmentParams` overloads and a
126
+ * slot's `'document'` outlets all use.
127
+ *
128
+ * Built from the parent's tree path plus each chain node's directory name,
129
+ * so an intercepting node contributes its marker
130
+ * (`/gallery/@modal/(.)photo/[id]`) and a route group contributes its
131
+ * parentheses.
132
+ *
133
+ * One definition for the render path, the eager access path and the outlet
134
+ * keys: they key the same things, and a divergence would silently strand one
135
+ * of them.
136
+ */
137
+ export declare function slotChainTreePath(chain: ReadonlyArray<{
138
+ segmentName?: string;
139
+ }>, parentTreePath: string): string;
105
140
  //# sourceMappingURL=segment-keys.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"segment-keys.d.ts","sourceRoot":"","sources":["../../src/routing/segment-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;GAMG;AAEH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAmBxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAmB7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAExD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIhF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D"}
1
+ {"version":3,"file":"segment-keys.d.ts","sourceRoot":"","sources":["../../src/routing/segment-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;GAMG;AAEH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAmBxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,CAmB7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAExD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIhF;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,2BAA2B;AAC3B,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,aAAa,CAAC;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9C,cAAc,EAAE,MAAM,GACrB,MAAM,CAOR"}
@@ -1,6 +1,6 @@
1
1
  import { i as parseTotal, n as useQueryStates, r as serializedEqual } from "../_chunks/use-query-states-D3MMl-KM.js";
2
2
  import { i as isStandardSchema, n as fromSchema, r as isCodec } from "../_chunks/schema-bridge-DyRs3cqy.js";
3
- import { r as getSearchParamsFromAls } from "../_chunks/als-slots-kbQrHTzm.js";
3
+ import { r as getSearchParamsFromAls } from "../_chunks/als-slots-CVTF-AMz.js";
4
4
  import { debounce, defaultRateLimit, throttle } from "nuqs/server";
5
5
  // src/search-params/define.ts
6
6
  /**
@@ -185,7 +185,10 @@ function buildDefinition(codecMap, urlKeys) {
185
185
  }
186
186
  function get() {
187
187
  if (typeof window !== "undefined") throw new Error("[timber] searchParams.get() is server-only. Use searchParams.useQueryStates() on the client.");
188
- return parseSync(getSearchParamsFromAls());
188
+ return parseSync(getSearchParamsFromAls({
189
+ codecs: codecMap,
190
+ urlKeys
191
+ }));
189
192
  }
190
193
  return {
191
194
  parse,
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","names":["useQueryStates","clientUseQueryStates"],"sources":["../../src/search-params/define.ts","../../src/search-params/wrappers.ts"],"sourcesContent":["/**\n * defineSearchParams — factory for SearchParamsDefinition<T>.\n *\n * Creates a typed, composable definition for a route's search parameters.\n * Accepts both SearchParamCodec values and Standard Schema objects (Zod,\n * Valibot, ArkType) with auto-detection. Supports URL key aliasing via\n * withUrlKey(), default-omission serialization, and composition via\n * .extend() / .pick().\n *\n * Design doc: design/23-search-params.md §\"defineSearchParams — The Factory\"\n */\n\nimport { useQueryStates as clientUseQueryStates } from '../client/use-query-states.ts';\nimport { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.ts';\nimport type { StandardSchemaV1 } from '../schema-bridge.ts';\nimport type { Codec } from '../codec.ts';\nimport type { Options as NuqsOptions } from 'nuqs';\n// Server-only reference for .get() — avoids pulling server ALS into client\n// bundles. In client environments, .get() throws before reaching this code\n// path. The slot lives in its own leaf module so that `request-context.ts`\n// can register the getter without importing this file, which would drag\n// `nuqs` into every server entry (TIM-1298). See shared/als-slots.ts.\nimport { getSearchParamsFromAls } from '../shared/als-slots.ts';\nimport { parseTotal } from './parse-total.ts';\nimport { serializedEqual } from './serialize-equal.ts';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A codec that converts between URL string values and typed values.\n *\n * `parse` receives the RAW url value: `string | string[] | undefined`.\n * A codec must be TOTAL over that domain — return a default rather than\n * throwing on an absent or repeated param.\n *\n * A codec whose own `parse` covers only a PRESENT, SINGLE-VALUED param\n * may publish `parseServerSide` instead, and timber calls that. nuqs\n * parsers do exactly this, which is how they become total here: absent →\n * `null` (or their `withDefault` value), repeated → the first value, and\n * a throw from the inner parse → `null`. See\n * design/23-search-params.md §'nuqs parsers, made total',\n * `parse-total.ts`, and tests/nuqs-codec-boundary.test.ts (TIM-1350).\n *\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected\n * by defineSearchParams and wrapped via fromSchema; those ARE total\n * through `parse` and are called that way.\n */\nexport interface SearchParamCodec<T> extends Omit<Codec<T>, 'serialize'> {\n /**\n * Typed value → URL string(s). Return `null` to omit/clear.\n *\n * A codec MAY return `string[]` to emit repeated keys (`?tag=a&tag=b`).\n * `buildSearchParams` appends one `key=value` entry per array element;\n * the nuqs bridge forwards the array to nuqs, which does the same.\n * Codecs that always produce a single value return a plain string.\n *\n * Wider than `Codec<T>.serialize` (`string | null`) because search params\n * have a repeated-key concept that cookies and segment params do not.\n */\n serialize(value: T): string | string[] | null;\n /** Optional URL key alias, set by withUrlKey(). */\n urlKey?: string;\n /**\n * Optional TOTAL entry point over `string | string[] | undefined`,\n * preferred over `parse` wherever timber invokes a codec. Declared here\n * so the protocol is typed rather than duck-checked at each wrapper:\n * anything that reconstructs a codec has to carry it, and a wrapper\n * cannot carry a property the interface does not admit.\n *\n * It returns `T`, not `T | null`. This is the entry point timber calls,\n * so whatever it returns IS the field's type — admitting a `null` the\n * field type did not carry would let `SearchParamCodec<string>` produce\n * `null` for an absent param under a non-nullable annotation. A codec\n * whose absent-case answer is `null` declares that in `T`, exactly as a\n * bare nuqs parser does: `parseAsString` is a `SearchParamCodec<string |\n * null>` here, never a `SearchParamCodec<string>`.\n *\n * nuqs parser builders satisfy this. See parse-total.ts.\n */\n parseServerSide?(value: string | string[] | undefined): T;\n}\n\n/** A codec with a URL key alias attached via withUrlKey(). */\nexport interface SearchParamCodecWithUrlKey<T> extends SearchParamCodec<T> {\n urlKey: string;\n}\n\n/** Infer the output type of a codec. */\nexport type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;\n\n/** Map of property names to codecs. */\nexport type CodecMap<T extends Record<string, unknown>> = {\n [K in keyof T]: SearchParamCodec<T[K]>;\n};\n\n/**\n * Options for a `setParams` call: nuqs's own `Options`, passed through\n * whole. Not a hand-copied subset — a whitelist silently dropped\n * `limitUrlUpdates` (debounce/throttle) and `clearOnDefault`, and would drop\n * whatever nuqs adds next (TIM-1623).\n *\n * `urlKeys` is not here: nuqs's `Options` does not carry it (it lives on\n * the hook-only `UseQueryStatesOptions`), and timber owns it — the aliases\n * come from the codecs (`withUrlKey`).\n *\n * The fields re-listed below are not a second declaration: each takes its\n * type from nuqs (`NuqsOptions['shallow']`), and is re-listed only because\n * nuqs's own JSDoc, which an editor shows on hover, is wrong for timber.\n * See design/23-search-params.md §\"Options pass through to nuqs\".\n */\nexport interface SetParamsOptions extends NuqsOptions {\n /**\n * `false` (timber's default): the write is an RSC navigation, so the server\n * renders the new params. `true`: the URL changes with no server request.\n */\n shallow?: NuqsOptions['shallow'];\n /** Scroll to the top after the write. Defaults to `true` in timber. */\n scroll?: NuqsOptions['scroll'];\n /**\n * Forwarded to nuqs, but it does not track the server request in timber.\n * timber runs navigations outside any transition, so `isPending` ends\n * before the RSC fetch does. Use `usePendingNavigation()` for a loading\n * state.\n */\n startTransition?: NuqsOptions['startTransition'];\n}\n\n/** Setter function returned by useQueryStates. */\nexport type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;\n\n/**\n * Options for the `useQueryStates` hook — the defaults for every setter call\n * from that hook instance. Same shape as {@link SetParamsOptions}; a per-call\n * option overrides the hook's.\n */\nexport type QueryStatesOptions = SetParamsOptions;\n\n/**\n * A fully typed, composable search params definition.\n *\n * Returned by defineSearchParams(). Carries a phantom _type property\n * for build-time type extraction.\n */\nexport interface SearchParamsDefinition<T extends Record<string, unknown>> {\n /** Parse raw URL search params into typed values. */\n parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n /** Parse a Promise of URLSearchParams (e.g., from the ALS `searchParams()` API). */\n parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;\n\n /**\n * Get typed search params from the current request context (ALS-backed).\n *\n * Server-only, sync. Reads getSearchParams() from ALS and parses through codecs.\n * Throws on client.\n *\n * ```tsx\n * // app/products/page.tsx\n * import { searchParams } from './search-params'\n * export default function Page() {\n * const { page, category } = searchParams.get()\n * }\n * ```\n */\n get(): T;\n\n /** Client hook — reads current URL params and returns typed values + setter. */\n useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];\n\n /** Extend with additional codecs or Standard Schema objects. */\n extend<U extends Record<string, SearchParamField>>(\n codecs: U\n ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }>;\n\n /** Pick a subset of keys. Preserves codecs and aliases. */\n pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;\n\n /**\n * Serialize values to a query string (no leading '?'), omitting defaults\n * and applying `withUrlKey` aliases. This is the value to pass to\n * `<Link searchParams={...}>`.\n *\n * Returns a **string**, not a `URLSearchParams`. A `<Link>` prop crosses\n * the RSC Flight boundary, and `URLSearchParams` is iterable — React\n * serializes it as an entries array, which arrives as `[['pg','2'], …]`\n * and renders as `?0=pg&0=2`. A string survives intact.\n */\n buildSearchParams(values: Partial<T>): string;\n\n /** Build a full path with query string, omitting defaults. */\n href(pathname: string, values: Partial<T>): string;\n\n /** Read-only codec map for spreading into .extend(). */\n codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n\n /** Read-only URL key alias map. Maps property names to URL query parameter keys. */\n readonly urlKeys: Readonly<Record<string, string>>;\n\n /**\n * Phantom property for build-time type extraction.\n * Never set at runtime — exists only in the type system.\n */\n readonly _type?: T;\n}\n\n// StandardSchemaV1 is imported from schema-bridge.ts — single source of truth.\n// Re-export for consumers that import it from this module.\nexport type { StandardSchemaV1 } from '../schema-bridge.ts';\n\n// ---------------------------------------------------------------------------\n// Type-level helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract a Standard Schema's declared *input* type from its optional\n * `~standard.types` property (part of the Standard Schema spec; Zod, Valibot,\n * and ArkType all declare it at the type level). Falls back to `never` when\n * the schema doesn't declare types (e.g. hand-written schemas): with no\n * metadata we can't know whether the schema handles `undefined`, so InferField\n * widens conservatively rather than risk a type lie.\n */\ntype InferSchemaInput<V> = V extends { '~standard': { types?: infer TS } }\n ? [NonNullable<TS>] extends [{ input: infer I }]\n ? I\n : never\n : never;\n\n/**\n * Infer the output type from either a SearchParamCodec or a StandardSchemaV1.\n *\n * A codec publishing `parseServerSide` is read through THAT signature, not\n * through `parse` — it is the entry point timber actually calls, and it is\n * the one that tells the truth about absent input. A bare `parseAsString`\n * declares `parse(value: string): string` but answers `null` for a missing\n * param, so the field is `string | null`; `parseAsInteger.withDefault(1)`\n * narrows its own `parseServerSide` to `NonNullable<number>` and the field\n * stays `number`. Reading `parse` instead produced a non-nullable type for\n * a nullable field (TIM-1350).\n *\n * The match is structural, not nuqs-specific: any codec declaring that\n * signature opts into being read through it, which is exactly the contract\n * `parseTotal` applies at runtime. The two must stay in step — a type\n * inferred from `parse` while the runtime calls `parseServerSide` is the\n * lie this branch exists to remove.\n *\n * Schemas whose input type rejects `undefined` (e.g. bare `z.string()`, whose\n * input is `string`) are implicitly optional: the URL might not contain the\n * param, and fromSchema returns `undefined` when the schema rejects absent\n * input and has no default. The output type widens to `T | undefined` so the\n * type doesn't lie. Schemas that accept `undefined` input (`.optional()`,\n * `.default()`) keep their declared output type.\n *\n * Limitation: `z.coerce.*` schemas declare input `unknown`, which accepts\n * `undefined` at the type level — so a coerce schema without `.default()`\n * keeps its narrow output type even though absent input yields `undefined`\n * at runtime. Add `.default()` to coerce schemas for accurate types.\n */\nexport type InferField<V> = V extends {\n parseServerSide(value: string | string[] | undefined): infer R;\n}\n ? R\n : V extends SearchParamCodec<infer T>\n ? T\n : V extends StandardSchemaV1<infer T>\n ? undefined extends InferSchemaInput<V>\n ? T\n : T | undefined\n : never;\n\n/**\n * A codec whose total entry point is `parseServerSide`, even when `parse`\n * has a narrower signature. nuqs multi parsers (`parseAsNativeArrayOf`) have\n * `parse(value: readonly string[])` — too narrow for `SearchParamCodec`'s\n * `parse(string | string[] | undefined)` — but their `parseServerSide`\n * covers the full domain. Timber never calls `parse` directly on these;\n * `parseTotal` always reaches `parseServerSide` first (TIM-1355).\n */\nexport interface TotalSearchParamCodec<T> {\n parseServerSide(value: string | string[] | undefined): T;\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n parse(...args: any[]): any;\n serialize(value: T): string | string[] | null;\n urlKey?: string;\n}\n\n/** Acceptable field value for defineSearchParams: a codec, a total codec, or a Standard Schema. */\nexport type SearchParamField<T = unknown> =\n | SearchParamCodec<T>\n | TotalSearchParamCodec<T>\n | StandardSchemaV1<T>;\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Convert URLSearchParams or a plain record to a normalized record\n * where repeated keys produce arrays.\n */\nfunction normalizeRaw(\n raw: URLSearchParams | Record<string, string | string[] | undefined>\n): Record<string, string | string[] | undefined> {\n if (raw instanceof URLSearchParams) {\n const result: Record<string, string | string[] | undefined> = Object.create(null);\n for (const key of new Set(raw.keys())) {\n const values = raw.getAll(key);\n result[key] = values.length === 1 ? values[0] : values;\n }\n return result;\n }\n return raw;\n}\n\n/**\n * Compute the serialized default value for a codec. Used for\n * default-omission: when serialize(value) === serialize(parse(undefined)),\n * the field is omitted from the URL.\n *\n * Goes through `parseTotal` for the same reason request-time parsing does:\n * a nuqs parser's own `parse` throws on absent input, and this is the\n * absent case by construction.\n *\n * **A codec with no value for an absent param has no default to omit**,\n * and `null` is returned rather than `serialize(null)`. Serializing it\n * makes the \"no value\" case collide with a real one: `parseAsInteger`\n * serializes `null` as the string `'null'`, so `buildSearchParams({ q:\n * 'null' })` would silently drop a legitimate value (before TIM-1350 the\n * absent parse was `undefined` and the swallowed input was the string\n * `'undefined'` — same defect, a less likely input). Nothing is lost:\n * `buildSearchParams` already skips a field whose `serialize` returns\n * `null`, so a codec that encodes \"no value\" as an omission behaves\n * identically, and one that encodes it as a real query value now writes\n * it instead of dropping it.\n *\n * Codecs are documented to return a default rather than throw, but a\n * hand-written codec that throws on absent input must not turn definition\n * into a crash — treat its default as null (nothing to omit). `serialize`\n * is inside the try for the same reason.\n *\n * Typed `SearchParamCodec<unknown>` rather than generic on purpose: the\n * absent-input value is whatever the codec's total entry point returns,\n * which for a nuqs parser is `T | null` while its `serialize` declares\n * `T`. Widening to `unknown` states that honestly instead of casting.\n */\nfunction getDefaultSerialized(codec: SearchParamCodec<unknown>): string | string[] | null {\n try {\n const absent = parseTotal(codec, undefined);\n return absent === null || absent === undefined ? null : codec.serialize(absent);\n } catch {\n return null;\n }\n}\n\n// isStandardSchema and isCodec are imported from schema-bridge.ts.\n\n/**\n * Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema\n * objects and wraps them with fromSchema. Reads .urlKey from codecs.\n *\n * The returned codec is typed as `SearchParamCodec<unknown>` because the\n * codec map uses that type. Both `fromSchema` results and nuqs parsers may\n * serialize to `string | string[] | null`; `buildSearchParams` handles the\n * union.\n */\nfunction resolveField(\n fieldName: string,\n value: SearchParamField\n): { codec: SearchParamCodec<unknown>; urlKey?: string } {\n // Check for codec first (codecs may also have '~standard' if they're nuqs parsers)\n if (isCodec(value)) {\n const urlKey = (value as SearchParamCodec<unknown>).urlKey;\n return { codec: value as SearchParamCodec<unknown>, urlKey };\n }\n\n // Auto-detect Standard Schema. Schemas that reject undefined input and\n // have no default are implicitly optional: fromSchema returns undefined\n // for absent params, and InferField widens the output type to\n // T | undefined. design/23-search-params.md §\"Implicit Optionality\"\n if (isStandardSchema(value)) {\n return { codec: fromSchema(value) };\n }\n\n throw new Error(\n `[timber] defineSearchParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n `(Zod, Valibot, ArkType).`\n );\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a SearchParamsDefinition from a map of codecs and/or Standard Schema\n * objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType\n * schemas with auto-detection.\n *\n * ```ts\n * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'\n * import { parseAsString, parseAsStringEnum } from 'nuqs/server'\n * import { z } from 'zod/v4'\n *\n * export const searchParams = defineSearchParams({\n * page: z.coerce.number().int().min(1).default(1), // Standard Schema — auto-wrapped\n * q: withUrlKey(parseAsString, 'search'), // nuqs codec with URL alias\n * sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),\n * })\n * ```\n */\n/**\n * Overload: accept a Standard Schema object schema (e.g., z.object({...})).\n *\n * The schema must have a `.shape` property whose values are themselves\n * Standard Schema objects. Each shape property becomes a field codec\n * via fromSchema().\n *\n * ```ts\n * const searchParams = defineSearchParams(\n * z.object({ page: z.coerce.number().default(1), q: z.string().optional() })\n * )\n * ```\n */\nexport function defineSearchParams<\n S extends StandardSchemaV1<Record<string, unknown>> & {\n shape: Record<string, StandardSchemaV1<unknown>>;\n },\n>(\n schema: S\n): SearchParamsDefinition<{ [K in keyof S['shape'] & string]: InferField<S['shape'][K]> }>;\n\n/**\n * Overload: accept a map of codecs and/or Standard Schema objects.\n */\nexport function defineSearchParams<C extends Record<string, SearchParamField>>(\n codecs: C\n): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }>;\n\nexport function defineSearchParams(\n codecsOrSchema:\n | Record<string, SearchParamField>\n | (StandardSchemaV1<unknown> & { shape: Record<string, StandardSchemaV1<unknown>> })\n): SearchParamsDefinition<Record<string, unknown>> {\n // Detect Standard Schema object with .shape (e.g., z.object(...))\n if (isStandardSchema(codecsOrSchema) && hasShape(codecsOrSchema)) {\n const fieldCodecs: Record<string, SearchParamField> = {};\n for (const [key, fieldSchema] of Object.entries(codecsOrSchema.shape)) {\n if (isStandardSchema(fieldSchema)) {\n fieldCodecs[key] = fieldSchema;\n } else {\n throw new Error(\n `[timber] defineSearchParams: field '${key}' in schema.shape is not a Standard Schema. ` +\n `All shape properties must be Standard Schema objects (Zod, Valibot, ArkType).`\n );\n }\n }\n return defineSearchParamsFromMap(fieldCodecs);\n }\n\n return defineSearchParamsFromMap(codecsOrSchema as Record<string, SearchParamField>);\n}\n\n/** Check if a schema has a .shape property with object-type values. */\nfunction hasShape(schema: unknown): schema is { shape: Record<string, unknown> } {\n return (\n typeof schema === 'object' &&\n schema !== null &&\n 'shape' in schema &&\n typeof (schema as { shape: unknown }).shape === 'object' &&\n (schema as { shape: unknown }).shape !== null\n );\n}\n\nfunction defineSearchParamsFromMap(\n codecs: Record<string, SearchParamField>\n): SearchParamsDefinition<Record<string, unknown>> {\n const resolvedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n const urlKeys: Record<string, string> = {};\n\n for (const [key, value] of Object.entries(codecs)) {\n const resolved = resolveField(key, value as SearchParamField);\n resolvedCodecs[key] = resolved.codec;\n if (resolved.urlKey) {\n urlKeys[key] = resolved.urlKey;\n }\n }\n\n return buildDefinition(resolvedCodecs as unknown as CodecMap<Record<string, unknown>>, urlKeys);\n}\n\n// ---------------------------------------------------------------------------\n// Internal: build the definition object\n// ---------------------------------------------------------------------------\n\n/**\n * Internal: build a SearchParamsDefinition from a typed codec map and url keys.\n */\nfunction buildDefinition<T extends Record<string, unknown>>(\n codecMap: CodecMap<T>,\n urlKeys: Record<string, string>\n): SearchParamsDefinition<T> {\n // Pre-compute default serialized values for omission check\n const defaultSerialized: Record<string, string | string[] | null> = {};\n for (const key of Object.keys(codecMap)) {\n defaultSerialized[key] = getDefaultSerialized(codecMap[key as keyof T]);\n }\n\n function getUrlKey(prop: string): string {\n return urlKeys[prop] ?? prop;\n }\n\n // ---- parse ----\n function parseSync(raw: URLSearchParams | Record<string, string | string[] | undefined>): T {\n const normalized = normalizeRaw(raw);\n const result: Record<string, unknown> = {};\n\n for (const prop of Object.keys(codecMap)) {\n const urlKey = getUrlKey(prop);\n const rawValue = normalized[urlKey];\n result[prop] = parseTotal(codecMap[prop as keyof T] as SearchParamCodec<unknown>, rawValue);\n }\n\n return result as T;\n }\n\n // Overloaded parse: sync when given raw params, async when given a Promise.\n // This enables the ergonomic pattern: await def.parse(searchParams())\n function parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n function parse(\n raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n ): Promise<T>;\n function parse(\n raw:\n | URLSearchParams\n | Record<string, string | string[] | undefined>\n | Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n ): T | Promise<T> {\n if (raw instanceof Promise) {\n return raw.then(parseSync);\n }\n return parseSync(raw);\n }\n\n // ---- buildSearchParams ----\n //\n // Returns a query string. It used to have a URLSearchParams-returning\n // sibling (`toSearchParams`) that `<Link>` consumed; that shape cannot\n // cross the RSC Flight boundary (see the interface docstring), and having\n // two methods produce the same query two ways was a drift waiting to\n // happen. One method now.\n function buildSearchParams(values: Partial<T>): string {\n const parts: string[] = [];\n\n for (const prop of Object.keys(codecMap)) {\n if (!(prop in values)) continue;\n const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n\n // TIM-1354: serialize may not be total over null — nuqs parsers like\n // parseAsIsoDate throw TypeError on null (null.toISOString()). Catch\n // TypeError and omit, matching what setParams does on the client.\n // Only TypeError — a deliberate throw (redirect(), notFound()) from a\n // codec's serialize must propagate, not be silently swallowed.\n let serialized: string | string[] | null;\n try {\n serialized = codec.serialize(values[prop as keyof T] as unknown);\n } catch (error) {\n if (error instanceof TypeError) continue;\n throw error;\n }\n\n if (serialized === null) continue;\n // Omit if serialized value matches the default\n if (serializedEqual(serialized, defaultSerialized[prop])) continue;\n\n // TIM-1353: string[] → repeated keys (?tag=a&tag=b)\n const urlKey = encodeURIComponent(getUrlKey(prop));\n if (Array.isArray(serialized)) {\n for (const entry of serialized) {\n parts.push(`${urlKey}=${encodeURIComponent(entry)}`);\n }\n } else {\n parts.push(`${urlKey}=${encodeURIComponent(serialized)}`);\n }\n }\n\n return parts.join('&');\n }\n\n // ---- href ----\n function href(pathname: string, values: Partial<T>): string {\n const qs = buildSearchParams(values);\n return qs ? `${pathname}?${qs}` : pathname;\n }\n\n // ---- extend ----\n function extend<U extends Record<string, SearchParamField>>(\n newCodecs: U\n ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }> {\n type Combined = T & { [K in keyof U]: InferField<U[K]> };\n\n // Resolve any Standard Schema objects in the extension\n const resolvedNewCodecs: Record<string, SearchParamCodec<unknown>> = {};\n const newUrlKeys: Record<string, string> = {};\n for (const [key, value] of Object.entries(newCodecs)) {\n const resolved = resolveField(key, value as SearchParamField);\n resolvedNewCodecs[key] = resolved.codec;\n if (resolved.urlKey) {\n newUrlKeys[key] = resolved.urlKey;\n }\n }\n\n const combinedCodecs = {\n ...codecMap,\n ...resolvedNewCodecs,\n } as unknown as CodecMap<Combined>;\n\n // Merge URL keys: base keys + new codec urlKeys from withUrlKey\n const combinedUrlKeys: Record<string, string> = { ...urlKeys, ...newUrlKeys };\n\n return buildDefinition<Combined>(combinedCodecs, combinedUrlKeys);\n }\n\n // ---- pick ----\n function pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>> {\n const pickedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n const pickedUrlKeys: Record<string, string> = {};\n\n for (const key of keys) {\n // Explicit guard — TypeScript prevents this, but JS callers and\n // casts reach here, and \"Cannot read properties of undefined\n // (reading 'serialize')\" is no help (TIM-1066).\n if (!(key in codecMap)) {\n throw new Error(\n `[timber] pick('${key}'): unknown key. ` +\n `Available keys: ${Object.keys(codecMap)\n .map((k) => `'${k}'`)\n .join(', ')}.`\n );\n }\n pickedCodecs[key] = codecMap[key] as SearchParamCodec<unknown>;\n if (key in urlKeys) {\n pickedUrlKeys[key] = urlKeys[key];\n }\n }\n\n return buildDefinition<Pick<T, K>>(\n pickedCodecs as unknown as CodecMap<Pick<T, K>>,\n pickedUrlKeys\n );\n }\n\n // ---- useQueryStates ----\n // Delegates to the 'use client' implementation from use-query-states.ts.\n //\n // In the RSC environment: use-query-states.ts is transformed by the RSC\n // plugin into a client reference proxy. Calling it throws — correct,\n // because hooks can't run during server component rendering.\n // In SSR: use-query-states.ts is the real nuqs-backed function. Hooks\n // work during SSR's renderToReadableStream, so this works correctly.\n // On the client: same as SSR — the real function is available.\n function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {\n return clientUseQueryStates(codecMap, options, Object.freeze({ ...urlKeys })) as [\n T,\n SetParams<T>,\n ];\n }\n\n // ---- get ----\n // ALS-backed: reads getSearchParams() from the current request context\n // and parses through codecs. Server-only, sync.\n function get(): T {\n if (typeof window !== 'undefined') {\n throw new Error(\n '[timber] searchParams.get() is server-only. ' +\n 'Use searchParams.useQueryStates() on the client.'\n );\n }\n const raw = getSearchParamsFromAls();\n return parseSync(raw);\n }\n\n const definition: SearchParamsDefinition<T> = {\n parse,\n get,\n useQueryStates,\n extend,\n pick,\n href,\n buildSearchParams,\n codecs: codecMap,\n urlKeys: Object.freeze({ ...urlKeys }),\n };\n\n return definition;\n}\n","/**\n * Codec wrappers — withDefault and withUrlKey.\n *\n * These are timber-specific utilities that work with any SearchParamCodec.\n * For actual codecs (string, integer, boolean, etc.), use nuqs parsers\n * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.\n *\n * Design doc: design/23-search-params.md\n */\n\nimport type {\n InferField,\n SearchParamCodec,\n SearchParamCodecWithUrlKey,\n SearchParamField,\n} from './define.ts';\nimport { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.ts';\nimport { parseTotal } from './parse-total.ts';\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. The output type becomes\n * non-nullable, and the wrapper is TOTAL over `string | string[] |\n * undefined` even when the inner codec is not.\n *\n * The default is substituted for `null` — the documented \"no value\"\n * answer — and for `undefined`, which is what an implicitly-optional\n * Standard Schema field and a bare `parseAsString` produce for an absent\n * param. Substituting only for `null` left a field typed non-nullable\n * `string` holding `undefined` (TIM-1350).\n *\n * The inner codec is invoked through `parseTotal`, so a nuqs parser gets\n * its own normalization (absent → null, repeated → first value, inner\n * throw → null) before either check applies. That is what makes\n * `withDefault(parseAsBoolean, false)` total; the wrapper itself does NOT\n * catch. A throw from a codec is a deliberate signal — `fromSchema` throws\n * on an async schema, and an app codec may `redirect()` or `notFound()` on\n * a value it refuses — and swallowing it would convert a loud failure into\n * a permanently-default field. design/09 §\"The SearchParamCodec Protocol\":\n * a codec that throws bubbles as a render-phase error, by design.\n *\n * Works with any codec — nuqs parsers, custom codecs, fromSchema results.\n *\n * ```ts\n * import { parseAsInteger } from 'nuqs/server'\n * import { withDefault } from '@timber-js/app/search-params'\n *\n * const page = withDefault(parseAsInteger, 1)\n * // page.parse(undefined) → 1 (not null)\n * // page.parse('5') → 5\n * ```\n *\n * The signature strips BOTH nullish constituents from the result, not just\n * `null`, because the runtime substitutes for both. An implicitly-optional\n * schema field is a `SearchParamCodec<string | undefined>`, and wrapping it\n * used to yield `SearchParamCodec<string | undefined>` — a field the\n * wrapper guarantees is always present, still typed as maybe-absent.\n */\nexport function withDefault<T>(\n codec: SearchParamCodec<T | null | undefined>,\n defaultValue: NonNullable<T>\n): SearchParamCodec<NonNullable<T>> {\n // A wrapper that rebuilds a codec from two methods drops everything else\n // the codec carries. `withUrlKey` lost `parseServerSide` that way; this\n // one lost `urlKey`, so `withDefault(withUrlKey(parseAsInteger, 'p'), 1)`\n // silently read `?page=` instead of `?p=`. Carry it explicitly rather\n // than spreading: this wrapper's own `parse` IS the total entry point,\n // and re-publishing the inner `parseServerSide` would let `parseTotal`\n // reach past it and skip the default entirely.\n const wrapped: SearchParamCodec<NonNullable<T>> = {\n parse(value: string | string[] | undefined): NonNullable<T> {\n const result = parseTotal(codec, value);\n return result === null || result === undefined ? defaultValue : result;\n },\n serialize(value: NonNullable<T>): string | string[] | null {\n return codec.serialize(value);\n },\n };\n if (codec.urlKey !== undefined) wrapped.urlKey = codec.urlKey;\n return wrapped;\n}\n\n// ---------------------------------------------------------------------------\n// withUrlKey\n// ---------------------------------------------------------------------------\n\n/**\n * Attach a URL key alias to a codec. The alias determines what query\n * parameter key is used in the URL, while the TypeScript property name\n * stays descriptive.\n *\n * Aliases travel with codecs through object spread composition — when\n * you spread a bundle containing aliased codecs into defineSearchParams,\n * the aliases come along automatically.\n *\n * ```ts\n * import { parseAsString } from 'nuqs/server'\n * import { withUrlKey } from '@timber-js/app/search-params'\n *\n * export const searchable = {\n * q: withUrlKey(parseAsString, 'search'),\n * // ?search=shoes → { q: 'shoes' }\n * }\n * ```\n *\n * Composes with withDefault:\n * ```ts\n * import { parseAsInteger } from 'nuqs/server'\n * withUrlKey(withDefault(parseAsInteger, 1), 'p')\n * ```\n */\nexport function withUrlKey<F extends SearchParamField>(\n codecOrSchema: F,\n urlKey: string\n): SearchParamCodecWithUrlKey<InferField<F>> {\n type T = InferField<F>;\n // Auto-detect Standard Schema (Zod, Valibot, ArkType) and wrap. Schemas\n // that reject undefined input are implicitly optional — fromSchema returns\n // undefined for absent params, and InferField widens the type to include\n // undefined. design/23-search-params.md §\"Implicit Optionality\"\n const codec: SearchParamCodec<T> = isCodec(codecOrSchema)\n ? (codecOrSchema as SearchParamCodec<T>)\n : isStandardSchema(codecOrSchema)\n ? (fromSchema(codecOrSchema) as SearchParamCodec<T>)\n : (codecOrSchema as SearchParamCodec<T>);\n // Carry the total entry point, bound like the other two methods. A\n // codec's totality lives in a THIRD property, `parseServerSide` (see\n // parse-total.ts); picking only `parse`/`serialize` silently produced a\n // non-total alias, so `withUrlKey(parseAsBoolean, 'b')` threw on an\n // absent param while the bare parser did not (TIM-1350).\n //\n // Bound explicitly rather than spread: a spread copies own enumerable\n // properties only, so a class-based codec — whose `parse` and\n // `serialize` this wrapper already reaches through the prototype —\n // would have kept its methods and lost exactly the one that makes it\n // total. Three properties, one rule, no dependence on how the inner\n // codec was constructed.\n const wrapped: SearchParamCodecWithUrlKey<T> = {\n parse: codec.parse.bind(codec),\n serialize: codec.serialize.bind(codec),\n urlKey,\n };\n if (typeof codec.parseServerSide === 'function') {\n wrapped.parseServerSide = codec.parseServerSide.bind(codec);\n }\n return wrapped;\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"index.js","names":["useQueryStates","clientUseQueryStates"],"sources":["../../src/search-params/define.ts","../../src/search-params/wrappers.ts"],"sourcesContent":["/**\n * defineSearchParams — factory for SearchParamsDefinition<T>.\n *\n * Creates a typed, composable definition for a route's search parameters.\n * Accepts both SearchParamCodec values and Standard Schema objects (Zod,\n * Valibot, ArkType) with auto-detection. Supports URL key aliasing via\n * withUrlKey(), default-omission serialization, and composition via\n * .extend() / .pick().\n *\n * Design doc: design/23-search-params.md §\"defineSearchParams — The Factory\"\n */\n\nimport { useQueryStates as clientUseQueryStates } from '../client/use-query-states.ts';\nimport { fromSchema, isStandardSchema, isCodec } from '../schema-bridge.ts';\nimport type { StandardSchemaV1 } from '../schema-bridge.ts';\nimport type { Codec } from '../codec.ts';\nimport type { Options as NuqsOptions } from 'nuqs';\n// Server-only reference for .get() — avoids pulling server ALS into client\n// bundles. In client environments, .get() throws before reaching this code\n// path. The slot lives in its own leaf module so that `request-context.ts`\n// can register the getter without importing this file, which would drag\n// `nuqs` into every server entry (TIM-1298). See shared/als-slots.ts.\nimport { getSearchParamsFromAls } from '../shared/als-slots.ts';\nimport { parseTotal } from './parse-total.ts';\nimport { serializedEqual } from './serialize-equal.ts';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/**\n * A codec that converts between URL string values and typed values.\n *\n * `parse` receives the RAW url value: `string | string[] | undefined`.\n * A codec must be TOTAL over that domain — return a default rather than\n * throwing on an absent or repeated param.\n *\n * A codec whose own `parse` covers only a PRESENT, SINGLE-VALUED param\n * may publish `parseServerSide` instead, and timber calls that. nuqs\n * parsers do exactly this, which is how they become total here: absent →\n * `null` (or their `withDefault` value), repeated → the first value, and\n * a throw from the inner parse → `null`. See\n * design/23-search-params.md §'nuqs parsers, made total',\n * `parse-total.ts`, and tests/nuqs-codec-boundary.test.ts (TIM-1350).\n *\n * Standard Schema objects (Zod, Valibot, ArkType) are auto-detected\n * by defineSearchParams and wrapped via fromSchema; those ARE total\n * through `parse` and are called that way.\n */\nexport interface SearchParamCodec<T> extends Omit<Codec<T>, 'serialize'> {\n /**\n * Typed value → URL string(s). Return `null` to omit/clear.\n *\n * A codec MAY return `string[]` to emit repeated keys (`?tag=a&tag=b`).\n * `buildSearchParams` appends one `key=value` entry per array element;\n * the nuqs bridge forwards the array to nuqs, which does the same.\n * Codecs that always produce a single value return a plain string.\n *\n * Wider than `Codec<T>.serialize` (`string | null`) because search params\n * have a repeated-key concept that cookies and segment params do not.\n */\n serialize(value: T): string | string[] | null;\n /** Optional URL key alias, set by withUrlKey(). */\n urlKey?: string;\n /**\n * Optional TOTAL entry point over `string | string[] | undefined`,\n * preferred over `parse` wherever timber invokes a codec. Declared here\n * so the protocol is typed rather than duck-checked at each wrapper:\n * anything that reconstructs a codec has to carry it, and a wrapper\n * cannot carry a property the interface does not admit.\n *\n * It returns `T`, not `T | null`. This is the entry point timber calls,\n * so whatever it returns IS the field's type — admitting a `null` the\n * field type did not carry would let `SearchParamCodec<string>` produce\n * `null` for an absent param under a non-nullable annotation. A codec\n * whose absent-case answer is `null` declares that in `T`, exactly as a\n * bare nuqs parser does: `parseAsString` is a `SearchParamCodec<string |\n * null>` here, never a `SearchParamCodec<string>`.\n *\n * nuqs parser builders satisfy this. See parse-total.ts.\n */\n parseServerSide?(value: string | string[] | undefined): T;\n}\n\n/** A codec with a URL key alias attached via withUrlKey(). */\nexport interface SearchParamCodecWithUrlKey<T> extends SearchParamCodec<T> {\n urlKey: string;\n}\n\n/** Infer the output type of a codec. */\nexport type InferCodec<C> = C extends SearchParamCodec<infer T> ? T : never;\n\n/** Map of property names to codecs. */\nexport type CodecMap<T extends Record<string, unknown>> = {\n [K in keyof T]: SearchParamCodec<T[K]>;\n};\n\n/**\n * Options for a `setParams` call: nuqs's own `Options`, passed through\n * whole. Not a hand-copied subset — a whitelist silently dropped\n * `limitUrlUpdates` (debounce/throttle) and `clearOnDefault`, and would drop\n * whatever nuqs adds next (TIM-1623).\n *\n * `urlKeys` is not here: nuqs's `Options` does not carry it (it lives on\n * the hook-only `UseQueryStatesOptions`), and timber owns it — the aliases\n * come from the codecs (`withUrlKey`).\n *\n * The fields re-listed below are not a second declaration: each takes its\n * type from nuqs (`NuqsOptions['shallow']`), and is re-listed only because\n * nuqs's own JSDoc, which an editor shows on hover, is wrong for timber.\n * See design/23-search-params.md §\"Options pass through to nuqs\".\n */\nexport interface SetParamsOptions extends NuqsOptions {\n /**\n * `false` (timber's default): the write is an RSC navigation, so the server\n * renders the new params. `true`: the URL changes with no server request.\n */\n shallow?: NuqsOptions['shallow'];\n /** Scroll to the top after the write. Defaults to `true` in timber. */\n scroll?: NuqsOptions['scroll'];\n /**\n * Forwarded to nuqs, but it does not track the server request in timber.\n * timber runs navigations outside any transition, so `isPending` ends\n * before the RSC fetch does. Use `usePendingNavigation()` for a loading\n * state.\n */\n startTransition?: NuqsOptions['startTransition'];\n}\n\n/** Setter function returned by useQueryStates. */\nexport type SetParams<T> = (values: Partial<T>, options?: SetParamsOptions) => void;\n\n/**\n * Options for the `useQueryStates` hook — the defaults for every setter call\n * from that hook instance. Same shape as {@link SetParamsOptions}; a per-call\n * option overrides the hook's.\n */\nexport type QueryStatesOptions = SetParamsOptions;\n\n/**\n * A fully typed, composable search params definition.\n *\n * Returned by defineSearchParams(). Carries a phantom _type property\n * for build-time type extraction.\n */\nexport interface SearchParamsDefinition<T extends Record<string, unknown>> {\n /** Parse raw URL search params into typed values. */\n parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n /** Parse a Promise of URLSearchParams (e.g., from the ALS `searchParams()` API). */\n parse(raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>): Promise<T>;\n\n /**\n * Get typed search params from the current request context (ALS-backed).\n *\n * Server-only, sync. Reads getSearchParams() from ALS and parses through codecs.\n * Throws on client.\n *\n * ```tsx\n * // app/products/page.tsx\n * import { searchParams } from './search-params'\n * export default function Page() {\n * const { page, category } = searchParams.get()\n * }\n * ```\n */\n get(): T;\n\n /** Client hook — reads current URL params and returns typed values + setter. */\n useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>];\n\n /** Extend with additional codecs or Standard Schema objects. */\n extend<U extends Record<string, SearchParamField>>(\n codecs: U\n ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }>;\n\n /** Pick a subset of keys. Preserves codecs and aliases. */\n pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>>;\n\n /**\n * Serialize values to a query string (no leading '?'), omitting defaults\n * and applying `withUrlKey` aliases. This is the value to pass to\n * `<Link searchParams={...}>`.\n *\n * Returns a **string**, not a `URLSearchParams`. A `<Link>` prop crosses\n * the RSC Flight boundary, and `URLSearchParams` is iterable — React\n * serializes it as an entries array, which arrives as `[['pg','2'], …]`\n * and renders as `?0=pg&0=2`. A string survives intact.\n */\n buildSearchParams(values: Partial<T>): string;\n\n /** Build a full path with query string, omitting defaults. */\n href(pathname: string, values: Partial<T>): string;\n\n /** Read-only codec map for spreading into .extend(). */\n codecs: { [K in keyof T]: SearchParamCodec<T[K]> };\n\n /** Read-only URL key alias map. Maps property names to URL query parameter keys. */\n readonly urlKeys: Readonly<Record<string, string>>;\n\n /**\n * Phantom property for build-time type extraction.\n * Never set at runtime — exists only in the type system.\n */\n readonly _type?: T;\n}\n\n// StandardSchemaV1 is imported from schema-bridge.ts — single source of truth.\n// Re-export for consumers that import it from this module.\nexport type { StandardSchemaV1 } from '../schema-bridge.ts';\n\n// ---------------------------------------------------------------------------\n// Type-level helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract a Standard Schema's declared *input* type from its optional\n * `~standard.types` property (part of the Standard Schema spec; Zod, Valibot,\n * and ArkType all declare it at the type level). Falls back to `never` when\n * the schema doesn't declare types (e.g. hand-written schemas): with no\n * metadata we can't know whether the schema handles `undefined`, so InferField\n * widens conservatively rather than risk a type lie.\n */\ntype InferSchemaInput<V> = V extends { '~standard': { types?: infer TS } }\n ? [NonNullable<TS>] extends [{ input: infer I }]\n ? I\n : never\n : never;\n\n/**\n * Infer the output type from either a SearchParamCodec or a StandardSchemaV1.\n *\n * A codec publishing `parseServerSide` is read through THAT signature, not\n * through `parse` — it is the entry point timber actually calls, and it is\n * the one that tells the truth about absent input. A bare `parseAsString`\n * declares `parse(value: string): string` but answers `null` for a missing\n * param, so the field is `string | null`; `parseAsInteger.withDefault(1)`\n * narrows its own `parseServerSide` to `NonNullable<number>` and the field\n * stays `number`. Reading `parse` instead produced a non-nullable type for\n * a nullable field (TIM-1350).\n *\n * The match is structural, not nuqs-specific: any codec declaring that\n * signature opts into being read through it, which is exactly the contract\n * `parseTotal` applies at runtime. The two must stay in step — a type\n * inferred from `parse` while the runtime calls `parseServerSide` is the\n * lie this branch exists to remove.\n *\n * Schemas whose input type rejects `undefined` (e.g. bare `z.string()`, whose\n * input is `string`) are implicitly optional: the URL might not contain the\n * param, and fromSchema returns `undefined` when the schema rejects absent\n * input and has no default. The output type widens to `T | undefined` so the\n * type doesn't lie. Schemas that accept `undefined` input (`.optional()`,\n * `.default()`) keep their declared output type.\n *\n * Limitation: `z.coerce.*` schemas declare input `unknown`, which accepts\n * `undefined` at the type level — so a coerce schema without `.default()`\n * keeps its narrow output type even though absent input yields `undefined`\n * at runtime. Add `.default()` to coerce schemas for accurate types.\n */\nexport type InferField<V> = V extends {\n parseServerSide(value: string | string[] | undefined): infer R;\n}\n ? R\n : V extends SearchParamCodec<infer T>\n ? T\n : V extends StandardSchemaV1<infer T>\n ? undefined extends InferSchemaInput<V>\n ? T\n : T | undefined\n : never;\n\n/**\n * A codec whose total entry point is `parseServerSide`, even when `parse`\n * has a narrower signature. nuqs multi parsers (`parseAsNativeArrayOf`) have\n * `parse(value: readonly string[])` — too narrow for `SearchParamCodec`'s\n * `parse(string | string[] | undefined)` — but their `parseServerSide`\n * covers the full domain. Timber never calls `parse` directly on these;\n * `parseTotal` always reaches `parseServerSide` first (TIM-1355).\n */\nexport interface TotalSearchParamCodec<T> {\n parseServerSide(value: string | string[] | undefined): T;\n // eslint-disable-next-line @typescript-eslint/no-explicit-any\n parse(...args: any[]): any;\n serialize(value: T): string | string[] | null;\n urlKey?: string;\n}\n\n/** Acceptable field value for defineSearchParams: a codec, a total codec, or a Standard Schema. */\nexport type SearchParamField<T = unknown> =\n | SearchParamCodec<T>\n | TotalSearchParamCodec<T>\n | StandardSchemaV1<T>;\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Convert URLSearchParams or a plain record to a normalized record\n * where repeated keys produce arrays.\n */\nfunction normalizeRaw(\n raw: URLSearchParams | Record<string, string | string[] | undefined>\n): Record<string, string | string[] | undefined> {\n if (raw instanceof URLSearchParams) {\n const result: Record<string, string | string[] | undefined> = Object.create(null);\n for (const key of new Set(raw.keys())) {\n const values = raw.getAll(key);\n result[key] = values.length === 1 ? values[0] : values;\n }\n return result;\n }\n return raw;\n}\n\n/**\n * Compute the serialized default value for a codec. Used for\n * default-omission: when serialize(value) === serialize(parse(undefined)),\n * the field is omitted from the URL.\n *\n * Goes through `parseTotal` for the same reason request-time parsing does:\n * a nuqs parser's own `parse` throws on absent input, and this is the\n * absent case by construction.\n *\n * **A codec with no value for an absent param has no default to omit**,\n * and `null` is returned rather than `serialize(null)`. Serializing it\n * makes the \"no value\" case collide with a real one: `parseAsInteger`\n * serializes `null` as the string `'null'`, so `buildSearchParams({ q:\n * 'null' })` would silently drop a legitimate value (before TIM-1350 the\n * absent parse was `undefined` and the swallowed input was the string\n * `'undefined'` — same defect, a less likely input). Nothing is lost:\n * `buildSearchParams` already skips a field whose `serialize` returns\n * `null`, so a codec that encodes \"no value\" as an omission behaves\n * identically, and one that encodes it as a real query value now writes\n * it instead of dropping it.\n *\n * Codecs are documented to return a default rather than throw, but a\n * hand-written codec that throws on absent input must not turn definition\n * into a crash — treat its default as null (nothing to omit). `serialize`\n * is inside the try for the same reason.\n *\n * Typed `SearchParamCodec<unknown>` rather than generic on purpose: the\n * absent-input value is whatever the codec's total entry point returns,\n * which for a nuqs parser is `T | null` while its `serialize` declares\n * `T`. Widening to `unknown` states that honestly instead of casting.\n */\nfunction getDefaultSerialized(codec: SearchParamCodec<unknown>): string | string[] | null {\n try {\n const absent = parseTotal(codec, undefined);\n return absent === null || absent === undefined ? null : codec.serialize(absent);\n } catch {\n return null;\n }\n}\n\n// isStandardSchema and isCodec are imported from schema-bridge.ts.\n\n/**\n * Resolve a field value to a SearchParamCodec. Auto-detects Standard Schema\n * objects and wraps them with fromSchema. Reads .urlKey from codecs.\n *\n * The returned codec is typed as `SearchParamCodec<unknown>` because the\n * codec map uses that type. Both `fromSchema` results and nuqs parsers may\n * serialize to `string | string[] | null`; `buildSearchParams` handles the\n * union.\n */\nfunction resolveField(\n fieldName: string,\n value: SearchParamField\n): { codec: SearchParamCodec<unknown>; urlKey?: string } {\n // Check for codec first (codecs may also have '~standard' if they're nuqs parsers)\n if (isCodec(value)) {\n const urlKey = (value as SearchParamCodec<unknown>).urlKey;\n return { codec: value as SearchParamCodec<unknown>, urlKey };\n }\n\n // Auto-detect Standard Schema. Schemas that reject undefined input and\n // have no default are implicitly optional: fromSchema returns undefined\n // for absent params, and InferField widens the output type to\n // T | undefined. design/23-search-params.md §\"Implicit Optionality\"\n if (isStandardSchema(value)) {\n return { codec: fromSchema(value) };\n }\n\n throw new Error(\n `[timber] defineSearchParams: field '${fieldName}' is not a valid codec or Standard Schema. ` +\n `Expected an object with { parse, serialize } methods, or a Standard Schema object ` +\n `(Zod, Valibot, ArkType).`\n );\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a SearchParamsDefinition from a map of codecs and/or Standard Schema\n * objects. Accepts both SearchParamCodec values and raw Zod/Valibot/ArkType\n * schemas with auto-detection.\n *\n * ```ts\n * import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params'\n * import { parseAsString, parseAsStringEnum } from 'nuqs/server'\n * import { z } from 'zod/v4'\n *\n * export const searchParams = defineSearchParams({\n * page: z.coerce.number().int().min(1).default(1), // Standard Schema — auto-wrapped\n * q: withUrlKey(parseAsString, 'search'), // nuqs codec with URL alias\n * sort: withDefault(parseAsStringEnum(['price', 'name']), 'price'),\n * })\n * ```\n */\n/**\n * Overload: accept a Standard Schema object schema (e.g., z.object({...})).\n *\n * The schema must have a `.shape` property whose values are themselves\n * Standard Schema objects. Each shape property becomes a field codec\n * via fromSchema().\n *\n * ```ts\n * const searchParams = defineSearchParams(\n * z.object({ page: z.coerce.number().default(1), q: z.string().optional() })\n * )\n * ```\n */\nexport function defineSearchParams<\n S extends StandardSchemaV1<Record<string, unknown>> & {\n shape: Record<string, StandardSchemaV1<unknown>>;\n },\n>(\n schema: S\n): SearchParamsDefinition<{ [K in keyof S['shape'] & string]: InferField<S['shape'][K]> }>;\n\n/**\n * Overload: accept a map of codecs and/or Standard Schema objects.\n */\nexport function defineSearchParams<C extends Record<string, SearchParamField>>(\n codecs: C\n): SearchParamsDefinition<{ [K in keyof C]: InferField<C[K]> }>;\n\nexport function defineSearchParams(\n codecsOrSchema:\n | Record<string, SearchParamField>\n | (StandardSchemaV1<unknown> & { shape: Record<string, StandardSchemaV1<unknown>> })\n): SearchParamsDefinition<Record<string, unknown>> {\n // Detect Standard Schema object with .shape (e.g., z.object(...))\n if (isStandardSchema(codecsOrSchema) && hasShape(codecsOrSchema)) {\n const fieldCodecs: Record<string, SearchParamField> = {};\n for (const [key, fieldSchema] of Object.entries(codecsOrSchema.shape)) {\n if (isStandardSchema(fieldSchema)) {\n fieldCodecs[key] = fieldSchema;\n } else {\n throw new Error(\n `[timber] defineSearchParams: field '${key}' in schema.shape is not a Standard Schema. ` +\n `All shape properties must be Standard Schema objects (Zod, Valibot, ArkType).`\n );\n }\n }\n return defineSearchParamsFromMap(fieldCodecs);\n }\n\n return defineSearchParamsFromMap(codecsOrSchema as Record<string, SearchParamField>);\n}\n\n/** Check if a schema has a .shape property with object-type values. */\nfunction hasShape(schema: unknown): schema is { shape: Record<string, unknown> } {\n return (\n typeof schema === 'object' &&\n schema !== null &&\n 'shape' in schema &&\n typeof (schema as { shape: unknown }).shape === 'object' &&\n (schema as { shape: unknown }).shape !== null\n );\n}\n\nfunction defineSearchParamsFromMap(\n codecs: Record<string, SearchParamField>\n): SearchParamsDefinition<Record<string, unknown>> {\n const resolvedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n const urlKeys: Record<string, string> = {};\n\n for (const [key, value] of Object.entries(codecs)) {\n const resolved = resolveField(key, value as SearchParamField);\n resolvedCodecs[key] = resolved.codec;\n if (resolved.urlKey) {\n urlKeys[key] = resolved.urlKey;\n }\n }\n\n return buildDefinition(resolvedCodecs as unknown as CodecMap<Record<string, unknown>>, urlKeys);\n}\n\n// ---------------------------------------------------------------------------\n// Internal: build the definition object\n// ---------------------------------------------------------------------------\n\n/**\n * Internal: build a SearchParamsDefinition from a typed codec map and url keys.\n */\nfunction buildDefinition<T extends Record<string, unknown>>(\n codecMap: CodecMap<T>,\n urlKeys: Record<string, string>\n): SearchParamsDefinition<T> {\n // Pre-compute default serialized values for omission check\n const defaultSerialized: Record<string, string | string[] | null> = {};\n for (const key of Object.keys(codecMap)) {\n defaultSerialized[key] = getDefaultSerialized(codecMap[key as keyof T]);\n }\n\n function getUrlKey(prop: string): string {\n return urlKeys[prop] ?? prop;\n }\n\n // ---- parse ----\n function parseSync(raw: URLSearchParams | Record<string, string | string[] | undefined>): T {\n const normalized = normalizeRaw(raw);\n const result: Record<string, unknown> = {};\n\n for (const prop of Object.keys(codecMap)) {\n const urlKey = getUrlKey(prop);\n const rawValue = normalized[urlKey];\n result[prop] = parseTotal(codecMap[prop as keyof T] as SearchParamCodec<unknown>, rawValue);\n }\n\n return result as T;\n }\n\n // Overloaded parse: sync when given raw params, async when given a Promise.\n // This enables the ergonomic pattern: await def.parse(searchParams())\n function parse(raw: URLSearchParams | Record<string, string | string[] | undefined>): T;\n function parse(\n raw: Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n ): Promise<T>;\n function parse(\n raw:\n | URLSearchParams\n | Record<string, string | string[] | undefined>\n | Promise<URLSearchParams | Record<string, string | string[] | undefined>>\n ): T | Promise<T> {\n if (raw instanceof Promise) {\n return raw.then(parseSync);\n }\n return parseSync(raw);\n }\n\n // ---- buildSearchParams ----\n //\n // Returns a query string. It used to have a URLSearchParams-returning\n // sibling (`toSearchParams`) that `<Link>` consumed; that shape cannot\n // cross the RSC Flight boundary (see the interface docstring), and having\n // two methods produce the same query two ways was a drift waiting to\n // happen. One method now.\n function buildSearchParams(values: Partial<T>): string {\n const parts: string[] = [];\n\n for (const prop of Object.keys(codecMap)) {\n if (!(prop in values)) continue;\n const codec = codecMap[prop as keyof T] as SearchParamCodec<unknown>;\n\n // TIM-1354: serialize may not be total over null — nuqs parsers like\n // parseAsIsoDate throw TypeError on null (null.toISOString()). Catch\n // TypeError and omit, matching what setParams does on the client.\n // Only TypeError — a deliberate throw (redirect(), notFound()) from a\n // codec's serialize must propagate, not be silently swallowed.\n let serialized: string | string[] | null;\n try {\n serialized = codec.serialize(values[prop as keyof T] as unknown);\n } catch (error) {\n if (error instanceof TypeError) continue;\n throw error;\n }\n\n if (serialized === null) continue;\n // Omit if serialized value matches the default\n if (serializedEqual(serialized, defaultSerialized[prop])) continue;\n\n // TIM-1353: string[] → repeated keys (?tag=a&tag=b)\n const urlKey = encodeURIComponent(getUrlKey(prop));\n if (Array.isArray(serialized)) {\n for (const entry of serialized) {\n parts.push(`${urlKey}=${encodeURIComponent(entry)}`);\n }\n } else {\n parts.push(`${urlKey}=${encodeURIComponent(serialized)}`);\n }\n }\n\n return parts.join('&');\n }\n\n // ---- href ----\n function href(pathname: string, values: Partial<T>): string {\n const qs = buildSearchParams(values);\n return qs ? `${pathname}?${qs}` : pathname;\n }\n\n // ---- extend ----\n function extend<U extends Record<string, SearchParamField>>(\n newCodecs: U\n ): SearchParamsDefinition<T & { [K in keyof U]: InferField<U[K]> }> {\n type Combined = T & { [K in keyof U]: InferField<U[K]> };\n\n // Resolve any Standard Schema objects in the extension\n const resolvedNewCodecs: Record<string, SearchParamCodec<unknown>> = {};\n const newUrlKeys: Record<string, string> = {};\n for (const [key, value] of Object.entries(newCodecs)) {\n const resolved = resolveField(key, value as SearchParamField);\n resolvedNewCodecs[key] = resolved.codec;\n if (resolved.urlKey) {\n newUrlKeys[key] = resolved.urlKey;\n }\n }\n\n const combinedCodecs = {\n ...codecMap,\n ...resolvedNewCodecs,\n } as unknown as CodecMap<Combined>;\n\n // Merge URL keys: base keys + new codec urlKeys from withUrlKey\n const combinedUrlKeys: Record<string, string> = { ...urlKeys, ...newUrlKeys };\n\n return buildDefinition<Combined>(combinedCodecs, combinedUrlKeys);\n }\n\n // ---- pick ----\n function pick<K extends keyof T & string>(...keys: K[]): SearchParamsDefinition<Pick<T, K>> {\n const pickedCodecs: Record<string, SearchParamCodec<unknown>> = {};\n const pickedUrlKeys: Record<string, string> = {};\n\n for (const key of keys) {\n // Explicit guard — TypeScript prevents this, but JS callers and\n // casts reach here, and \"Cannot read properties of undefined\n // (reading 'serialize')\" is no help (TIM-1066).\n if (!(key in codecMap)) {\n throw new Error(\n `[timber] pick('${key}'): unknown key. ` +\n `Available keys: ${Object.keys(codecMap)\n .map((k) => `'${k}'`)\n .join(', ')}.`\n );\n }\n pickedCodecs[key] = codecMap[key] as SearchParamCodec<unknown>;\n if (key in urlKeys) {\n pickedUrlKeys[key] = urlKeys[key];\n }\n }\n\n return buildDefinition<Pick<T, K>>(\n pickedCodecs as unknown as CodecMap<Pick<T, K>>,\n pickedUrlKeys\n );\n }\n\n // ---- useQueryStates ----\n // Delegates to the 'use client' implementation from use-query-states.ts.\n //\n // In the RSC environment: use-query-states.ts is transformed by the RSC\n // plugin into a client reference proxy. Calling it throws — correct,\n // because hooks can't run during server component rendering.\n // In SSR: use-query-states.ts is the real nuqs-backed function. Hooks\n // work during SSR's renderToReadableStream, so this works correctly.\n // On the client: same as SSR — the real function is available.\n function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {\n return clientUseQueryStates(codecMap, options, Object.freeze({ ...urlKeys })) as [\n T,\n SetParams<T>,\n ];\n }\n\n // ---- get ----\n // ALS-backed: reads getSearchParams() from the current request context\n // and parses through codecs. Server-only, sync.\n function get(): T {\n if (typeof window !== 'undefined') {\n throw new Error(\n '[timber] searchParams.get() is server-only. ' +\n 'Use searchParams.useQueryStates() on the client.'\n );\n }\n const raw = getSearchParamsFromAls({ codecs: codecMap, urlKeys });\n return parseSync(raw);\n }\n\n const definition: SearchParamsDefinition<T> = {\n parse,\n get,\n useQueryStates,\n extend,\n pick,\n href,\n buildSearchParams,\n codecs: codecMap,\n urlKeys: Object.freeze({ ...urlKeys }),\n };\n\n return definition;\n}\n","/**\n * Codec wrappers — withDefault and withUrlKey.\n *\n * These are timber-specific utilities that work with any SearchParamCodec.\n * For actual codecs (string, integer, boolean, etc.), use nuqs parsers\n * or Standard Schema objects (Zod, Valibot, ArkType) with auto-detection.\n *\n * Design doc: design/23-search-params.md\n */\n\nimport type {\n InferField,\n SearchParamCodec,\n SearchParamCodecWithUrlKey,\n SearchParamField,\n} from './define.ts';\nimport { isCodec, isStandardSchema, fromSchema } from '../schema-bridge.ts';\nimport { parseTotal } from './parse-total.ts';\n\n// ---------------------------------------------------------------------------\n// withDefault\n// ---------------------------------------------------------------------------\n\n/**\n * Wrap a nullable codec with a default value. The output type becomes\n * non-nullable, and the wrapper is TOTAL over `string | string[] |\n * undefined` even when the inner codec is not.\n *\n * The default is substituted for `null` — the documented \"no value\"\n * answer — and for `undefined`, which is what an implicitly-optional\n * Standard Schema field and a bare `parseAsString` produce for an absent\n * param. Substituting only for `null` left a field typed non-nullable\n * `string` holding `undefined` (TIM-1350).\n *\n * The inner codec is invoked through `parseTotal`, so a nuqs parser gets\n * its own normalization (absent → null, repeated → first value, inner\n * throw → null) before either check applies. That is what makes\n * `withDefault(parseAsBoolean, false)` total; the wrapper itself does NOT\n * catch. A throw from a codec is a deliberate signal — `fromSchema` throws\n * on an async schema, and an app codec may `redirect()` or `notFound()` on\n * a value it refuses — and swallowing it would convert a loud failure into\n * a permanently-default field. design/09 §\"The SearchParamCodec Protocol\":\n * a codec that throws bubbles as a render-phase error, by design.\n *\n * Works with any codec — nuqs parsers, custom codecs, fromSchema results.\n *\n * ```ts\n * import { parseAsInteger } from 'nuqs/server'\n * import { withDefault } from '@timber-js/app/search-params'\n *\n * const page = withDefault(parseAsInteger, 1)\n * // page.parse(undefined) → 1 (not null)\n * // page.parse('5') → 5\n * ```\n *\n * The signature strips BOTH nullish constituents from the result, not just\n * `null`, because the runtime substitutes for both. An implicitly-optional\n * schema field is a `SearchParamCodec<string | undefined>`, and wrapping it\n * used to yield `SearchParamCodec<string | undefined>` — a field the\n * wrapper guarantees is always present, still typed as maybe-absent.\n */\nexport function withDefault<T>(\n codec: SearchParamCodec<T | null | undefined>,\n defaultValue: NonNullable<T>\n): SearchParamCodec<NonNullable<T>> {\n // A wrapper that rebuilds a codec from two methods drops everything else\n // the codec carries. `withUrlKey` lost `parseServerSide` that way; this\n // one lost `urlKey`, so `withDefault(withUrlKey(parseAsInteger, 'p'), 1)`\n // silently read `?page=` instead of `?p=`. Carry it explicitly rather\n // than spreading: this wrapper's own `parse` IS the total entry point,\n // and re-publishing the inner `parseServerSide` would let `parseTotal`\n // reach past it and skip the default entirely.\n const wrapped: SearchParamCodec<NonNullable<T>> = {\n parse(value: string | string[] | undefined): NonNullable<T> {\n const result = parseTotal(codec, value);\n return result === null || result === undefined ? defaultValue : result;\n },\n serialize(value: NonNullable<T>): string | string[] | null {\n return codec.serialize(value);\n },\n };\n if (codec.urlKey !== undefined) wrapped.urlKey = codec.urlKey;\n return wrapped;\n}\n\n// ---------------------------------------------------------------------------\n// withUrlKey\n// ---------------------------------------------------------------------------\n\n/**\n * Attach a URL key alias to a codec. The alias determines what query\n * parameter key is used in the URL, while the TypeScript property name\n * stays descriptive.\n *\n * Aliases travel with codecs through object spread composition — when\n * you spread a bundle containing aliased codecs into defineSearchParams,\n * the aliases come along automatically.\n *\n * ```ts\n * import { parseAsString } from 'nuqs/server'\n * import { withUrlKey } from '@timber-js/app/search-params'\n *\n * export const searchable = {\n * q: withUrlKey(parseAsString, 'search'),\n * // ?search=shoes → { q: 'shoes' }\n * }\n * ```\n *\n * Composes with withDefault:\n * ```ts\n * import { parseAsInteger } from 'nuqs/server'\n * withUrlKey(withDefault(parseAsInteger, 1), 'p')\n * ```\n */\nexport function withUrlKey<F extends SearchParamField>(\n codecOrSchema: F,\n urlKey: string\n): SearchParamCodecWithUrlKey<InferField<F>> {\n type T = InferField<F>;\n // Auto-detect Standard Schema (Zod, Valibot, ArkType) and wrap. Schemas\n // that reject undefined input are implicitly optional — fromSchema returns\n // undefined for absent params, and InferField widens the type to include\n // undefined. design/23-search-params.md §\"Implicit Optionality\"\n const codec: SearchParamCodec<T> = isCodec(codecOrSchema)\n ? (codecOrSchema as SearchParamCodec<T>)\n : isStandardSchema(codecOrSchema)\n ? (fromSchema(codecOrSchema) as SearchParamCodec<T>)\n : (codecOrSchema as SearchParamCodec<T>);\n // Carry the total entry point, bound like the other two methods. A\n // codec's totality lives in a THIRD property, `parseServerSide` (see\n // parse-total.ts); picking only `parse`/`serialize` silently produced a\n // non-total alias, so `withUrlKey(parseAsBoolean, 'b')` threw on an\n // absent param while the bare parser did not (TIM-1350).\n //\n // Bound explicitly rather than spread: a spread copies own enumerable\n // properties only, so a class-based codec — whose `parse` and\n // `serialize` this wrapper already reaches through the prototype —\n // would have kept its methods and lost exactly the one that makes it\n // total. Three properties, one rule, no dependence on how the inner\n // codec was constructed.\n const wrapped: SearchParamCodecWithUrlKey<T> = {\n parse: codec.parse.bind(codec),\n serialize: codec.serialize.bind(codec),\n urlKey,\n };\n if (typeof codec.parseServerSide === 'function') {\n wrapped.parseServerSide = codec.parseServerSide.bind(codec);\n }\n return wrapped;\n}\n"],"mappings":"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"}
@@ -269,4 +269,27 @@ export interface SegmentCaptureStore {
269
269
  }
270
270
  /** @internal — import via segment-hash/capture.ts */
271
271
  export declare const segmentCaptureAls: AsyncLocalStorage<SegmentCaptureStore>;
272
+ /** The request inputs a `'document'` segment's render may read: its key. */
273
+ export interface DocumentReadScope {
274
+ /** The segment's outlet path, for error messages. */
275
+ segmentPath: string;
276
+ /** Segment param names in the key. */
277
+ params: ReadonlySet<string>;
278
+ /**
279
+ * The fields of the key's search-params definition, each with the codec and
280
+ * URL key it is read through — a field of another definition matches only
281
+ * when both are the same.
282
+ */
283
+ searchParams: ReadonlyMap<string, {
284
+ codec: unknown;
285
+ urlKey: string;
286
+ }>;
287
+ /**
288
+ * The key's cookies, by name, with the codec of the definition the key
289
+ * holds: a keyed cookie may be read only through that definition.
290
+ */
291
+ cookies: ReadonlyMap<string, unknown>;
292
+ }
293
+ /** @internal — run and read via segment-lifetime/read-scope.ts */
294
+ export declare const documentReadScopeAls: AsyncLocalStorage<DocumentReadScope>;
272
295
  //# sourceMappingURL=als-registry.d.ts.map