npm - rwsdk - Versions diffs - 1.0.0-beta.4 → 1.0.0-beta.40 - Mend

rwsdk 1.0.0-beta.4 → 1.0.0-beta.40

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 (139) hide show

package/dist/lib/constants.d.mts +1 -0
package/dist/lib/constants.mjs +7 -4
package/dist/lib/e2e/browser.mjs +6 -2
package/dist/lib/e2e/constants.d.mts +4 -0
package/dist/lib/e2e/constants.mjs +49 -12
package/dist/lib/e2e/dev.mjs +37 -49
package/dist/lib/e2e/environment.d.mts +2 -0
package/dist/lib/e2e/environment.mjs +201 -64
package/dist/lib/e2e/index.d.mts +1 -0
package/dist/lib/e2e/index.mjs +1 -0
package/dist/lib/e2e/poll.d.mts +1 -1
package/dist/lib/e2e/release.d.mts +1 -0
package/dist/lib/e2e/release.mjs +16 -32
package/dist/lib/e2e/tarball.mjs +2 -34
package/dist/lib/e2e/testHarness.d.mts +34 -3
package/dist/lib/e2e/testHarness.mjs +219 -90
package/dist/lib/e2e/utils.d.mts +1 -0
package/dist/lib/e2e/utils.mjs +15 -0
package/dist/runtime/client/client.d.ts +35 -0
package/dist/runtime/client/client.js +35 -0
package/dist/runtime/client/navigation.d.ts +49 -0
package/dist/runtime/client/navigation.js +80 -31
package/dist/runtime/entries/clientSSR.d.ts +1 -0
package/dist/runtime/entries/clientSSR.js +3 -0
package/dist/runtime/entries/no-react-server-ssr-bridge.d.ts +0 -0
package/dist/runtime/entries/no-react-server-ssr-bridge.js +2 -0
package/dist/runtime/entries/router.d.ts +1 -0
package/dist/runtime/entries/routerClient.d.ts +1 -0
package/dist/runtime/entries/routerClient.js +1 -0
package/dist/runtime/entries/worker.d.ts +2 -0
package/dist/runtime/entries/worker.js +2 -0
package/dist/runtime/imports/__mocks__/use-client-lookup.d.ts +6 -0
package/dist/runtime/imports/__mocks__/use-client-lookup.js +6 -0
package/dist/runtime/lib/db/SqliteDurableObject.d.ts +2 -2
package/dist/runtime/lib/db/SqliteDurableObject.js +2 -2
package/dist/runtime/lib/db/createDb.d.ts +1 -2
package/dist/runtime/lib/db/createDb.js +4 -0
package/dist/runtime/lib/db/typeInference/builders/alterTable.d.ts +13 -3
package/dist/runtime/lib/db/typeInference/builders/columnDefinition.d.ts +35 -21
package/dist/runtime/lib/db/typeInference/builders/createTable.d.ts +9 -2
package/dist/runtime/lib/db/typeInference/database.d.ts +16 -2
package/dist/runtime/lib/db/typeInference/typetests/alterTable.typetest.js +80 -5
package/dist/runtime/lib/db/typeInference/typetests/createTable.typetest.js +104 -2
package/dist/runtime/lib/db/typeInference/typetests/testUtils.d.ts +1 -0
package/dist/runtime/lib/db/typeInference/utils.d.ts +59 -9
package/dist/runtime/lib/links.d.ts +21 -7
package/dist/runtime/lib/links.js +82 -24
package/dist/runtime/lib/links.test.js +20 -0
package/dist/runtime/lib/manifest.d.ts +1 -1
package/dist/runtime/lib/manifest.js +7 -4
package/dist/runtime/lib/realtime/client.js +8 -2
package/dist/runtime/lib/realtime/worker.d.ts +1 -1
package/dist/runtime/lib/router.d.ts +153 -36
package/dist/runtime/lib/router.js +169 -20
package/dist/runtime/lib/router.test.js +241 -0
package/dist/runtime/lib/stitchDocumentAndAppStreams.d.ts +66 -0
package/dist/runtime/lib/stitchDocumentAndAppStreams.js +302 -35
package/dist/runtime/lib/stitchDocumentAndAppStreams.test.d.ts +1 -0
package/dist/runtime/lib/stitchDocumentAndAppStreams.test.js +418 -0
package/dist/runtime/lib/{rwContext.d.ts → types.d.ts} +1 -0
package/dist/runtime/lib/types.js +1 -0
package/dist/runtime/render/renderDocumentHtmlStream.d.ts +1 -1
package/dist/runtime/render/renderToStream.d.ts +4 -2
package/dist/runtime/render/renderToStream.js +53 -24
package/dist/runtime/render/renderToString.d.ts +3 -6
package/dist/runtime/requestInfo/types.d.ts +4 -1
package/dist/runtime/requestInfo/utils.d.ts +9 -0
package/dist/runtime/requestInfo/utils.js +44 -0
package/dist/runtime/requestInfo/worker.d.ts +0 -1
package/dist/runtime/requestInfo/worker.js +3 -10
package/dist/runtime/script.d.ts +1 -3
package/dist/runtime/script.js +1 -10
package/dist/runtime/state.d.ts +3 -0
package/dist/runtime/state.js +13 -0
package/dist/runtime/worker.d.ts +3 -1
package/dist/runtime/worker.js +32 -0
package/dist/scripts/debug-sync.mjs +18 -20
package/dist/scripts/worker-run.d.mts +1 -1
package/dist/scripts/worker-run.mjs +59 -113
package/dist/use-synced-state/SyncedStateServer.d.mts +21 -0
package/dist/use-synced-state/SyncedStateServer.mjs +128 -0
package/dist/use-synced-state/__tests__/SyncStateServer.test.d.mts +1 -0
package/dist/use-synced-state/__tests__/SyncStateServer.test.mjs +109 -0
package/dist/use-synced-state/__tests__/useSyncState.test.d.ts +1 -0
package/dist/use-synced-state/__tests__/useSyncState.test.js +115 -0
package/dist/use-synced-state/__tests__/useSyncedState.test.d.ts +1 -0
package/dist/use-synced-state/__tests__/useSyncedState.test.js +115 -0
package/dist/use-synced-state/__tests__/worker.test.d.mts +1 -0
package/dist/use-synced-state/__tests__/worker.test.mjs +69 -0
package/dist/use-synced-state/client-core.d.ts +26 -0
package/dist/use-synced-state/client-core.js +39 -0
package/dist/use-synced-state/client.d.ts +3 -0
package/dist/use-synced-state/client.js +4 -0
package/dist/use-synced-state/constants.d.mts +1 -0
package/dist/use-synced-state/constants.mjs +1 -0
package/dist/use-synced-state/useSyncedState.d.ts +20 -0
package/dist/use-synced-state/useSyncedState.js +58 -0
package/dist/use-synced-state/worker.d.mts +13 -0
package/dist/use-synced-state/worker.mjs +69 -0
package/dist/vite/buildApp.mjs +34 -2
package/dist/vite/cloudflarePreInitPlugin.d.mts +11 -0
package/dist/vite/cloudflarePreInitPlugin.mjs +40 -0
package/dist/vite/configPlugin.mjs +9 -14
package/dist/vite/constants.d.mts +1 -0
package/dist/vite/constants.mjs +1 -0
package/dist/vite/createDirectiveLookupPlugin.mjs +10 -7
package/dist/vite/devServerTimingPlugin.mjs +4 -0
package/dist/vite/diagnosticAssetGraphPlugin.d.mts +4 -0
package/dist/vite/diagnosticAssetGraphPlugin.mjs +41 -0
package/dist/vite/directiveModulesDevPlugin.mjs +9 -1
package/dist/vite/directivesPlugin.mjs +4 -4
package/dist/vite/envResolvers.d.mts +11 -0
package/dist/vite/envResolvers.mjs +20 -0
package/dist/vite/getViteEsbuild.mjs +2 -1
package/dist/vite/hmrStabilityPlugin.d.mts +2 -0
package/dist/vite/hmrStabilityPlugin.mjs +73 -0
package/dist/vite/injectVitePreamblePlugin.mjs +0 -4
package/dist/vite/knownDepsResolverPlugin.d.mts +0 -6
package/dist/vite/knownDepsResolverPlugin.mjs +25 -17
package/dist/vite/linkerPlugin.d.mts +2 -1
package/dist/vite/linkerPlugin.mjs +11 -3
package/dist/vite/linkerPlugin.test.mjs +15 -0
package/dist/vite/miniflareHMRPlugin.mjs +6 -38
package/dist/vite/moveStaticAssetsPlugin.mjs +35 -4
package/dist/vite/redwoodPlugin.mjs +8 -10
package/dist/vite/runDirectivesScan.mjs +72 -18
package/dist/vite/ssrBridgePlugin.mjs +132 -40
package/dist/vite/ssrBridgeWrapPlugin.d.mts +2 -0
package/dist/vite/ssrBridgeWrapPlugin.mjs +85 -0
package/dist/vite/staleDepRetryPlugin.d.mts +2 -0
package/dist/vite/staleDepRetryPlugin.mjs +74 -0
package/dist/vite/statePlugin.d.mts +4 -0
package/dist/vite/statePlugin.mjs +62 -0
package/dist/vite/transformJsxScriptTagsPlugin.mjs +0 -5
package/dist/vite/virtualPlugin.mjs +6 -7
package/package.json +27 -10
package/dist/vite/manifestPlugin.d.mts +0 -4
package/dist/vite/manifestPlugin.mjs +0 -63
/package/dist/runtime/lib/{rwContext.js → links.test.d.ts} +0 -0

package/dist/runtime/lib/router.d.ts CHANGED Viewed

@@ -1,37 +1,48 @@
-import type { Kysely } from "kysely";
 import React from "react";
 import { RequestInfo } from "../requestInfo/types";
-export type DocumentProps<T extends RequestInfo = RequestInfo> = T & {
-    children: React.ReactNode;
-};
-export type LayoutProps<T extends RequestInfo = RequestInfo> = {
-    children?: React.ReactNode;
-    requestInfo?: T;
-};
-export type RwContext = {
-    nonce: string;
-    Document: React.FC<DocumentProps<any>>;
-    rscPayload: boolean;
-    ssr: boolean;
-    layouts?: React.FC<LayoutProps<any>>[];
-    databases: Map<string, Kysely<any>>;
-    scriptsToBeLoaded: Set<string>;
-    pageRouteResolved: PromiseWithResolvers<void> | undefined;
-    actionResult?: unknown;
-};
-export type RouteMiddleware<T extends RequestInfo = RequestInfo> = (requestInfo: T) => MaybePromise<React.JSX.Element | Response | void>;
-type RouteFunction<T extends RequestInfo = RequestInfo> = (requestInfo: T) => MaybePromise<Response>;
+import type { DocumentProps, LayoutProps } from "./types.js";
 type MaybePromise<T> = T | Promise<T>;
-type RouteComponent<T extends RequestInfo = RequestInfo> = (requestInfo: T) => MaybePromise<React.JSX.Element | Response | void>;
-type RouteHandler<T extends RequestInfo = RequestInfo> = RouteFunction<T> | RouteComponent<T> | [...RouteMiddleware<T>[], RouteFunction<T> | RouteComponent<T>];
-export type Route<T extends RequestInfo = RequestInfo> = RouteMiddleware<T> | RouteDefinition<T> | Array<Route<T>>;
-export type RouteDefinition<T extends RequestInfo = RequestInfo> = {
+type BivariantRouteHandler<T extends RequestInfo, R> = {
+    bivarianceHack(requestInfo: T): R;
+}["bivarianceHack"];
+export type RouteMiddleware<T extends RequestInfo = RequestInfo> = BivariantRouteHandler<T, MaybePromise<React.JSX.Element | Response | void>>;
+type RouteFunction<T extends RequestInfo = RequestInfo> = BivariantRouteHandler<T, MaybePromise<Response>>;
+type RouteComponent<T extends RequestInfo = RequestInfo> = BivariantRouteHandler<T, MaybePromise<React.JSX.Element | Response | void>>;
+type RouteHandler<T extends RequestInfo = RequestInfo> = RouteFunction<T> | RouteComponent<T> | readonly [...RouteMiddleware<T>[], RouteFunction<T> | RouteComponent<T>];
+declare const METHOD_VERBS: readonly ["delete", "get", "head", "patch", "post", "put"];
+export type MethodVerb = (typeof METHOD_VERBS)[number];
+export type MethodHandlers<T extends RequestInfo = RequestInfo> = {
+    [K in MethodVerb]?: RouteHandler<T>;
+} & {
+    config?: {
+        disable405?: true;
+        disableOptions?: true;
+    };
+    custom?: {
+        [method: string]: RouteHandler<T>;
+    };
+};
+export type Route<T extends RequestInfo = RequestInfo> = RouteMiddleware<T> | RouteDefinition<string, T> | readonly Route<T>[];
+type NormalizedRouteDefinition<T extends RequestInfo = RequestInfo> = {
     path: string;
-    handler: RouteHandler<T>;
+    handler: RouteHandler<T> | MethodHandlers<T>;
     layouts?: React.FC<LayoutProps<T>>[];
 };
+export type RouteDefinition<Path extends string = string, T extends RequestInfo = RequestInfo> = NormalizedRouteDefinition<T> & {
+    readonly __rwPath?: Path;
+};
+type TrimTrailingSlash<S extends string> = S extends `${infer Head}/` ? TrimTrailingSlash<Head> : S;
+type TrimLeadingSlash<S extends string> = S extends `/${infer Rest}` ? TrimLeadingSlash<Rest> : S;
+type NormalizePrefix<Prefix extends string> = TrimTrailingSlash<TrimLeadingSlash<Prefix>> extends "" ? "" : `/${TrimTrailingSlash<TrimLeadingSlash<Prefix>>}`;
+type NormalizePath<Path extends string> = TrimTrailingSlash<Path> extends "/" ? "/" : `/${TrimTrailingSlash<TrimLeadingSlash<Path>>}`;
+type JoinPaths<Prefix extends string, Path extends string> = NormalizePrefix<Prefix> extends "" ? NormalizePath<Path> : Path extends "/" ? NormalizePrefix<Prefix> : `${NormalizePrefix<Prefix>}${NormalizePath<Path>}`;
+type PrefixedRouteValue<Prefix extends string, Value> = Value extends RouteDefinition<infer Path, infer Req> ? RouteDefinition<JoinPaths<Prefix, Path>, Req> : Value extends readonly Route<any>[] ? PrefixedRouteArray<Prefix, Value> : Value;
+type PrefixedRouteArray<Prefix extends string, Routes extends readonly Route<any>[]> = Routes extends readonly [] ? [] : Routes extends readonly [infer Head, ...infer Tail] ? readonly [
+    PrefixedRouteValue<Prefix, Head>,
+    ...PrefixedRouteArray<Prefix, Tail extends readonly Route<any>[] ? Tail : []>
+] : ReadonlyArray<PrefixedRouteValue<Prefix, Routes[number]>>;
 export declare function matchPath<T extends RequestInfo = RequestInfo>(routePath: string, requestPath: string): T["params"] | null;
-export declare function defineRoutes<T extends RequestInfo = RequestInfo>(routes: Route<T>[]): {
+export declare function defineRoutes<T extends RequestInfo = RequestInfo>(routes: readonly Route<T>[]): {
     routes: Route<T>[];
     handle: ({ request, renderPage, getRequestInfo, onError, runWithRequestInfoOverrides, rscActionHandler, }: {
         request: Request;
@@ -42,20 +53,126 @@ export declare function defineRoutes<T extends RequestInfo = RequestInfo>(routes
         rscActionHandler: (request: Request) => Promise<unknown>;
     }) => Response | Promise<Response>;
 };
-export declare function route<T extends RequestInfo = RequestInfo>(path: string, handler: RouteHandler<T>): RouteDefinition<T>;
-export declare function index<T extends RequestInfo = RequestInfo>(handler: RouteHandler<T>): RouteDefinition<T>;
-export declare function prefix<T extends RequestInfo = RequestInfo>(prefixPath: string, routes: Route<T>[]): Route<T>[];
+/**
+ * Defines a route handler for a path pattern.
+ *
+ * Supports three types of path patterns:
+ * - Static: /about, /contact
+ * - Parameters: /users/:id, /posts/:postId/edit
+ * - Wildcards: /files/\*, /api/\*\/download
+ *
+ * @example
+ * // Static route
+ * route("/about", () => <AboutPage />)
+ *
+ * @example
+ * // Route with parameters
+ * route("/users/:id", ({ params }) => {
+ *   return <UserProfile userId={params.id} />
+ * })
+ *
+ * @example
+ * // Route with wildcards
+ * route("/files/*", ({ params }) => {
+ *   const filePath = params.$0
+ *   return <FileViewer path={filePath} />
+ * })
+ *
+ * @example
+ * // Method-based routing
+ * route("/api/users", {
+ *   get: () => Response.json(users),
+ *   post: ({ request }) => Response.json({ status: "created" }, { status: 201 }),
+ *   delete: () => new Response(null, { status: 204 }),
+ * })
+ *
+ * @example
+ * // Route with middleware array
+ * route("/admin", [isAuthenticated, isAdmin, () => <AdminDashboard />])
+ */
+export declare function route<Path extends string, T extends RequestInfo = RequestInfo>(path: Path, handler: RouteHandler<T> | MethodHandlers<T>): RouteDefinition<NormalizePath<Path>, T>;
+/**
+ * Defines a route handler for the root path "/".
+ *
+ * @example
+ * // Homepage
+ * index(() => <HomePage />)
+ *
+ * @example
+ * // With middleware
+ * index([logRequest, () => <HomePage />])
+ */
+export declare function index<T extends RequestInfo = RequestInfo>(handler: RouteHandler<T>): RouteDefinition<"/", T>;
+/**
+ * Prefixes a group of routes with a path.
+ *
+ * @example
+ * // Organize blog routes under /blog
+ * const blogRoutes = [
+ *   route("/", () => <BlogIndex />),
+ *   route("/post/:id", ({ params }) => <BlogPost id={params.id} />),
+ *   route("/admin", [isAuthenticated, () => <BlogAdmin />]),
+ * ]
+ *
+ * // In worker.tsx
+ * defineApp([
+ *   render(Document, [
+ *     route("/", () => <HomePage />),
+ *     prefix("/blog", blogRoutes),
+ *   ]),
+ * ])
+ */
+export declare function prefix<Prefix extends string, T extends RequestInfo = RequestInfo, Routes extends readonly Route<T>[] = readonly Route<T>[]>(prefixPath: Prefix, routes: Routes): PrefixedRouteArray<Prefix, Routes>;
 export declare const wrapHandlerToThrowResponses: <T extends RequestInfo = RequestInfo>(handler: RouteFunction<T> | RouteComponent<T>) => RouteHandler<T>;
-export declare function layout<T extends RequestInfo = RequestInfo>(LayoutComponent: React.FC<LayoutProps<T>>, routes: Route<T>[]): Route<T>[];
-export declare function render<T extends RequestInfo = RequestInfo>(Document: React.FC<DocumentProps<T>>, routes: Route<T>[],
 /**
- * @param options - Configuration options for rendering.
+ * Wraps routes with a layout component.
+ *
+ * @example
+ * // Define a layout component
+ * function BlogLayout({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <div>
+ *       <nav>Blog Navigation</nav>
+ *       <main>{children}</main>
+ *     </div>
+ *   )
+ * }
+ *
+ * // Apply layout to routes
+ * const blogRoutes = layout(BlogLayout, [
+ *   route("/", () => <BlogIndex />),
+ *   route("/post/:id", ({ params }) => <BlogPost id={params.id} />),
+ * ])
+ */
+export declare function layout<T extends RequestInfo = RequestInfo, Routes extends readonly Route<T>[] = readonly Route<T>[]>(LayoutComponent: React.FC<LayoutProps<T>>, routes: Routes): Routes;
+/**
+ * Wraps routes with a Document component and configures rendering options.
+ *
  * @param options.rscPayload - Toggle the RSC payload that's appended to the Document. Disabling this will mean that interactivity no longer works.
- * @param options.ssr - Disable sever side rendering for all these routes. This only allow client side rendering`, which requires `rscPayload` to be enabled.
+ * @param options.ssr - Disable sever side rendering for all these routes. This only allow client side rendering, which requires `rscPayload` to be enabled.
+ *
+ * @example
+ * // Basic usage
+ * defineApp([
+ *   render(Document, [
+ *     route("/", () => <HomePage />),
+ *     route("/about", () => <AboutPage />),
+ *   ]),
+ * ])
+ *
+ * @example
+ * // With custom rendering options
+ * render(Document, [
+ *   route("/", () => <HomePage />),
+ * ], {
+ *   rscPayload: true,
+ *   ssr: true,
+ * })
  */
-options?: {
+type RenderedRoutes<T extends RequestInfo, Routes extends readonly Route<T>[]> = readonly [RouteMiddleware<T>, ...Routes];
+export declare function render<T extends RequestInfo = RequestInfo, Routes extends readonly Route<T>[] = readonly Route<T>[]>(Document: React.FC<DocumentProps<T>>, routes: Routes, options?: {
     rscPayload?: boolean;
     ssr?: boolean;
-}): Route<T>[];
+}): RenderedRoutes<T, Routes>;
 export declare const isClientReference: (value: any) => boolean;
 export {};

package/dist/runtime/lib/router.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import React from "react";
 import { isValidElementType } from "react-is";
+const METHOD_VERBS = ["delete", "get", "head", "patch", "post", "put"];
 export function matchPath(routePath, requestPath) {
     // Check for invalid pattern: multiple colons in a segment (e.g., /:param1:param2/)
     if (routePath.includes(":")) {
@@ -60,6 +61,38 @@ function flattenRoutes(routes) {
         return [...acc, route];
     }, []);
 }
+function isMethodHandlers(handler) {
+    return (typeof handler === "object" && handler !== null && !Array.isArray(handler));
+}
+function handleOptionsRequest(methodHandlers) {
+    const methods = new Set([
+        ...(methodHandlers.config?.disableOptions ? [] : ["OPTIONS"]),
+        ...METHOD_VERBS.filter((verb) => methodHandlers[verb]).map((verb) => verb.toUpperCase()),
+        ...Object.keys(methodHandlers.custom ?? {}).map((method) => method.toUpperCase()),
+    ]);
+    return new Response(null, {
+        status: 204,
+        headers: {
+            Allow: Array.from(methods).sort().join(", "),
+        },
+    });
+}
+function handleMethodNotAllowed(methodHandlers) {
+    const optionsResponse = handleOptionsRequest(methodHandlers);
+    return new Response("Method Not Allowed", {
+        status: 405,
+        headers: optionsResponse.headers,
+    });
+}
+function getHandlerForMethod(methodHandlers, method) {
+    const lowerMethod = method.toLowerCase();
+    // Check standard method verbs
+    if (METHOD_VERBS.includes(lowerMethod)) {
+        return methodHandlers[lowerMethod];
+    }
+    // Check custom methods (already normalized to lowercase)
+    return methodHandlers.custom?.[lowerMethod];
+}
 export function defineRoutes(routes) {
     const flattenedRoutes = flattenRoutes(routes);
     return {
@@ -125,9 +158,32 @@ export function defineRoutes(routes) {
                 if (!params) {
                     continue; // Not a match, keep going.
                 }
+                // Resolve handler if method-based routing
+                let handler;
+                if (isMethodHandlers(route.handler)) {
+                    const requestMethod = request.method;
+                    // Handle OPTIONS request
+                    if (requestMethod === "OPTIONS" &&
+                        !route.handler.config?.disableOptions) {
+                        return handleOptionsRequest(route.handler);
+                    }
+                    // Try to find handler for the request method
+                    handler = getHandlerForMethod(route.handler, requestMethod);
+                    if (!handler) {
+                        // Method not supported for this route
+                        if (!route.handler.config?.disable405) {
+                            return handleMethodNotAllowed(route.handler);
+                        }
+                        // If 405 is disabled, continue to next route
+                        continue;
+                    }
+                }
+                else {
+                    handler = route.handler;
+                }
                 // Found a match: run route-specific middlewares, then the final component, then stop.
                 return await runWithRequestInfoOverrides({ params }, async () => {
-                    const { routeMiddlewares, componentHandler } = parseHandlers(route.handler);
+                    const { routeMiddlewares, componentHandler } = parseHandlers(handler);
                     // Route-specific middlewares
                     for (const mw of routeMiddlewares) {
                         const result = await mw(getRequestInfo());
@@ -165,20 +221,99 @@ export function defineRoutes(routes) {
         },
     };
 }
+/**
+ * Defines a route handler for a path pattern.
+ *
+ * Supports three types of path patterns:
+ * - Static: /about, /contact
+ * - Parameters: /users/:id, /posts/:postId/edit
+ * - Wildcards: /files/\*, /api/\*\/download
+ *
+ * @example
+ * // Static route
+ * route("/about", () => <AboutPage />)
+ *
+ * @example
+ * // Route with parameters
+ * route("/users/:id", ({ params }) => {
+ *   return <UserProfile userId={params.id} />
+ * })
+ *
+ * @example
+ * // Route with wildcards
+ * route("/files/*", ({ params }) => {
+ *   const filePath = params.$0
+ *   return <FileViewer path={filePath} />
+ * })
+ *
+ * @example
+ * // Method-based routing
+ * route("/api/users", {
+ *   get: () => Response.json(users),
+ *   post: ({ request }) => Response.json({ status: "created" }, { status: 201 }),
+ *   delete: () => new Response(null, { status: 204 }),
+ * })
+ *
+ * @example
+ * // Route with middleware array
+ * route("/admin", [isAuthenticated, isAdmin, () => <AdminDashboard />])
+ */
 export function route(path, handler) {
-    if (!path.endsWith("/")) {
-        path = path + "/";
+    let normalizedPath = path;
+    if (!normalizedPath.endsWith("/")) {
+        normalizedPath = normalizedPath + "/";
+    }
+    // Normalize custom method keys to lowercase
+    if (isMethodHandlers(handler) && handler.custom) {
+        handler = {
+            ...handler,
+            custom: Object.fromEntries(Object.entries(handler.custom).map(([method, methodHandler]) => [
+                method.toLowerCase(),
+                methodHandler,
+            ])),
+        };
     }
     return {
-        path,
+        path: normalizedPath,
         handler,
+        __rwPath: normalizedPath,
     };
 }
+/**
+ * Defines a route handler for the root path "/".
+ *
+ * @example
+ * // Homepage
+ * index(() => <HomePage />)
+ *
+ * @example
+ * // With middleware
+ * index([logRequest, () => <HomePage />])
+ */
 export function index(handler) {
     return route("/", handler);
 }
+/**
+ * Prefixes a group of routes with a path.
+ *
+ * @example
+ * // Organize blog routes under /blog
+ * const blogRoutes = [
+ *   route("/", () => <BlogIndex />),
+ *   route("/post/:id", ({ params }) => <BlogPost id={params.id} />),
+ *   route("/admin", [isAuthenticated, () => <BlogAdmin />]),
+ * ]
+ *
+ * // In worker.tsx
+ * defineApp([
+ *   render(Document, [
+ *     route("/", () => <HomePage />),
+ *     prefix("/blog", blogRoutes),
+ *   ]),
+ * ])
+ */
 export function prefix(prefixPath, routes) {
-    return routes.map((r) => {
+    const prefixed = routes.map((r) => {
         if (typeof r === "function") {
             const middleware = (requestInfo) => {
                 const url = new URL(requestInfo.request.url);
@@ -193,13 +328,14 @@ export function prefix(prefixPath, routes) {
             // Recursively process nested route arrays
             return prefix(prefixPath, r);
         }
-        // For RouteDefinition objects, update the path and preserve layouts
+        const routeDef = r;
         return {
-            path: prefixPath + r.path,
-            handler: r.handler,
-            ...(r.layouts && { layouts: r.layouts }),
+            path: prefixPath + routeDef.path,
+            handler: routeDef.handler,
+            ...(routeDef.layouts && { layouts: routeDef.layouts }),
         };
     });
+    return prefixed;
 }
 function wrapWithLayouts(Component, layouts = [], requestInfo) {
     if (layouts.length === 0) {
@@ -242,8 +378,27 @@ export const wrapHandlerToThrowResponses = (handler) => {
     ComponentWrappedToThrowResponses.__rwsdk_route_component = true;
     return ComponentWrappedToThrowResponses;
 };
+/**
+ * Wraps routes with a layout component.
+ *
+ * @example
+ * // Define a layout component
+ * function BlogLayout({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <div>
+ *       <nav>Blog Navigation</nav>
+ *       <main>{children}</main>
+ *     </div>
+ *   )
+ * }
+ *
+ * // Apply layout to routes
+ * const blogRoutes = layout(BlogLayout, [
+ *   route("/", () => <BlogIndex />),
+ *   route("/post/:id", ({ params }) => <BlogPost id={params.id} />),
+ * ])
+ */
 export function layout(LayoutComponent, routes) {
-    // Attach layouts directly to route definitions
     return routes.map((route) => {
         if (typeof route === "function") {
             // Pass through middleware as-is
@@ -253,20 +408,14 @@ export function layout(LayoutComponent, routes) {
             // Recursively process nested route arrays
             return layout(LayoutComponent, route);
         }
-        // For RouteDefinition objects, prepend the layout so outer layouts come first
+        const routeDef = route;
         return {
-            ...route,
-            layouts: [LayoutComponent, ...(route.layouts || [])],
+            ...routeDef,
+            layouts: [LayoutComponent, ...(routeDef.layouts || [])],
         };
     });
 }
-export function render(Document, routes,
-/**
- * @param options - Configuration options for rendering.
- * @param options.rscPayload - Toggle the RSC payload that's appended to the Document. Disabling this will mean that interactivity no longer works.
- * @param options.ssr - Disable sever side rendering for all these routes. This only allow client side rendering`, which requires `rscPayload` to be enabled.
- */
-options = {}) {
+export function render(Document, routes, options = {}) {
     options = {
         rscPayload: true,
         ssr: true,