weifuwu 0.30.1 → 0.31.0

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "description": "Web-standard HTTP microframework for Node.js — (req, ctx) => Response",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./react/client": {
+      "types": "./dist/react/client.d.ts",
+      "default": "./dist/react/client.js"
+    },
+    "./react/navigation": {
+      "types": "./dist/react/navigation.d.ts",
+      "default": "./dist/react/navigation.js"
     }
   },
   "files": [
@@ -17,8 +29,8 @@
     "build": "node scripts/build.mjs",
     "prepublishOnly": "npm run build && tsc --emitDeclarationOnly --outdir dist",
     "typecheck": "tsc --noEmit",
-    "test": "node --test 'src/test/**/*.test.ts'",
-    "test:coverage": "node --experimental-test-coverage --test 'src/test/**/*.test.ts'",
+    "pretest": "docker compose up -d --wait 2>/dev/null; sleep 1",
+    "test": "node --env-file=.env --test 'src/test/**/*.test.ts'",
     "release": "node scripts/release.mjs",
     "release:dry": "node scripts/release.mjs --dry-run"
   },
@@ -27,14 +39,30 @@
     "graphql": "^16",
     "ioredis": "^5.11.0",
     "postgres": "^3.4.9",
-    "ws": "^8",
-    "zod": "^4.4.3"
+    "ws": "^8"
+  },
+  "peerDependencies": {
+    "react": "19",
+    "react-dom": "19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^25",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
     "@types/ws": "^8",
-    "@eslint/js": "^10.0.1",
+    "esbuild": "^0.28.1",
     "globals": "^17.7.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "typescript-eslint": "^8.62.1"
   },
   "sideEffects": false

package/dist/core/cookie.d.ts

@@ -1,36 +0,0 @@
-/** Options for setting a cookie. All fields map to standard Set-Cookie attributes. */
-export interface CookieOptions {
-    domain?: string;
-    path?: string;
-    maxAge?: number;
-    expires?: Date;
-    httpOnly?: boolean;
-    secure?: boolean;
-    sameSite?: 'strict' | 'lax' | 'none';
-}
-/** Parse cookies from a Request's `Cookie` header.
- *
- * @example
- * ```ts
- * const cookies = getCookies(req)
- * console.log(cookies.session_id) // value or undefined
- * ``` */
-export declare function getCookies(req: Request): Record<string, string>;
-/** Set a cookie on a Response.
- *
- * Appends a `Set-Cookie` header to the existing response headers.
- * Returns a new Response with the added header.
- *
- * @example
- * ```ts
- * const res = new Response('ok')
- * return setCookie(res, 'session', token, { httpOnly: true, path: '/' })
- * ``` */
-export declare function setCookie(res: Response, name: string, value: string, options?: CookieOptions): Response;
-/** Delete a cookie by setting `Max-Age=0`.
- *
- * @example
- * ```ts
- * return deleteCookie(res, 'session')
- * ``` */
-export declare function deleteCookie(res: Response, name: string, options?: Omit<CookieOptions, 'maxAge'>): Response;

package/dist/core/env.d.ts

@@ -1,69 +0,0 @@
-import type { Context, Middleware } from '../types.ts';
-/**
- * Get all public environment variables (those prefixed with `WEIFUWU_PUBLIC_`),
- * with the prefix stripped.
- *
- * ```ts
- * const pub = getPublicEnv()
- * // WEIFUWU_PUBLIC_API_URL=http://api.example.com → { API_URL: 'http://api.example.com' }
- * ```
- */
-export declare function getPublicEnv(): Record<string, string>;
-declare module '../types.ts' {
-    interface Context {
-        env?: Record<string, string>;
-    }
-}
-/**
- * Whether this code is running from the compiled `dist/index.js` bundle.
- * `false` when running TypeScript source directly (dev workflow in weifuwu repo).
- *
- * Used by modules that need to resolve package-internal files differently
- * depending on whether they are compiled (published npm package) or raw TS.
- */
-export declare function isBundled(): boolean;
-/**
- * Whether `NODE_ENV` is explicitly set to `'development'`.
- *
- * Used for dev-only features: HMR, livereload, React `createRoot` (not hydrate).
- * **Not** the opposite of {@link isProd} — when `NODE_ENV` is unset, both return `false`.
- */
-export declare function isDev(): boolean;
-/**
- * Whether `NODE_ENV` is explicitly set to `'production'`.
- *
- * Used for production-only behavior: plain-text 404, suppressed warnings, minified output.
- */
-export declare function isProd(): boolean;
-/**
- * Load environment variables from a `.env` file into `process.env`.
- *
- * Does **not** override existing `process.env` values.
- * Supports quoted values and inline comments.
- *
- * @param path - Path to `.env` file (default: `'.env'` relative to cwd).
- *
- * ```ts
- * import { loadEnv } from 'weifuwu'
- * loadEnv()
- * console.log(process.env.PORT)
- * ```
- */
-export declare function loadEnv(path?: string): void;
-/**
- * Public env middleware.
- *
- * Injects `ctx.env` with all environment variables prefixed with `WEIFUWU_PUBLIC_`,
- * with the prefix stripped. Safe to expose to the client.
- *
- * ```ts
- * import { env } from 'weifuwu'
- * app.use(env())
- *
- * // .env:  WEIFUWU_PUBLIC_API_URL=https://api.example.com
- * // ctx:   ctx.env.API_URL === 'https://api.example.com'
- * ```
- */
-export declare function env(): Middleware<Context, Context & {
-    env: Record<string, string>;
-}>;

package/dist/core/html.d.ts

@@ -1,34 +0,0 @@
-/**
- * Safe HTML rendering via tagged template literals.
- *
- * Auto-escapes interpolated values to prevent XSS.
- * Use `raw()` for trusted HTML that should not be escaped.
- *
- * ```ts
- * import { html, raw } from '@weifuwujs/core'
- *
- * html`<h1>${title}</h1>`               // auto-escaped
- * html`<div>${raw(trustedHtml)}</div>`   // unescaped
- * html`<ul>${items.map(i => html`<li>${i}</li>`)}</ul>`  // arrays
- * html`${isAdmin && html`<button>Admin</button>`}`        // conditionals
- * html`<div>${html`<span>nested</span>`}</div>`           // nested (safe)
- * ```
- */
-interface RawHtml {
-    _raw: string;
-}
-export type HtmlValue = string | number | boolean | null | undefined | HtmlValue[] | RawHtml;
-/**
- * Tagged template literal for safe HTML.
- *
- * Interpolated values are auto-escaped. Use {@link raw} to bypass escaping
- * for trusted HTML. Nested `html` calls are safe (not double-escaped).
- */
-export declare function html(strings: TemplateStringsArray, ...values: HtmlValue[]): string;
-/**
- * Bypass HTML escaping for trusted content.
- *
- * Can be used standalone or inside {@link html} tagged templates.
- */
-export declare function raw(content: string): HtmlValue;
-export {};

package/dist/core/sse.d.ts

@@ -1,47 +0,0 @@
-/**
- * Format an SSE message string with a named event type.
- *
- * ```ts
- * formatSSE('ping', { ts: Date.now() })
- * // "event: ping\ndata: {"ts":...}\n\n"
- * ```
- */
-export declare function formatSSE(event: string, data: unknown): string;
-/**
- * Format an SSE message string with only a data line (no event type).
- *
- * ```ts
- * formatSSEData({ message: 'hello' })
- * // "data: {"message":"hello"}\n\n"
- * ```
- */
-export declare function formatSSEData(data: unknown): string;
-/** An SSE event to be sent via {@link createSSEStream}. */
-export interface SSEEvent {
-    /** Event type (maps to `event:` field). */
-    event: string;
-    /** Event payload (serialized as JSON in `data:` field). */
-    data: unknown;
-}
-/**
- * Create a Server-Sent Events (SSE) `Response` from an async iterable.
- *
- * Each item in the iterable is serialized as an SSE message:
- * - If the item has a `.type` property → `event: {type}` + `data: {item}`
- * - Otherwise → `data: {item}`
- *
- * Errors are sent as `event: error` messages. `AbortError` is silently ignored.
- *
- * ```ts
- * app.get('/events', () => {
- *   async function* generate() {
- *     yield { type: 'ping', data: { ts: Date.now() } }
- *   }
- *   return createSSEStream(generate())
- * })
- * ```
- */
-export declare function createSSEStream(iterable: AsyncIterable<any>, opts?: {
-    headers?: Record<string, string>;
-    status?: number;
-}): Response;

package/dist/middleware/csrf.d.ts

@@ -1,31 +0,0 @@
-import type { Context, Middleware } from '../types.ts';
-declare module '../types.ts' {
-    interface Context {
-        csrf: CsrfInjected;
-    }
-}
-export interface CsrfInjected {
-    token: string;
-}
-/** CSRF protection module — a {@link Middleware} that injects `ctx.csrf`. */
-export type CsrfModule = Middleware<Context, Context & CsrfInjected>;
-export interface CsrfOptions {
-    /** Cookie name for CSRF token (default: `'_csrf'`). */
-    cookie?: string;
-    /** Request header name for CSRF token (default: `'x-csrf-token'`). */
-    header?: string;
-    /** Form body key for CSRF token (default: `'_csrf'`). */
-    key?: string;
-    /** HTTP methods to exclude from CSRF protection (default: `['GET', 'HEAD', 'OPTIONS']`). */
-    excludeMethods?: string[];
-}
-/**
- * CSRF protection middleware.
- *
- * On excluded methods (GET, HEAD, OPTIONS), generates a token and stores it
- * in a cookie. On other methods, validates the token from header or body
- * against the cookie.
- *
- * Injects `ctx.csrf.token` for use in forms.
- */
-export declare function csrf(options?: CsrfOptions): Middleware<Context, Context & CsrfInjected>;

package/dist/middleware/flash.d.ts

@@ -1,44 +0,0 @@
-import type { Context, Middleware } from '../types.ts';
-declare module '../types.ts' {
-    interface Context {
-        flash: FlashInjected;
-    }
-}
-/** Flash message module — a {@link Middleware} that injects `ctx.flash`. */
-export type FlashModule = Middleware<Context, Context & FlashInjected>;
-/** Options for {@link flash}. */
-export interface FlashOptions {
-    /**
-     * Cookie name to store the flash message.
-     * @default 'flash'
-     */
-    name?: string;
-}
-/**
- * Flash message object injected into `ctx.flash`.
- */
-export interface FlashInjected {
-    /**
-     * The flash value read from the incoming cookie.
-     * `undefined` if no flash cookie is present.
-     * Automatically cleared after the response is sent.
-     */
-    value: unknown;
-    /**
-     * Set a flash message and return a 302 redirect response.
-     *
-     * @param data - Any JSON-serializable value to store as the flash message.
-     * @param location - Redirect location (defaults to the `Referer` header).
-     * @returns A 302 Response with a `Set-Cookie` header.
-     */
-    set: (data: unknown, location?: string) => Response;
-}
-/**
- * Flash message middleware — injects `ctx.flash`.
- *
- * @param options - Cookie name configuration.
- * @returns Middleware that injects `ctx.flash` (`FlashInjected`).
- */
-export declare function flash(options?: FlashOptions): Middleware<Context, Context & {
-    flash: FlashInjected;
-}>;

package/dist/middleware/health.d.ts

@@ -1,24 +0,0 @@
-import { Router } from '../core/router.ts';
-/** Options for {@link health}. */
-export interface HealthOptions {
-    /** Health check endpoint path (default: `'/__health'`). */
-    path?: string;
-    /** Async function that throws if the service is unhealthy. Called on each request. */
-    check?: () => Promise<void>;
-}
-/**
- * Health check endpoint.
- *
- * Returns 200 with `'OK'` if the check passes, 503 if it fails.
- *
- * ```ts
- * import { health } from 'weifuwu'
- *
- * app.use(health({
- *   check: async () => {
- *     await db.query('SELECT 1')
- *   },
- * }))
- * ```
- */
-export declare function health(options?: HealthOptions): Router;

package/dist/middleware/i18n.d.ts

@@ -1,39 +0,0 @@
-import { Router } from '../core/router.ts';
-import type { Context, Middleware } from '../types.ts';
-declare module '../types.ts' {
-    interface Context {
-        i18n: I18nInjected;
-    }
-}
-export interface I18nInjected {
-    locale: string;
-    messages?: Record<string, unknown>;
-    t: (key: string, params?: Record<string, string>, fallback?: string) => string;
-    set?: (value: string, loc?: string) => Response;
-}
-export interface I18nOptions {
-    /** Default locale (default: 'en'). */
-    default?: string;
-    /** Directory containing `{locale}.json` translation files. */
-    dir?: string;
-    /** Inline translation messages keyed by locale. */
-    messages?: Record<string, Record<string, unknown>>;
-    /** Cookie name for locale (default: 'locale'). Set empty to disable. */
-    cookie?: string;
-    /** Whether to detect locale from Accept-Language header (default: true). */
-    fromAcceptLanguage?: boolean;
-}
-/**
- * i18n module. Returns a Router with an attached `.middleware()` method.
- *
- * ```ts
- * const l = i18n({ dir: './locales' })
- * app.use(l.middleware())  // → ctx.i18n = { locale, t, set }
- * app.mount('/', l)          // → GET /__lang/:locale (switch route)
- * ```
- */
-export interface I18nModule extends Router {
-    /** Middleware that injects `ctx.i18n = { locale, t, set }`. */
-    middleware: () => Middleware<Context, Context & I18nInjected>;
-}
-export declare function i18n(options?: I18nOptions): I18nModule;

package/dist/middleware/request-id.d.ts

@@ -1,40 +0,0 @@
-import type { Context, Middleware } from '../types.ts';
-declare module '../types.ts' {
-    interface Context {
-        requestId: string;
-    }
-}
-/** Options for {@link requestId}. */
-/** Request ID module — a {@link Middleware} that injects `ctx.requestId`. */
-export type RequestIdModule = Middleware<Context, Context & {
-    requestId: string;
-}>;
-export interface RequestIdOptions {
-    /** Header name for request ID (default: `'X-Request-ID'`). */
-    header?: string;
-    /** Custom ID generator (default: `crypto.randomUUID`). */
-    generator?: () => string;
-}
-/**
- * Request ID middleware.
- *
- * @deprecated Use `trace()` from 'weifuwu' instead — it injects `ctx.trace.requestId`
- * along with `traceId` and `elapsed()` in a single middleware.
- *
- * ```ts
- * // Old:
- * app.use(requestId())
- * ctx.requestId
- *
- * // New:
- * app.use(trace())
- * ctx.trace.requestId
- * ```
- *
- * Reads an incoming `X-Request-ID` header (or custom header name) from the
- * request. If absent, generates a new UUID. Sets the response header and
- * injects `ctx.requestId`.
- */
-export declare function requestId(options?: RequestIdOptions): Middleware<Context, Context & {
-    requestId: string;
-}>;

package/dist/middleware/theme.d.ts

@@ -1,31 +0,0 @@
-import { Router } from '../core/router.ts';
-import type { Context, Middleware } from '../types.ts';
-declare module '../types.ts' {
-    interface Context {
-        theme: ThemeInjected;
-    }
-}
-export interface ThemeInjected {
-    value: string;
-    set: (value: string, loc?: string) => Response;
-}
-export interface ThemeOptions {
-    /** Default theme value (default: 'system'). */
-    default?: string;
-    /** Cookie name (default: 'theme'). Set to empty string to disable cookie. */
-    cookie?: string;
-}
-/**
- * Theme module. Returns a Router with an attached `.middleware()` method.
- *
- * ```ts
- * const t = theme()
- * app.use(t.middleware())  // → ctx.theme = { value, set }
- * app.mount('/', t)          // → GET /__theme/dark (switch route)
- * ```
- */
-export interface ThemeModule extends Router {
-    /** Middleware that injects `ctx.theme = { value, set }`. */
-    middleware: () => Middleware<Context, Context & ThemeInjected>;
-}
-export declare function theme(options?: ThemeOptions): ThemeModule;

package/dist/middleware/validate.d.ts

@@ -1,32 +0,0 @@
-import type { ZodSchema } from 'zod';
-import type { Middleware } from '../types.ts';
-declare module '../types.ts' {
-    interface Context {
-        parsed: Record<string, unknown>;
-    }
-}
-/** Validation middleware — a {@link Middleware} that injects `ctx.parsed` with validated data. */
-export type ValidateModule = Middleware;
-export interface ValidationSchemas {
-    body?: ZodSchema;
-    query?: ZodSchema;
-    params?: ZodSchema;
-    headers?: ZodSchema;
-}
-/**
- * Request validation middleware using Zod schemas.
- *
- * Validates `params`, `query`, `body`, and/or `headers` against schemas.
- * Returns 422 with error details on mismatch.
- * Injects `ctx.parsed` with validated-and-transformed values.
- *
- * ```ts
- * import { z } from 'zod'
- *
- * app.get('/users/:id', validate({
- *   params: z.object({ id: z.string() }),
- *   query: z.object({ include: z.string().optional() }),
- * }), handler)
- * ```
- */
-export declare function validate(schemas?: ValidationSchemas): Middleware;