@rangojs/router 0.0.0-experimental.6 → 0.0.0-experimental.64e3ae06

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 (300) hide show
  1. package/AGENTS.md +9 -0
  2. package/README.md +884 -4
  3. package/dist/bin/rango.js +1606 -0
  4. package/dist/vite/index.js +4567 -769
  5. package/package.json +77 -58
  6. package/skills/breadcrumbs/SKILL.md +250 -0
  7. package/skills/cache-guide/SKILL.md +262 -0
  8. package/skills/caching/SKILL.md +85 -23
  9. package/skills/composability/SKILL.md +172 -0
  10. package/skills/debug-manifest/SKILL.md +12 -8
  11. package/skills/document-cache/SKILL.md +18 -16
  12. package/skills/fonts/SKILL.md +167 -0
  13. package/skills/hooks/SKILL.md +334 -72
  14. package/skills/host-router/SKILL.md +218 -0
  15. package/skills/intercept/SKILL.md +131 -8
  16. package/skills/layout/SKILL.md +100 -3
  17. package/skills/links/SKILL.md +89 -30
  18. package/skills/loader/SKILL.md +388 -38
  19. package/skills/middleware/SKILL.md +171 -34
  20. package/skills/mime-routes/SKILL.md +128 -0
  21. package/skills/parallel/SKILL.md +78 -1
  22. package/skills/prerender/SKILL.md +643 -0
  23. package/skills/rango/SKILL.md +85 -16
  24. package/skills/response-routes/SKILL.md +411 -0
  25. package/skills/route/SKILL.md +226 -14
  26. package/skills/router-setup/SKILL.md +123 -30
  27. package/skills/tailwind/SKILL.md +129 -0
  28. package/skills/theme/SKILL.md +9 -8
  29. package/skills/typesafety/SKILL.md +318 -89
  30. package/skills/use-cache/SKILL.md +324 -0
  31. package/src/__internal.ts +102 -4
  32. package/src/bin/rango.ts +321 -0
  33. package/src/browser/action-coordinator.ts +97 -0
  34. package/src/browser/action-response-classifier.ts +99 -0
  35. package/src/browser/event-controller.ts +87 -64
  36. package/src/browser/history-state.ts +80 -0
  37. package/src/browser/intercept-utils.ts +52 -0
  38. package/src/browser/link-interceptor.ts +24 -4
  39. package/src/browser/logging.ts +55 -0
  40. package/src/browser/merge-segment-loaders.ts +20 -12
  41. package/src/browser/navigation-bridge.ts +282 -557
  42. package/src/browser/navigation-client.ts +170 -71
  43. package/src/browser/navigation-store.ts +33 -50
  44. package/src/browser/navigation-transaction.ts +297 -0
  45. package/src/browser/network-error-handler.ts +61 -0
  46. package/src/browser/partial-update.ts +292 -310
  47. package/src/browser/prefetch/cache.ts +206 -0
  48. package/src/browser/prefetch/fetch.ts +145 -0
  49. package/src/browser/prefetch/observer.ts +65 -0
  50. package/src/browser/prefetch/policy.ts +48 -0
  51. package/src/browser/prefetch/queue.ts +128 -0
  52. package/src/browser/rango-state.ts +112 -0
  53. package/src/browser/react/Link.tsx +193 -73
  54. package/src/browser/react/NavigationProvider.tsx +78 -11
  55. package/src/browser/react/context.ts +6 -0
  56. package/src/browser/react/filter-segment-order.ts +11 -0
  57. package/src/browser/react/index.ts +12 -12
  58. package/src/browser/react/location-state-shared.ts +95 -53
  59. package/src/browser/react/location-state.ts +60 -15
  60. package/src/browser/react/mount-context.ts +6 -1
  61. package/src/browser/react/nonce-context.ts +23 -0
  62. package/src/browser/react/shallow-equal.ts +27 -0
  63. package/src/browser/react/use-action.ts +29 -51
  64. package/src/browser/react/use-client-cache.ts +5 -3
  65. package/src/browser/react/use-handle.ts +32 -79
  66. package/src/browser/react/use-href.tsx +2 -2
  67. package/src/browser/react/use-link-status.ts +6 -5
  68. package/src/browser/react/use-navigation.ts +22 -63
  69. package/src/browser/react/use-params.ts +65 -0
  70. package/src/browser/react/use-pathname.ts +47 -0
  71. package/src/browser/react/use-router.ts +63 -0
  72. package/src/browser/react/use-search-params.ts +56 -0
  73. package/src/browser/react/use-segments.ts +80 -97
  74. package/src/browser/response-adapter.ts +73 -0
  75. package/src/browser/rsc-router.tsx +167 -55
  76. package/src/browser/scroll-restoration.ts +117 -44
  77. package/src/browser/segment-reconciler.ts +216 -0
  78. package/src/browser/segment-structure-assert.ts +16 -0
  79. package/src/browser/server-action-bridge.ts +504 -599
  80. package/src/browser/shallow.ts +6 -1
  81. package/src/browser/types.ts +118 -47
  82. package/src/browser/validate-redirect-origin.ts +29 -0
  83. package/src/build/generate-manifest.ts +235 -24
  84. package/src/build/generate-route-types.ts +36 -0
  85. package/src/build/index.ts +13 -0
  86. package/src/build/route-trie.ts +265 -0
  87. package/src/build/route-types/ast-helpers.ts +25 -0
  88. package/src/build/route-types/ast-route-extraction.ts +98 -0
  89. package/src/build/route-types/codegen.ts +102 -0
  90. package/src/build/route-types/include-resolution.ts +411 -0
  91. package/src/build/route-types/param-extraction.ts +48 -0
  92. package/src/build/route-types/per-module-writer.ts +128 -0
  93. package/src/build/route-types/router-processing.ts +479 -0
  94. package/src/build/route-types/scan-filter.ts +78 -0
  95. package/src/build/runtime-discovery.ts +231 -0
  96. package/src/cache/background-task.ts +34 -0
  97. package/src/cache/cache-key-utils.ts +44 -0
  98. package/src/cache/cache-policy.ts +125 -0
  99. package/src/cache/cache-runtime.ts +338 -0
  100. package/src/cache/cache-scope.ts +122 -305
  101. package/src/cache/cf/cf-cache-store.ts +571 -17
  102. package/src/cache/cf/index.ts +13 -3
  103. package/src/cache/document-cache.ts +101 -72
  104. package/src/cache/handle-capture.ts +81 -0
  105. package/src/cache/handle-snapshot.ts +41 -0
  106. package/src/cache/index.ts +1 -15
  107. package/src/cache/memory-segment-store.ts +191 -13
  108. package/src/cache/profile-registry.ts +73 -0
  109. package/src/cache/read-through-swr.ts +134 -0
  110. package/src/cache/segment-codec.ts +256 -0
  111. package/src/cache/taint.ts +98 -0
  112. package/src/cache/types.ts +72 -122
  113. package/src/client.rsc.tsx +3 -1
  114. package/src/client.tsx +106 -126
  115. package/src/component-utils.ts +4 -4
  116. package/src/components/DefaultDocument.tsx +5 -1
  117. package/src/context-var.ts +86 -0
  118. package/src/debug.ts +17 -7
  119. package/src/errors.ts +108 -2
  120. package/src/handle.ts +15 -29
  121. package/src/handles/MetaTags.tsx +73 -20
  122. package/src/handles/breadcrumbs.ts +66 -0
  123. package/src/handles/index.ts +1 -0
  124. package/src/handles/meta.ts +30 -13
  125. package/src/host/cookie-handler.ts +165 -0
  126. package/src/host/errors.ts +97 -0
  127. package/src/host/index.ts +53 -0
  128. package/src/host/pattern-matcher.ts +214 -0
  129. package/src/host/router.ts +352 -0
  130. package/src/host/testing.ts +79 -0
  131. package/src/host/types.ts +146 -0
  132. package/src/host/utils.ts +25 -0
  133. package/src/href-client.ts +119 -29
  134. package/src/index.rsc.ts +153 -19
  135. package/src/index.ts +211 -30
  136. package/src/internal-debug.ts +11 -0
  137. package/src/loader.rsc.ts +26 -147
  138. package/src/loader.ts +27 -10
  139. package/src/network-error-thrower.tsx +3 -1
  140. package/src/outlet-provider.tsx +45 -0
  141. package/src/prerender/param-hash.ts +37 -0
  142. package/src/prerender/store.ts +185 -0
  143. package/src/prerender.ts +463 -0
  144. package/src/reverse.ts +330 -0
  145. package/src/root-error-boundary.tsx +41 -29
  146. package/src/route-content-wrapper.tsx +7 -4
  147. package/src/route-definition/dsl-helpers.ts +934 -0
  148. package/src/route-definition/helper-factories.ts +200 -0
  149. package/src/route-definition/helpers-types.ts +430 -0
  150. package/src/route-definition/index.ts +52 -0
  151. package/src/route-definition/redirect.ts +93 -0
  152. package/src/route-definition.ts +1 -1428
  153. package/src/route-map-builder.ts +217 -123
  154. package/src/route-name.ts +53 -0
  155. package/src/route-types.ts +59 -8
  156. package/src/router/content-negotiation.ts +116 -0
  157. package/src/router/debug-manifest.ts +72 -0
  158. package/src/router/error-handling.ts +9 -9
  159. package/src/router/find-match.ts +160 -0
  160. package/src/router/handler-context.ts +374 -81
  161. package/src/router/intercept-resolution.ts +397 -0
  162. package/src/router/lazy-includes.ts +236 -0
  163. package/src/router/loader-resolution.ts +215 -122
  164. package/src/router/logging.ts +251 -0
  165. package/src/router/manifest.ts +150 -35
  166. package/src/router/match-api.ts +620 -0
  167. package/src/router/match-context.ts +5 -3
  168. package/src/router/match-handlers.ts +440 -0
  169. package/src/router/match-middleware/background-revalidation.ts +80 -93
  170. package/src/router/match-middleware/cache-lookup.ts +382 -9
  171. package/src/router/match-middleware/cache-store.ts +51 -22
  172. package/src/router/match-middleware/intercept-resolution.ts +55 -17
  173. package/src/router/match-middleware/segment-resolution.ts +25 -6
  174. package/src/router/match-pipelines.ts +10 -45
  175. package/src/router/match-result.ts +34 -28
  176. package/src/router/metrics.ts +235 -15
  177. package/src/router/middleware-cookies.ts +55 -0
  178. package/src/router/middleware-types.ts +222 -0
  179. package/src/router/middleware.ts +327 -369
  180. package/src/router/pattern-matching.ts +211 -43
  181. package/src/router/prerender-match.ts +402 -0
  182. package/src/router/preview-match.ts +170 -0
  183. package/src/router/revalidation.ts +137 -38
  184. package/src/router/router-context.ts +40 -21
  185. package/src/router/router-interfaces.ts +452 -0
  186. package/src/router/router-options.ts +592 -0
  187. package/src/router/router-registry.ts +24 -0
  188. package/src/router/segment-resolution/fresh.ts +570 -0
  189. package/src/router/segment-resolution/helpers.ts +263 -0
  190. package/src/router/segment-resolution/loader-cache.ts +198 -0
  191. package/src/router/segment-resolution/revalidation.ts +1242 -0
  192. package/src/router/segment-resolution/static-store.ts +67 -0
  193. package/src/router/segment-resolution.ts +21 -0
  194. package/src/router/segment-wrappers.ts +291 -0
  195. package/src/router/telemetry-otel.ts +299 -0
  196. package/src/router/telemetry.ts +300 -0
  197. package/src/router/timeout.ts +148 -0
  198. package/src/router/trie-matching.ts +239 -0
  199. package/src/router/types.ts +77 -3
  200. package/src/router.ts +665 -4182
  201. package/src/rsc/handler-context.ts +45 -0
  202. package/src/rsc/handler.ts +764 -754
  203. package/src/rsc/helpers.ts +140 -6
  204. package/src/rsc/index.ts +0 -20
  205. package/src/rsc/loader-fetch.ts +209 -0
  206. package/src/rsc/manifest-init.ts +86 -0
  207. package/src/rsc/nonce.ts +14 -0
  208. package/src/rsc/origin-guard.ts +141 -0
  209. package/src/rsc/progressive-enhancement.ts +379 -0
  210. package/src/rsc/response-error.ts +37 -0
  211. package/src/rsc/response-route-handler.ts +347 -0
  212. package/src/rsc/rsc-rendering.ts +237 -0
  213. package/src/rsc/runtime-warnings.ts +42 -0
  214. package/src/rsc/server-action.ts +348 -0
  215. package/src/rsc/ssr-setup.ts +128 -0
  216. package/src/rsc/types.ts +38 -11
  217. package/src/search-params.ts +230 -0
  218. package/src/segment-system.tsx +26 -14
  219. package/src/server/context.ts +182 -51
  220. package/src/server/cookie-store.ts +190 -0
  221. package/src/server/fetchable-loader-store.ts +37 -0
  222. package/src/server/handle-store.ts +94 -15
  223. package/src/server/loader-registry.ts +15 -56
  224. package/src/server/request-context.ts +439 -73
  225. package/src/server.ts +35 -128
  226. package/src/ssr/index.tsx +100 -31
  227. package/src/static-handler.ts +114 -0
  228. package/src/theme/ThemeProvider.tsx +21 -15
  229. package/src/theme/ThemeScript.tsx +5 -5
  230. package/src/theme/constants.ts +5 -2
  231. package/src/theme/index.ts +4 -14
  232. package/src/theme/theme-context.ts +4 -30
  233. package/src/theme/theme-script.ts +21 -18
  234. package/src/types/boundaries.ts +158 -0
  235. package/src/types/cache-types.ts +198 -0
  236. package/src/types/error-types.ts +192 -0
  237. package/src/types/global-namespace.ts +100 -0
  238. package/src/types/handler-context.ts +687 -0
  239. package/src/types/index.ts +88 -0
  240. package/src/types/loader-types.ts +183 -0
  241. package/src/types/route-config.ts +170 -0
  242. package/src/types/route-entry.ts +109 -0
  243. package/src/types/segments.ts +148 -0
  244. package/src/types.ts +1 -1623
  245. package/src/urls/include-helper.ts +197 -0
  246. package/src/urls/index.ts +53 -0
  247. package/src/urls/path-helper-types.ts +339 -0
  248. package/src/urls/path-helper.ts +329 -0
  249. package/src/urls/pattern-types.ts +95 -0
  250. package/src/urls/response-types.ts +106 -0
  251. package/src/urls/type-extraction.ts +372 -0
  252. package/src/urls/urls-function.ts +98 -0
  253. package/src/urls.ts +1 -802
  254. package/src/use-loader.tsx +85 -77
  255. package/src/vite/discovery/bundle-postprocess.ts +184 -0
  256. package/src/vite/discovery/discover-routers.ts +344 -0
  257. package/src/vite/discovery/prerender-collection.ts +385 -0
  258. package/src/vite/discovery/route-types-writer.ts +258 -0
  259. package/src/vite/discovery/self-gen-tracking.ts +47 -0
  260. package/src/vite/discovery/state.ts +108 -0
  261. package/src/vite/discovery/virtual-module-codegen.ts +203 -0
  262. package/src/vite/index.ts +11 -782
  263. package/src/vite/plugin-types.ts +48 -0
  264. package/src/vite/plugins/cjs-to-esm.ts +93 -0
  265. package/src/vite/plugins/client-ref-dedup.ts +115 -0
  266. package/src/vite/plugins/client-ref-hashing.ts +105 -0
  267. package/src/vite/{expose-action-id.ts → plugins/expose-action-id.ts} +72 -53
  268. package/src/vite/plugins/expose-id-utils.ts +287 -0
  269. package/src/vite/plugins/expose-ids/export-analysis.ts +296 -0
  270. package/src/vite/plugins/expose-ids/handler-transform.ts +179 -0
  271. package/src/vite/plugins/expose-ids/loader-transform.ts +74 -0
  272. package/src/vite/plugins/expose-ids/router-transform.ts +110 -0
  273. package/src/vite/plugins/expose-ids/types.ts +45 -0
  274. package/src/vite/plugins/expose-internal-ids.ts +569 -0
  275. package/src/vite/plugins/refresh-cmd.ts +65 -0
  276. package/src/vite/plugins/use-cache-transform.ts +323 -0
  277. package/src/vite/plugins/version-injector.ts +83 -0
  278. package/src/vite/plugins/version-plugin.ts +266 -0
  279. package/src/vite/{virtual-entries.ts → plugins/virtual-entries.ts} +27 -16
  280. package/src/vite/plugins/virtual-stub-plugin.ts +29 -0
  281. package/src/vite/rango.ts +445 -0
  282. package/src/vite/router-discovery.ts +777 -0
  283. package/src/vite/utils/ast-handler-extract.ts +517 -0
  284. package/src/vite/utils/banner.ts +36 -0
  285. package/src/vite/utils/bundle-analysis.ts +137 -0
  286. package/src/vite/utils/manifest-utils.ts +70 -0
  287. package/src/vite/{package-resolution.ts → utils/package-resolution.ts} +25 -29
  288. package/src/vite/utils/prerender-utils.ts +189 -0
  289. package/src/vite/utils/shared-utils.ts +169 -0
  290. package/CLAUDE.md +0 -43
  291. package/src/browser/lru-cache.ts +0 -69
  292. package/src/browser/request-controller.ts +0 -164
  293. package/src/cache/memory-store.ts +0 -253
  294. package/src/href-context.ts +0 -33
  295. package/src/href.ts +0 -255
  296. package/src/server/route-manifest-cache.ts +0 -173
  297. package/src/vite/expose-handle-id.ts +0 -209
  298. package/src/vite/expose-loader-id.ts +0 -426
  299. package/src/vite/expose-location-state-id.ts +0 -177
  300. /package/src/vite/{version.d.ts → plugins/version.d.ts} +0 -0
@@ -0,0 +1,251 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
3
+
4
+ // -- Revalidation trace types --
5
+
6
+ export interface RevalidationTraceEntry {
7
+ segmentId: string;
8
+ segmentType: string;
9
+ belongsToRoute: boolean;
10
+ source:
11
+ | "segment-resolution"
12
+ | "cache-hit"
13
+ | "loader"
14
+ | "parallel"
15
+ | "orphan-layout"
16
+ | "route-handler"
17
+ | "layout-handler"
18
+ | "intercept-loader";
19
+ defaultShouldRevalidate: boolean;
20
+ finalShouldRevalidate: boolean;
21
+ reason: string;
22
+ customRevalidators?: number;
23
+ }
24
+
25
+ export interface RevalidationTraceMeta {
26
+ method: string;
27
+ prevUrl: string;
28
+ nextUrl: string;
29
+ routeKey: string;
30
+ isAction: boolean;
31
+ stale?: boolean;
32
+ }
33
+
34
+ export interface RevalidationTrace {
35
+ meta: RevalidationTraceMeta;
36
+ entries: RevalidationTraceEntry[];
37
+ }
38
+
39
+ // -- Log context --
40
+
41
+ interface RouterLogContext {
42
+ requestId: string;
43
+ transactionId: string;
44
+ depth: number;
45
+ revalidationTrace?: RevalidationTrace;
46
+ }
47
+
48
+ interface RouterLogOptions {
49
+ request: Request;
50
+ transaction: string;
51
+ }
52
+
53
+ interface LogDetails {
54
+ [key: string]: unknown;
55
+ }
56
+
57
+ const routerLogContext = new AsyncLocalStorage<RouterLogContext>();
58
+ const requestIds = new WeakMap<Request, string>();
59
+
60
+ let requestCounter = 0;
61
+ let transactionCounter = 0;
62
+
63
+ function nextId(prefix: string, counter: number): string {
64
+ return `${prefix}${counter.toString(36)}`;
65
+ }
66
+
67
+ function getHeaderRequestId(request: Request): string | null {
68
+ const candidate =
69
+ request.headers.get("x-rsc-router-request-id") ??
70
+ request.headers.get("x-request-id") ??
71
+ request.headers.get("cf-ray");
72
+ if (!candidate) return null;
73
+ const trimmed = candidate.trim();
74
+ return trimmed.length > 0 ? trimmed : null;
75
+ }
76
+
77
+ function getOrCreateRequestId(request: Request): string {
78
+ const existing = requestIds.get(request);
79
+ if (existing) return existing;
80
+
81
+ const fromHeaders = getHeaderRequestId(request);
82
+ if (fromHeaders) {
83
+ requestIds.set(request, fromHeaders);
84
+ return fromHeaders;
85
+ }
86
+
87
+ requestCounter += 1;
88
+ const generated = nextId("req-", requestCounter);
89
+ requestIds.set(request, generated);
90
+ return generated;
91
+ }
92
+
93
+ export function runWithRouterLogContext<T>(
94
+ options: RouterLogOptions,
95
+ fn: () => T,
96
+ ): T {
97
+ if (!INTERNAL_RANGO_DEBUG) {
98
+ return fn();
99
+ }
100
+
101
+ const requestId = getOrCreateRequestId(options.request);
102
+ transactionCounter += 1;
103
+ const transactionId = `${options.transaction}-${nextId("tx-", transactionCounter)}`;
104
+
105
+ return routerLogContext.run(
106
+ {
107
+ requestId,
108
+ transactionId,
109
+ depth: 0,
110
+ },
111
+ fn,
112
+ );
113
+ }
114
+
115
+ export function withRouterLogScope<T>(
116
+ label: string,
117
+ fn: () => Promise<T>,
118
+ ): Promise<T>;
119
+ export function withRouterLogScope<T>(label: string, fn: () => T): T;
120
+ export function withRouterLogScope<T>(
121
+ label: string,
122
+ fn: () => Promise<T> | T,
123
+ ): Promise<T> | T {
124
+ const ctx = routerLogContext.getStore();
125
+ if (!INTERNAL_RANGO_DEBUG || !ctx) {
126
+ return fn();
127
+ }
128
+
129
+ debugLog(label, "start");
130
+
131
+ return routerLogContext.run({ ...ctx, depth: ctx.depth + 1 }, () => {
132
+ try {
133
+ const result = fn();
134
+ if (result && typeof (result as Promise<T>).then === "function") {
135
+ return (result as Promise<T>).then(
136
+ (value) => {
137
+ debugLog(label, "end");
138
+ return value;
139
+ },
140
+ (error) => {
141
+ debugLog(label, "error", { error: String(error) });
142
+ throw error;
143
+ },
144
+ );
145
+ }
146
+ debugLog(label, "end");
147
+ return result;
148
+ } catch (error) {
149
+ debugLog(label, "error", { error: String(error) });
150
+ throw error;
151
+ }
152
+ });
153
+ }
154
+
155
+ export function isRouterDebugEnabled(): boolean {
156
+ return INTERNAL_RANGO_DEBUG && !!routerLogContext.getStore();
157
+ }
158
+
159
+ function formatPrefix(scope: string): string {
160
+ const ctx = routerLogContext.getStore();
161
+ if (!ctx) return `[Router][${scope}]`;
162
+ const indent = " ".repeat(ctx.depth);
163
+ return `[Router][req:${ctx.requestId}][tx:${ctx.transactionId}] ${indent}[${scope}]`;
164
+ }
165
+
166
+ export function debugLog(
167
+ scope: string,
168
+ message: string,
169
+ details?: LogDetails,
170
+ ): void {
171
+ if (!isRouterDebugEnabled()) return;
172
+
173
+ const prefix = formatPrefix(scope);
174
+ if (details) {
175
+ console.log(`${prefix} ${message}`, details);
176
+ return;
177
+ }
178
+
179
+ console.log(`${prefix} ${message}`);
180
+ }
181
+
182
+ export function debugWarn(
183
+ scope: string,
184
+ message: string,
185
+ details?: LogDetails,
186
+ ): void {
187
+ if (!isRouterDebugEnabled()) return;
188
+
189
+ const prefix = formatPrefix(scope);
190
+ if (details) {
191
+ console.warn(`${prefix} ${message}`, details);
192
+ return;
193
+ }
194
+
195
+ console.warn(`${prefix} ${message}`);
196
+ }
197
+
198
+ // -- Revalidation trace helpers --
199
+
200
+ export function isTraceActive(): boolean {
201
+ if (!INTERNAL_RANGO_DEBUG) return false;
202
+ const ctx = routerLogContext.getStore();
203
+ return !!ctx?.revalidationTrace;
204
+ }
205
+
206
+ export function startRevalidationTrace(meta: RevalidationTraceMeta): void {
207
+ const ctx = routerLogContext.getStore();
208
+ if (!ctx || !INTERNAL_RANGO_DEBUG) return;
209
+ ctx.revalidationTrace = { meta, entries: [] };
210
+ }
211
+
212
+ export function pushRevalidationTraceEntry(
213
+ entry: RevalidationTraceEntry,
214
+ ): void {
215
+ const ctx = routerLogContext.getStore();
216
+ if (!ctx?.revalidationTrace) return;
217
+ ctx.revalidationTrace.entries.push(entry);
218
+ }
219
+
220
+ export function flushRevalidationTrace(): RevalidationTrace | null {
221
+ const ctx = routerLogContext.getStore();
222
+ if (!ctx?.revalidationTrace) return null;
223
+ const trace = ctx.revalidationTrace;
224
+ ctx.revalidationTrace = undefined;
225
+
226
+ if (trace.entries.length === 0) return trace;
227
+
228
+ const revalidated = trace.entries.filter((e) => e.finalShouldRevalidate);
229
+ const skipped = trace.entries.filter((e) => !e.finalShouldRevalidate);
230
+
231
+ debugLog("revalidation-trace", "flush", {
232
+ method: trace.meta.method,
233
+ routeKey: trace.meta.routeKey,
234
+ isAction: trace.meta.isAction,
235
+ stale: trace.meta.stale,
236
+ prevUrl: trace.meta.prevUrl,
237
+ nextUrl: trace.meta.nextUrl,
238
+ total: trace.entries.length,
239
+ revalidated: revalidated.length,
240
+ skipped: skipped.length,
241
+ entries: trace.entries.map((e) => ({
242
+ segmentId: e.segmentId,
243
+ type: e.segmentType,
244
+ source: e.source,
245
+ revalidate: e.finalShouldRevalidate,
246
+ reason: e.reason,
247
+ })),
248
+ });
249
+
250
+ return trace;
251
+ }
@@ -6,27 +6,85 @@
6
6
 
7
7
  import { invariant, RouteNotFoundError } from "../errors";
8
8
  import { createRouteHelpers } from "../route-definition";
9
- import { getContext, runWithPrefixes, type EntryData, type MetricsStore } from "../server/context";
9
+ import {
10
+ getContext,
11
+ runWithPrefixes,
12
+ type EntryData,
13
+ type MetricsStore,
14
+ } from "../server/context";
10
15
  import MapRootLayout from "../server/root-layout";
11
16
  import type { RouteEntry } from "../types";
12
17
  import type { UrlPatterns } from "../urls";
18
+ import { VERSION } from "@rangojs/router:version";
19
+
20
+ // Module-level manifest cache: avoids re-executing DSL handler on every request.
21
+ // Handler execution is deterministic (components, loaders, middleware are module-level
22
+ // stable references), so the resulting EntryData tree can be safely cached and reused
23
+ // across requests within the same isolate.
24
+ //
25
+ // Cache is keyed by (VERSION, mountIndex, routeKey, isSSR). VERSION comes from the
26
+ // @rangojs/router:version virtual module which Vite invalidates on RSC module HMR.
27
+ // When VERSION changes, this module re-evaluates and the cache is recreated empty.
28
+ // Including VERSION in the key is additional defense against stale entries.
29
+ const manifestModuleCache = new Map<string, Map<string, EntryData>>();
13
30
 
14
31
  /**
15
32
  * Load manifest from route entry with AsyncLocalStorage context
16
33
  * Handles lazy imports, unwrapping, and validation
17
34
  *
18
- * Note: We don't cache manifests at the module level because includes are
19
- * lazily evaluated. Caching an incomplete manifest would cause cache misses
20
- * for routes in not-yet-evaluated includes.
35
+ * Results are cached at module level after first execution. Subsequent calls
36
+ * for the same (routeKey, isSSR) within the same isolate return cached data
37
+ * without re-executing the DSL handler.
38
+ */
39
+ /**
40
+ * Clear the module-level manifest cache.
41
+ * Called on HMR to ensure stale handler references are discarded.
21
42
  */
43
+ export function clearManifestCache(): void {
44
+ manifestModuleCache.clear();
45
+ }
46
+
22
47
  export async function loadManifest(
23
48
  entry: RouteEntry<any>,
24
49
  routeKey: string,
25
50
  path: string,
26
51
  metricsStore?: MetricsStore,
27
- isSSR?: boolean
52
+ isSSR?: boolean,
28
53
  ): Promise<EntryData> {
54
+ // Helper to push a metric entry
55
+ const pushMetric = metricsStore
56
+ ? (label: string, start: number) => {
57
+ metricsStore.metrics.push({
58
+ label,
59
+ duration: performance.now() - start,
60
+ startTime: start - metricsStore.requestStart,
61
+ });
62
+ }
63
+ : undefined;
64
+
29
65
  const mountIndex = entry.mountIndex;
66
+
67
+ // Check module-level cache (persists across requests within same isolate)
68
+ // Include routerId so multi-router setups (host routing) don't share cached
69
+ // EntryData across routers with overlapping mountIndex + routeKey combinations.
70
+ const cacheKey = `${VERSION}:${entry.routerId ?? ""}:${mountIndex ?? ""}:${routeKey}:${isSSR ? 1 : 0}`;
71
+ const cached = manifestModuleCache.get(cacheKey);
72
+ if (cached) {
73
+ const cacheStart = performance.now();
74
+ // Set up Store for downstream consumers (segment resolution reads Store.manifest)
75
+ const Store = getContext().getOrCreateStore(routeKey);
76
+ Store.mountIndex = mountIndex;
77
+ Store.isSSR = isSSR;
78
+ if (metricsStore) Store.metrics = metricsStore;
79
+ // Restore cached manifest into Store
80
+ for (const [k, v] of cached) {
81
+ Store.manifest.set(k, v);
82
+ }
83
+ pushMetric?.("manifest:cache-hit", cacheStart);
84
+ return cached.get(routeKey)!;
85
+ }
86
+
87
+ const storeSetupStart = performance.now();
30
88
  const Store = getContext().getOrCreateStore(routeKey);
31
89
 
32
90
  // Set mount index in store for unique shortCode prefixes
@@ -40,20 +98,54 @@ export async function loadManifest(
40
98
  Store.metrics = metricsStore;
41
99
  }
42
100
 
101
+ pushMetric?.("manifest:store-setup", storeSetupStart);
102
+
43
103
  // Clear manifest before rebuilding to prevent stale entry mutations
104
+ const clearStart = performance.now();
44
105
  Store.manifest.clear();
106
+ pushMetric?.("manifest:clear", clearStart);
45
107
 
46
108
  try {
47
109
  // Include mountIndex in namespace to ensure unique cache keys per mount
48
- const namespaceWithMount = mountIndex !== undefined
49
- ? `#router.M${mountIndex}`
50
- : "#router";
110
+ const namespaceWithMount =
111
+ mountIndex !== undefined ? `#router.M${mountIndex}` : "#router";
51
112
 
52
113
  // For lazy entries, use the captured parent from include() context
53
114
  // This ensures routes are registered under the correct layout hierarchy
54
- const lazyContext = entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
55
- const parentForContext = lazyContext?.parent as EntryData | null ?? Store.parent;
115
+ const lazyContext =
116
+ entry.lazy && entry.lazyPatterns ? entry.lazyContext : null;
117
+ const parentForContext =
118
+ (lazyContext?.parent as EntryData | null) ?? Store.parent;
119
+
120
+ // For lazy entries, merge captured counters from include() so the
121
+ // handler's entries get shortCode indices after sibling entries that
122
+ // were created during pattern extraction. This prevents shortCode
123
+ // collisions between lazy and non-lazy entries under the same parent
124
+ // (e.g., ArticlesLayout and BlogLayout both under NavLayout).
125
+ if (lazyContext && (lazyContext as any).counters) {
126
+ const captured = (lazyContext as any).counters as Record<string, number>;
127
+ for (const [key, value] of Object.entries(captured)) {
128
+ Store.counters[key] = Math.max(Store.counters[key] ?? 0, value);
129
+ }
130
+ }
56
131
 
132
+ // Propagate cache profiles for DSL-time cache("profileName") resolution.
133
+ // Non-lazy entries carry profiles directly; lazy entries carry them
134
+ // in the captured lazyContext from include() time.
135
+ const entryProfiles =
136
+ entry.cacheProfiles ?? (lazyContext as any)?.cacheProfiles;
137
+ if (entryProfiles) {
138
+ Store.cacheProfiles = entryProfiles;
139
+ }
140
+
141
+ // Propagate rootScoped from lazyContext so that routes inside
142
+ // nested { name: "sub" } under { name: "" } keep inherited root scope
143
+ // when the manifest is rebuilt on each request.
144
+ if (lazyContext && (lazyContext as any).rootScoped !== undefined) {
145
+ Store.rootScoped = (lazyContext as any).rootScoped;
146
+ }
147
+
148
+ const handlerExecStart = performance.now();
57
149
  const useItems = await getContext().runWithStore(
58
150
  Store,
59
151
  Store.namespace || namespaceWithMount,
@@ -62,25 +154,23 @@ export async function loadManifest(
62
154
  // Create helpers for lazy-loaded handlers that need them
63
155
  const helpers = createRouteHelpers();
64
156
 
65
- // For lazy entries, use lazyPatterns.handler() with proper prefixes
157
+ // For lazy entries, use lazyPatterns.handler() with proper prefixes.
158
+ // Do NOT wrap in MapRootLayout here: the captured parent chain from
159
+ // pattern extraction already includes the synthetic MapRootLayout
160
+ // parent, so adding another would create an extra level that does
161
+ // not exist in the non-lazy (root handler) path and would produce
162
+ // mismatched shortCodes.
66
163
  if (entry.lazy && entry.lazyPatterns) {
67
164
  const lazyPatterns = entry.lazyPatterns as UrlPatterns<any>;
68
165
  const includePrefix = (entry as any)._lazyPrefix || "";
69
166
  const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
70
167
 
71
- // Wrap in root layout and run with prefixes
72
- const wrappedItems = helpers.layout(MapRootLayout, () => {
73
- if (fullPrefix || lazyContext?.namePrefix) {
74
- return runWithPrefixes(
75
- fullPrefix,
76
- lazyContext?.namePrefix,
77
- () => lazyPatterns.handler()
78
- );
79
- }
80
- return lazyPatterns.handler();
81
- });
82
-
83
- return [wrappedItems].flat(3);
168
+ if (fullPrefix || lazyContext?.namePrefix) {
169
+ return runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () =>
170
+ lazyPatterns.handler(),
171
+ );
172
+ }
173
+ return lazyPatterns.handler();
84
174
  }
85
175
 
86
176
  // Wrap handler execution in root layout so routes get correct parent
@@ -106,35 +196,60 @@ export async function loadManifest(
106
196
  "default" in load
107
197
  ) {
108
198
  // Promise<{ default: () => Array }> - e.g., dynamic import
109
- // Lazy-loaded handlers may need helpers (passed as optional arg)
199
+ if (typeof load.default !== "function") {
200
+ throw new Error(
201
+ `[@rangojs/router] Unsupported async handler: { default } must be a function, ` +
202
+ `got ${typeof load.default}. Use () => import('./urls') for lazy loading.`,
203
+ );
204
+ }
110
205
  return (load.default as (h?: any) => any)(helpers);
111
206
  }
112
207
  if (typeof load === "function") {
113
208
  // Promise<() => Array>
114
209
  return (load as (h?: any) => any)(helpers);
115
210
  }
116
- // Promise<Array> - direct array from async handler
117
- return load;
211
+ // Reject unsupported async handler results. Supported shapes are:
212
+ // Promise<{ default: fn }> — dynamic import
213
+ // Promise<fn> — lazy function
214
+ // Direct Promise<Array> is not supported; use a function wrapper.
215
+ throw new Error(
216
+ `[@rangojs/router] Unsupported async handler result (${typeof load}). ` +
217
+ `Lazy route handlers must resolve to a function or { default: fn }, ` +
218
+ `not a direct array. Wrap your handler: () => import('./urls') or ` +
219
+ `() => Promise.resolve((h) => [...])`,
220
+ );
118
221
  }
119
222
 
120
223
  // Inline handler - routes were registered with correct parent inside layout
121
224
  return [wrappedItems].flat(3);
122
- }
225
+ },
123
226
  );
227
+ pushMetric?.("manifest:handler-exec", handlerExecStart);
124
228
 
229
+ const validationStart = performance.now();
125
230
  invariant(
126
231
  useItems && useItems.length > 0,
127
- "Did not receive any handler from router.map()"
128
- );
129
- invariant(
130
- useItems.some((item: { type: string }) => item.type === "layout"),
131
- "Top-level handler must be a layout"
232
+ "Did not receive any handler from router.map()",
132
233
  );
234
+ // For non-lazy entries the root handler is wrapped in MapRootLayout,
235
+ // so the result always contains a layout item. Lazy entries run the
236
+ // included patterns handler directly (no MapRootLayout wrapper) so
237
+ // we skip this check -- the layout is in the captured parent chain.
238
+ if (!lazyContext) {
239
+ invariant(
240
+ useItems.some((item: { type: string }) => item.type === "layout"),
241
+ "Top-level handler must be a layout",
242
+ );
243
+ }
133
244
 
134
245
  invariant(
135
246
  Store.manifest.has(routeKey),
136
- `Route must be registered for ${routeKey}`
247
+ `Route must be registered for ${routeKey}`,
137
248
  );
249
+ pushMetric?.("manifest:validation", validationStart);
250
+
251
+ // Cache manifest for future requests in this isolate
252
+ manifestModuleCache.set(cacheKey, new Map(Store.manifest));
138
253
 
139
254
  return Store.manifest.get(routeKey)!;
140
255
  } catch (e) {
@@ -148,7 +263,7 @@ export async function loadManifest(
148
263
  routeKey,
149
264
  },
150
265
  },
151
- }
266
+ },
152
267
  );
153
268
  }
154
269
  }