@rangojs/router 0.0.0-experimental.20 → 0.0.0-experimental.204030a9
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/AGENTS.md +4 -0
- package/README.md +242 -55
- package/dist/bin/rango.js +277 -99
- package/dist/vite/index.js +2929 -1132
- package/dist/vite/index.js.bak +5448 -0
- package/dist/vite/plugins/cloudflare-protocol-loader-hook.mjs +76 -0
- package/package.json +68 -21
- package/skills/breadcrumbs/SKILL.md +252 -0
- package/skills/bundle-analysis/SKILL.md +159 -0
- package/skills/cache-guide/SKILL.md +243 -21
- package/skills/caching/SKILL.md +159 -10
- package/skills/composability/SKILL.md +27 -2
- package/skills/document-cache/SKILL.md +78 -55
- package/skills/handler-use/SKILL.md +364 -0
- package/skills/hooks/SKILL.md +262 -51
- package/skills/host-router/SKILL.md +243 -0
- package/skills/i18n/SKILL.md +276 -0
- package/skills/intercept/SKILL.md +46 -4
- package/skills/layout/SKILL.md +28 -7
- package/skills/links/SKILL.md +249 -17
- package/skills/loader/SKILL.md +291 -31
- package/skills/middleware/SKILL.md +49 -12
- package/skills/migrate-nextjs/SKILL.md +562 -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 +197 -6
- package/skills/prerender/SKILL.md +125 -102
- package/skills/rango/SKILL.md +242 -23
- package/skills/react-compiler/SKILL.md +168 -0
- package/skills/response-routes/SKILL.md +66 -9
- package/skills/route/SKILL.md +91 -8
- package/skills/router-setup/SKILL.md +98 -8
- package/skills/server-actions/SKILL.md +751 -0
- package/skills/streams-and-websockets/SKILL.md +283 -0
- package/skills/testing/SKILL.md +511 -188
- package/skills/typesafety/SKILL.md +354 -50
- package/skills/use-cache/SKILL.md +34 -5
- package/skills/view-transitions/SKILL.md +294 -0
- package/src/__augment-tests__/augment.ts +81 -0
- package/src/__augment-tests__/augmented.check.ts +117 -0
- package/src/__internal.ts +92 -0
- package/src/browser/action-coordinator.ts +53 -36
- package/src/browser/app-shell.ts +52 -0
- package/src/browser/app-version.ts +14 -0
- package/src/browser/event-controller.ts +91 -70
- package/src/browser/history-state.ts +21 -0
- package/src/browser/index.ts +3 -3
- package/src/browser/link-interceptor.ts +4 -0
- package/src/browser/navigation-bridge.ts +183 -18
- package/src/browser/navigation-client.ts +187 -57
- package/src/browser/navigation-store.ts +75 -17
- package/src/browser/navigation-transaction.ts +21 -37
- package/src/browser/partial-update.ts +143 -40
- package/src/browser/prefetch/cache.ts +275 -28
- package/src/browser/prefetch/fetch.ts +191 -46
- package/src/browser/prefetch/policy.ts +6 -0
- package/src/browser/prefetch/queue.ts +123 -20
- package/src/browser/prefetch/resource-ready.ts +77 -0
- package/src/browser/rango-state.ts +53 -13
- package/src/browser/react/Link.tsx +98 -14
- package/src/browser/react/NavigationProvider.tsx +110 -33
- package/src/browser/react/context.ts +7 -2
- package/src/browser/react/filter-segment-order.ts +51 -7
- package/src/browser/react/index.ts +3 -0
- package/src/browser/react/location-state-shared.ts +175 -4
- package/src/browser/react/location-state.ts +39 -13
- package/src/browser/react/use-handle.ts +23 -64
- package/src/browser/react/use-navigation.ts +22 -2
- package/src/browser/react/use-params.ts +20 -8
- package/src/browser/react/use-reverse.ts +106 -0
- package/src/browser/react/use-router.ts +43 -10
- package/src/browser/react/use-segments.ts +11 -8
- package/src/browser/response-adapter.ts +25 -0
- package/src/browser/rsc-router.tsx +200 -75
- package/src/browser/scroll-restoration.ts +46 -39
- package/src/browser/segment-reconciler.ts +36 -9
- package/src/browser/segment-structure-assert.ts +2 -2
- package/src/browser/server-action-bridge.ts +31 -36
- package/src/browser/types.ts +81 -5
- package/src/build/collect-fallback-refs.ts +107 -0
- package/src/build/generate-manifest.ts +65 -40
- package/src/build/generate-route-types.ts +5 -0
- package/src/build/index.ts +2 -0
- package/src/build/route-trie.ts +69 -26
- package/src/build/route-types/codegen.ts +4 -4
- package/src/build/route-types/include-resolution.ts +9 -2
- package/src/build/route-types/per-module-writer.ts +7 -4
- package/src/build/route-types/router-processing.ts +278 -88
- 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-runtime.ts +15 -11
- package/src/cache/cache-scope.ts +76 -49
- package/src/cache/cf/cf-cache-store.ts +501 -18
- package/src/cache/cf/index.ts +5 -1
- package/src/cache/document-cache.ts +17 -7
- package/src/cache/index.ts +1 -0
- package/src/cache/taint.ts +55 -0
- package/src/client.rsc.tsx +5 -1
- package/src/client.tsx +95 -284
- package/src/context-var.ts +72 -2
- package/src/debug.ts +2 -2
- package/src/decode-loader-results.ts +36 -0
- package/src/errors.ts +30 -1
- package/src/handle.ts +65 -12
- package/src/handles/breadcrumbs.ts +66 -0
- package/src/handles/index.ts +1 -0
- package/src/host/index.ts +2 -5
- package/src/host/router.ts +129 -57
- package/src/host/types.ts +31 -2
- package/src/host/utils.ts +1 -1
- package/src/href-client.ts +140 -20
- package/src/index.rsc.ts +15 -40
- package/src/index.ts +92 -76
- package/src/loader-store.ts +500 -0
- package/src/loader.rsc.ts +2 -5
- package/src/loader.ts +3 -10
- package/src/missing-id-error.ts +68 -0
- package/src/outlet-context.ts +1 -1
- package/src/prerender/store.ts +57 -15
- package/src/prerender.ts +141 -80
- package/src/response-utils.ts +37 -0
- package/src/reverse.ts +65 -15
- package/src/route-content-wrapper.tsx +6 -28
- package/src/route-definition/dsl-helpers.ts +435 -260
- package/src/route-definition/helper-factories.ts +29 -139
- package/src/route-definition/helpers-types.ts +110 -34
- package/src/route-definition/index.ts +3 -3
- package/src/route-definition/redirect.ts +11 -3
- package/src/route-definition/resolve-handler-use.ts +155 -0
- package/src/route-definition/use-item-types.ts +32 -0
- package/src/route-map-builder.ts +7 -1
- package/src/route-types.ts +37 -41
- package/src/router/basename.ts +14 -0
- package/src/router/content-negotiation.ts +113 -1
- package/src/router/error-handling.ts +1 -1
- package/src/router/find-match.ts +4 -2
- package/src/router/handler-context.ts +105 -39
- package/src/router/intercept-resolution.ts +15 -22
- package/src/router/lazy-includes.ts +12 -9
- package/src/router/loader-resolution.ts +175 -23
- package/src/router/logging.ts +5 -2
- package/src/router/manifest.ts +31 -16
- package/src/router/match-api.ts +129 -193
- package/src/router/match-handlers.ts +63 -20
- package/src/router/match-middleware/background-revalidation.ts +30 -2
- package/src/router/match-middleware/cache-lookup.ts +136 -106
- package/src/router/match-middleware/cache-store.ts +54 -10
- package/src/router/match-middleware/intercept-resolution.ts +9 -7
- package/src/router/match-middleware/segment-resolution.ts +61 -5
- package/src/router/match-result.ts +124 -18
- package/src/router/metrics.ts +239 -14
- package/src/router/middleware-types.ts +61 -31
- package/src/router/middleware.ts +226 -124
- package/src/router/navigation-snapshot.ts +182 -0
- package/src/router/pattern-matching.ts +118 -19
- package/src/router/prerender-match.ts +114 -10
- package/src/router/preview-match.ts +32 -102
- package/src/router/request-classification.ts +286 -0
- package/src/router/revalidation.ts +85 -9
- package/src/router/route-snapshot.ts +245 -0
- package/src/router/router-context.ts +6 -1
- package/src/router/router-interfaces.ts +91 -29
- package/src/router/router-options.ts +89 -19
- package/src/router/router-registry.ts +2 -5
- package/src/router/segment-resolution/fresh.ts +240 -23
- package/src/router/segment-resolution/helpers.ts +30 -25
- package/src/router/segment-resolution/loader-cache.ts +1 -0
- package/src/router/segment-resolution/revalidation.ts +483 -289
- package/src/router/segment-resolution/view-transition-default.ts +36 -0
- package/src/router/segment-wrappers.ts +2 -0
- package/src/router/substitute-pattern-params.ts +56 -0
- package/src/router/telemetry.ts +99 -0
- package/src/router/trie-matching.ts +38 -15
- package/src/router/types.ts +9 -0
- package/src/router/url-params.ts +49 -0
- package/src/router.ts +120 -32
- package/src/rsc/handler-context.ts +2 -2
- package/src/rsc/handler.ts +524 -370
- package/src/rsc/helpers.ts +91 -43
- package/src/rsc/index.ts +1 -21
- package/src/rsc/loader-fetch.ts +23 -3
- package/src/rsc/manifest-init.ts +5 -1
- package/src/rsc/origin-guard.ts +28 -10
- package/src/rsc/progressive-enhancement.ts +39 -10
- package/src/rsc/response-route-handler.ts +46 -53
- package/src/rsc/rsc-rendering.ts +69 -89
- package/src/rsc/runtime-warnings.ts +9 -10
- package/src/rsc/server-action.ts +39 -47
- package/src/rsc/ssr-setup.ts +144 -0
- package/src/rsc/types.ts +19 -3
- package/src/search-params.ts +20 -17
- package/src/segment-content-promise.ts +67 -0
- package/src/segment-loader-promise.ts +122 -0
- package/src/segment-system.tsx +219 -67
- package/src/serialize.ts +243 -0
- package/src/server/context.ts +285 -63
- package/src/server/cookie-store.ts +28 -4
- package/src/server/handle-store.ts +19 -0
- package/src/server/loader-registry.ts +9 -8
- package/src/server/request-context.ts +228 -65
- package/src/server.ts +6 -0
- package/src/ssr/index.tsx +9 -1
- package/src/static-handler.ts +19 -7
- package/src/testing/cache-status.ts +166 -0
- package/src/testing/collect-handle.ts +63 -0
- package/src/testing/dispatch.ts +440 -0
- package/src/testing/dom.entry.ts +22 -0
- package/src/testing/e2e/fixture.ts +154 -0
- package/src/testing/e2e/index.ts +149 -0
- package/src/testing/e2e/matchers.ts +51 -0
- package/src/testing/e2e/page-helpers.ts +272 -0
- package/src/testing/e2e/parity.ts +306 -0
- package/src/testing/e2e/server.ts +183 -0
- package/src/testing/flight-matchers.ts +104 -0
- package/src/testing/flight-runtime.d.ts +21 -0
- package/src/testing/flight.entry.ts +22 -0
- package/src/testing/flight.ts +182 -0
- package/src/testing/generated-routes.ts +223 -0
- package/src/testing/index.ts +98 -0
- package/src/testing/internal/context.ts +151 -0
- package/src/testing/render-route.tsx +536 -0
- package/src/testing/run-loader.ts +296 -0
- package/src/testing/run-middleware.ts +170 -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 +112 -0
- package/src/theme/index.ts +4 -13
- package/src/types/cache-types.ts +4 -4
- package/src/types/global-namespace.ts +39 -26
- package/src/types/handler-context.ts +197 -79
- package/src/types/index.ts +1 -0
- package/src/types/loader-types.ts +41 -15
- package/src/types/request-scope.ts +126 -0
- package/src/types/route-config.ts +17 -8
- package/src/types/route-entry.ts +19 -1
- package/src/types/segments.ts +37 -6
- package/src/urls/include-helper.ts +34 -67
- package/src/urls/index.ts +0 -3
- package/src/urls/path-helper-types.ts +50 -9
- package/src/urls/path-helper.ts +63 -63
- package/src/urls/pattern-types.ts +48 -19
- package/src/urls/response-types.ts +25 -22
- package/src/urls/type-extraction.ts +26 -116
- package/src/urls/urls-function.ts +1 -5
- package/src/use-loader.tsx +487 -44
- package/src/vite/debug.ts +185 -0
- package/src/vite/discovery/bundle-postprocess.ts +63 -91
- package/src/vite/discovery/discover-routers.ts +106 -53
- 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 +222 -107
- 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 +50 -13
- package/src/vite/discovery/virtual-module-codegen.ts +13 -23
- package/src/vite/index.ts +10 -3
- package/src/vite/plugin-types.ts +111 -72
- package/src/vite/plugins/cjs-to-esm.ts +8 -7
- package/src/vite/plugins/client-ref-dedup.ts +16 -0
- package/src/vite/plugins/client-ref-hashing.ts +28 -5
- 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 +214 -0
- package/src/vite/plugins/expose-action-id.ts +55 -33
- package/src/vite/plugins/expose-id-utils.ts +24 -8
- package/src/vite/plugins/expose-ids/export-analysis.ts +100 -20
- package/src/vite/plugins/expose-ids/handler-transform.ts +12 -35
- package/src/vite/plugins/expose-ids/loader-transform.ts +3 -5
- package/src/vite/plugins/expose-ids/router-transform.ts +20 -3
- package/src/vite/plugins/expose-internal-ids.ts +544 -317
- package/src/vite/plugins/performance-tracks.ts +92 -0
- package/src/vite/plugins/refresh-cmd.ts +127 -0
- package/src/vite/plugins/use-cache-transform.ts +65 -50
- package/src/vite/plugins/version-injector.ts +39 -23
- package/src/vite/plugins/version-plugin.ts +72 -3
- package/src/vite/plugins/virtual-entries.ts +2 -2
- package/src/vite/rango.ts +265 -226
- package/src/vite/router-discovery.ts +924 -137
- package/src/vite/utils/ast-handler-extract.ts +15 -15
- package/src/vite/utils/banner.ts +4 -4
- package/src/vite/utils/bundle-analysis.ts +4 -2
- package/src/vite/utils/client-chunks.ts +190 -0
- package/src/vite/utils/forward-user-plugins.ts +193 -0
- package/src/vite/utils/manifest-utils.ts +21 -5
- package/src/vite/utils/package-resolution.ts +41 -1
- package/src/vite/utils/prerender-utils.ts +98 -5
- package/src/vite/utils/shared-utils.ts +109 -27
- package/src/browser/action-response-classifier.ts +0 -99
- package/src/route-definition/route-function.ts +0 -119
package/src/host/types.ts
CHANGED
|
@@ -35,12 +35,24 @@ export type Middleware = (
|
|
|
35
35
|
*/
|
|
36
36
|
export type HostPattern = string | string[];
|
|
37
37
|
|
|
38
|
+
/**
|
|
39
|
+
* Whether a route entry is an inline request handler or a lazy module mount.
|
|
40
|
+
*
|
|
41
|
+
* Stored on the entry so discovery and runtime act on the consumer's declared
|
|
42
|
+
* intent instead of inferring it from the function's shape (arity/return value),
|
|
43
|
+
* which is ambiguous: a lazy loader may declare an ignored param, and an inline
|
|
44
|
+
* handler may be async. `.map()` registers `"handler"`, `.lazy()` registers
|
|
45
|
+
* `"lazy"`.
|
|
46
|
+
*/
|
|
47
|
+
export type RouteEntryKind = "handler" | "lazy";
|
|
48
|
+
|
|
38
49
|
/**
|
|
39
50
|
* Result from testing a hostname against patterns
|
|
40
51
|
*/
|
|
41
52
|
export interface HostMatchResult {
|
|
42
53
|
pattern: string;
|
|
43
54
|
handler: Handler | LazyHandler;
|
|
55
|
+
kind: RouteEntryKind;
|
|
44
56
|
}
|
|
45
57
|
|
|
46
58
|
/**
|
|
@@ -53,9 +65,24 @@ export interface HostRouteBuilder {
|
|
|
53
65
|
use(...middleware: Middleware[]): HostRouteBuilder;
|
|
54
66
|
|
|
55
67
|
/**
|
|
56
|
-
* Map to
|
|
68
|
+
* Map to an inline request handler `(request, input) => Response`.
|
|
69
|
+
*
|
|
70
|
+
* For a lazily-imported sub-app or handler module, use {@link lazy} instead -
|
|
71
|
+
* `.map(() => import(...))` is rejected (the return type is not a `Response`)
|
|
72
|
+
* and would not be discovered at build time.
|
|
73
|
+
*/
|
|
74
|
+
map(handler: Handler): HostRouter;
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Mount a lazily-imported handler or host router:
|
|
78
|
+
* `.lazy(() => import("./sub-app"))`.
|
|
79
|
+
*
|
|
80
|
+
* The loader takes no arguments and resolves to a module whose `default`
|
|
81
|
+
* export is a request `Handler` or a nested `HostRouter`. Only `.lazy()`
|
|
82
|
+
* entries are invoked during build-time discovery to trigger the sub-app's
|
|
83
|
+
* `createRouter()` registration.
|
|
57
84
|
*/
|
|
58
|
-
|
|
85
|
+
lazy(handler: LazyHandler): HostRouter;
|
|
59
86
|
}
|
|
60
87
|
|
|
61
88
|
/**
|
|
@@ -134,6 +161,8 @@ export interface RouteEntry {
|
|
|
134
161
|
patterns: string[];
|
|
135
162
|
middleware: Middleware[];
|
|
136
163
|
handler: Handler | LazyHandler;
|
|
164
|
+
/** Whether `handler` is an inline request handler or a lazy module mount. */
|
|
165
|
+
kind: RouteEntryKind;
|
|
137
166
|
isFallback?: boolean;
|
|
138
167
|
}
|
|
139
168
|
|
package/src/host/utils.ts
CHANGED
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
* app: ['*', 'www.*']
|
|
16
16
|
* });
|
|
17
17
|
*
|
|
18
|
-
* router.host(hosts.admin).
|
|
18
|
+
* router.host(hosts.admin).lazy(() => import("./apps/admin")); // Type-safe!
|
|
19
19
|
* ```
|
|
20
20
|
*/
|
|
21
21
|
export function defineHosts<T extends Record<string, string | string[]>>(
|
package/src/href-client.ts
CHANGED
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
*/
|
|
16
16
|
|
|
17
17
|
import type { GetRegisteredRoutes } from "./types.js";
|
|
18
|
+
import type { JsonSerialize } from "./serialize.js";
|
|
18
19
|
import type { ResponseEnvelope } from "./urls.js";
|
|
19
20
|
|
|
20
21
|
/**
|
|
@@ -103,29 +104,75 @@ type NameForPattern<TPattern extends string, TRoutes = GetRegisteredRoutes> = {
|
|
|
103
104
|
}[keyof TRoutes];
|
|
104
105
|
|
|
105
106
|
/**
|
|
106
|
-
*
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
*
|
|
107
|
+
* Strip a query (`?…`) and/or hash (`#…`) suffix before matching, so a concrete
|
|
108
|
+
* URL like `/api/health?ts=1` still resolves to its route's response. Removes
|
|
109
|
+
* from the earliest of `?`/`#`: a `#` before the first `?` (the query is part of
|
|
110
|
+
* a fragment, e.g. `/health#top?x=1`) is handled, as is a `/:` that only appears
|
|
111
|
+
* inside the query (e.g. `/health?next=/:id`).
|
|
112
|
+
*/
|
|
113
|
+
type StripPathSuffix<T extends string> = T extends `${infer Base}?${string}`
|
|
114
|
+
? Base extends `${infer Frag}#${string}`
|
|
115
|
+
? Frag
|
|
116
|
+
: Base
|
|
117
|
+
: T extends `${infer Base}#${string}`
|
|
118
|
+
? Base
|
|
119
|
+
: T;
|
|
120
|
+
|
|
121
|
+
/** Extract a route entry's response payload (or `never` for RSC routes). */
|
|
122
|
+
type ResponsePayloadOf<TRoutes, K extends keyof TRoutes> = TRoutes[K] extends {
|
|
123
|
+
readonly response: infer R;
|
|
124
|
+
}
|
|
125
|
+
? Exclude<R, Response>
|
|
126
|
+
: never;
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Look up the response payload for a route, keyed by either a route pattern
|
|
130
|
+
* (`/api/products/:id`) or a concrete path (`/api/products/123`). The same type
|
|
131
|
+
* serves a pattern lookup and a typed `fetch` wrapper that forwards a concrete
|
|
132
|
+
* `Rango.Path`:
|
|
110
133
|
*
|
|
111
|
-
*
|
|
112
|
-
* PathResponse<"/api/
|
|
134
|
+
* PathResponse<"/api/products/:id"> → Product // by pattern
|
|
135
|
+
* PathResponse<"/api/products/123"> → Product // by concrete path
|
|
113
136
|
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
137
|
+
* The query/hash suffix is stripped first; the stripped key is then treated as a
|
|
138
|
+
* pattern when it contains a `/:param` segment and matched exactly (precise even
|
|
139
|
+
* for nested dynamic routes), otherwise as a concrete path matched against each
|
|
140
|
+
* route's `PatternToPath` template. Because those holes are `${string}`
|
|
141
|
+
* (slash-greedy), a concrete path under a *nested* dynamic route can match several
|
|
142
|
+
* patterns and union their responses — pattern lookups do not have this
|
|
143
|
+
* looseness. RSC routes (no response) and unmatched keys resolve to `never`.
|
|
144
|
+
*/
|
|
145
|
+
type ResponsePayloadFor<
|
|
146
|
+
TPath extends string,
|
|
147
|
+
TRoutes = GetRegisteredRoutes,
|
|
148
|
+
> = ResponsePayloadForKey<StripPathSuffix<TPath>, TRoutes>;
|
|
149
|
+
|
|
150
|
+
type ResponsePayloadForKey<
|
|
151
|
+
TKey extends string,
|
|
152
|
+
TRoutes,
|
|
153
|
+
> = TKey extends `${string}/:${string}`
|
|
154
|
+
? {
|
|
155
|
+
[K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TKey
|
|
156
|
+
? ResponsePayloadOf<TRoutes, K>
|
|
157
|
+
: never;
|
|
158
|
+
}[keyof TRoutes]
|
|
159
|
+
: {
|
|
160
|
+
[K in keyof TRoutes]: TKey extends PatternToPath<RoutePattern<TRoutes, K>>
|
|
161
|
+
? ResponsePayloadOf<TRoutes, K>
|
|
162
|
+
: never;
|
|
163
|
+
}[keyof TRoutes];
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* Public response type for a route, keyed by pattern or concrete path. The
|
|
167
|
+
* payload is wrapped in `JsonSerialize` so it describes the JSON **wire** value a
|
|
168
|
+
* consumer receives from `fetch().then(r => r.json())`, not the handler's raw
|
|
169
|
+
* return type — e.g. a handler returning `{ createdAt: Date }` resolves here to
|
|
170
|
+
* `ResponseEnvelope<{ createdAt: string }>`.
|
|
116
171
|
*/
|
|
117
172
|
export type PathResponse<
|
|
118
|
-
|
|
173
|
+
TPath extends string,
|
|
119
174
|
TRoutes = GetRegisteredRoutes,
|
|
120
|
-
> = ResponseEnvelope<
|
|
121
|
-
{
|
|
122
|
-
[K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern
|
|
123
|
-
? TRoutes[K] extends { readonly response: infer R }
|
|
124
|
-
? Exclude<R, Response>
|
|
125
|
-
: never
|
|
126
|
-
: never;
|
|
127
|
-
}[keyof TRoutes]
|
|
128
|
-
>;
|
|
175
|
+
> = ResponseEnvelope<JsonSerialize<ResponsePayloadFor<TPath, TRoutes>>>;
|
|
129
176
|
|
|
130
177
|
/**
|
|
131
178
|
* Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
|
|
@@ -140,7 +187,7 @@ type OptionalTrailingSlash<T extends string> = T extends `${infer Base}/`
|
|
|
140
187
|
/**
|
|
141
188
|
* Union of all valid paths from registered routes
|
|
142
189
|
*
|
|
143
|
-
* Generated from
|
|
190
|
+
* Generated from Rango.RegisteredRoutes via module augmentation.
|
|
144
191
|
* Allows optional query strings and hash fragments.
|
|
145
192
|
*/
|
|
146
193
|
export type ValidPaths<TRoutes = GetRegisteredRoutes> =
|
|
@@ -154,6 +201,76 @@ export type ValidPaths<TRoutes = GetRegisteredRoutes> =
|
|
|
154
201
|
}[keyof TRoutes]
|
|
155
202
|
>;
|
|
156
203
|
|
|
204
|
+
// Module-scoped alias so the ambient `Rango.PathResponse` below can reference
|
|
205
|
+
// the module-level `PathResponse` without the global namespace shadowing the
|
|
206
|
+
// name when both are called `PathResponse`.
|
|
207
|
+
type GlobalPathResponse<
|
|
208
|
+
TPattern extends string,
|
|
209
|
+
TRoutes = GetRegisteredRoutes,
|
|
210
|
+
> = PathResponse<TPattern, TRoutes>;
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Ambient path types on the `Rango` namespace.
|
|
214
|
+
*
|
|
215
|
+
* These live on the same global namespace consumers already augment for
|
|
216
|
+
* `Rango.Env` / `Rango.Vars`, so they are reachable with no import wherever the
|
|
217
|
+
* router's types are in scope. They are the public, recommended surface for
|
|
218
|
+
* typing anything that wraps `href()`. `ValidPaths` / `PathResponse` stay as the
|
|
219
|
+
* internal building blocks behind them.
|
|
220
|
+
*/
|
|
221
|
+
declare global {
|
|
222
|
+
namespace Rango {
|
|
223
|
+
/**
|
|
224
|
+
* Union of every valid route path accepted by `href()`.
|
|
225
|
+
*
|
|
226
|
+
* Type a wrapper's path parameter as `Rango.Path` so it shares `href()`'s
|
|
227
|
+
* compile-time validation against the registered routes:
|
|
228
|
+
*
|
|
229
|
+
* ```ts
|
|
230
|
+
* import { href } from "@rangojs/router/client";
|
|
231
|
+
*
|
|
232
|
+
* export const appHref = (path: Rango.Path) => href(path);
|
|
233
|
+
* ```
|
|
234
|
+
*
|
|
235
|
+
* Resolves from `Rango.RegisteredRoutes` when augmented, otherwise the
|
|
236
|
+
* auto-generated `Rango.GeneratedRouteMap`, otherwise a permissive
|
|
237
|
+
* `/${string}` fallback.
|
|
238
|
+
*/
|
|
239
|
+
type Path<TRoutes = GetRegisteredRoutes> = ValidPaths<TRoutes>;
|
|
240
|
+
|
|
241
|
+
/**
|
|
242
|
+
* Response payload for a route, looked up from the global route map by
|
|
243
|
+
* either a route pattern (`/api/products/:id`) or a concrete path
|
|
244
|
+
* (`/api/products/123`). Because it accepts a concrete `Rango.Path`, it
|
|
245
|
+
* doubles as the return type of a typed `fetch` wrapper:
|
|
246
|
+
*
|
|
247
|
+
* ```ts
|
|
248
|
+
* type Product = Rango.PathResponse<"/api/products/:id">; // by pattern
|
|
249
|
+
* type Same = Rango.PathResponse<"/api/products/42">; // by concrete path
|
|
250
|
+
*
|
|
251
|
+
* const get = async <T extends Rango.Path>(
|
|
252
|
+
* path: T,
|
|
253
|
+
* ): Promise<Rango.PathResponse<T>> =>
|
|
254
|
+
* fetch(href(path)).then((r) => r.json());
|
|
255
|
+
* ```
|
|
256
|
+
*
|
|
257
|
+
* The payload is the JSON **wire** shape (via `Rango.JsonSerialize`), not the
|
|
258
|
+
* handler's raw return — a handler returning `{ createdAt: Date }` resolves
|
|
259
|
+
* here to `ResponseEnvelope<{ createdAt: string }>`, matching what
|
|
260
|
+
* `fetch().then(r => r.json())` actually yields.
|
|
261
|
+
*
|
|
262
|
+
* Only resolves once `Rango.RegisteredRoutes` carries response metadata (the
|
|
263
|
+
* generated map has paths and search but no payloads). Pass an explicit route
|
|
264
|
+
* map as the second argument to look up against a non-global map (rarely
|
|
265
|
+
* needed in app code).
|
|
266
|
+
*/
|
|
267
|
+
type PathResponse<
|
|
268
|
+
TPath extends string,
|
|
269
|
+
TRoutes = GetRegisteredRoutes,
|
|
270
|
+
> = GlobalPathResponse<TPath, TRoutes>;
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
|
|
157
274
|
/**
|
|
158
275
|
* Type-safe href function for client-side use
|
|
159
276
|
*
|
|
@@ -186,7 +303,10 @@ export function href<T extends ValidPaths>(path: T, mount?: string): string {
|
|
|
186
303
|
const normalizedMount = mount.endsWith("/") ? mount.slice(0, -1) : mount;
|
|
187
304
|
return normalizedMount + path;
|
|
188
305
|
}
|
|
189
|
-
|
|
306
|
+
// ValidPaths is built from template literals so T does extend string at
|
|
307
|
+
// runtime, but the inference can fail past a certain route-union complexity
|
|
308
|
+
// and TypeScript reports T as not assignable to string.
|
|
309
|
+
return path as string;
|
|
190
310
|
}
|
|
191
311
|
|
|
192
312
|
/**
|
package/src/index.rsc.ts
CHANGED
|
@@ -11,8 +11,6 @@
|
|
|
11
11
|
|
|
12
12
|
// Re-export all universal exports from index.ts
|
|
13
13
|
export {
|
|
14
|
-
// Universal rendering utilities
|
|
15
|
-
renderSegments,
|
|
16
14
|
// Error classes
|
|
17
15
|
RouteNotFoundError,
|
|
18
16
|
DataNotFoundError,
|
|
@@ -20,10 +18,8 @@ export {
|
|
|
20
18
|
MiddlewareError,
|
|
21
19
|
HandlerError,
|
|
22
20
|
BuildError,
|
|
21
|
+
DslContextError,
|
|
23
22
|
InvalidHandlerError,
|
|
24
|
-
NetworkError,
|
|
25
|
-
isNetworkError,
|
|
26
|
-
sanitizeError,
|
|
27
23
|
RouterError,
|
|
28
24
|
Skip,
|
|
29
25
|
isSkip,
|
|
@@ -40,7 +36,6 @@ export type {
|
|
|
40
36
|
TrailingSlashMode,
|
|
41
37
|
// Handler types
|
|
42
38
|
Handler,
|
|
43
|
-
ScopedRouteMap,
|
|
44
39
|
HandlerContext,
|
|
45
40
|
ExtractParams,
|
|
46
41
|
GenericParams,
|
|
@@ -49,6 +44,7 @@ export type {
|
|
|
49
44
|
// Revalidation types
|
|
50
45
|
RevalidateParams,
|
|
51
46
|
Revalidate,
|
|
47
|
+
ActionRef,
|
|
52
48
|
RouteKeys,
|
|
53
49
|
// Loader types
|
|
54
50
|
LoaderDefinition,
|
|
@@ -73,7 +69,7 @@ export type {
|
|
|
73
69
|
|
|
74
70
|
// Router options type (server-only, so import directly)
|
|
75
71
|
export type {
|
|
76
|
-
|
|
72
|
+
RangoOptions,
|
|
77
73
|
SSRStreamMode,
|
|
78
74
|
SSROptions,
|
|
79
75
|
ResolveStreamingContext,
|
|
@@ -106,6 +102,7 @@ export type {
|
|
|
106
102
|
LayoutUseItem,
|
|
107
103
|
AllUseItems,
|
|
108
104
|
UseItems,
|
|
105
|
+
HandlerUseItem,
|
|
109
106
|
} from "./route-types.js";
|
|
110
107
|
|
|
111
108
|
// Handle API
|
|
@@ -120,9 +117,9 @@ export { nonce } from "./rsc/nonce.js";
|
|
|
120
117
|
// Pre-render handler API
|
|
121
118
|
export {
|
|
122
119
|
Prerender,
|
|
123
|
-
|
|
120
|
+
Passthrough,
|
|
124
121
|
type PrerenderHandlerDefinition,
|
|
125
|
-
type
|
|
122
|
+
type PassthroughHandlerDefinition,
|
|
126
123
|
type PrerenderOptions,
|
|
127
124
|
type BuildContext,
|
|
128
125
|
type StaticBuildContext,
|
|
@@ -130,16 +127,11 @@ export {
|
|
|
130
127
|
} from "./prerender.js";
|
|
131
128
|
|
|
132
129
|
// Static handler API
|
|
133
|
-
export {
|
|
134
|
-
Static,
|
|
135
|
-
isStaticHandler,
|
|
136
|
-
type StaticHandlerDefinition,
|
|
137
|
-
} from "./static-handler.js";
|
|
130
|
+
export { Static, type StaticHandlerDefinition } from "./static-handler.js";
|
|
138
131
|
|
|
139
132
|
// Django-style URL patterns (RSC/server context)
|
|
140
133
|
export {
|
|
141
134
|
urls,
|
|
142
|
-
RESPONSE_TYPE,
|
|
143
135
|
type PathHelpers,
|
|
144
136
|
type PathOptions,
|
|
145
137
|
type UrlPatterns,
|
|
@@ -161,7 +153,7 @@ export {
|
|
|
161
153
|
// Core router (server-side)
|
|
162
154
|
export {
|
|
163
155
|
createRouter,
|
|
164
|
-
type
|
|
156
|
+
type Rango,
|
|
165
157
|
type RootLayoutProps,
|
|
166
158
|
type RouterRequestInput,
|
|
167
159
|
} from "./router.js";
|
|
@@ -171,6 +163,7 @@ export type { HandlerCacheConfig } from "./rsc/types.js";
|
|
|
171
163
|
|
|
172
164
|
// Built-in handles (server-side)
|
|
173
165
|
export { Meta } from "./handles/meta.js";
|
|
166
|
+
export { Breadcrumbs, type BreadcrumbItem } from "./handles/breadcrumbs.js";
|
|
174
167
|
|
|
175
168
|
// Request context (for accessing request data in server actions/components).
|
|
176
169
|
// Re-exported with a narrowed return type so that public consumers only see
|
|
@@ -181,6 +174,9 @@ export type { PublicRequestContext as RequestContext } from "./server/request-co
|
|
|
181
174
|
import type { PublicRequestContext } from "./server/request-context.js";
|
|
182
175
|
import type { DefaultEnv } from "./types/global-namespace.js";
|
|
183
176
|
|
|
177
|
+
// Shared base for every user-facing request context (mirrors index.ts).
|
|
178
|
+
export type { RequestScope, ExecutionContext } from "./types/request-scope.js";
|
|
179
|
+
|
|
184
180
|
export const getRequestContext: <
|
|
185
181
|
TEnv = DefaultEnv,
|
|
186
182
|
>() => PublicRequestContext<TEnv> = _getRequestContextInternal;
|
|
@@ -206,8 +202,6 @@ export type {
|
|
|
206
202
|
ReverseFunction,
|
|
207
203
|
ExtractLocalRoutes,
|
|
208
204
|
ParamsFor,
|
|
209
|
-
SanitizePrefix,
|
|
210
|
-
MergeRoutes,
|
|
211
205
|
} from "./reverse.js";
|
|
212
206
|
export { scopedReverse, createReverse } from "./reverse.js";
|
|
213
207
|
|
|
@@ -220,12 +214,6 @@ export type {
|
|
|
220
214
|
RouteParams,
|
|
221
215
|
} from "./search-params.js";
|
|
222
216
|
|
|
223
|
-
// Debug utilities for route matching (development only)
|
|
224
|
-
export {
|
|
225
|
-
enableMatchDebug,
|
|
226
|
-
getMatchDebugStats,
|
|
227
|
-
} from "./router/pattern-matching.js";
|
|
228
|
-
|
|
229
217
|
// Location state (universal)
|
|
230
218
|
export {
|
|
231
219
|
createLocationState,
|
|
@@ -234,27 +222,14 @@ export {
|
|
|
234
222
|
type LocationStateOptions,
|
|
235
223
|
} from "./browser/react/location-state-shared.js";
|
|
236
224
|
|
|
237
|
-
// Path
|
|
238
|
-
|
|
225
|
+
// Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
|
|
226
|
+
// `Rango.PathResponse`, declared in href-client.ts) — no import needed.
|
|
239
227
|
|
|
240
228
|
// Telemetry sink
|
|
241
229
|
export { createConsoleSink } from "./router/telemetry.js";
|
|
242
230
|
export { createOTelSink } from "./router/telemetry-otel.js";
|
|
243
231
|
export type { OTelTracer, OTelSpan } from "./router/telemetry-otel.js";
|
|
244
|
-
export type {
|
|
245
|
-
TelemetrySink,
|
|
246
|
-
TelemetryEvent,
|
|
247
|
-
RequestStartEvent,
|
|
248
|
-
RequestEndEvent,
|
|
249
|
-
RequestErrorEvent,
|
|
250
|
-
RequestTimeoutEvent,
|
|
251
|
-
LoaderStartEvent,
|
|
252
|
-
LoaderEndEvent,
|
|
253
|
-
LoaderErrorEvent,
|
|
254
|
-
HandlerErrorEvent,
|
|
255
|
-
CacheDecisionEvent,
|
|
256
|
-
RevalidationDecisionEvent,
|
|
257
|
-
} from "./router/telemetry.js";
|
|
232
|
+
export type { TelemetrySink, TelemetryEvent } from "./router/telemetry.js";
|
|
258
233
|
|
|
259
234
|
// Timeout types and error class
|
|
260
235
|
export { RouterTimeoutError } from "./router/timeout.js";
|