rwsdk 1.0.0-beta.5 → 1.0.0-beta.50

package/dist/runtime/lib/links.js

@@ -1,38 +1,96 @@
+export function linkFor() {
+    return createLinkFunction();
+}
+export function createLinks(_app) {
+    return linkFor();
+}
+// Implementation
 export function defineLinks(routes) {
-    // Validate routes at runtime
+    // If no routes provided, this is the app type overload
+    // At runtime, we can't distinguish, but the type system ensures
+    // this only happens when called as defineLinks<App>()
+    // We delegate to linkFor which handles app types correctly
+    if (routes === undefined) {
+        // This branch is only reachable when called as defineLinks<App>()
+        // The return type is AppLink<App> due to the overload
+        // We use linkFor internally which doesn't need runtime route validation
+        return linkFor();
+    }
+    // Original implementation for route arrays
     routes.forEach((route) => {
         if (typeof route !== "string") {
-            throw new Error(`Invalid route: ${route}. Routes must be strings.`);
+            throw new Error(`RedwoodSDK: Invalid route: ${route}. Routes must be string literals. Ensure you're passing an array of route paths.`);
         }
     });
-    return (path, params) => {
+    const link = createLinkFunction();
+    return ((path, params) => {
         if (!routes.includes(path)) {
-            throw new Error(`Invalid route: ${path}`);
+            throw new Error(`RedwoodSDK: Invalid route: ${path}. This route is not included in the routes array passed to defineLinks(). Check for typos or ensure the route is defined in your router.`);
         }
-        if (!params)
+        return link(path, params);
+    });
+}
+const TOKEN_REGEX = /:([a-zA-Z0-9_]+)|\*/g;
+function createLinkFunction() {
+    return ((path, params) => {
+        const expectsParams = hasRouteParameters(path);
+        if (!params || Object.keys(params).length === 0) {
+            if (expectsParams) {
+                throw new Error(`RedwoodSDK: Route ${path} requires an object of parameters (e.g., link("${path}", { id: "123" })).`);
+            }
             return path;
-        let result = path;
-        // Replace named parameters
-        for (const [key, value] of Object.entries(params)) {
-            if (key.startsWith("$")) {
-                // Replace each star with its corresponding $ parameter
-                const starIndex = parseInt(key.slice(1));
-                const stars = result.match(/\*/g) || [];
-                if (starIndex >= stars.length) {
-                    throw new Error(`Parameter ${key} has no corresponding * in route`);
-                }
-                // Replace the nth star with the value
-                let count = 0;
-                result = result.replace(/\*/g, (match) => count++ === starIndex ? value : match);
+        }
+        return interpolate(path, params);
+    });
+}
+function hasRouteParameters(path) {
+    TOKEN_REGEX.lastIndex = 0;
+    const result = TOKEN_REGEX.test(path);
+    TOKEN_REGEX.lastIndex = 0;
+    return result;
+}
+function interpolate(template, params) {
+    let result = "";
+    let lastIndex = 0;
+    let wildcardIndex = 0;
+    const consumed = new Set();
+    TOKEN_REGEX.lastIndex = 0;
+    let match;
+    while ((match = TOKEN_REGEX.exec(template)) !== null) {
+        result += template.slice(lastIndex, match.index);
+        if (match[1]) {
+            const name = match[1];
+            const value = params[name];
+            if (value === undefined) {
+                throw new Error(`RedwoodSDK: Missing parameter "${name}" for route ${template}. Ensure you're providing all required parameters in the params object.`);
             }
-            else {
-                // Handle named parameters
-                if (typeof value !== "string") {
-                    throw new Error(`Parameter ${key} must be a string`);
-                }
-                result = result.replace(`:${key}`, value);
+            result += encodeURIComponent(value);
+            consumed.add(name);
+        }
+        else {
+            const key = `$${wildcardIndex}`;
+            const value = params[key];
+            if (value === undefined) {
+                throw new Error(`RedwoodSDK: Missing parameter "${key}" for route ${template}. Wildcard routes use $0, $1, etc. as parameter keys.`);
             }
+            result += encodeWildcardValue(value);
+            consumed.add(key);
+            wildcardIndex += 1;
+        }
+        lastIndex = TOKEN_REGEX.lastIndex;
+    }
+    result += template.slice(lastIndex);
+    for (const key of Object.keys(params)) {
+        if (!consumed.has(key)) {
+            throw new Error(`RedwoodSDK: Parameter "${key}" is not used by route ${template}. Check your params object for typos or remove unused parameters.`);
         }
-        return result;
-    };
+    }
+    TOKEN_REGEX.lastIndex = 0;
+    return result;
+}
+function encodeWildcardValue(value) {
+    return value
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
 }

package/dist/runtime/lib/links.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/lib/links.test.js

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { defineLinks } from "./links";
+const link = defineLinks(["/", "/users/:id", "/files/*"]);
+describe("link helpers", () => {
+    it("returns static routes without parameters", () => {
+        expect(link("/")).toBe("/");
+    });
+    it("replaces named parameters with encoded values", () => {
+        expect(link("/users/:id", { id: "user id" })).toBe("/users/user%20id");
+    });
+    it("replaces wildcard parameters preserving path segments", () => {
+        expect(link("/files/*", { $0: "docs/Guide Document.md" })).toBe("/files/docs/Guide%20Document.md");
+    });
+    it("throws when parameters are missing", () => {
+        expect(() => link("/users/:id")).toThrowError(/requires an object of parameters/i);
+    });
+    it("throws when extra parameters are supplied", () => {
+        expect(() => link("/users/:id", { id: "123", extra: "value" })).toThrowError(/is not used by route/i);
+    });
+});

package/dist/runtime/lib/manifest.d.ts

@@ -8,4 +8,4 @@ export interface ManifestChunk {
     css?: string[];
     assets?: string[];
 }
-export declare const getManifest: () => Promise<Manifest>;
+export declare function getManifest(): Promise<Manifest>;

package/dist/runtime/lib/manifest.js

@@ -1,14 +1,17 @@
 let manifest;
-export const getManifest = async () => {
+export async function getManifest() {
     if (manifest) {
         return manifest;
     }
     if (import.meta.env.VITE_IS_DEV_SERVER) {
+        // In dev, there's no manifest, so we can use an empty object.
         manifest = {};
     }
     else {
-        const { default: prodManifest } = await import("virtual:rwsdk:manifest.js");
-        manifest = prodManifest;
+        // context(justinvdm, 2 Oct 2025): In production, the manifest is a
+        // placeholder string that will be replaced by the linker plugin with the
+        // actual manifest JSON object.
+        manifest = "__RWSDK_MANIFEST_PLACEHOLDER__";
     }
     return manifest;
-};
+}

package/dist/runtime/lib/realtime/client.js

@@ -1,7 +1,15 @@
-import { createFromReadableStream } from "react-server-dom-webpack/client.browser";
+// context(justinvdm, 14 Aug 2025): `react-server-dom-webpack` uses this globa ___webpack_require__ global,
+// so we need to import our client entry point (which sets it), before importing
+// prettier-ignore
 import { initClient } from "../../client/client";
-import { packMessage, unpackMessage, } from "./protocol";
+// prettier-ignore
+import { isActionResponse, } from "../../client/types";
+// prettier-ignore
+import { createFromReadableStream } from "react-server-dom-webpack/client.browser";
+// prettier-ignore
 import { MESSAGE_TYPE } from "./shared";
+// prettier-ignore
+import { packMessage, unpackMessage, } from "./protocol";
 const DEFAULT_KEY = "default";
 export const initRealtimeClient = ({ key = DEFAULT_KEY, handleResponse, } = {}) => {
     const transport = realtimeTransport({ key, handleResponse });
@@ -50,7 +58,7 @@ export const realtimeTransport = ({ key = DEFAULT_KEY, handleResponse, }) => (tr
         }
         return ws;
     };
-    const realtimeCallServer = async (id, args) => {
+    const realtimeCallServer = async (id, args, _source, _method) => {
         try {
             const socket = ensureWs();
             const { encodeReply } = await import("react-server-dom-webpack/client.browser");
@@ -74,7 +82,7 @@ export const realtimeTransport = ({ key = DEFAULT_KEY, handleResponse, }) => (tr
         }
         catch (e) {
             console.error("[Realtime] Error calling server", e);
-            return null;
+            return undefined;
         }
     };
     const processResponse = async (response) => {
@@ -91,13 +99,27 @@ export const realtimeTransport = ({ key = DEFAULT_KEY, handleResponse, }) => (tr
                 streamForRsc = response.body;
             }
             if (!shouldContinue) {
-                return null;
+                return undefined;
             }
             const rscPayload = createFromReadableStream(streamForRsc, {
                 callServer: realtimeCallServer,
             });
             transportContext.setRscPayload(rscPayload);
-            return (await rscPayload).actionResult;
+            const rawActionResult = (await rscPayload).actionResult;
+            if (isActionResponse(rawActionResult)) {
+                const actionResponse = rawActionResult.__rw_action_response;
+                const handledByHook = transportContext.onActionResponse?.(actionResponse) === true;
+                if (!handledByHook) {
+                    const location = actionResponse.headers["location"];
+                    const isRedirect = actionResponse.status >= 300 && actionResponse.status < 400;
+                    if (location && isRedirect) {
+                        window.location.href = location;
+                        return undefined;
+                    }
+                }
+                return rawActionResult;
+            }
+            return rawActionResult;
         }
         catch (err) {
             throw err;

package/dist/runtime/lib/realtime/worker.d.ts

@@ -1,3 +1,3 @@
 import type { RealtimeDurableObject } from "./durableObject";
 export { renderRealtimeClients } from "./renderRealtimeClients";
-export declare const realtimeRoute: (getDurableObjectNamespace: (env: Cloudflare.Env) => DurableObjectNamespace<RealtimeDurableObject>) => import("../router").RouteDefinition<import("../../worker").RequestInfo<any, import("../../worker").DefaultAppContext>>;
+export declare const realtimeRoute: (getDurableObjectNamespace: (env: Cloudflare.Env) => DurableObjectNamespace<RealtimeDurableObject>) => import("../router").RouteDefinition<"/__realtime", import("../../worker").RequestInfo<any, import("../../worker").DefaultAppContext>>;

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

@@ -1,37 +1,52 @@
-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;
+import type { DocumentProps, LayoutProps } from "./types.js";
+type MaybePromise<T> = T | Promise<T>;
+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>>;
+export type ExceptHandler<T extends RequestInfo = RequestInfo> = {
+    __rwExcept: true;
+    handler: (error: unknown, requestInfo: T) => MaybePromise<React.JSX.Element | Response | void>;
 };
-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;
+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 RouteMiddleware<T extends RequestInfo = RequestInfo> = (requestInfo: T) => MaybePromise<React.JSX.Element | Response | void>;
-type RouteFunction<T extends RequestInfo = RequestInfo> = (requestInfo: T) => MaybePromise<Response>;
-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> = {
+export type Route<T extends RequestInfo = RequestInfo> = RouteMiddleware<T> | RouteDefinition<string, T> | ExceptHandler<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 ExceptHandler<any> ? Value : 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 +57,124 @@ 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>;
+/**
+ * Defines an error handler that catches errors from routes, middleware, and RSC actions.
+ *
+ * @example
+ * // Global error handler
+ * except((error, requestInfo) => {
+ *   console.error(error);
+ *   return new Response("Internal Server Error", { status: 500 });
+ * })
+ *
+ * @example
+ * // Error handler that returns a React component
+ * except((error) => {
+ *   return <ErrorPage error={error} />;
+ * })
+ */
+export declare function except<T extends RequestInfo = RequestInfo>(handler: (error: unknown, requestInfo: T) => MaybePromise<React.JSX.Element | Response | void>): ExceptHandler<T>;
+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 {};