weifuwu 0.30.2 → 0.31.0

package/README.md

@@ -169,6 +169,121 @@ const gql = graphql((req, ctx) => ({
 app.mount('/graphql', gql)
 ```
 
+### React SSR
+
+> Requires `react >= 19`, `react-dom >= 19` (optional peerDependencies).
+
+```bash
+npm install react react-dom
+```
+
+```ts
+import { react, Link, useServerData, ErrorBoundary } from 'weifuwu'
+import { createElement as h } from 'react'
+
+// ── Server ──────────────────────────────────────────────
+
+app.use(react({
+  layout: ({ children }) =>
+    h('html', null,
+      h('head', null, h('title', null, 'My App')),
+      h('body', null, h('div', { id: 'root' }, children)),
+    ),
+}))
+
+// Render React components to HTML
+app.get('/', (_req, ctx) =>
+  ctx.render(h('h1', null, 'Hello SSR'), {
+    head: { title: 'Home' },
+    data: { greeting: 'Hello' },
+  })
+)
+
+// Streaming SSR
+app.get('/dashboard', (_req, ctx) =>
+  ctx.renderStream(h(Dashboard))
+)
+
+// Layout nesting via mount
+const admin = new Router()
+admin.use(react({ layout: AdminLayout }))
+admin.get('/dashboard', (_req, ctx) => ctx.render(h(AdminDashboard)))
+app.mount('/admin', admin)
+
+// ── Shared components ──────────────────────────────────
+
+// Use the same component on server and client
+function Page() {
+  const { greeting } = useServerData<{ greeting: string }>()
+  return h('h1', null, greeting)
+}
+
+// Link works on both sides: <a> on server, SPA <a> on client
+function Nav() {
+  return h('nav', null,
+    h(Link, { href: '/' }, 'Home'),
+    h(Link, { href: '/users' }, 'Users'),
+  )
+}
+
+// ErrorBoundary catches client-side render errors
+function SafeUserProfile() {
+  return h(ErrorBoundary, { fallback: h('div', null, 'Error') },
+    h(UserProfile),
+  )
+}
+
+// ── Client (SPA navigation) ────────────────────────────
+
+// client.ts — bundled separately with esbuild
+import { hydrate, createClientRouter, defineRoute } from 'weifuwu/react/client'
+
+const userRoute = defineRoute({
+  path: '/users/:id',
+  component: UserPage,
+  loader: (params) => fetch(`/users/${params.id}?_data`).then(r => r.json()),
+})
+
+const router = createClientRouter([
+  { path: '/', component: HomePage },
+  userRoute,
+])
+
+hydrate(router.App)
+```
+
+**Key concepts:**
+
+| Feature | Description |
+|---|---|
+| `ctx.render(el, opts)` | Render React to HTML. Auto-detects `?_data` → returns JSON. |
+| `ctx.renderStream(el)` | Streaming SSR via `renderToReadableStream`. |
+| `useServerData<T>()` | Access data on both server (via `ctx.render({ data })`) and client (via `loader`). |
+| `Link` | Shared component — `<a>` on server, SPA `<a>` on client. |
+| `Form` | Shared — `<form>` on server, `fetch` + revalidate on client. |
+| `ErrorBoundary` | Catches render errors on client (SSR uses `onError`). |
+| `useNavigation()` | `{ state: 'idle' \| 'loading' }` for progress indicators. |
+| `useParams()` / `useNavigate()` / `useRevalidate()` | Router hooks. |
+| `defineRoute()` | Type-safe route config — captures loader return type. |
+| `createClientRouter()` | Client-side SPA router with loader-based data fetching. |
+| `hydrate(App)` | Hydrate server-rendered HTML on the client. |
+| `head: { title, meta }` | Inject dynamic `<title>` and `<meta>` tags. |
+
+**Import paths:**
+
+```ts
+// Server-side
+import { react, Link, Form, ErrorBoundary, useServerData } from 'weifuwu'
+
+// Client-side (for browser bundles)
+import { hydrate, createClientRouter, defineRoute, Link } from 'weifuwu/react/client'
+
+// Shared primitives (safe for both, pure React — no react-dom import)
+import { Link, Form, useServerData, useParams, useNavigation } from 'weifuwu/react/navigation'
+```
+
+See [examples/react-ssr/](examples/react-ssr/) for a complete demo.
+
 ### Types
 
 | Export | Description |
@@ -290,10 +405,13 @@ weifuwu/
 │   ├── middleware/          ← cors, helmet, compress, rate-limit, static, upload
 │   ├── postgres/
 │   ├── redis/
+│   ├── react/              ← react SSR (render, navigation, client)
 │   ├── queue/              ← cron, index, types
 │   ├── graphql.ts
 │   ├── hub.ts
-│   └── test/               ← 122 tests (18 files)
+│   └── test/               ← 131 tests (18 files)
+├── examples/
+│   └── react-ssr/          ← full SPA demo
 └── dist/
 ```
 
@@ -302,5 +420,5 @@ weifuwu/
 ```bash
 npm run build          # esbuild → dist/index.js
 npm run typecheck      # tsc --noEmit
-npm test              # 122 tests (requires docker compose)
+npm test              # 131 tests (requires docker compose)
 ```

package/dist/index.d.ts

@@ -30,3 +30,10 @@ export { createHub } from './hub.ts';
 export type { Hub, HubOptions } from './hub.ts';
 export { queue } from './queue/index.ts';
 export type { QueueOptions, QueueJob, Queue, QueueInjected } from './queue/types.ts';
+export { react } from './react/index.ts';
+export type { ReactOptions, RenderOptions, ReactInjected } from './react/types.ts';
+export { useServerData, ServerDataContext } from './react/index.ts';
+export { Link, useParams, useNavigate, useRevalidate, Form, useNavigation } from './react/index.ts';
+export type { LinkProps, FormProps, NavigationState } from './react/index.ts';
+export { ErrorBoundary } from './react/index.ts';
+export type { ErrorBoundaryProps } from './react/index.ts';

package/dist/index.js

@@ -1111,7 +1111,7 @@ function defaultKey(_req, _ctx) {
 }
 function rateLimit(options) {
   const max = options?.max ?? 100;
-  const window = options?.window ?? 6e4;
+  const window2 = options?.window ?? 6e4;
   const getKey = options?.key ?? defaultKey;
   const message = options?.message ?? "Too Many Requests";
   const storeType = options?.store ?? "memory";
@@ -1138,7 +1138,7 @@ function rateLimit(options) {
         }
       }
     },
-    Math.min(window, 3e4)
+    Math.min(window2, 3e4)
   ) : null;
   if (interval?.unref) interval.unref();
   async function checkAndIncrement(key) {
@@ -1147,16 +1147,16 @@ function rateLimit(options) {
       const redisKey = `${keyPrefix}${key}`;
       const count = await redis2.incr(redisKey);
       if (count === 1) {
-        await redis2.pexpire(redisKey, window);
+        await redis2.pexpire(redisKey, window2);
       }
       const pttl = await redis2.pttl(redisKey);
-      const reset = pttl > 0 ? now + pttl : now + window;
+      const reset = pttl > 0 ? now + pttl : now + window2;
       return { count, reset };
     }
     const entry = hits.get(key);
     if (!entry || entry.reset < now) {
-      hits.set(key, { count: 1, reset: now + window });
-      return { count: 1, reset: now + window };
+      hits.set(key, { count: 1, reset: now + window2 });
+      return { count: 1, reset: now + window2 };
     }
     entry.count++;
     return { count: entry.count, reset: entry.reset };
@@ -1877,11 +1877,346 @@ function queue(opts) {
   };
   return q;
 }
+
+// src/react/index.ts
+import { Fragment as Fragment2 } from "react";
+
+// src/react/render.ts
+import {
+  createElement,
+  Fragment
+} from "react";
+import { renderToString, renderToReadableStream } from "react-dom/server";
+
+// src/react/context.ts
+import { createContext } from "react";
+var CTX_KEY = /* @__PURE__ */ Symbol.for("weifuwu.react.ServerDataContext");
+function getServerDataContext() {
+  const globalStore = globalThis;
+  if (globalStore[CTX_KEY]) return globalStore[CTX_KEY];
+  const ctx = createContext({});
+  ctx.displayName = "ServerData";
+  globalStore[CTX_KEY] = ctx;
+  return ctx;
+}
+var ServerDataContext = getServerDataContext();
+
+// src/react/render.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function escapeAttr(s) {
+  return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+function buildHeadTags(head) {
+  if (!head) return "";
+  const tags = [];
+  if (head.title) tags.push(`<title>${escapeAttr(head.title)}</title>`);
+  if (head.meta) {
+    for (const [name, content] of Object.entries(head.meta)) {
+      tags.push(`<meta name="${escapeAttr(name)}" content="${escapeAttr(content)}">`);
+    }
+  }
+  if (head.links) {
+    for (const link of head.links) {
+      const attrs = Object.entries(link).map(([k, v]) => `${k}="${escapeAttr(v)}"`).join(" ");
+      tags.push(`<link ${attrs}>`);
+    }
+  }
+  if (head.scripts) {
+    for (const script of head.scripts) {
+      const entries = Object.entries(script).filter(([, v]) => v !== void 0);
+      const attrs = entries.map(([k, v]) => `${k}="${escapeAttr(v)}"`).join(" ");
+      tags.push(`<script ${attrs}></script>`);
+    }
+  }
+  return tags.join("");
+}
+function injectHeadIntoHtml(html, headTags) {
+  if (!headTags) return html;
+  let result = html;
+  if (headTags.includes("<title>")) {
+    const titleMatch = headTags.match(/<title>[^<]*<\/title>/);
+    if (titleMatch) {
+      result = result.replace(/<title>[^<]*<\/title>/, titleMatch[0]);
+      headTags = headTags.replace(titleMatch[0], "");
+    }
+  }
+  if (headTags) {
+    result = result.replace("</head>", headTags + "</head>");
+  }
+  return result;
+}
+function injectHeadIntoStream(sourceStream, headTags) {
+  if (!headTags) return sourceStream;
+  let titleTag = "";
+  let rest = headTags;
+  const titleMatch = headTags.match(/<title>[^<]*<\/title>/);
+  if (titleMatch) {
+    titleTag = titleMatch[0];
+    rest = headTags.replace(titleMatch[0], "");
+  }
+  let titleInjected = !titleTag;
+  let headInjected = !rest;
+  return new ReadableStream({
+    async start(controller) {
+      const reader = sourceStream.getReader();
+      let buffer = "";
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          if (!titleInjected) {
+            const idx = buffer.indexOf("<title>");
+            const endIdx = buffer.indexOf("</title>", idx);
+            if (idx !== -1 && endIdx !== -1) {
+              controller.enqueue(
+                encoder.encode(buffer.slice(0, idx) + titleTag + buffer.slice(endIdx + 8))
+              );
+              buffer = "";
+              titleInjected = true;
+              continue;
+            }
+          }
+          if (!headInjected) {
+            const idx = buffer.indexOf("</head>");
+            if (idx !== -1) {
+              controller.enqueue(
+                encoder.encode(buffer.slice(0, idx) + rest + buffer.slice(idx))
+              );
+              buffer = "";
+              headInjected = true;
+              continue;
+            }
+          }
+          if (titleInjected && headInjected && buffer) {
+            controller.enqueue(encoder.encode(buffer));
+            buffer = "";
+          }
+        }
+        if (buffer) controller.enqueue(encoder.encode(buffer));
+        controller.close();
+      } catch (err) {
+        controller.error(err);
+      }
+    }
+  });
+}
+function wrapElement(element, layouts, data) {
+  let wrapped = element;
+  for (let i = layouts.length - 1; i >= 0; i--) {
+    wrapped = createElement(layouts[i], null, wrapped);
+  }
+  const json = JSON.stringify(data).replace(/</g, "\\u003c");
+  const dataScript = createElement("script", {
+    id: "__WEIFUWU_DATA__",
+    type: "application/json",
+    dangerouslySetInnerHTML: { __html: json }
+  });
+  return createElement(
+    ServerDataContext.Provider,
+    { value: data },
+    createElement(Fragment, null, wrapped, dataScript)
+  );
+}
+function render(element, layouts, options = {}) {
+  const data = options.data ?? {};
+  const wrapped = wrapElement(element, layouts, data);
+  let html = renderToString(wrapped);
+  const headTags = buildHeadTags(options.head);
+  html = injectHeadIntoHtml(html, headTags);
+  return new Response("<!DOCTYPE html>\n" + html, {
+    status: options.status ?? 200,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      ...options.headers
+    }
+  });
+}
+async function renderStream(element, layouts, options = {}) {
+  const data = options.data ?? {};
+  const wrapped = wrapElement(element, layouts, data);
+  const headTags = buildHeadTags(options.head);
+  let stream = await renderToReadableStream(wrapped);
+  stream = injectHeadIntoStream(stream, headTags);
+  const doctype = encoder.encode("<!DOCTYPE html>\n");
+  const combined = new ReadableStream({
+    async start(controller) {
+      controller.enqueue(doctype);
+      try {
+        const reader = stream.getReader();
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) {
+            controller.close();
+            break;
+          }
+          controller.enqueue(value);
+        }
+      } catch (err) {
+        controller.error(err);
+      }
+    }
+  });
+  return new Response(combined, {
+    status: options.status ?? 200,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "transfer-encoding": "chunked",
+      ...options.headers
+    }
+  });
+}
+
+// src/react/hooks.ts
+import { useContext } from "react";
+function useServerData() {
+  return useContext(ServerDataContext);
+}
+
+// src/react/navigation.ts
+import {
+  createElement as createElement2,
+  createContext as createContext2,
+  useContext as useContext2
+} from "react";
+
+// src/react/error-boundary.ts
+import { Component } from "react";
+var ErrorBoundary = class extends Component {
+  state = { error: null };
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, info) {
+    this.props.onError?.(error, info);
+  }
+  render() {
+    if (this.state.error) {
+      return this.props.fallback;
+    }
+    return this.props.children;
+  }
+};
+
+// src/react/navigation.ts
+var RouterContext = createContext2(null);
+RouterContext.displayName = "ClientRouter";
+function useParams() {
+  return useContext2(RouterContext)?.params ?? {};
+}
+function useNavigate() {
+  const ctx = useContext2(RouterContext);
+  if (!ctx) throw new Error("useNavigate() must be used within a client router");
+  return ctx.navigate;
+}
+function useNavigation() {
+  const ctx = useContext2(RouterContext);
+  return { state: ctx?.state ?? "idle" };
+}
+function Link({ href, children, ...props }) {
+  const router = useContext2(RouterContext);
+  const isExternal = href.startsWith("http://") || href.startsWith("https://") || href.startsWith("//") || href.startsWith("mailto:") || href.startsWith("tel:");
+  if (!router || isExternal || props.target !== void 0) {
+    return createElement2("a", { href, ...props }, children);
+  }
+  const handleClick = (e) => {
+    if (e.ctrlKey || e.metaKey || e.altKey || e.shiftKey) return;
+    if (e.button !== 0) return;
+    e.preventDefault();
+    router.navigate(href);
+  };
+  return createElement2("a", { href, onClick: handleClick, ...props }, children);
+}
+function useRevalidate() {
+  const ctx = useContext2(RouterContext);
+  if (!ctx) throw new Error("useRevalidate() must be used within a client router");
+  return ctx.revalidate;
+}
+function Form({ method = "post", action, children, ...props }) {
+  const router = useContext2(RouterContext);
+  if (!router) {
+    return createElement2("form", { method, action, ...props }, children);
+  }
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    const form = e.target;
+    const formData = new FormData(form);
+    const url = action || window.location.pathname;
+    const fetchMethod = method === "get" ? "GET" : method.toUpperCase();
+    try {
+      const res = await fetch(url, {
+        method: fetchMethod,
+        body: fetchMethod === "GET" ? void 0 : formData,
+        redirect: "manual"
+      });
+      if (res.status >= 300 && res.status < 400) {
+        const loc = res.headers.get("Location");
+        if (loc) {
+          router.navigate(loc);
+          return;
+        }
+      }
+      await router.revalidate();
+    } catch (err) {
+      console.error("[weifuwu/react] Form submit failed:", err);
+    }
+  };
+  return createElement2(
+    "form",
+    { method, action, ...props, onSubmit: handleSubmit },
+    children
+  );
+}
+
+// src/react/index.ts
+var LAYOUTS_KEY = /* @__PURE__ */ Symbol.for("weifuwu:react:layouts");
+var SETUP_KEY = /* @__PURE__ */ Symbol.for("weifuwu:react:setup");
+function bag(ctx) {
+  return ctx;
+}
+function isDataRequest(req) {
+  try {
+    return new URL(req.url).searchParams.has("_data");
+  } catch {
+    return false;
+  }
+}
+function react(opts = {}) {
+  const layout = opts.layout ?? Fragment2;
+  const mw = (req, ctx, next) => {
+    const b = bag(ctx);
+    const layouts = b[LAYOUTS_KEY] ?? [];
+    b[LAYOUTS_KEY] = layouts;
+    layouts.push(layout);
+    if (!b[SETUP_KEY]) {
+      b[SETUP_KEY] = true;
+      ctx.render = (element, renderOpts) => {
+        if (renderOpts?.data && isDataRequest(req)) {
+          return Promise.resolve(Response.json(renderOpts.data));
+        }
+        return Promise.resolve(render(element, layouts, renderOpts));
+      };
+      ctx.renderStream = (element, renderOpts) => {
+        if (renderOpts?.data && isDataRequest(req)) {
+          return Promise.resolve(Response.json(renderOpts.data));
+        }
+        return renderStream(element, layouts, renderOpts);
+      };
+    }
+    return next(req, ctx);
+  };
+  return mw;
+}
 export {
   DEFAULT_MAX_BODY,
+  ErrorBoundary,
+  Form,
   HttpError,
+  Link,
   MIGRATIONS_TABLE,
   Router,
+  ServerDataContext,
   compress,
   cors,
   createHub,
@@ -1893,11 +2228,17 @@ export {
   postgres,
   queue,
   rateLimit,
+  react,
   redis,
   runWithTrace,
   serve,
   serveStatic,
   trace,
   traceElapsed,
-  upload
+  upload,
+  useNavigate,
+  useNavigation,
+  useParams,
+  useRevalidate,
+  useServerData
 };

package/dist/react/client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Client-side entry for React hydration + SPA navigation.
+ *
+ * Usage (in a client bundle):
+ * ```ts
+ * import { hydrate, createClientRouter } from 'weifuwu/react/client'
+ * import HomePage from './pages/HomePage.js'
+ *
+ * const router = createClientRouter([
+ *   { path: '/', component: HomePage },
+ *   { path: '/users/:id', component: UserPage, loader: ... },
+ * ])
+ * hydrate(router.App)
+ * ```
+ */
+import { type ComponentType, type ReactElement } from 'react';
+import { type LinkProps } from './navigation.ts';
+export interface HydrateOptions {
+    container?: HTMLElement;
+}
+export interface ClientRoute {
+    path: string;
+    component: ComponentType;
+    loader?: (params: Record<string, string>) => Promise<Record<string, unknown>>;
+}
+export interface ClientRouter {
+    App: ComponentType;
+    Link: (props: LinkProps) => ReactElement;
+    useParams: () => Record<string, string>;
+    navigate: (url: string) => Promise<void>;
+}
+export { Link, useParams, useNavigate, useRevalidate, Form, useNavigation } from './navigation.ts';
+export type { LinkProps, FormProps, NavigationState } from './navigation.ts';
+export { ErrorBoundary } from './error-boundary.ts';
+export type { ErrorBoundaryProps } from './error-boundary.ts';
+export { defineRoute } from './route-utils.ts';
+export declare function createClientRouter(routes: ClientRoute[]): ClientRouter;
+export declare function hydrate(App: ComponentType, opts?: HydrateOptions): void;
+export { useServerData } from './hooks.ts';