@rangojs/router 0.0.0-experimental.d20dd405 → 0.0.0-experimental.d98a8e9d

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 (242) hide show
  1. package/README.md +8 -8
  2. package/dist/bin/rango.js +147 -57
  3. package/dist/testing/vitest.js +82 -0
  4. package/dist/vite/index.js +917 -500
  5. package/package.json +55 -11
  6. package/skills/api-client/SKILL.md +211 -0
  7. package/skills/bundle-analysis/SKILL.md +159 -0
  8. package/skills/cache-guide/SKILL.md +220 -30
  9. package/skills/caching/SKILL.md +116 -8
  10. package/skills/composability/SKILL.md +27 -2
  11. package/skills/document-cache/SKILL.md +78 -55
  12. package/skills/handler-use/SKILL.md +1 -1
  13. package/skills/hooks/SKILL.md +196 -21
  14. package/skills/host-router/SKILL.md +45 -20
  15. package/skills/intercept/SKILL.md +1 -4
  16. package/skills/layout/SKILL.md +4 -7
  17. package/skills/links/SKILL.md +22 -10
  18. package/skills/loader/SKILL.md +166 -23
  19. package/skills/middleware/SKILL.md +13 -9
  20. package/skills/migrate-nextjs/SKILL.md +1 -1
  21. package/skills/mime-routes/SKILL.md +27 -0
  22. package/skills/observability/SKILL.md +137 -0
  23. package/skills/parallel/SKILL.md +3 -6
  24. package/skills/prerender/SKILL.md +14 -33
  25. package/skills/rango/SKILL.md +243 -26
  26. package/skills/react-compiler/SKILL.md +168 -0
  27. package/skills/response-routes/SKILL.md +114 -47
  28. package/skills/route/SKILL.md +9 -4
  29. package/skills/router-setup/SKILL.md +3 -3
  30. package/skills/server-actions/SKILL.md +53 -41
  31. package/skills/testing/SKILL.md +128 -0
  32. package/skills/testing/bindings.md +89 -0
  33. package/skills/testing/cache-prerender.md +98 -0
  34. package/skills/testing/client-components.md +121 -0
  35. package/skills/testing/e2e-parity.md +124 -0
  36. package/skills/testing/flight.md +89 -0
  37. package/skills/testing/handles.md +127 -0
  38. package/skills/testing/loader.md +108 -0
  39. package/skills/testing/middleware.md +97 -0
  40. package/skills/testing/render-handler.md +102 -0
  41. package/skills/testing/response-routes.md +94 -0
  42. package/skills/testing/reverse-and-types.md +83 -0
  43. package/skills/testing/server-actions.md +89 -0
  44. package/skills/testing/server-tree.md +128 -0
  45. package/skills/testing/setup.md +120 -0
  46. package/skills/typesafety/SKILL.md +310 -26
  47. package/skills/use-cache/SKILL.md +34 -5
  48. package/skills/view-transitions/SKILL.md +85 -3
  49. package/src/__augment-tests__/augment.ts +81 -0
  50. package/src/__augment-tests__/augmented.check.ts +116 -0
  51. package/src/browser/action-coordinator.ts +53 -36
  52. package/src/browser/event-controller.ts +42 -66
  53. package/src/browser/history-state.ts +21 -0
  54. package/src/browser/index.ts +3 -3
  55. package/src/browser/navigation-bridge.ts +9 -67
  56. package/src/browser/navigation-client.ts +68 -83
  57. package/src/browser/navigation-store.ts +7 -8
  58. package/src/browser/navigation-transaction.ts +10 -28
  59. package/src/browser/partial-update.ts +8 -16
  60. package/src/browser/prefetch/cache.ts +58 -27
  61. package/src/browser/prefetch/fetch.ts +92 -33
  62. package/src/browser/react/NavigationProvider.tsx +55 -65
  63. package/src/browser/react/location-state-shared.ts +175 -4
  64. package/src/browser/react/location-state.ts +39 -13
  65. package/src/browser/react/use-handle.ts +17 -9
  66. package/src/browser/react/use-params.ts +3 -4
  67. package/src/browser/react/use-reverse.ts +19 -12
  68. package/src/browser/react/use-router.ts +14 -1
  69. package/src/browser/response-adapter.ts +32 -1
  70. package/src/browser/rsc-router.tsx +35 -16
  71. package/src/browser/scroll-restoration.ts +30 -25
  72. package/src/browser/segment-structure-assert.ts +2 -2
  73. package/src/browser/server-action-bridge.ts +23 -30
  74. package/src/browser/types.ts +2 -0
  75. package/src/build/collect-fallback-refs.ts +107 -0
  76. package/src/build/generate-manifest.ts +60 -35
  77. package/src/build/generate-route-types.ts +2 -0
  78. package/src/build/index.ts +8 -1
  79. package/src/build/prefix-tree-utils.ts +123 -0
  80. package/src/build/route-trie.ts +43 -0
  81. package/src/build/route-types/codegen.ts +4 -4
  82. package/src/build/route-types/include-resolution.ts +1 -1
  83. package/src/build/route-types/per-module-writer.ts +7 -4
  84. package/src/build/route-types/router-processing.ts +55 -14
  85. package/src/build/route-types/scan-filter.ts +1 -1
  86. package/src/build/route-types/source-scan.ts +118 -0
  87. package/src/build/runtime-discovery.ts +9 -20
  88. package/src/cache/cache-scope.ts +28 -42
  89. package/src/cache/cf/cf-cache-store.ts +49 -6
  90. package/src/client.tsx +9 -30
  91. package/src/context-var.ts +5 -5
  92. package/src/decode-loader-results.ts +36 -0
  93. package/src/errors.ts +30 -4
  94. package/src/handle.ts +32 -14
  95. package/src/host/index.ts +2 -2
  96. package/src/host/router.ts +129 -57
  97. package/src/host/types.ts +31 -2
  98. package/src/host/utils.ts +1 -1
  99. package/src/href-client.ts +136 -20
  100. package/src/index.rsc.ts +7 -6
  101. package/src/index.ts +14 -8
  102. package/src/loader-store.ts +500 -0
  103. package/src/loader.rsc.ts +25 -7
  104. package/src/loader.ts +16 -9
  105. package/src/missing-id-error.ts +68 -0
  106. package/src/prerender.ts +27 -6
  107. package/src/response-utils.ts +9 -0
  108. package/src/reverse.ts +16 -13
  109. package/src/route-content-wrapper.tsx +6 -28
  110. package/src/route-definition/dsl-helpers.ts +238 -263
  111. package/src/route-definition/helper-factories.ts +29 -139
  112. package/src/route-definition/helpers-types.ts +37 -14
  113. package/src/route-definition/use-item-types.ts +32 -0
  114. package/src/route-types.ts +19 -41
  115. package/src/router/basename.ts +14 -0
  116. package/src/router/content-negotiation.ts +15 -2
  117. package/src/router/error-handling.ts +1 -1
  118. package/src/router/find-match.ts +54 -6
  119. package/src/router/intercept-resolution.ts +4 -18
  120. package/src/router/lazy-includes.ts +35 -16
  121. package/src/router/loader-resolution.ts +79 -36
  122. package/src/router/manifest.ts +19 -6
  123. package/src/router/match-handlers.ts +62 -20
  124. package/src/router/match-middleware/cache-lookup.ts +44 -91
  125. package/src/router/match-middleware/cache-store.ts +3 -2
  126. package/src/router/match-result.ts +32 -30
  127. package/src/router/metrics.ts +1 -1
  128. package/src/router/middleware-types.ts +1 -1
  129. package/src/router/middleware.ts +46 -78
  130. package/src/router/pattern-matching.ts +15 -2
  131. package/src/router/prerender-match.ts +1 -1
  132. package/src/router/preview-match.ts +3 -1
  133. package/src/router/request-classification.ts +4 -28
  134. package/src/router/revalidation.ts +43 -1
  135. package/src/router/router-interfaces.ts +45 -28
  136. package/src/router/router-options.ts +40 -1
  137. package/src/router/router-registry.ts +2 -5
  138. package/src/router/segment-resolution/fresh.ts +19 -6
  139. package/src/router/segment-resolution/revalidation.ts +19 -6
  140. package/src/router/segment-resolution/view-transition-default.ts +36 -0
  141. package/src/router/telemetry.ts +99 -0
  142. package/src/router/trie-matching.ts +22 -3
  143. package/src/router/types.ts +8 -0
  144. package/src/router.ts +51 -28
  145. package/src/rsc/handler-context.ts +2 -2
  146. package/src/rsc/handler.ts +20 -65
  147. package/src/rsc/helpers.ts +22 -2
  148. package/src/rsc/index.ts +1 -1
  149. package/src/rsc/manifest-init.ts +28 -41
  150. package/src/rsc/origin-guard.ts +28 -10
  151. package/src/rsc/response-error.ts +79 -12
  152. package/src/rsc/response-route-handler.ts +43 -60
  153. package/src/rsc/rsc-rendering.ts +27 -53
  154. package/src/rsc/runtime-warnings.ts +9 -10
  155. package/src/rsc/server-action.ts +13 -37
  156. package/src/rsc/ssr-setup.ts +16 -0
  157. package/src/rsc/types.ts +2 -2
  158. package/src/runtime-env.ts +18 -0
  159. package/src/search-params.ts +4 -4
  160. package/src/segment-system.tsx +64 -49
  161. package/src/serialize.ts +243 -0
  162. package/src/server/context.ts +150 -51
  163. package/src/server/cookie-store.ts +28 -4
  164. package/src/server/request-context.ts +57 -9
  165. package/src/static-handler.ts +25 -3
  166. package/src/testing/cache-status.ts +166 -0
  167. package/src/testing/collect-handle.ts +63 -0
  168. package/src/testing/dispatch.ts +581 -0
  169. package/src/testing/dom.entry.ts +22 -0
  170. package/src/testing/e2e/fixture.ts +188 -0
  171. package/src/testing/e2e/index.ts +149 -0
  172. package/src/testing/e2e/matchers.ts +51 -0
  173. package/src/testing/e2e/page-helpers.ts +272 -0
  174. package/src/testing/e2e/parity.ts +326 -0
  175. package/src/testing/e2e/server.ts +195 -0
  176. package/src/testing/flight-matchers.ts +110 -0
  177. package/src/testing/flight-normalize.ts +38 -0
  178. package/src/testing/flight-runtime.d.ts +57 -0
  179. package/src/testing/flight-tree.ts +682 -0
  180. package/src/testing/flight.entry.ts +51 -0
  181. package/src/testing/flight.ts +234 -0
  182. package/src/testing/generated-routes.ts +223 -0
  183. package/src/testing/index.ts +106 -0
  184. package/src/testing/internal/context.ts +304 -0
  185. package/src/testing/internal/flight-client-globals.ts +30 -0
  186. package/src/testing/internal/seed-vars.ts +42 -0
  187. package/src/testing/render-handler.ts +323 -0
  188. package/src/testing/render-route.tsx +590 -0
  189. package/src/testing/run-loader.ts +363 -0
  190. package/src/testing/run-middleware.ts +205 -0
  191. package/src/testing/vitest-stubs/cloudflare-email.ts +9 -0
  192. package/src/testing/vitest-stubs/cloudflare-workers.ts +21 -0
  193. package/src/testing/vitest-stubs/plugin-rsc.ts +16 -0
  194. package/src/testing/vitest-stubs/version.ts +5 -0
  195. package/src/testing/vitest.ts +285 -0
  196. package/src/types/global-namespace.ts +39 -26
  197. package/src/types/handler-context.ts +56 -11
  198. package/src/types/index.ts +1 -0
  199. package/src/types/loader-types.ts +6 -3
  200. package/src/types/segments.ts +18 -1
  201. package/src/urls/include-helper.ts +10 -53
  202. package/src/urls/index.ts +1 -5
  203. package/src/urls/path-helper-types.ts +11 -3
  204. package/src/urls/path-helper.ts +17 -52
  205. package/src/urls/pattern-types.ts +36 -19
  206. package/src/urls/response-types.ts +20 -19
  207. package/src/urls/type-extraction.ts +58 -139
  208. package/src/urls/urls-function.ts +1 -5
  209. package/src/use-loader.tsx +413 -42
  210. package/src/vite/debug.ts +1 -0
  211. package/src/vite/discovery/bundle-postprocess.ts +6 -6
  212. package/src/vite/discovery/discover-routers.ts +75 -72
  213. package/src/vite/discovery/discovery-errors.ts +194 -0
  214. package/src/vite/discovery/prerender-collection.ts +19 -25
  215. package/src/vite/discovery/route-types-writer.ts +40 -84
  216. package/src/vite/discovery/state.ts +33 -0
  217. package/src/vite/discovery/virtual-module-codegen.ts +13 -23
  218. package/src/vite/index.ts +2 -0
  219. package/src/vite/plugin-types.ts +67 -0
  220. package/src/vite/plugins/cjs-to-esm.ts +3 -7
  221. package/src/vite/plugins/client-ref-hashing.ts +12 -1
  222. package/src/vite/plugins/cloudflare-protocol-stub.ts +1 -1
  223. package/src/vite/plugins/expose-action-id.ts +2 -2
  224. package/src/vite/plugins/expose-id-utils.ts +12 -8
  225. package/src/vite/plugins/expose-ids/export-analysis.ts +100 -20
  226. package/src/vite/plugins/expose-ids/handler-transform.ts +8 -61
  227. package/src/vite/plugins/expose-ids/loader-transform.ts +3 -5
  228. package/src/vite/plugins/expose-internal-ids.ts +47 -67
  229. package/src/vite/plugins/performance-tracks.ts +12 -16
  230. package/src/vite/plugins/use-cache-transform.ts +13 -11
  231. package/src/vite/plugins/version-injector.ts +2 -12
  232. package/src/vite/plugins/version-plugin.ts +59 -2
  233. package/src/vite/plugins/virtual-entries.ts +2 -2
  234. package/src/vite/rango.ts +67 -15
  235. package/src/vite/router-discovery.ts +208 -63
  236. package/src/vite/utils/ast-handler-extract.ts +15 -15
  237. package/src/vite/utils/bundle-analysis.ts +4 -2
  238. package/src/vite/utils/client-chunks.ts +190 -0
  239. package/src/vite/utils/forward-user-plugins.ts +193 -0
  240. package/src/vite/utils/manifest-utils.ts +8 -59
  241. package/src/vite/utils/shared-utils.ts +107 -26
  242. package/src/browser/action-response-classifier.ts +0 -99
package/src/prerender.ts CHANGED
@@ -38,6 +38,7 @@ import type { ReverseFunction } from "./reverse.js";
38
38
  import type { DefaultReverseRouteMap } from "./types/global-namespace.js";
39
39
  import type { UseItems, HandlerUseItem } from "./route-types.js";
40
40
  import { isCachedFunction } from "./cache/taint.js";
41
+ import { isUnderTestRunner } from "./runtime-env.js";
41
42
 
42
43
  // -- Named route resolution types -------------------------------------------
43
44
 
@@ -69,9 +70,9 @@ type BuildReverseFunction = [DefaultReverseRouteMap] extends [
69
70
  * Default route map for Prerender named route resolution.
70
71
  * Uses GeneratedRouteMap (from gen file) to avoid circular dependencies.
71
72
  */
72
- type DefaultPrerenderRouteMap = keyof RSCRouter.GeneratedRouteMap extends never
73
+ type DefaultPrerenderRouteMap = keyof Rango.GeneratedRouteMap extends never
73
74
  ? {}
74
- : RSCRouter.GeneratedRouteMap;
75
+ : Rango.GeneratedRouteMap;
75
76
 
76
77
  /** Extract params from a route map entry (string pattern or { path } object). */
77
78
  type ExtractParamsFromEntry<TEntry> = TEntry extends string
@@ -273,6 +274,11 @@ export interface PrerenderHandlerDefinition<
273
274
  use?: () => UseItems<HandlerUseItem>;
274
275
  }
275
276
 
277
+ // Process-stable fallback id counter (mirrors createHandle / createLoader). Only
278
+ // assigned in a bare unit test where the Vite plugin did not inject an id; never
279
+ // fires in a real build (the plugin always injects).
280
+ let runtimePrerenderIdCounter = 0;
281
+
276
282
  // -- Overloads --------------------------------------------------------------
277
283
  //
278
284
  // T accepts: named route string (global or .local) OR explicit param object.
@@ -376,12 +382,27 @@ export function Prerender<TParams extends Record<string, any>>(
376
382
  );
377
383
  }
378
384
 
379
- if (!id) {
385
+ // Throw unless under a test runner. The plugin always injects $$id for a
386
+ // supported `export const` Prerender on every build, so a missing id means
387
+ // either no plugin (a bare test — fall back below) or an UNSUPPORTED shape the
388
+ // plugin silently skipped (dev OR a real build — fail loud; a synthetic id
389
+ // would degrade to a silent prerender miss). The message is already small (no
390
+ // stack-parsing diagnostic), so it ships as-is. isUnderTestRunner() is
391
+ // runtime-safe — never a bare `process.env` access.
392
+ if (!id && !isUnderTestRunner()) {
380
393
  throw new Error(
381
- "[rsc-router] Prerender: missing $$id. " +
382
- "Ensure the exposeInternalIds Vite plugin is configured.",
394
+ "[rango] Prerender: missing $$id. Use `export const X = Prerender(...)` " +
395
+ "and ensure the exposeInternalIds Vite plugin is configured.",
383
396
  );
384
397
  }
398
+ // Under vitest with no plugin id: assign a process-stable runtime id so a
399
+ // whole-app router with Prerender routes constructs in a bare test (for
400
+ // dispatch / assertGeneratedRoutesMatch). Never reached in a real build (the
401
+ // throw above fires there); prerender storage/lookup keys on routeName +
402
+ // paramHash, never $$id (mirrors createHandle / createLoader).
403
+ if (!id) {
404
+ id = `__rango_runtime_prerender_${runtimePrerenderIdCounter++}`;
405
+ }
385
406
 
386
407
  return {
387
408
  __brand: "prerenderHandler" as const,
@@ -499,7 +520,7 @@ export function Passthrough<
499
520
  ): PassthroughHandlerDefinition<TParams, TEnv> {
500
521
  if (!isPrerenderHandler(prerenderDef)) {
501
522
  throw new Error(
502
- "[rsc-router] Passthrough: first argument must be a Prerender() definition.",
523
+ "[rango] Passthrough: first argument must be a Prerender() definition.",
503
524
  );
504
525
  }
505
526
  return {
@@ -26,3 +26,12 @@ export function isWebSocketUpgradeResponse(response: Response): boolean {
26
26
  (response as unknown as { webSocket?: unknown }).webSocket != null
27
27
  );
28
28
  }
29
+
30
+ // Location truthiness (not presence) so an empty `Location: ""` is not a redirect.
31
+ export function isRedirectResponse(response: Response): boolean {
32
+ return (
33
+ response.status >= 300 &&
34
+ response.status < 400 &&
35
+ Boolean(response.headers.get("Location"))
36
+ );
37
+ }
package/src/reverse.ts CHANGED
@@ -231,47 +231,50 @@ export type LocalReverseParams<TPattern extends string> =
231
231
  };
232
232
 
233
233
  /**
234
- * Type-safe local reverse function with dot-prefixed names only.
234
+ * Type-safe local reverse function.
235
235
  *
236
236
  * Returned by `useReverse(routes)` on the client. The route map is the
237
237
  * exposure boundary (a generated `routes` from a `urls()` module) and the
238
- * scope is implicit from that import — there is no global namespace, so
239
- * names must be dot-prefixed to mirror `ctx.reverse(".name")`.
238
+ * scope is implicit from that import. Names may be written with or without a
239
+ * leading dot — `reverse("post")` and `reverse(".post")` are identical. The dot
240
+ * is a cosmetic readability convention (and parity with `ctx.reverse(".name")`);
241
+ * there is no separate global namespace here, so it carries no meaning.
240
242
  *
241
243
  * @example
242
244
  * ```typescript
243
245
  * const reverse = useReverse(blogRoutes);
244
- * reverse(".index"); // ✓ no params
245
- * reverse(".post", { postId: "hello" }); // ✓ with params
246
- * reverse(".search", {}, { q: "hi" }); // ✓ with search schema
247
- * reverse(".typo"); // ✗ compile error
246
+ * reverse("index"); // ✓ no params (dot optional)
247
+ * reverse(".index"); // ✓ identical to the above
248
+ * reverse("post", { postId: "hello" }); // ✓ with params
249
+ * reverse("search", {}, { q: "hi" }); // ✓ with search schema
250
+ * reverse("typo"); // ✗ compile error
248
251
  * ```
249
252
  */
250
253
  export type LocalReverseFunction<TLocalRoutes> = {
251
254
  /**
252
- * Dot-prefixed local route without params
255
+ * Route without params (leading dot optional)
253
256
  */
254
257
  <TName extends keyof TLocalRoutes & string>(
255
258
  name: IsEmptyObject<
256
259
  ExtractParams<RoutePatternFor<TLocalRoutes, TName>>
257
260
  > extends true
258
- ? `.${TName}`
261
+ ? TName | `.${TName}`
259
262
  : never,
260
263
  ): string;
261
264
 
262
265
  /**
263
- * Dot-prefixed local route with params
266
+ * Route with params (leading dot optional)
264
267
  */
265
268
  <TName extends keyof TLocalRoutes & string>(
266
- name: `.${TName}`,
269
+ name: TName | `.${TName}`,
267
270
  params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
268
271
  ): string;
269
272
 
270
273
  /**
271
- * Dot-prefixed local route with params and search
274
+ * Route with params and search (leading dot optional)
272
275
  */
273
276
  <TName extends keyof TLocalRoutes & string>(
274
- name: `.${TName}`,
277
+ name: TName | `.${TName}`,
275
278
  params: LocalReverseParams<RoutePatternFor<TLocalRoutes, TName>>,
276
279
  search: ResolveSearchSchema<ExtractSearchSchema<TLocalRoutes, TName>>,
277
280
  ): string;
@@ -4,7 +4,7 @@ import { Suspense, use, useId } from "react";
4
4
  import { invariant } from "./errors";
5
5
  import { OutletProvider } from "./outlet-provider.js";
6
6
  import type { ResolvedSegment } from "./types.js";
7
- import { isLoaderDataResult } from "./types.js";
7
+ import { decodeLoaderResults } from "./decode-loader-results.js";
8
8
 
9
9
  /**
10
10
  * Stable async wrapper component for route content
@@ -26,10 +26,6 @@ export function RouteContentWrapper({
26
26
  fallback?: ReactNode;
27
27
  segmentId?: string;
28
28
  }): ReactNode {
29
- if (!content) {
30
- // Already resolved
31
- return content as ReactNode;
32
- }
33
29
  return (
34
30
  <Suspense
35
31
  fallback={fallback ?? null}
@@ -159,28 +155,10 @@ function LoaderResolver({
159
155
  ? use(loaderDataPromise)
160
156
  : loaderDataPromise;
161
157
 
162
- // Build loaderData record from resolved values
163
- const loaderData: Record<string, any> = {};
164
- let loaderErrorFallback: ReactNode = null;
165
-
166
- loaderIds.forEach((id, i) => {
167
- const result = resolvedData[i];
168
-
169
- if (isLoaderDataResult(result)) {
170
- if (result.ok) {
171
- loaderData[id] = result.data;
172
- } else {
173
- if (result.fallback) {
174
- loaderErrorFallback = result.fallback;
175
- } else {
176
- throw new Error(result.error.message);
177
- }
178
- }
179
- } else {
180
- // Legacy format - direct data
181
- loaderData[id] = result;
182
- }
183
- });
158
+ const { loaderData, errorFallback } = decodeLoaderResults(
159
+ resolvedData,
160
+ loaderIds,
161
+ );
184
162
 
185
163
  return (
186
164
  <OutletProvider
@@ -190,7 +168,7 @@ function LoaderResolver({
190
168
  parallel={parallel}
191
169
  loaderData={Object.keys(loaderData).length > 0 ? loaderData : undefined}
192
170
  >
193
- {loaderErrorFallback ?? children}
171
+ {errorFallback ?? children}
194
172
  </OutletProvider>
195
173
  );
196
174
  }