weifuwu 0.23.2 → 0.23.3

package/README.md

@@ -475,6 +475,26 @@ app.use(cors({ credentials: true, maxAge: 3600 }))
 | `credentials` | `boolean` | `false` | Allow cookies/credentials |
 | `maxAge` | `number` | — | Preflight cache duration (seconds) |
 
+### flash [α]
+
+Cookie-based flash message. Read from request, write via redirect.
+
+```ts
+app.use(flash())
+
+app.get('/', (req, ctx) => {
+  const msg = ctx.flash.value  // { type: 'success', text: 'Saved!' } or undefined
+})
+
+app.post('/save', (req, ctx) => {
+  return ctx.flash.set({ type: 'success', text: 'Saved!' }, '/articles')
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | `'flash'` | Cookie name |
+
 ### cache [α]
 
 Response caching middleware with memory and Redis stores. Caches GET/HEAD responses, with tag-based invalidation.
@@ -1092,6 +1112,24 @@ class MyModule extends PgModule {
 
 Where helpers + `and`/`or`/`not` can be imported from `'weifuwu'` alongside `postgres`. Full column builders and table helpers are in the same barrel.
 
+### cron-utils
+
+Shared cron expression parsing utilities. All functions operate in **local timezone**.
+
+```ts
+import { cronNext } from 'weifuwu'
+
+// Next weekday at 09:00
+const next = cronNext('0 9 * * 1-5')
+console.log(new Date(next))
+```
+
+| Function | Description |
+|----------|-------------|
+| `parsePattern(pattern)` | Parse 5-field cron pattern into `Set<number>[]` |
+| `matches(fields, date)` | Check if a date matches a parsed pattern |
+| `cronNext(expr, from?)` | Calculate next matching timestamp (`from` defaults to now) |
+
 ### fts — Full-Text Search (PostgreSQL)
 
 Utilities for PostgreSQL full-text search: create GIN indexes, search with ranking, and generate highlighted snippets.
@@ -1315,7 +1353,24 @@ app.use(requestId({ header: 'X-Request-Id', generator: () => crypto.randomUUID()
 | `header` | `string` | `'X-Request-ID'` | Header name to read/write |
 | `generator` | `() => string` | `crypto.randomUUID()` | ID generator |
 
+### trace
 
+Request-scoped tracing via `AsyncLocalStorage`. Used internally by `serve()`.
+
+```ts
+import { currentTraceId, runWithTrace, traceElapsed } from 'weifuwu'
+
+// Inside a middleware or handler
+const traceId = currentTraceId()  // UUID or incoming X-Trace-Id
+const elapsed = traceElapsed()    // ms since request started
+```
+
+| Function | Description |
+|----------|-------------|
+| `currentTraceId()` | Current request trace ID, or `undefined` outside a request |
+| `currentTrace()` | Full `{ traceId, startTime }` context |
+| `traceElapsed()` | Milliseconds elapsed since the trace started |
+| `runWithTrace(traceId, fn)` | Execute `fn` inside a trace scope |
 
 ### s3 [α] — S3-compatible object storage
 

package/cli/template/.weifuwu/ssr/2e3a7e60.js

@@ -1,8 +1,8 @@
-// ui/app/page.tsx
+// cli/template/ui/app/page.tsx
 import { useState } from "react";
 import { useWebsocket, useLoaderData, useLocale, useTheme } from "weifuwu/react";
 
-// ui/components/Greeting.tsx
+// cli/template/ui/components/Greeting.tsx
 import { jsxs } from "react/jsx-runtime";
 function Greeting({ name }) {
   return /* @__PURE__ */ jsxs("span", { className: "text-red-500 font-bold", children: [
@@ -11,7 +11,7 @@ function Greeting({ name }) {
   ] });
 }
 
-// ui/app/page.tsx
+// cli/template/ui/app/page.tsx
 import { jsx, jsxs as jsxs2 } from "react/jsx-runtime";
 function Home() {
   const [input, setInput] = useState("");

package/dist/analytics.d.ts

@@ -1,15 +1,35 @@
 import type { Middleware } from './types.ts';
 import { Router } from './router.ts';
+/** Options for {@link analytics}. */
 export interface AnalyticsOptions {
+    /** Path prefixes to exclude from analytics (default: `['/__analytics', '/__wfw', '/static']`). */
     excluded?: string[];
+    /** PostgreSQL client for persistent storage. Required for production use. */
     pg?: {
         sql: (strings: TemplateStringsArray, ...values: any[]) => Promise<any[]>;
         table: (name: string, cols: any) => any;
     };
 }
+/** Analytics module returned by {@link analytics}. */
 export interface AnalyticsModule extends Router {
+    /** Middleware that records page views. */
     middleware: () => Middleware;
+    /** Create/update the analytics database tables. */
     migrate: () => Promise<void>;
+    /** Close the in-memory store and any timers. */
     close: () => Promise<void>;
 }
+/**
+ * Page view analytics module.
+ *
+ * Records page views with referrer and device type. Supports in-memory and PostgreSQL storage.
+ * Provides a dashboard at `GET /__analytics`.
+ *
+ * ```ts
+ * import { analytics, postgres } from 'weifuwu'
+ *
+ * const pg = postgres({ connection: DATABASE_URL })
+ * app.use(analytics({ pg }).middleware())
+ * ```
+ */
 export declare function analytics(options?: AnalyticsOptions): AnalyticsModule;

package/dist/client-locale.d.ts

@@ -1,3 +1,23 @@
+/**
+ * React hook to read and change the locale on the client side.
+ *
+ * Changes are made via SPA navigation to `/__lang/{locale}`, which is
+ * intercepted by the client router and applied without a full page reload.
+ *
+ * ```tsx
+ * import { useLocale } from 'weifuwu/react'
+ *
+ * function LangSwitcher() {
+ *   const { locale, setLocale, t } = useLocale()
+ *   return (
+ *     <>
+ *       <p>{t('greeting')}</p>
+ *       <button onClick={() => setLocale('zh')}>中文</button>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
 export declare function useLocale(): {
     locale: string | undefined;
     setLocale: (locale: string) => Promise<void>;

package/dist/client-theme.d.ts

@@ -1,4 +1,33 @@
+/**
+ * Apply a theme value to the DOM by setting `document.documentElement.dataset.theme`.
+ * Resolves `'system'` to the user's `prefers-color-scheme` preference.
+ * Call this directly from non-React code (e.g. a `<script>` tag).
+ *
+ * ```ts
+ * import { applyTheme } from 'weifuwu/react'
+ * applyTheme('dark')
+ * ```
+ */
 declare function applyTheme(theme: string): void;
+/**
+ * React hook to read and change the theme on the client side.
+ *
+ * Applies the resolved theme to `document.documentElement.dataset.theme`.
+ * Tracks system preference changes when theme is `'system'`.
+ *
+ * ```tsx
+ * import { useTheme } from 'weifuwu/react'
+ *
+ * function ThemeToggle() {
+ *   const { theme, resolvedTheme, setTheme } = useTheme()
+ *   return (
+ *     <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
+ *       Current: {resolvedTheme}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 export declare function useTheme(): {
     theme: string;
     resolvedTheme: string;

package/dist/compress.d.ts

@@ -1,6 +1,20 @@
 import type { Middleware } from './types.ts';
+/** Options for {@link compress}. */
 export interface CompressOptions {
+    /** Compression level (1-9, default: 6). */
     level?: number;
+    /** Minimum response body size in bytes to compress (default: 1024). */
     threshold?: number;
 }
+/**
+ * Response compression middleware (brotli, gzip, deflate).
+ *
+ * Automatically selects the best encoding based on `Accept-Encoding` header.
+ * Skips compression for small responses, images, audio, video, and already-encoded responses.
+ *
+ * ```ts
+ * import { compress } from 'weifuwu'
+ * app.use(compress())
+ * ```
+ */
 export declare function compress(options?: CompressOptions): Middleware;

package/dist/cors.d.ts

@@ -1,10 +1,25 @@
 import type { Middleware } from './types.ts';
+/** Options for {@link cors}. */
 export interface CORSOptions {
+    /** Allowed origin(s). Default `'*'`. If `credentials: true`, reflects the request origin. */
     origin?: string | string[] | ((origin: string) => string | boolean | undefined);
+    /** Allowed HTTP methods. Default: `GET, HEAD, PUT, PATCH, POST, DELETE`. */
     methods?: string[];
+    /** Allowed request headers. Default: `Content-Type, Authorization`. */
     allowedHeaders?: string[];
+    /** Exposed response headers. */
     exposedHeaders?: string[];
+    /** Whether to expose `Access-Control-Allow-Credentials`. */
     credentials?: boolean;
+    /** `Access-Control-Max-Age` in seconds. */
     maxAge?: number;
 }
+/**
+ * CORS middleware.
+ *
+ * ```ts
+ * import { cors } from 'weifuwu'
+ * app.use(cors({ origin: 'https://myapp.com', credentials: true }))
+ * ```
+ */
 export declare function cors(options?: CORSOptions): Middleware;

package/dist/cron-utils.d.ts

@@ -1,8 +1,73 @@
 /**
  * Shared cron expression parsing utilities.
  * Used by both queue (Redis-backed) and in-memory scheduler.
+ *
+ * All functions operate in **local timezone**.
+ *
+ * ```ts
+ * import { cronNext } from 'weifuwu'
+ *
+ * // Get next weekday at 09:00
+ * const next = cronNext('0 9 * * 1-5')
+ * console.log(new Date(next))
+ * ```
+ */
+/**
+ * Parse a single cron field (e.g. `"* /5"`, `"1-10"`, `"1,3,5"`) into a set
+ * of matching integer values within `[min, max]`.
+ *
+ * @param field - The cron field expression.
+ * @param min - Minimum valid value (inclusive).
+ * @param max - Maximum valid value (inclusive).
+ * @returns Set of matching integer values.
+ * @throws If the field contains an invalid expression (step of 0, NaN, etc.).
+ *
+ * ```ts
+ * parseField('1-5', 1, 31)  // Set { 1, 2, 3, 4, 5 }
+ * ```
  */
 export declare function parseField(field: string, min: number, max: number): Set<number>;
+/**
+ * Parse a full 5-field cron expression into an array of 5 Sets.
+ *
+ * @param pattern - Standard cron expression: `minute hour day month weekday`
+ * @returns Array of 5 Sets (minute, hour, day, month, weekday).
+ * @throws If the pattern does not contain exactly 5 fields.
+ *
+ * ```ts
+ * const fields = parsePattern('0 9 * * 1-5')
+ * fields[1] // hour: { 9 }
+ * fields[4] // weekday: { 1, 2, 3, 4, 5 }
+ * ```
+ */
 export declare function parsePattern(pattern: string): Set<number>[];
+/**
+ * Check whether a given date matches a parsed cron pattern.
+ * Uses local timezone methods (getMinutes, getHours, etc.).
+ *
+ * @param fields - Parsed pattern from {@link parsePattern}.
+ * @param date - Date to check.
+ * @returns `true` if the date matches the pattern.
+ *
+ * ```ts
+ * const fields = parsePattern('0 9 * * 1-5') // weekdays at 09:00
+ * matches(fields, new Date('2026-06-15T09:00:00')) // true (Monday)
+ * ```
+ */
 export declare function matches(fields: Set<number>[], date: Date): boolean;
+/**
+ * Calculate the next future timestamp (ms since epoch) matching a cron expression.
+ * Scans forward minute by minute, up to 1 year ahead.
+ * Uses local timezone.
+ *
+ * @param expr - Standard 5-field cron expression.
+ * @param from - Starting point (default: now). The result is always > `from`.
+ * @returns Unix timestamp (ms) of the next matching time.
+ * @throws If no matching time is found within 1 year.
+ *
+ * ```ts
+ * const next = cronNext('30 14 * * *') // next 14:30
+ * console.log(new Date(next).toISOString())
+ * ```
+ */
 export declare function cronNext(expr: string, from?: Date): number;

package/dist/csrf.d.ts

@@ -1,10 +1,39 @@
 import type { Context, Middleware } from './types.ts';
+/** Options for {@link csrf}. */
 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.csrfToken` for use in forms.
+ *
+ * ```ts
+ * import { csrf } from 'weifuwu'
+ * app.use(csrf())
+ *
+ * // In a form:
+ * app.get('/form', (req, ctx) => {
+ *   return new Response(`
+ *     <form method="POST">
+ *       <input type="hidden" name="_csrf" value="${ctx.csrfToken}" />
+ *       <input type="submit" />
+ *     </form>
+ *   `, { headers: { 'content-type': 'text/html' } })
+ * })
+ * ```
+ */
 export declare function csrf(options?: CsrfOptions): Middleware<Context, Context & {
     csrfToken: string;
 }>;

package/dist/env.d.ts

@@ -1,8 +1,28 @@
-/** Whether NODE_ENV is explicitly set to 'development'.
- *  Used for dev-only features: HMR, livereload, no minification, createRoot (not hydrate).
- *  NOT the opposite of isProd() — when NODE_ENV is unset, both return false. */
+/**
+ * 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, minification. */
+/**
+ * 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;

package/dist/flash.d.ts

@@ -1,17 +1,19 @@
-import type { Middleware } from './types.ts';
-export interface FlashOptions {
-    /** Cookie name (default: 'flash'). */
-    name?: string;
-}
 /**
  * Flash message middleware.
  *
+ * Provides a cookie-based flash message system:
+ * - Read: `ctx.flash.value` parses the incoming flash cookie
+ * - Write: `ctx.flash.set(data, location)` sets a new flash and redirects
+ * - Auto-clear: after reading, the flash cookie is cleared from the response
+ *
  * ```ts
+ * import { flash } from 'weifuwu'
+ *
  * app.use(flash())
  *
  * // Read flash
  * app.get('/', (req, ctx) => {
- *   const msg = ctx.flash.value  // { type: 'success', text: 'Saved!' }
+ *   const msg = ctx.flash.value  // e.g. { type: 'success', text: 'Saved!' }
  * })
  *
  * // Set flash + redirect
@@ -21,4 +23,61 @@ export interface FlashOptions {
  * })
  * ```
  */
-export declare function flash(options?: FlashOptions): Middleware;
+import type { Context, Middleware } from './types.ts';
+/** 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`.
+ *
+ * Access the current flash with `.value`, or set a new flash with `.set()`.
+ * The `.value` is automatically cleared after being read.
+ */
+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.
+     *
+     * ```ts
+     * return ctx.flash.set({ type: 'success', text: 'Saved!' }, '/articles')
+     * ```
+     */
+    set: (data: unknown, location?: string) => Response;
+}
+/**
+ * Flash message middleware — injects `ctx.flash`.
+ *
+ * @param options - Cookie name configuration.
+ * @returns Middleware that injects `ctx.flash` (`FlashInjected`).
+ *
+ * ```ts
+ * app.use(flash())
+ *
+ * // Read
+ * app.get('/', (req, ctx) => {
+ *   const msg = ctx.flash.value
+ * })
+ *
+ * // Write + redirect
+ * app.post('/save', async (req, ctx) => {
+ *   return ctx.flash.set({ type: 'success', text: 'Saved!' }, '/articles')
+ * })
+ * ```
+ */
+export declare function flash(options?: FlashOptions): Middleware<Context, Context & {
+    flash: FlashInjected;
+}>;

package/dist/health.d.ts

@@ -1,6 +1,24 @@
 import { Router } from './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/helmet.d.ts

@@ -1,18 +1,33 @@
 import type { Middleware } from './types.ts';
+/** Options for {@link helmet}. Set any header to `false` to omit it. */
 export interface HelmetOptions {
+    /** `Content-Security-Policy` header value. */
     contentSecurityPolicy?: string | false;
+    /** `Cross-Origin-Embedder-Policy` header value. */
     crossOriginEmbedderPolicy?: string | false;
+    /** `Cross-Origin-Opener-Policy` header value. */
     crossOriginOpenerPolicy?: string | false;
+    /** `Cross-Origin-Resource-Policy` header value. */
     crossOriginResourcePolicy?: string | false;
+    /** `Origin-Agent-Cluster` header value. */
     originAgentCluster?: string | false;
+    /** `Referrer-Policy` header value. */
     referrerPolicy?: string | false;
+    /** `Strict-Transport-Security` header value. */
     strictTransportSecurity?: string | false;
+    /** `X-Content-Type-Options` header value. */
     xContentTypeOptions?: string | false;
+    /** `X-DNS-Prefetch-Control` header value. */
     xDnsPrefetchControl?: string | false;
+    /** `X-Download-Options` header value. */
     xDownloadOptions?: string | false;
+    /** `X-Frame-Options` header value. */
     xFrameOptions?: string | false;
+    /** `X-Permitted-Cross-Domain-Policies` header value. */
     xPermittedCrossDomainPolicies?: string | false;
+    /** `X-XSS-Protection` header value. */
     xXssProtection?: string | false;
+    /** `Permissions-Policy` header value. */
     permissionsPolicy?: string | false;
 }
 export declare function helmet(options?: HelmetOptions): Middleware;

package/dist/hub.d.ts

@@ -1,12 +1,36 @@
-import type { Redis } from './vendor.ts';
+import type { Redis, WebSocket } from './vendor.ts';
+/** Options for {@link createHub}. */
 export interface HubOptions {
+    /** Optional Redis client for cross-process pub/sub broadcast. */
     redis?: Redis;
+    /** Key prefix for Redis channels (default: `'hub:'`). */
     prefix?: string;
 }
+/**
+ * In-memory (and optionally Redis-backed) pub/sub hub for WebSocket rooms.
+ *
+ * Used internally by the WebSocket handler to implement `ctx.ws.join()` / `ctx.ws.sendRoom()`. */
 export interface Hub {
+    /** Subscribe a WebSocket to a room/group. */
     join(key: string, ws: WebSocket): void;
+    /** Unsubscribe a WebSocket from all rooms. */
     leave(ws: WebSocket): void;
+    /** Send a JSON message to all members of a room. */
     broadcast(key: string, data: unknown): void;
+    /** Close the hub, disconnect Redis subscribers, clear all rooms. */
     close(): Promise<void>;
 }
+/**
+ * Create a pub/sub hub for WebSocket room management.
+ *
+ * In-memory by default. Pass `redis` to enable cross-process broadcasting.
+ *
+ * ```ts
+ * import { createHub } from 'weifuwu'
+ *
+ * const hub = createHub()
+ * hub.join('room:general', ws)
+ * hub.broadcast('room:general', { type: 'chat', text: 'Hello' })
+ * ```
+ */
 export declare function createHub(opts?: HubOptions): Hub;