weifuwu 0.30.1 → 0.31.0

package/README.md

@@ -2,8 +2,6 @@
 
 Web-standard HTTP microframework for Node.js — `(req, ctx) => Response`.
 
-## Usage
-
 ```bash
 npm install weifuwu
 ```
@@ -18,35 +16,24 @@ serve(app, { port: 3000 })
 
 ## Exports
 
-Everything is exported from `'weifuwu'`:
-
 ### Core
 
-| Export | Kind | Description |
-|---|---|---|
-| `serve(app, opts?)` | function | Start HTTP server. Takes a `Router`. Returns `Server`. |
-| `Router` | class | Trie-based HTTP router with WebSocket support. |
-| `loadEnv(path?)` | function | Load `.env` file into `process.env`. |
-| `isDev()` | function | `true` unless `NODE_ENV` is `production` or `test`. |
-| `isProd()` | function | `true` if `NODE_ENV` is `production`. |
-| `isBundled()` | function | `true` when running the esbuild bundle (checks `__WFW_BUNDLED__`). |
-| `getPublicEnv()` | function | Returns all `process.env` keys prefixed with `WEIFUWU_PUBLIC_`. |
-| `DEFAULT_MAX_BODY` | const | `10 * 1024 * 1024` (10MB). |
+| Export | Description |
+|---|---|
+| `serve(app, opts?)` | Start HTTP server. Returns `Server` with `port`, `hostname`, `ready`, `close()`. |
+| `Router` | Trie-based HTTP router with WebSocket support. |
+| `HttpError` | `new HttpError(message, status)`. Throw to return that status code. |
+| `DEFAULT_MAX_BODY` | `10 * 1024 * 1024` (10MB). |
 
-### Router
+### Router API
 
 ```ts
 const app = new Router()
 
 // HTTP methods
 app.get(path, ...handlers)
-app.post(path, ...handlers)
-app.put(path, ...handlers)
-app.delete(path, ...handlers)
-app.patch(path, ...handlers)
-app.head(path, ...handlers)
-app.options(path, ...handlers)
-app.all(path, ...handlers)    // match any method
+app.post / put / delete / patch / head / options(path, ...handlers)
+app.all(path, ...handlers)    // any method
 
 // WebSocket
 app.ws(path, ...middlewares, handler)
@@ -54,183 +41,260 @@ app.ws(path, ...middlewares, handler)
 
 // Middleware & mounting
 app.use(middleware)           // global middleware
-app.mount(prefix, router)     // mount sub-router at prefix
-app.onError(handler)          // global error handler
-app.routes()                  // debug: string[] of all registered routes
+app.mount(prefix, router)     // sub-router at prefix
+app.onError(handler)          // error handler: (error, req, ctx) => Response
+app.routes()                  // debug: list all registered routes
 
 // Path params
 app.get('/users/:id', (req, ctx) => {
-  const id = ctx.params.id   // string
-  const q = ctx.query.search // from ?search=...
+  ctx.params.id   // string
+  ctx.query.search // from ?search=...
 })
 ```
 
 ### Middleware
 
-| Export | Kind | Description |
-|---|---|---|
-| `cors(opts?)` | middleware | CORS headers. `origin`, `methods`, `headers`, `credentials`, `maxAge`. |
-| `helmet(opts?)` | middleware | Security headers (CSP, HSTS, X-Frame-Options, etc). |
-| `compress(opts?)` | middleware | gzip / brotli / deflate response compression. |
-| `rateLimit(opts?)` | middleware | Sliding-window rate limiter. `windowMs`, `max`, `keyGenerator`. |
-| `requestId(opts?)` | middleware | Generates `X-Request-ID` header. `header`, `generator`. |
-| `logger(opts?)` | middleware | Structured request logging. `format`, `level`, `stream`. |
-| `validate(schemas?)` | middleware | Zod-based request validation. `{ body?, query?, params?, headers? }`. |
-| `upload(opts?)` | middleware | Multipart file upload. `maxSize`, `dest`, `preservePath`. |
-| `health(opts?)` | function→Router | Health check router. Mount at `/_health` or custom path. |
-| `env()` | middleware | Injects `WEIFUWU_PUBLIC_*` env vars into `ctx.env`. |
-| `trace(opts?)` | middleware | Injects trace context into `ctx.trace` (requestId, traceId, startTime, elapsed). |
-
-### Route-level tools
-
-| Export | Kind | Description |
-|---|---|---|
-| `serveStatic(root, opts?)` | handler | Serve static files. `cacheControl`, `index`, `dotfiles`. |
-| `graphql(options)` | function→Router | GraphQL endpoint. Pass a `GraphQLHandler` function `({ query, variables, ctx })`. |
-
-### HTML rendering
-
-| Export | Kind | Description |
-|---|---|---|
-| `html(template, ...values)` | tagged template | Auto-escaped HTML builder. Signal/Computed-aware. |
-| `raw(content)` | function | Raw unescaped HTML string (use with caution). |
-
-### SSE (Server-Sent Events)
-
-| Export | Kind | Description |
-|---|---|---|
-| `createSSEStream()` | function | Create an SSE stream controller for `text/event-stream` responses. |
-| `formatSSE(event, data)` | function | Format a single SSE event string. |
-| `formatSSEData(data)` | function | Format SSE data string. |
-
-### Cookies
-
-| Export | Kind | Description |
-|---|---|---|
-| `getCookies(req)` | function | Parse cookies from `Request`. Returns `Record<string, string>`. |
-| `setCookie(headers, name, value, opts?)` | function | Set `Set-Cookie` header. `path`, `domain`, `maxAge`, `httpOnly`, `secure`, `sameSite`, `partitioned`. |
-| `deleteCookie(headers, name, opts?)` | function | Delete a cookie (Max-Age=0). |
+| Export | Description |
+|---|---|
+| `cors(opts?)` | CORS headers. `origin`, `methods`, `headers`, `credentials`, `maxAge`. |
+| `helmet(opts?)` | Security headers: CSP, HSTS, X-Frame-Options, X-Content-Type-Options, etc. |
+| `compress(opts?)` | gzip / brotli / deflate response compression. |
+| `rateLimit(opts?)` | Sliding-window rate limiter. `windowMs`, `max`, `keyGenerator`, Redis backend. |
+| `logger(opts?)` | Request logging. `format: 'short' | 'combined' | 'json'`. |
+| `upload(opts?)` | Multipart file upload via `req.formData()`. Injects `ctx.parsed`. |
+| `serveStatic(root, opts?)` | Static file handler. `cacheControl`, `index`. |
+| `trace(opts?)` | Injects `ctx.trace = { requestId, traceId, elapsed(), startTime }`. |
 
-### Postgres
+### Tracing
+
+| Export | Description |
+|---|---|
+| `currentTraceId()` | Current request's trace ID (AsyncLocalStorage). |
+| `currentTrace()` | Current trace context `{ traceId, startTime }`. |
+| `runWithTrace(id, fn)` | Run `fn` in a trace context. Auto-generates UUID if id is null. |
+| `traceElapsed()` | Milliseconds since trace start. |
+| `trace(opts?)` | Middleware that injects `ctx.trace`. |
 
-| Export | Kind | Description |
-|---|---|---|
-| `postgres(opts?)` | middleware+client | Create a Postgres client. `url`, `host`, `port`, `database`, `user`, `password`, `max`. |
-| `MIGRATIONS_TABLE` | const | Migration table name: `_weifuwu_migrations`. |
+### Postgres
 
 ```ts
+import { postgres, MIGRATIONS_TABLE } from 'weifuwu'
+
 const sql = postgres({ url: process.env.DATABASE_URL })
+app.use(sql)  // injects ctx.sql
 
-// As middleware — injects ctx.sql
-app.use(sql)
-// As query client
-const rows = await sql.client`SELECT * FROM users WHERE id = ${id}`
+const rows = await sql.sql`SELECT * FROM users WHERE id = ${id}`
 
 // Migrations
 await sql.migrate({
-  '001_init': async (s) => {
-    await s`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`
-  },
+  '001_init': async (s) => await s`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`,
 })
 ```
 
 ### Redis
 
-| Export | Kind | Description |
-|---|---|---|
-| `redis(opts?)` | middleware+client | Create a Redis client (ioredis). `url`, `host`, `port`, `password`, `db`. |
-
 ```ts
+import { redis } from 'weifuwu'
+
 const r = redis({ url: process.env.REDIS_URL })
 app.use(r)  // injects ctx.redis
-await r.client.set('key', 'value')
+await r.redis.set('key', 'value')
 ```
 
 ### Queue & Cron
 
-| Export | Kind | Description |
-|---|---|---|
-| `queue(opts?)` | middleware+instance | In-process job queue with cron support. `concurrency`. |
-
 ```ts
-const q = queue({ concurrency: 3 })
+import { queue } from 'weifuwu'
+
+const q = queue()
 app.use(q)  // injects ctx.queue
 
-q.process('send-email', async (job) => {
-  await sendEmail(job.data.to)
+q.process('email', async (job) => {
+  await sendEmail(job.payload.to)
 })
 
 q.cron('cleanup', '0 3 * * *', async () => {
   await cleanupOldSessions()
 })
 
-await q.add('send-email', { to: 'user@example.com' })
+await q.add('email', { to: 'user@example.com' })
+await q.add('remind', {}, { delay: 60_000 })
+await q.add('report', {}, { schedule: '0 9 * * 1' })
+
+q.run()  // start processing
 ```
 
 ### WebSocket Hub
 
-| Export | Kind | Description |
-|---|---|---|
-| `createHub(opts?)` | function | Pub/Sub hub for cross-connection broadcast. Supports Redis adapter for multi-process. |
-
 ```ts
+import { createHub } from 'weifuwu'
+
 const hub = createHub()
 app.ws('/chat', {
   open(ws, ctx) {
     ctx.ws.join('lobby')
-    ctx.ws.json({ type: 'join', room: 'lobby' })
+    ctx.ws.json({ type: 'join' })
   },
   message(ws, ctx, data) {
-    ctx.ws.sendRoom('lobby', { type: 'chat', text: data.toString() })
+    ctx.ws.sendRoom('lobby', { text: data.toString() })
   },
 })
 ```
 
-### Theme & I18n
+### GraphQL
 
-| Export | Kind | Description |
-|---|---|---|
-| `theme(opts?)` | middleware+Router | Theme middleware. Injects `ctx.theme` with `get()`, `set(theme)`, `toggle()`. Routes: `/__theme/:theme`. |
-| `i18n(opts?)` | middleware+Router | I18n middleware. Injects `ctx.i18n` with `locale`, `t(key, params?)`, `set(locale)`. `dir` for locale JSON files. Routes: `/__lang/:locale`. |
-| `flash()` | middleware | Flash messages. Injects `ctx.flash` with `set(msg)`, `get()`. One-time messages across redirects. |
-| `csrf()` | middleware | CSRF protection. Injects `ctx.csrf` with `token`. Auto-validates on `POST`/`PUT`/`PATCH`/`DELETE`. |
+```ts
+import { graphql } from 'weifuwu'
+
+const gql = graphql((req, ctx) => ({
+  schema: `
+    type Query {
+      hello: String
+      user(id: ID!): User
+    }
+    type User {
+      id: ID
+      name: String
+    }
+  `,
+  resolvers: {
+    Query: {
+      hello: () => 'world',
+      user: (_, { id }) => ctx.sql`SELECT * FROM users WHERE id = ${id}`.then(r => r[0]),
+    },
+  },
+  graphiql: true,
+}))
 
-### Tracing
+app.mount('/graphql', gql)
+```
 
-| Export | Kind | Description |
-|---|---|---|
-| `currentTraceId()` | function | Get current request's trace ID (from AsyncLocalStorage). |
-| `currentTrace()` | function | Get current trace context `{ traceId, startTime }`. |
-| `runWithTrace(id, fn)` | function | Run `fn` with a trace context. Auto-generates ID if null. |
-| `traceElapsed()` | function | Milliseconds since trace start. |
+### React SSR
 
-### Error handling
+> Requires `react >= 19`, `react-dom >= 19` (optional peerDependencies).
 
-| Export | Kind | Description |
-|---|---|---|
-| `HttpError` | class | `new HttpError(message, status)`. Throw to return that status. |
-| `app.onError(handler)` | Router method | Global error handler: `(error, req, ctx) => Response`. |
+```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()),
+})
 
-### Testing
+const router = createClientRouter([
+  { path: '/', component: HomePage },
+  userRoute,
+])
 
-| Export | Kind | Description |
-|---|---|---|
-| `testApp(app)` | function | Create a test client for a Router. Returns `{ get, post, put, delete, patch }` for `(path, opts?)`. |
-| `createTestServer(app, opts?)` | function | Start a test server on a random port. Returns `{ server, url }`. |
-| `createTestDb()` | function | Create an ephemeral Postgres test database. |
-| `withTestDb(fn)` | function | Run `fn(sql)` with a temp database, auto-cleanup. |
+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 |
 |---|---|
-| `Context` | `{ params, query, mountPath?, user?, loaderData?, env?, [key: string] }` |
+| `Context` | `{ params, query, mountPath?, [key: string] }` |
 | `Handler<T>` | `(req: Request, ctx: T) => Response \| Promise<Response>` |
-| `Middleware<In, Out>` | `(req, ctx, next) => Response \| Promise<Response>` |
+| `Middleware` | `(req, ctx, next) => Response \| Promise<Response>` |
 | `WebSocketHandler` | `{ open?, message?, close?, error? }` |
 | `HttpError` | `Error` subclass with `.status: number` |
 | `Closeable` | `{ close(): Promise<void> }` |
-| `Server` | `{ stop, close, port, hostname, ready }` |
+| `Server` | `{ close, port, hostname, ready }` |
 | `ServeOptions` | `{ port, hostname, signal, maxBodySize, timeout, keepAliveTimeout, headersTimeout, shutdown }` |
 
 ## Handler / Middleware patterns
@@ -238,14 +302,13 @@ app.ws('/chat', {
 ```ts
 // Handler — standard Web API
 app.get('/api/data', (req, ctx) => {
-  const { q } = ctx.query
-  const id = ctx.params.id
-  return Response.json({ q, id })
+  const q = ctx.query.q
+  return Response.json({ q })
 })
 
 // Async
 app.get('/db/users', async (req, ctx) => {
-  const rows = await sql`SELECT * FROM users`
+  const rows = await ctx.sql`SELECT * FROM users`
   return Response.json(rows)
 })
 
@@ -264,15 +327,11 @@ app.use(async (req, ctx, next) => {
   return res
 })
 
-// Route-level middleware (before handler)
-app.get('/admin', validate(bodySchema), authCheck, adminHandler)
-
 // Error handler
 app.onError((err, req, ctx) => {
   if (err instanceof HttpError) {
     return Response.json({ error: err.message }, { status: err.status })
   }
-  console.error(err)
   return new Response('Internal error', { status: 500 })
 })
 ```
@@ -280,85 +339,52 @@ app.onError((err, req, ctx) => {
 ## Complete example
 
 ```ts
-import { serve, Router, loadEnv, cors, helmet, compress, logger, requestId, rateLimit, postgres, redis, queue, HttpError, html } from 'weifuwu'
-
-loadEnv()
+import { serve, Router, cors, helmet, compress, logger, trace, rateLimit, postgres, redis, queue, HttpError } from 'weifuwu'
 
 const app = new Router()
 
 // Global middleware
-app.use(requestId())
+app.use(trace())
 app.use(logger())
 app.use(cors())
 app.use(helmet())
 app.use(compress())
 app.use(rateLimit({ windowMs: 60_000, max: 100 }))
 
-// Database & services
-const sql = postgres({ url: process.env.DATABASE_URL })
-const cache = redis({ url: process.env.REDIS_URL })
-const jobs = queue()
-
+// Database
+const sql = postgres()
 app.use(sql)
-app.use(cache)
-app.use(jobs)
 
 // Routes
-app.get('/', () => html`<h1>weifuwu</h1><p>Running on ${process.version}</p>`)
-
 app.get('/api/users', async (req, ctx) => {
-  const users = await ctx.sql`SELECT id, name, email FROM users ORDER BY id`
+  const users = await ctx.sql`SELECT id, name FROM users ORDER BY id`
   return Response.json(users)
 })
 
-app.get('/api/users/:id', async (req, ctx) => {
-  const [user] = await ctx.sql`SELECT * FROM users WHERE id = ${ctx.params.id}`
-  if (!user) throw new HttpError('User not found', 404)
-  return Response.json(user)
-})
-
 app.post('/api/users', async (req, ctx) => {
   const { name, email } = await req.json()
-  const [user] = await ctx.sql`INSERT INTO users (name, email) VALUES (${name}, ${email}) RETURNING *`
+  const [user] = await ctx.sql`INSERT INTO users (name,email) VALUES (${name},${email}) RETURNING *`
   return Response.json(user, { status: 201 })
 })
 
-// Background job
-jobs.process('welcome-email', async (job) => {
-  const { userId } = job.data
-  const [user] = await sql.client`SELECT * FROM users WHERE id = ${userId}`
-  await sendWelcomeEmail(user.email)
-})
-
-app.post('/api/register', async (req, ctx) => {
-  const { name, email } = await req.json()
-  const [user] = await ctx.sql`INSERT INTO users (name, email) VALUES (${name}, ${email}) RETURNING *`
-  await ctx.queue.add('welcome-email', { userId: user.id })
-  return Response.json(user, { status: 201 })
+app.get('/api/users/:id', async (req, ctx) => {
+  const [user] = await ctx.sql`SELECT * FROM users WHERE id = ${ctx.params.id}`
+  if (!user) throw new HttpError('Not found', 404)
+  return Response.json(user)
 })
 
-// WebSocket chat
+// WebSocket
 app.ws('/chat', {
-  open(ws, ctx) {
-    ctx.ws.join('lobby')
-  },
-  message(ws, ctx, data) {
-    ctx.ws.sendRoom('lobby', { text: data.toString() })
-  },
+  open(ws, ctx) { ctx.ws.join('lobby') },
+  message(ws, ctx, data) { ctx.ws.sendRoom('lobby', { text: data.toString() }) },
 })
 
 // Error handling
-app.onError((err, req, ctx) => {
-  if (err instanceof HttpError) {
-    return Response.json({ error: err.message }, { status: err.status })
-  }
+app.onError((err) => {
+  if (err instanceof HttpError) return Response.json({ error: err.message }, { status: err.status })
   return Response.json({ error: 'Internal error' }, { status: 500 })
 })
 
-// Health check
-import { health } from 'weifuwu'
-app.mount('/_health', health())
-
 serve(app, { port: 3000 })
 ```
 
@@ -368,27 +394,31 @@ serve(app, { port: 3000 })
 weifuwu/
 ├── package.json
 ├── tsconfig.json
+├── docker-compose.yml      ← postgres + redis for tests
 ├── scripts/
 │   ├── build.mjs
 │   └── release.mjs
 ├── src/
-│   ├── index.ts              ← all exports
-│   ├── types.ts              ← Context, Handler, Middleware, HttpError
-├── core/                 ← serve, router, trace, env, logger, cookie, sse, html
-│   ├── middleware/        ← cors, compress, helmet, rate-limit, static, validate, upload, health, theme, i18n, flash, csrf, request-id
-├── postgres/             ← postgres client, migrations, module injection
-│   ├── redis/                ← redis client
-│   ├── queue/                ← job queue, cron
-│   ├── graphql.ts            ← schema-first GraphQL handler
-│   ├── hub.ts                ← pub/sub hub (WebSocket rooms)
-│   └── test/                 ← 324 tests
+│   ├── index.ts
+│   ├── types.ts
+│   ├── core/               ← serve, router, ws, trace, logger
+│   ├── 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/               ← 131 tests (18 files)
+├── examples/
+│   └── react-ssr/          ← full SPA demo
 └── dist/
 ```
 
 ## Development
 
 ```bash
-npm run build          # esbuild bundle → dist/index.js
+npm run build          # esbuild → dist/index.js
 npm run typecheck      # tsc --noEmit
-npm test              # node --test (324 tests, 0 failures)
+npm test              # 131 tests (requires docker compose)
 ```