rwsdk 1.0.0-beta.25 → 1.0.0-beta.27

package/dist/runtime/client/client.d.ts

@@ -4,6 +4,39 @@ export { ClientOnly } from "./ClientOnly.js";
 export { initClientNavigation, navigate } from "./navigation.js";
 import type { HydrationOptions, Transport } from "./types";
 export declare const fetchTransport: Transport;
+/**
+ * Initializes the React client and hydrates the RSC payload.
+ *
+ * This function sets up client-side hydration for React Server Components,
+ * making the page interactive. Call this from your client entry point.
+ *
+ * @param transport - Custom transport for server communication (defaults to fetchTransport)
+ * @param hydrateRootOptions - Options passed to React's hydrateRoot
+ * @param handleResponse - Custom response handler for navigation errors
+ *
+ * @example
+ * // Basic usage
+ * import { initClient } from "rwsdk/client";
+ *
+ * initClient();
+ *
+ * @example
+ * // With client-side navigation
+ * import { initClient, initClientNavigation } from "rwsdk/client";
+ *
+ * const { handleResponse } = initClientNavigation();
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // With custom React hydration options
+ * initClient({
+ *   hydrateRootOptions: {
+ *     onRecoverableError: (error) => {
+ *       console.warn("Recoverable error:", error);
+ *     },
+ *   },
+ * });
+ */
 export declare const initClient: ({ transport, hydrateRootOptions, handleResponse, }?: {
     transport?: Transport;
     hydrateRootOptions?: HydrationOptions;

package/dist/runtime/client/client.js

@@ -50,6 +50,39 @@ export const fetchTransport = (transportContext) => {
     };
     return fetchCallServer;
 };
+/**
+ * Initializes the React client and hydrates the RSC payload.
+ *
+ * This function sets up client-side hydration for React Server Components,
+ * making the page interactive. Call this from your client entry point.
+ *
+ * @param transport - Custom transport for server communication (defaults to fetchTransport)
+ * @param hydrateRootOptions - Options passed to React's hydrateRoot
+ * @param handleResponse - Custom response handler for navigation errors
+ *
+ * @example
+ * // Basic usage
+ * import { initClient } from "rwsdk/client";
+ *
+ * initClient();
+ *
+ * @example
+ * // With client-side navigation
+ * import { initClient, initClientNavigation } from "rwsdk/client";
+ *
+ * const { handleResponse } = initClientNavigation();
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // With custom React hydration options
+ * initClient({
+ *   hydrateRootOptions: {
+ *     onRecoverableError: (error) => {
+ *       console.warn("Recoverable error:", error);
+ *     },
+ *   },
+ * });
+ */
 export const initClient = async ({ transport = fetchTransport, hydrateRootOptions, handleResponse, } = {}) => {
     const transportContext = {
         setRscPayload: () => { },

package/dist/runtime/client/navigation.d.ts

@@ -12,6 +12,47 @@ export interface NavigateOptions {
     };
 }
 export declare function navigate(href: string, options?: NavigateOptions): Promise<void>;
+/**
+ * Initializes client-side navigation for Single Page App (SPA) behavior.
+ *
+ * Intercepts clicks on internal links and fetches page content without full-page reloads.
+ * Returns a handleResponse function to pass to initClient.
+ *
+ * @param opts.scrollToTop - Scroll to top after navigation (default: true)
+ * @param opts.scrollBehavior - How to scroll: 'instant', 'smooth', or 'auto' (default: 'instant')
+ * @param opts.onNavigate - Callback executed after history push but before RSC fetch
+ *
+ * @example
+ * // Basic usage
+ * import { initClient, initClientNavigation } from "rwsdk/client";
+ *
+ * const { handleResponse } = initClientNavigation();
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // With custom scroll behavior
+ * const { handleResponse } = initClientNavigation({
+ *   scrollBehavior: "smooth",
+ *   scrollToTop: true,
+ * });
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // Preserve scroll position (e.g., for infinite scroll)
+ * const { handleResponse } = initClientNavigation({
+ *   scrollToTop: false,
+ * });
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // With navigation callback
+ * const { handleResponse } = initClientNavigation({
+ *   onNavigate: () => {
+ *     console.log("Navigating to:", window.location.href);
+ *   },
+ * });
+ * initClient({ handleResponse });
+ */
 export declare function initClientNavigation(opts?: ClientNavigationOptions): {
     handleResponse: (response: Response) => boolean;
 };

package/dist/runtime/client/navigation.js

@@ -64,6 +64,47 @@ function saveScrollPosition(x, y) {
         scrollY: y,
     }, "", window.location.href);
 }
+/**
+ * Initializes client-side navigation for Single Page App (SPA) behavior.
+ *
+ * Intercepts clicks on internal links and fetches page content without full-page reloads.
+ * Returns a handleResponse function to pass to initClient.
+ *
+ * @param opts.scrollToTop - Scroll to top after navigation (default: true)
+ * @param opts.scrollBehavior - How to scroll: 'instant', 'smooth', or 'auto' (default: 'instant')
+ * @param opts.onNavigate - Callback executed after history push but before RSC fetch
+ *
+ * @example
+ * // Basic usage
+ * import { initClient, initClientNavigation } from "rwsdk/client";
+ *
+ * const { handleResponse } = initClientNavigation();
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // With custom scroll behavior
+ * const { handleResponse } = initClientNavigation({
+ *   scrollBehavior: "smooth",
+ *   scrollToTop: true,
+ * });
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // Preserve scroll position (e.g., for infinite scroll)
+ * const { handleResponse } = initClientNavigation({
+ *   scrollToTop: false,
+ * });
+ * initClient({ handleResponse });
+ *
+ * @example
+ * // With navigation callback
+ * const { handleResponse } = initClientNavigation({
+ *   onNavigate: () => {
+ *     console.log("Navigating to:", window.location.href);
+ *   },
+ * });
+ * initClient({ handleResponse });
+ */
 export function initClientNavigation(opts = {}) {
     IS_CLIENT_NAVIGATION = true;
     history.scrollRestoration = "auto";

package/dist/runtime/lib/db/SqliteDurableObject.d.ts

@@ -1,11 +1,11 @@
 import { DurableObject } from "cloudflare:workers";
-import { Kysely, QueryResult } from "kysely";
+import { Kysely, KyselyPlugin, QueryResult } from "kysely";
 export declare class SqliteDurableObject<T = any> extends DurableObject {
     migrations: Record<string, any>;
     kysely: Kysely<T>;
     private initialized;
     private migrationTableName;
-    constructor(ctx: DurableObjectState, env: any, migrations: Record<string, any>, migrationTableName?: string);
+    constructor(ctx: DurableObjectState, env: any, migrations: Record<string, any>, migrationTableName?: string, plugins?: KyselyPlugin[]);
     initialize(): Promise<void>;
     kyselyExecuteQuery<R>(compiledQuery: {
         sql: string;

package/dist/runtime/lib/db/SqliteDurableObject.js

@@ -6,14 +6,14 @@ import { createMigrator } from "./index.js";
 const log = debug("sdk:do-db");
 // Base class for Durable Objects that need Kysely database access
 export class SqliteDurableObject extends DurableObject {
-    constructor(ctx, env, migrations, migrationTableName = "__migrations") {
+    constructor(ctx, env, migrations, migrationTableName = "__migrations", plugins = [new ParseJSONResultsPlugin()]) {
         super(ctx, env);
         this.initialized = false;
         this.migrations = migrations;
         this.migrationTableName = migrationTableName;
         this.kysely = new Kysely({
             dialect: new DODialect({ ctx }),
-            plugins: [new ParseJSONResultsPlugin()],
+            plugins: plugins,
         });
     }
     async initialize() {

package/dist/runtime/lib/db/typeInference/builders/columnDefinition.d.ts

@@ -1,5 +1,5 @@
 import { ColumnDefinitionNode, Expression, sql } from "kysely";
-type DefaultValueExpression = string | number | boolean | null | typeof sql;
+type DefaultValueExpression = string | number | boolean | null | ReturnType<typeof sql>;
 export interface ColumnDefinitionBuilder<TType> {
     autoIncrement(): ColumnDefinitionBuilder<TType>;
     identity(): ColumnDefinitionBuilder<TType>;

package/dist/runtime/lib/db/typeInference/typetests/createTable.typetest.js

@@ -1,3 +1,4 @@
+import { sql } from "kysely";
 (_it = "createTable") => {
     const migrations = {
         "001_init": {
@@ -23,6 +24,7 @@
                         .addColumn("username", "text", (col) => col.notNull())
                         .addColumn("age", "integer", (col) => col.defaultTo(18))
                         .addColumn("active", "boolean", (col) => col.defaultTo(true))
+                        .addColumn("anotherBoolean", "boolean", (col) => col.defaultTo(sql `true`))
                         .execute(),
                 ];
             },
@@ -30,4 +32,3 @@
     };
     (_test) => { };
 };
-export {};

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

@@ -10,5 +10,23 @@ type ParseRoute<T extends string> = T extends `${infer Start}:${infer Param}/${i
 type LinkFunction<T extends readonly string[]> = {
     <Path extends T[number]>(path: Path, params?: ParseRoute<Path> extends Record<string, never> ? undefined : ParseRoute<Path>): string;
 };
+/**
+ * Creates a type-safe link generation function from route patterns.
+ *
+ * @example
+ * // Define your routes
+ * const link = defineLinks([
+ *   "/",
+ *   "/about",
+ *   "/users/:id",
+ *   "/files/*",
+ * ] as const)
+ *
+ * // Generate links with type checking
+ * link("/")                                  // "/"
+ * link("/about")                             // "/about"
+ * link("/users/:id", { id: "123" })          // "/users/123"
+ * link("/files/*", { $0: "docs/guide.pdf" }) // "/files/docs/guide.pdf"
+ */
 export declare function defineLinks<const T extends readonly string[]>(routes: T): LinkFunction<T>;
 export {};

package/dist/runtime/lib/links.js

@@ -1,3 +1,21 @@
+/**
+ * Creates a type-safe link generation function from route patterns.
+ *
+ * @example
+ * // Define your routes
+ * const link = defineLinks([
+ *   "/",
+ *   "/about",
+ *   "/users/:id",
+ *   "/files/*",
+ * ] as const)
+ *
+ * // Generate links with type checking
+ * link("/")                                  // "/"
+ * link("/about")                             // "/about"
+ * link("/users/:id", { id: "123" })          // "/users/123"
+ * link("/files/*", { $0: "docs/guide.pdf" }) // "/files/docs/guide.pdf"
+ */
 export function defineLinks(routes) {
     // Validate routes at runtime
     routes.forEach((route) => {

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

@@ -5,7 +5,7 @@ export type RouteMiddleware<T extends RequestInfo = RequestInfo> = (requestInfo:
 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>];
+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> = {
@@ -37,18 +37,123 @@ export declare function defineRoutes<T extends RequestInfo = RequestInfo>(routes
         rscActionHandler: (request: Request) => Promise<unknown>;
     }) => Response | Promise<Response>;
 };
+/**
+ * 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<T extends RequestInfo = RequestInfo>(path: string, handler: RouteHandler<T> | MethodHandlers<T>): RouteDefinition<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<T extends RequestInfo = RequestInfo>(prefixPath: string, routes: Route<T>[]): Route<T>[];
 export declare const wrapHandlerToThrowResponses: <T extends RequestInfo = RequestInfo>(handler: RouteFunction<T> | RouteComponent<T>) => RouteHandler<T>;
+/**
+ * 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>(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 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?: {
+export declare function render<T extends RequestInfo = RequestInfo>(Document: React.FC<DocumentProps<T>>, routes: Route<T>[], options?: {
     rscPayload?: boolean;
     ssr?: boolean;
 }): Route<T>[];

package/dist/runtime/lib/router.js

@@ -221,6 +221,43 @@ 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 + "/";
@@ -240,9 +277,39 @@ export function route(path, handler) {
         handler,
     };
 }
+/**
+ * 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) => {
         if (typeof r === "function") {
@@ -308,6 +375,26 @@ 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) => {
@@ -326,13 +413,31 @@ export function layout(LayoutComponent, routes) {
         };
     });
 }
-export function render(Document, routes, 
 /**
- * @param options - Configuration options for rendering.
+ * 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 = {}) {
+export function render(Document, routes, options = {}) {
     options = {
         rscPayload: true,
         ssr: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rwsdk",
-  "version": "1.0.0-beta.25",
+  "version": "1.0.0-beta.27",
   "description": "Build fast, server-driven webapps on Cloudflare with SSR, RSC, and realtime",
   "type": "module",
   "bin": {
@@ -196,7 +196,7 @@
     "semver": "~7.7.1",
     "tsx": "~4.20.0",
     "typescript": "~5.9.0",
-    "vite": "~7.1.9",
+    "vite": "~7.2.0",
     "vitest": "~3.2.0"
   }
 }