@rangojs/router 0.0.0-experimental.a769fbe7 → 0.0.0-experimental.ac99d918
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.
- package/README.md +211 -43
- package/dist/bin/rango.js +279 -102
- package/dist/testing/vitest.js +82 -0
- package/dist/vite/index.js +3313 -1160
- package/dist/vite/index.js.bak +5448 -0
- package/dist/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
- package/package.json +62 -11
- package/skills/api-client/SKILL.md +211 -0
- package/skills/breadcrumbs/SKILL.md +63 -1
- package/skills/bundle-analysis/SKILL.md +159 -0
- package/skills/cache-guide/SKILL.md +222 -30
- package/skills/caching/SKILL.md +263 -8
- package/skills/composability/SKILL.md +27 -2
- package/skills/css/SKILL.md +76 -0
- package/skills/document-cache/SKILL.md +78 -55
- package/skills/handler-use/SKILL.md +364 -0
- package/skills/hooks/SKILL.md +250 -30
- package/skills/host-router/SKILL.md +124 -22
- package/skills/i18n/SKILL.md +276 -0
- package/skills/intercept/SKILL.md +49 -5
- package/skills/layout/SKILL.md +35 -9
- package/skills/links/SKILL.md +249 -17
- package/skills/loader/SKILL.md +223 -9
- package/skills/middleware/SKILL.md +52 -13
- package/skills/migrate-nextjs/SKILL.md +584 -0
- package/skills/migrate-react-router/SKILL.md +769 -0
- package/skills/mime-routes/SKILL.md +27 -0
- package/skills/observability/SKILL.md +137 -0
- package/skills/parallel/SKILL.md +77 -7
- package/skills/prerender/SKILL.md +123 -100
- package/skills/rango/SKILL.md +250 -22
- package/skills/react-compiler/SKILL.md +168 -0
- package/skills/response-routes/SKILL.md +122 -47
- package/skills/route/SKILL.md +66 -5
- package/skills/router-setup/SKILL.md +38 -3
- package/skills/server-actions/SKILL.md +775 -0
- package/skills/streams-and-websockets/SKILL.md +283 -0
- package/skills/tailwind/SKILL.md +27 -3
- package/skills/testing/SKILL.md +129 -0
- package/skills/testing/bindings.md +89 -0
- package/skills/testing/cache-prerender.md +124 -0
- package/skills/testing/client-components.md +122 -0
- package/skills/testing/e2e-parity.md +125 -0
- package/skills/testing/flight.md +92 -0
- package/skills/testing/handles.md +129 -0
- package/skills/testing/loader.md +128 -0
- package/skills/testing/middleware.md +99 -0
- package/skills/testing/render-handler.md +121 -0
- package/skills/testing/response-routes.md +95 -0
- package/skills/testing/reverse-and-types.md +84 -0
- package/skills/testing/server-actions.md +107 -0
- package/skills/testing/server-tree.md +128 -0
- package/skills/testing/setup.md +120 -0
- package/skills/typesafety/SKILL.md +319 -27
- package/skills/use-cache/SKILL.md +36 -5
- package/skills/vercel/SKILL.md +107 -0
- package/skills/view-transitions/SKILL.md +294 -0
- package/src/__augment-tests__/augment.ts +81 -0
- package/src/__augment-tests__/augmented.check.ts +116 -0
- package/src/__internal.ts +1 -66
- package/src/browser/action-coordinator.ts +53 -36
- package/src/browser/action-fence.ts +47 -0
- package/src/browser/app-shell.ts +39 -0
- package/src/browser/app-version.ts +14 -0
- package/src/browser/cookie-name.ts +140 -0
- package/src/browser/event-controller.ts +81 -147
- package/src/browser/history-state.ts +21 -0
- package/src/browser/index.ts +3 -3
- package/src/browser/invalidate-client-cache.ts +52 -0
- package/src/browser/navigation-bridge.ts +66 -14
- package/src/browser/navigation-client.ts +172 -109
- package/src/browser/navigation-store-handle.ts +38 -0
- package/src/browser/navigation-store.ts +76 -67
- package/src/browser/navigation-transaction.ts +9 -59
- package/src/browser/partial-update.ts +79 -93
- package/src/browser/prefetch/cache.ts +180 -62
- package/src/browser/prefetch/fetch.ts +252 -39
- package/src/browser/prefetch/queue.ts +42 -8
- package/src/browser/rango-state.ts +158 -76
- package/src/browser/react/Link.tsx +72 -10
- package/src/browser/react/NavigationProvider.tsx +83 -31
- package/src/browser/react/ScrollRestoration.tsx +10 -6
- package/src/browser/react/context.ts +7 -2
- package/src/browser/react/filter-segment-order.ts +49 -7
- package/src/browser/react/index.ts +0 -48
- package/src/browser/react/location-state-shared.ts +166 -8
- package/src/browser/react/location-state.ts +39 -14
- package/src/browser/react/use-action.ts +6 -15
- package/src/browser/react/use-handle.ts +23 -69
- package/src/browser/react/use-link-status.ts +0 -4
- package/src/browser/react/use-navigation.ts +22 -5
- package/src/browser/react/use-params.ts +20 -10
- package/src/browser/react/use-reverse.ts +106 -0
- package/src/browser/react/use-router.ts +46 -11
- package/src/browser/react/use-search-params.ts +0 -5
- package/src/browser/react/use-segments.ts +11 -21
- package/src/browser/response-adapter.ts +52 -1
- package/src/browser/rsc-router.tsx +111 -24
- package/src/browser/scroll-restoration.ts +29 -19
- package/src/browser/segment-reconciler.ts +36 -14
- package/src/browser/segment-structure-assert.ts +2 -2
- package/src/browser/server-action-bridge.ts +176 -62
- package/src/browser/types.ts +60 -11
- package/src/browser/validate-redirect-origin.ts +43 -16
- package/src/build/collect-fallback-refs.ts +107 -0
- package/src/build/generate-manifest.ts +65 -40
- package/src/build/generate-route-types.ts +6 -0
- package/src/build/index.ts +8 -2
- package/src/build/prefix-tree-utils.ts +123 -0
- package/src/build/route-trie.ts +137 -32
- package/src/build/route-types/codegen.ts +4 -4
- package/src/build/route-types/include-resolution.ts +9 -2
- package/src/build/route-types/param-extraction.ts +6 -3
- package/src/build/route-types/per-module-writer.ts +7 -4
- package/src/build/route-types/router-processing.ts +333 -94
- package/src/build/route-types/scan-filter.ts +9 -2
- package/src/build/route-types/source-scan.ts +118 -0
- package/src/build/runtime-discovery.ts +9 -20
- package/src/cache/cache-error.ts +104 -0
- package/src/cache/cache-policy.ts +68 -28
- package/src/cache/cache-runtime.ts +134 -32
- package/src/cache/cache-scope.ts +100 -74
- package/src/cache/cache-tag.ts +98 -0
- package/src/cache/cf/cf-cache-store.ts +2256 -241
- package/src/cache/cf/index.ts +6 -16
- package/src/cache/document-cache.ts +61 -20
- package/src/cache/handle-snapshot.ts +63 -0
- package/src/cache/index.ts +22 -20
- package/src/cache/memory-segment-store.ts +136 -37
- package/src/cache/profile-registry.ts +6 -30
- package/src/cache/read-through-swr.ts +41 -11
- package/src/cache/segment-codec.ts +0 -16
- package/src/cache/tag-invalidation.ts +230 -0
- package/src/cache/types.ts +33 -100
- package/src/cache/vercel/index.ts +11 -0
- package/src/cache/vercel/vercel-cache-store.ts +799 -0
- package/src/client.rsc.tsx +6 -21
- package/src/client.tsx +108 -290
- package/src/component-utils.ts +19 -0
- package/src/context-var.ts +17 -5
- package/src/decode-loader-results.ts +36 -0
- package/src/defer.ts +196 -0
- package/src/deps/browser.ts +0 -1
- package/src/deps/ssr.ts +0 -1
- package/src/errors.ts +30 -4
- package/src/handle.ts +70 -22
- package/src/handles/MetaTags.tsx +0 -14
- package/src/handles/breadcrumbs.ts +16 -5
- package/src/handles/meta.ts +0 -39
- package/src/host/cookie-handler.ts +0 -36
- package/src/host/errors.ts +0 -24
- package/src/host/index.ts +8 -2
- package/src/host/pattern-matcher.ts +7 -50
- package/src/host/router.ts +107 -99
- package/src/host/testing.ts +40 -27
- package/src/host/types.ts +37 -4
- package/src/host/utils.ts +1 -1
- package/src/href-client.ts +137 -22
- package/src/index.rsc.ts +69 -10
- package/src/index.ts +112 -14
- package/src/internal-debug.ts +2 -4
- package/src/loader-store.ts +500 -0
- package/src/loader.rsc.ts +20 -13
- package/src/loader.ts +12 -11
- package/src/missing-id-error.ts +68 -0
- package/src/network-error-thrower.tsx +1 -6
- package/src/outlet-context.ts +1 -1
- package/src/outlet-provider.tsx +1 -5
- package/src/prerender/param-hash.ts +10 -11
- package/src/prerender/store.ts +37 -41
- package/src/prerender.ts +198 -82
- package/src/redirect-origin.ts +100 -0
- package/src/response-utils.ts +37 -0
- package/src/reverse.ts +65 -15
- package/src/root-error-boundary.tsx +1 -19
- package/src/route-content-wrapper.tsx +7 -72
- package/src/route-definition/dsl-helpers.ts +413 -275
- package/src/route-definition/helper-factories.ts +29 -139
- package/src/route-definition/helpers-types.ts +107 -32
- package/src/route-definition/index.ts +3 -0
- package/src/route-definition/redirect.ts +50 -8
- package/src/route-definition/resolve-handler-use.ts +161 -0
- package/src/route-definition/use-item-types.ts +32 -0
- package/src/route-map-builder.ts +0 -16
- package/src/route-types.ts +37 -41
- package/src/router/basename.ts +14 -0
- package/src/router/content-negotiation.ts +108 -9
- package/src/router/error-handling.ts +13 -17
- package/src/router/find-match.ts +44 -23
- package/src/router/handler-context.ts +46 -30
- package/src/router/intercept-resolution.ts +23 -23
- package/src/router/lazy-includes.ts +15 -52
- package/src/router/loader-resolution.ts +207 -30
- package/src/router/logging.ts +0 -6
- package/src/router/manifest.ts +40 -42
- package/src/router/match-api.ts +120 -204
- package/src/router/match-context.ts +0 -22
- package/src/router/match-handlers.ts +58 -58
- package/src/router/match-middleware/background-revalidation.ts +0 -7
- package/src/router/match-middleware/cache-lookup.ts +161 -262
- package/src/router/match-middleware/cache-store.ts +3 -33
- package/src/router/match-middleware/intercept-resolution.ts +0 -22
- package/src/router/match-middleware/segment-resolution.ts +45 -14
- package/src/router/match-pipelines.ts +1 -42
- package/src/router/match-result.ts +87 -39
- package/src/router/metrics.ts +0 -34
- package/src/router/middleware-types.ts +7 -140
- package/src/router/middleware.ts +169 -140
- package/src/router/navigation-snapshot.ts +131 -0
- package/src/router/params-util.ts +23 -0
- package/src/router/pattern-matching.ts +109 -63
- package/src/router/prerender-match.ts +190 -54
- package/src/router/preview-match.ts +32 -102
- package/src/router/request-classification.ts +276 -0
- package/src/router/revalidation.ts +63 -55
- package/src/router/route-snapshot.ts +244 -0
- package/src/router/router-context.ts +0 -27
- package/src/router/router-interfaces.ts +100 -35
- package/src/router/router-options.ts +91 -11
- package/src/router/router-registry.ts +2 -5
- package/src/router/segment-resolution/fresh.ts +119 -65
- package/src/router/segment-resolution/helpers.ts +34 -0
- package/src/router/segment-resolution/loader-cache.ts +40 -37
- package/src/router/segment-resolution/revalidation.ts +329 -305
- package/src/router/segment-resolution/static-store.ts +19 -5
- package/src/router/segment-resolution/streamed-handler-telemetry.ts +52 -0
- package/src/router/segment-resolution/view-transition-default.ts +36 -0
- package/src/router/segment-resolution.ts +4 -1
- package/src/router/segment-wrappers.ts +0 -3
- package/src/router/state-cookie-name.ts +33 -0
- package/src/router/substitute-pattern-params.ts +56 -0
- package/src/router/telemetry-otel.ts +0 -20
- package/src/router/telemetry.ts +96 -19
- package/src/router/timeout.ts +0 -20
- package/src/router/trie-matching.ts +91 -46
- package/src/router/types.ts +9 -63
- package/src/router/url-params.ts +44 -0
- package/src/router.ts +128 -42
- package/src/rsc/handler-context.ts +3 -2
- package/src/rsc/handler.ts +492 -409
- package/src/rsc/helpers.ts +162 -46
- package/src/rsc/index.ts +1 -1
- package/src/rsc/json-route-result.ts +38 -0
- package/src/rsc/loader-fetch.ts +18 -3
- package/src/rsc/manifest-init.ts +33 -42
- package/src/rsc/origin-guard.ts +39 -25
- package/src/rsc/progressive-enhancement.ts +28 -4
- package/src/rsc/redirect-guard.ts +99 -0
- package/src/rsc/response-error.ts +79 -12
- package/src/rsc/response-route-handler.ts +90 -63
- package/src/rsc/rsc-rendering.ts +53 -56
- package/src/rsc/runtime-warnings.ts +23 -10
- package/src/rsc/server-action.ts +74 -69
- package/src/rsc/ssr-setup.ts +18 -2
- package/src/rsc/types.ts +22 -9
- package/src/runtime-env.ts +18 -0
- package/src/search-params.ts +4 -20
- package/src/segment-content-promise.ts +67 -0
- package/src/segment-loader-promise.ts +134 -0
- package/src/segment-system.tsx +208 -201
- package/src/serialize.ts +243 -0
- package/src/server/context.ts +211 -52
- package/src/server/cookie-store.ts +80 -5
- package/src/server/handle-store.ts +26 -24
- package/src/server/loader-registry.ts +10 -28
- package/src/server/request-context.ts +289 -124
- package/src/ssr/index.tsx +22 -15
- package/src/static-handler.ts +27 -18
- package/src/testing/cache-status.ts +162 -0
- package/src/testing/collect-handle.ts +40 -0
- package/src/testing/dispatch.ts +618 -0
- package/src/testing/dom.entry.ts +22 -0
- package/src/testing/e2e/fixture.ts +188 -0
- package/src/testing/e2e/index.ts +128 -0
- package/src/testing/e2e/matchers.ts +35 -0
- package/src/testing/e2e/page-helpers.ts +272 -0
- package/src/testing/e2e/parity.ts +387 -0
- package/src/testing/e2e/server.ts +195 -0
- package/src/testing/flight-matchers.ts +97 -0
- package/src/testing/flight-normalize.ts +11 -0
- package/src/testing/flight-runtime.d.ts +57 -0
- package/src/testing/flight-tree.ts +682 -0
- package/src/testing/flight.entry.ts +52 -0
- package/src/testing/flight.ts +232 -0
- package/src/testing/generated-routes.ts +183 -0
- package/src/testing/index.ts +99 -0
- package/src/testing/internal/context.ts +348 -0
- package/src/testing/internal/flight-client-globals.ts +30 -0
- package/src/testing/internal/seed-vars.ts +54 -0
- package/src/testing/render-handler.ts +330 -0
- package/src/testing/render-route.tsx +566 -0
- package/src/testing/run-loader.ts +378 -0
- package/src/testing/run-middleware.ts +205 -0
- package/src/testing/vitest-stubs/cloudflare-email.ts +9 -0
- package/src/testing/vitest-stubs/cloudflare-workers.ts +21 -0
- package/src/testing/vitest-stubs/plugin-rsc.ts +16 -0
- package/src/testing/vitest-stubs/version.ts +5 -0
- package/src/testing/vitest.ts +305 -0
- package/src/theme/ThemeProvider.tsx +0 -52
- package/src/theme/ThemeScript.tsx +0 -6
- package/src/theme/constants.ts +0 -12
- package/src/theme/index.ts +0 -7
- package/src/theme/theme-context.ts +1 -5
- package/src/theme/theme-script.ts +0 -14
- package/src/theme/use-theme.ts +0 -3
- package/src/types/boundaries.ts +0 -35
- package/src/types/cache-types.ts +17 -8
- package/src/types/error-types.ts +30 -90
- package/src/types/global-namespace.ts +54 -41
- package/src/types/handler-context.ts +124 -70
- package/src/types/index.ts +1 -10
- package/src/types/loader-types.ts +40 -11
- package/src/types/request-scope.ts +107 -0
- package/src/types/route-config.ts +6 -50
- package/src/types/route-entry.ts +12 -7
- package/src/types/segments.ts +36 -15
- package/src/urls/include-helper.ts +33 -70
- package/src/urls/index.ts +1 -11
- package/src/urls/path-helper-types.ts +58 -11
- package/src/urls/path-helper.ts +57 -111
- package/src/urls/pattern-types.ts +48 -19
- package/src/urls/response-types.ts +25 -22
- package/src/urls/type-extraction.ts +58 -139
- package/src/urls/urls-function.ts +1 -18
- package/src/use-loader.tsx +346 -89
- package/src/vite/debug.ts +185 -0
- package/src/vite/discovery/bundle-postprocess.ts +36 -38
- package/src/vite/discovery/discover-routers.ts +130 -85
- package/src/vite/discovery/discovery-errors.ts +194 -0
- package/src/vite/discovery/gate-state.ts +171 -0
- package/src/vite/discovery/prerender-collection.ts +192 -99
- package/src/vite/discovery/route-types-writer.ts +40 -84
- package/src/vite/discovery/self-gen-tracking.ts +27 -1
- package/src/vite/discovery/state.ts +51 -4
- package/src/vite/discovery/virtual-module-codegen.ts +14 -34
- package/src/vite/index.ts +8 -0
- package/src/vite/plugin-types.ts +236 -6
- package/src/vite/plugins/cjs-to-esm.ts +8 -18
- package/src/vite/plugins/client-ref-dedup.ts +16 -11
- package/src/vite/plugins/client-ref-hashing.ts +28 -15
- package/src/vite/plugins/cloudflare-protocol-loader-hook.d.mts +23 -0
- package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
- package/src/vite/plugins/cloudflare-protocol-stub.ts +194 -0
- package/src/vite/plugins/expose-action-id.ts +48 -95
- package/src/vite/plugins/expose-id-utils.ts +11 -50
- package/src/vite/plugins/expose-ids/export-analysis.ts +76 -34
- package/src/vite/plugins/expose-ids/handler-transform.ts +10 -48
- package/src/vite/plugins/expose-ids/loader-transform.ts +3 -20
- package/src/vite/plugins/expose-ids/router-transform.ts +20 -16
- package/src/vite/plugins/expose-internal-ids.ts +554 -317
- package/src/vite/plugins/performance-tracks.ts +65 -207
- package/src/vite/plugins/refresh-cmd.ts +89 -27
- package/src/vite/plugins/use-cache-transform.ts +73 -83
- package/src/vite/plugins/vercel-output.ts +258 -0
- package/src/vite/plugins/version-injector.ts +21 -25
- package/src/vite/plugins/version-plugin.ts +32 -23
- package/src/vite/plugins/virtual-entries.ts +46 -17
- package/src/vite/rango.ts +207 -125
- package/src/vite/router-discovery.ts +931 -133
- package/src/vite/utils/ast-handler-extract.ts +15 -31
- package/src/vite/utils/banner.ts +1 -1
- package/src/vite/utils/bundle-analysis.ts +10 -15
- package/src/vite/utils/client-chunks.ts +184 -0
- package/src/vite/utils/forward-user-plugins.ts +171 -0
- package/src/vite/utils/manifest-utils.ts +4 -59
- package/src/vite/utils/package-resolution.ts +20 -52
- package/src/vite/utils/prerender-utils.ts +27 -29
- package/src/vite/utils/shared-utils.ts +97 -44
- package/src/browser/action-response-classifier.ts +0 -99
- package/src/browser/debug-channel.ts +0 -93
- package/src/browser/react/use-client-cache.ts +0 -58
- package/src/browser/shallow.ts +0 -40
- package/src/handles/index.ts +0 -7
- package/src/router/middleware-cookies.ts +0 -55
|
@@ -1,25 +1,72 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Prefetch Cache
|
|
3
3
|
*
|
|
4
|
-
* In-memory cache storing
|
|
5
|
-
* on subsequent navigation.
|
|
6
|
-
*
|
|
7
|
-
*
|
|
4
|
+
* In-memory cache storing eagerly-decoded prefetch payloads for instant,
|
|
5
|
+
* already-warm cache hits on subsequent navigation. A prefetch fetches the
|
|
6
|
+
* RSC partial AND decodes it (createFromFetch) up front — decoding the Flight
|
|
7
|
+
* stream resolves the route's client references, so the route's JS chunks are
|
|
8
|
+
* imported during prefetch rather than on click. The decoded payload is reused
|
|
9
|
+
* verbatim by navigation, so a prefetched click loads no new code. Two key
|
|
10
|
+
* scopes are in play:
|
|
11
|
+
* - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
|
|
12
|
+
* shape `rangoState\0/target?...`. Shared across all source pages and
|
|
13
|
+
* invalidated automatically when Rango state bumps (deploy or
|
|
14
|
+
* server-action invalidation).
|
|
15
|
+
* - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
|
|
16
|
+
* — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
|
|
17
|
+
* (so rotation invalidates source-scoped entries too) plus the source
|
|
18
|
+
* href (so each originating page gets its own slot). Populated when the
|
|
19
|
+
* server tags a response with `X-RSC-Prefetch-Scope: source` (intercept
|
|
20
|
+
* modals etc.), OR when a Link opts in with `prefetchKey=":source"` — in
|
|
21
|
+
* both cases so source-sensitive responses cannot bleed into navigations
|
|
22
|
+
* from other pages.
|
|
8
23
|
*
|
|
9
24
|
* Also tracks in-flight prefetch promises. Each promise resolves to the
|
|
10
|
-
*
|
|
11
|
-
* still-downloading prefetch without
|
|
25
|
+
* decoded prefetch entry (or null), letting navigation adopt a
|
|
26
|
+
* still-downloading prefetch without issuing a duplicate request. A
|
|
27
|
+
* single promise can be registered under multiple alias keys (see
|
|
28
|
+
* `setInflightPromiseWithAliases`) so same-source navigations adopt via
|
|
29
|
+
* their source key while cross-source ones fall through to the wildcard
|
|
30
|
+
* alias — with consume/clear atomically removing every alias.
|
|
12
31
|
*
|
|
13
32
|
* Replaces the previous browser HTTP cache approach which was unreliable
|
|
14
33
|
* due to response draining race conditions and browser inconsistencies.
|
|
34
|
+
*
|
|
35
|
+
* State here lives in module-level singletons (cache, inflight, generation,
|
|
36
|
+
* cacheTTL, etc.) rather than a per-instance factory. This is correct because
|
|
37
|
+
* exactly one router is live per document — an SPA navigation crossing a
|
|
38
|
+
* host-router boundary forces a full document reload — so the singletons are
|
|
39
|
+
* effectively per-document. Unit tests reset them via clearPrefetchCache().
|
|
15
40
|
*/
|
|
16
41
|
|
|
17
42
|
import { abortAllPrefetches } from "./queue.js";
|
|
18
43
|
import { invalidateRangoState } from "../rango-state.js";
|
|
44
|
+
import type { RscPayload } from "../types.js";
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* A prefetch that has been fetched AND eagerly decoded. Storing the decoded
|
|
48
|
+
* payload (not the raw Response) is what makes a prefetched navigation "warm":
|
|
49
|
+
* decoding the Flight stream during prefetch pulls the route's client chunks,
|
|
50
|
+
* so the click reuses ready elements and loads no new JS.
|
|
51
|
+
*/
|
|
52
|
+
export interface DecodedPrefetch {
|
|
53
|
+
/** The eagerly-decoded RSC payload. Reused verbatim by navigation. */
|
|
54
|
+
payload: Promise<RscPayload>;
|
|
55
|
+
/**
|
|
56
|
+
* Resolves when the underlying RSC stream finishes draining. Navigation
|
|
57
|
+
* forwards this as its streamComplete so scroll/revalidation gating is
|
|
58
|
+
* unchanged from the fresh-fetch path.
|
|
59
|
+
*/
|
|
60
|
+
streamComplete: Promise<void>;
|
|
61
|
+
/**
|
|
62
|
+
* Prefetch scope as tagged by the server via `X-RSC-Prefetch-Scope`.
|
|
63
|
+
* `"source"` means the response is source-page-sensitive and must not be
|
|
64
|
+
* reused by a navigation from a different page — navigation enforces this
|
|
65
|
+
* when it adopted an inflight entry through the wildcard key.
|
|
66
|
+
*/
|
|
67
|
+
scope: "source" | "wildcard";
|
|
68
|
+
}
|
|
19
69
|
|
|
20
|
-
// Default TTL: 5 minutes. Overridden by initPrefetchCache() with
|
|
21
|
-
// the server-configured prefetchCacheTTL from router options.
|
|
22
|
-
// 0 disables the in-memory cache entirely.
|
|
23
70
|
let cacheTTL = 300_000;
|
|
24
71
|
|
|
25
72
|
/**
|
|
@@ -41,33 +88,73 @@ export function isPrefetchCacheDisabled(): boolean {
|
|
|
41
88
|
const MAX_PREFETCH_CACHE_SIZE = 50;
|
|
42
89
|
|
|
43
90
|
interface PrefetchCacheEntry {
|
|
44
|
-
|
|
91
|
+
entry: DecodedPrefetch;
|
|
45
92
|
timestamp: number;
|
|
46
93
|
}
|
|
47
94
|
|
|
48
95
|
const cache = new Map<string, PrefetchCacheEntry>();
|
|
49
96
|
const inflight = new Set<string>();
|
|
50
97
|
|
|
98
|
+
const inflightPromises = new Map<string, Promise<DecodedPrefetch | null>>();
|
|
99
|
+
|
|
100
|
+
const inflightAliases = new Map<string, string[]>();
|
|
101
|
+
|
|
102
|
+
const adoptedKeys = new Set<string>();
|
|
103
|
+
|
|
104
|
+
let generation = 0;
|
|
105
|
+
|
|
51
106
|
/**
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
107
|
+
* Build a cache key by combining a scope prefix with the target URL.
|
|
108
|
+
*
|
|
109
|
+
* Low-level primitive — callers that want a specific scope should use
|
|
110
|
+
* one of:
|
|
111
|
+
* - Wildcard (source-agnostic): prefix is the Rango state value from
|
|
112
|
+
* `getRangoState()`. Shared across all source pages. Invalidated
|
|
113
|
+
* automatically when Rango state bumps (deploy or server-action).
|
|
114
|
+
* Key shape: `rangoState\0/target?...`.
|
|
115
|
+
* - Source-scoped: use `buildSourceKey()`. Key shape:
|
|
116
|
+
* `rangoState\0sourceHref\0/target?...` — embeds the Rango state so
|
|
117
|
+
* rotation invalidates source-scoped entries alongside wildcard ones,
|
|
118
|
+
* plus the source page href so the key is unique per originating page.
|
|
119
|
+
* Populated either when the server tags a response with
|
|
120
|
+
* `X-RSC-Prefetch-Scope: source` (intercept modals, etc.) or when a
|
|
121
|
+
* Link opts in via `prefetchKey=":source"`.
|
|
122
|
+
*
|
|
123
|
+
* The `_rsc_segments` query param that travels in the target URL means
|
|
124
|
+
* clients with different mounted segment trees naturally get different
|
|
125
|
+
* keys — so segment-level diffs remain consistent across both scopes.
|
|
55
126
|
*/
|
|
56
|
-
|
|
127
|
+
export function buildPrefetchKey(prefix: string, targetUrl: URL): string {
|
|
128
|
+
return prefix + "\0" + targetUrl.pathname + targetUrl.search;
|
|
129
|
+
}
|
|
57
130
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
131
|
+
/**
|
|
132
|
+
* Build a source-scoped cache key. Key shape:
|
|
133
|
+
* `rangoState\0sourceHref\0/target?...`.
|
|
134
|
+
*
|
|
135
|
+
* - `rangoState` is included so state rotation invalidates source-scoped
|
|
136
|
+
* entries alongside wildcard ones.
|
|
137
|
+
* - `sourceHref` makes the key unique per originating page.
|
|
138
|
+
*/
|
|
139
|
+
export function buildSourceKey(
|
|
140
|
+
rangoState: string,
|
|
141
|
+
sourceHref: string,
|
|
142
|
+
targetUrl: URL,
|
|
143
|
+
): string {
|
|
144
|
+
return buildPrefetchKey(rangoState + "\0" + sourceHref, targetUrl);
|
|
145
|
+
}
|
|
62
146
|
|
|
63
147
|
/**
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
* different pages gets separate entries — the server response varies
|
|
67
|
-
* based on the source page context (diff-based rendering).
|
|
148
|
+
* Walk an inflight key plus any sibling aliases registered via
|
|
149
|
+
* `setInflightPromiseWithAliases`, invoking `fn` for each.
|
|
68
150
|
*/
|
|
69
|
-
|
|
70
|
-
|
|
151
|
+
function forEachAlias(key: string, fn: (k: string) => void): void {
|
|
152
|
+
const aliases = inflightAliases.get(key);
|
|
153
|
+
if (aliases) {
|
|
154
|
+
for (const k of aliases) fn(k);
|
|
155
|
+
} else {
|
|
156
|
+
fn(key);
|
|
157
|
+
}
|
|
71
158
|
}
|
|
72
159
|
|
|
73
160
|
/**
|
|
@@ -86,14 +173,14 @@ export function hasPrefetch(key: string): boolean {
|
|
|
86
173
|
}
|
|
87
174
|
|
|
88
175
|
/**
|
|
89
|
-
* Consume a cached prefetch
|
|
90
|
-
* One-time consumption: the entry is deleted after retrieval.
|
|
176
|
+
* Consume a cached, eagerly-decoded prefetch. Returns null if not found or
|
|
177
|
+
* expired. One-time consumption: the entry is deleted after retrieval.
|
|
91
178
|
* Returns null when caching is disabled (TTL <= 0).
|
|
92
179
|
*
|
|
93
180
|
* Does NOT check in-flight prefetches — use consumeInflightPrefetch()
|
|
94
|
-
* for that (returns a Promise instead of a
|
|
181
|
+
* for that (returns a Promise instead of a resolved entry).
|
|
95
182
|
*/
|
|
96
|
-
export function consumePrefetch(key: string):
|
|
183
|
+
export function consumePrefetch(key: string): DecodedPrefetch | null {
|
|
97
184
|
if (cacheTTL <= 0) return null;
|
|
98
185
|
const entry = cache.get(key);
|
|
99
186
|
if (!entry) return null;
|
|
@@ -102,52 +189,72 @@ export function consumePrefetch(key: string): Response | null {
|
|
|
102
189
|
return null;
|
|
103
190
|
}
|
|
104
191
|
cache.delete(key);
|
|
105
|
-
return entry.
|
|
192
|
+
return entry.entry;
|
|
106
193
|
}
|
|
107
194
|
|
|
108
195
|
/**
|
|
109
196
|
* Consume an in-flight prefetch promise. Returns null if no prefetch is
|
|
110
|
-
* in-flight for this key. The returned Promise resolves to the
|
|
111
|
-
*
|
|
197
|
+
* in-flight for this key. The returned Promise resolves to the decoded
|
|
198
|
+
* prefetch entry (or null if the fetch failed/was aborted, or carried a
|
|
199
|
+
* control header the navigation must re-fetch to honor).
|
|
112
200
|
*
|
|
113
|
-
* One-time consumption: the promise entry is removed
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
*
|
|
201
|
+
* One-time consumption: the promise entry is removed (along with any
|
|
202
|
+
* sibling aliases registered via `setInflightPromiseWithAliases`) so a
|
|
203
|
+
* second call on any alias returns null — only one caller can adopt the
|
|
204
|
+
* shared Response stream. The `inflight` set entry is intentionally
|
|
205
|
+
* kept so that `hasPrefetch()` continues to return true while the
|
|
206
|
+
* underlying fetch is still downloading — this prevents
|
|
207
|
+
* `prefetchDirect()` or other callers from starting a duplicate request
|
|
208
|
+
* during the handoff window. The inflight flag is cleaned up naturally
|
|
209
|
+
* by `clearPrefetchInflight()` in the fetch's `.finally()`.
|
|
120
210
|
*/
|
|
121
211
|
export function consumeInflightPrefetch(
|
|
122
212
|
key: string,
|
|
123
|
-
): Promise<
|
|
213
|
+
): Promise<DecodedPrefetch | null> | null {
|
|
124
214
|
const promise = inflightPromises.get(key);
|
|
125
215
|
if (!promise) return null;
|
|
126
|
-
// Remove the promise
|
|
127
|
-
|
|
216
|
+
// Remove the promise under every alias so a second consumer cannot
|
|
217
|
+
// adopt the same stream and race on the body, and mark every alias as
|
|
218
|
+
// adopted so the pending `storePrefetch` (which resolves later, after this
|
|
219
|
+
// adoption) does not leave the now-owned, single-use entry in the cache map.
|
|
220
|
+
// `inflightAliases` is intentionally preserved — `clearPrefetchInflight()` in
|
|
221
|
+
// the fetch's `.finally()` still needs it to clear every inflight flag and
|
|
222
|
+
// adopted marker; deleting here would strand the sibling's flag forever.
|
|
223
|
+
forEachAlias(key, (k) => {
|
|
224
|
+
inflightPromises.delete(k);
|
|
225
|
+
adoptedKeys.add(k);
|
|
226
|
+
});
|
|
128
227
|
return promise;
|
|
129
228
|
}
|
|
130
229
|
|
|
131
230
|
/**
|
|
132
|
-
* Store
|
|
133
|
-
* The response should be a clone() of the original so the caller can
|
|
134
|
-
* still consume the body. The clone's body streams independently.
|
|
231
|
+
* Store an eagerly-decoded prefetch in the in-memory cache.
|
|
135
232
|
*
|
|
136
233
|
* Skips storage if the generation has changed since the fetch started
|
|
137
234
|
* (a server action invalidated the cache mid-flight).
|
|
138
235
|
*/
|
|
139
236
|
export function storePrefetch(
|
|
140
237
|
key: string,
|
|
141
|
-
|
|
238
|
+
entry: DecodedPrefetch,
|
|
142
239
|
fetchGeneration: number,
|
|
143
240
|
): void {
|
|
144
241
|
if (cacheTTL <= 0) return;
|
|
145
242
|
if (fetchGeneration !== generation) return;
|
|
146
243
|
|
|
244
|
+
// If a navigation already adopted this prefetch's in-flight promise, it owns
|
|
245
|
+
// the single-use entry (and has drained its handle generator). Do NOT also
|
|
246
|
+
// publish it to the cache map, or a later navigation would be served the
|
|
247
|
+
// exhausted entry and lose that route's handles. Clear the marker (under all
|
|
248
|
+
// aliases) now that the decision is made.
|
|
249
|
+
if (adoptedKeys.has(key)) {
|
|
250
|
+
forEachAlias(key, (k) => adoptedKeys.delete(k));
|
|
251
|
+
return;
|
|
252
|
+
}
|
|
253
|
+
|
|
147
254
|
// Evict expired entries
|
|
148
255
|
const now = Date.now();
|
|
149
|
-
for (const [k,
|
|
150
|
-
if (now -
|
|
256
|
+
for (const [k, cached] of cache) {
|
|
257
|
+
if (now - cached.timestamp > cacheTTL) {
|
|
151
258
|
cache.delete(k);
|
|
152
259
|
}
|
|
153
260
|
}
|
|
@@ -158,7 +265,7 @@ export function storePrefetch(
|
|
|
158
265
|
if (oldest) cache.delete(oldest);
|
|
159
266
|
}
|
|
160
267
|
|
|
161
|
-
cache.set(key, {
|
|
268
|
+
cache.set(key, { entry, timestamp: now });
|
|
162
269
|
}
|
|
163
270
|
|
|
164
271
|
/**
|
|
@@ -173,33 +280,44 @@ export function markPrefetchInflight(key: string): void {
|
|
|
173
280
|
inflight.add(key);
|
|
174
281
|
}
|
|
175
282
|
|
|
176
|
-
/**
|
|
177
|
-
* Store the in-flight Promise for a prefetch so navigation can reuse it.
|
|
178
|
-
*/
|
|
179
283
|
export function setInflightPromise(
|
|
180
284
|
key: string,
|
|
181
|
-
promise: Promise<
|
|
285
|
+
promise: Promise<DecodedPrefetch | null>,
|
|
182
286
|
): void {
|
|
183
287
|
inflightPromises.set(key, promise);
|
|
184
288
|
}
|
|
185
289
|
|
|
290
|
+
/**
|
|
291
|
+
* Store the same in-flight Promise under multiple keys, recording them
|
|
292
|
+
* as sibling aliases. Consuming or clearing any one alias atomically
|
|
293
|
+
* removes every entry, guaranteeing the shared Response stream has a
|
|
294
|
+
* single consumer even when navigation looks up either key.
|
|
295
|
+
*/
|
|
296
|
+
export function setInflightPromiseWithAliases(
|
|
297
|
+
keys: string[],
|
|
298
|
+
promise: Promise<DecodedPrefetch | null>,
|
|
299
|
+
): void {
|
|
300
|
+
for (const k of keys) {
|
|
301
|
+
inflightPromises.set(k, promise);
|
|
302
|
+
inflightAliases.set(k, keys);
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
|
|
186
306
|
export function clearPrefetchInflight(key: string): void {
|
|
187
|
-
|
|
188
|
-
|
|
307
|
+
forEachAlias(key, (k) => {
|
|
308
|
+
inflight.delete(k);
|
|
309
|
+
inflightPromises.delete(k);
|
|
310
|
+
inflightAliases.delete(k);
|
|
311
|
+
adoptedKeys.delete(k);
|
|
312
|
+
});
|
|
189
313
|
}
|
|
190
314
|
|
|
191
|
-
/**
|
|
192
|
-
* Invalidate all prefetch state. Called when server actions mutate data.
|
|
193
|
-
* Clears the in-memory cache, cancels in-flight prefetches, and rotates
|
|
194
|
-
* the Rango state key so CDN-cached responses are also invalidated.
|
|
195
|
-
*
|
|
196
|
-
* Uses abortAllPrefetches (hard cancel) because in-flight responses
|
|
197
|
-
* may contain stale data after a mutation.
|
|
198
|
-
*/
|
|
199
315
|
export function clearPrefetchCache(): void {
|
|
200
316
|
generation++;
|
|
201
317
|
inflight.clear();
|
|
202
318
|
inflightPromises.clear();
|
|
319
|
+
inflightAliases.clear();
|
|
320
|
+
adoptedKeys.clear();
|
|
203
321
|
cache.clear();
|
|
204
322
|
abortAllPrefetches();
|
|
205
323
|
invalidateRangoState();
|