weifuwu 0.28.2 → 0.30.0

package/dist/core/env.d.ts

@@ -0,0 +1,69 @@
+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

@@ -0,0 +1,34 @@
+/**
+ * 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/logger.d.ts

@@ -0,0 +1,16 @@
+import type { Middleware, Context } from '../types.ts';
+export interface LoggerOptions {
+    /** 'short' = method + path + status + ms, 'combined' = short + query string, 'json' = structured stderr JSON */
+    format?: 'short' | 'combined' | 'json';
+}
+export interface LogEvent {
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    method?: string;
+    path?: string;
+    status?: number;
+    elapsed_ms?: number;
+    traceId?: string;
+    timestamp?: string;
+}
+export declare function logger(options?: LoggerOptions): Middleware<Context, Context>;

package/dist/core/router.d.ts

@@ -0,0 +1,95 @@
+import type { WebSocket, Context, Handler, Middleware, ErrorHandler } from '../types.ts';
+import { type IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { type Hub } from '../hub.ts';
+declare module '../types.ts' {
+    interface Context {
+        ws: {
+            /** Per-connection state object */
+            state: Record<string, unknown>;
+            /** Send JSON to this connection */
+            json(data: unknown): void;
+            /** Join a room */
+            join(room: string): void;
+            /** Leave a room */
+            leave(room: string): void;
+            /** Broadcast to a room */
+            sendRoom(room: string, data: unknown): void;
+        };
+    }
+}
+export type WebSocketHandler = {
+    open?: (ws: WebSocket, ctx: Context) => void | Promise<void>;
+    message?: (ws: WebSocket, ctx: Context, data: string | Buffer) => void | Promise<void>;
+    close?: (ws: WebSocket, ctx: Context) => void | Promise<void>;
+    error?: (ws: WebSocket, ctx: Context, error: Error) => void | Promise<void>;
+};
+type WsUpgradeHandler = (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+export declare class Router<T extends Context = Context> {
+    private root;
+    private wsRoot;
+    private globalMws;
+    private errorHandler?;
+    private _hasWildcard;
+    private _hub?;
+    private _wss?;
+    /** Track which ctx fields have been injected so far (for dependency checking). */
+    private _ctxFields;
+    private get wss();
+    private get hub();
+    /** Inject a custom hub (e.g. with Redis for cross-process broadcast). */
+    wsHub(hub: Hub): this;
+    /** Global middleware — accumulates types into Router<T>. */
+    use<Out extends Context>(mw: Middleware<Context, Out>): Router<T & Out>;
+    /**
+     * Mount a sub-router at the given path prefix.
+     * All routes from the sub-router are registered with the prefix.
+     *
+     * ```ts
+     * const admin = new Router()
+     * admin.get('/dashboard', handler)
+     * app.mount('/admin', admin)  // → GET /admin/dashboard
+     * ```
+     */
+    mount(path: string, router: Router<Context>): Router<T>;
+    /**
+     * Check a middleware's dependency metadata and emit warnings if
+     * required fields haven't been injected yet.
+     * Attach __meta to a middleware function:
+     *
+     * ```ts
+     * mw.__meta = { injects: ['sql'], depends: ['session'] }
+     * ```
+     */
+    private _checkMiddlewareMeta;
+    get(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
+    post(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
+    put(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
+    delete(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
+    patch(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
+    head(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
+    options(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
+    all(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
+    onError(handler: ErrorHandler<T>): Router<T>;
+    private _route;
+    /** Internal route registration — no type constraints (used by _mountRouter). */
+    private _routeImpl;
+    ws(path: string, ...args: [...Middleware<T, T>[], WebSocketHandler]): Router<T>;
+    handler(): Handler<T>;
+    /** Returns a human-readable list of all registered routes. Useful for debugging. */
+    routes(): string[];
+    private _collectRoutes;
+    private _collectWsRoutes;
+    websocketHandler(): WsUpgradeHandler;
+    private _mountRouter;
+    private _collect;
+    private _collectWs;
+    private splitPath;
+    private matchTrie;
+    private matchWsTrie;
+    private handleError;
+    private _notFoundResponse;
+    private handle;
+    private runChain;
+}
+export {};

package/dist/core/serve.d.ts

@@ -0,0 +1,36 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { Router } from './router.ts';
+export interface ServeOptions {
+    port?: number;
+    hostname?: string;
+    signal?: AbortSignal;
+    /** Max request body size in bytes. Default: 10MB. Set to 0 for unlimited. */
+    maxBodySize?: number;
+    /** Socket timeout in ms (inactivity). Default: 30_000. */
+    timeout?: number;
+    /** Keep-Alive idle timeout in ms. Default: 5_000. */
+    keepAliveTimeout?: number;
+    /** Headers timeout in ms (must be > keepAliveTimeout). Default: 6_000. */
+    headersTimeout?: number;
+    shutdown?: boolean;
+}
+export interface Server {
+    stop: (timeoutMs?: number) => Promise<void>;
+    /** Alias for `stop()`. Prefer this for consistency with other modules. */
+    close: (timeoutMs?: number) => Promise<void>;
+    readonly port: number;
+    readonly hostname: string;
+    ready: Promise<void>;
+}
+/** Default max body size: 10MB. Set maxBodySize: 0 for unlimited. */
+export declare const DEFAULT_MAX_BODY: number;
+export declare function readBody(req: IncomingMessage, maxSize?: number): Promise<Buffer>;
+export declare function createRequest(req: IncomingMessage, body: Buffer): [Request, Record<string, string>];
+export declare function sendResponse(res: ServerResponse, response: Response, opts?: {
+    traceId?: string | null;
+}): Promise<void>;
+export declare function createTestServer(router: Router, options?: ServeOptions): Promise<{
+    server: Server;
+    url: string;
+}>;
+export declare function serve(router: Router, options?: ServeOptions): Server;

package/dist/core/sse.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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/core/trace.d.ts

@@ -0,0 +1,95 @@
+import type { Context, Middleware } from '../types.ts';
+declare module '../types.ts' {
+    interface Context {
+        trace: TraceInjected;
+    }
+}
+export interface TraceInjected {
+    /** Unique request identifier (from X-Request-ID header or auto-generated). */
+    requestId: string;
+    /** Unique trace identifier for the request. */
+    traceId: string;
+    /** Milliseconds elapsed since the trace started. */
+    elapsed: () => number;
+    /** Timestamp (ms) when the trace started. */
+    startTime: number;
+}
+export interface TraceContext {
+    /** Unique identifier for the current request trace. */
+    traceId: string;
+    /** Timestamp (ms since epoch) when the trace started. */
+    startTime: number;
+}
+/**
+ * Get the current request's trace ID.
+ * Returns `undefined` when called outside a request context (e.g. at startup).
+ *
+ * ```ts
+ * const traceId = currentTraceId()
+ * log.info({ traceId }, 'request started')
+ * ```
+ */
+export declare function currentTraceId(): string | undefined;
+/**
+ * Get the full current trace context ({ traceId, startTime }).
+ * Returns `undefined` outside a request.
+ */
+export declare function currentTrace(): TraceContext | undefined;
+/**
+ * Run a function inside a trace context.
+ * Used internally by `serve()` for every incoming request.
+ * If `incomingTraceId` is provided (e.g. from an `X-Trace-Id` header) it is reused;
+ * otherwise a new UUID is generated.
+ *
+ * ```ts
+ * const result = runWithTrace(req.headers.get('x-trace-id'), () => {
+ *   return handleRequest(req)
+ * })
+ * ```
+ *
+ * @param incomingTraceId - Optional trace ID from upstream. Pass `null` to auto-generate.
+ * @param fn - Function to execute within the trace scope.
+ * @returns The return value of `fn`.
+ */
+export declare function runWithTrace<T>(incomingTraceId: string | null, fn: () => T): T;
+/**
+ * Milliseconds elapsed since the current trace started.
+ * Returns `0` if called outside a request context.
+ *
+ * ```ts
+ * app.use(async (req, ctx, next) => {
+ *   const res = await next(req, ctx)
+ *   console.log('handled in', traceElapsed(), 'ms')
+ *   return res
+ * })
+ * ```
+ */
+export declare function traceElapsed(): number;
+/** Options for {@link trace}. */
+export interface TraceOptions {
+    /** Header name for request ID (default: `'X-Request-ID'`). */
+    header?: string;
+    /** Custom ID generator (default: `crypto.randomUUID`). */
+    generator?: () => string;
+}
+/**
+ * Request tracing middleware.
+ *
+ * Injects `ctx.trace = { requestId, traceId, elapsed, startTime }`.
+ * Reads/writes `X-Request-ID` header. Combines the functionality of `requestId()`
+ * with the per-request tracing from `AsyncLocalStorage`.
+ *
+ * ```ts
+ * import { trace } from 'weifuwu'
+ * app.use(trace())
+ *
+ * app.get('/', (req, ctx) => {
+ *   console.log(ctx.trace.requestId)  // 550e8400-e29b-...
+ *   console.log(ctx.trace.traceId)    // same as currentTraceId()
+ *   console.log(ctx.trace.elapsed())  // ms since request start
+ * })
+ * ```
+ */
+export declare function trace(options?: TraceOptions): Middleware<Context, Context & {
+    trace: TraceInjected;
+}>;

package/dist/graphql.d.ts

@@ -0,0 +1,16 @@
+import { type GraphQLSchema } from 'graphql';
+import type { Context } from './types.ts';
+import { Router } from './core/router.ts';
+export interface GraphQLOptions {
+    schema: string | GraphQLSchema;
+    rootValue?: any;
+    resolvers?: any;
+    context?: (req: Request, ctx: Context) => Record<string, any> | Promise<Record<string, any>>;
+    graphiql?: boolean;
+    /** Max query depth (nesting). Default: 10. Set 0 to disable. */
+    maxDepth?: number;
+    /** Execution timeout in ms. Default: 30_000. */
+    timeout?: number;
+}
+export type GraphQLHandler = (req: Request, ctx: Context) => GraphQLOptions | Promise<GraphQLOptions>;
+export declare function graphql(handler: GraphQLHandler): Router;

package/dist/hub.d.ts

@@ -0,0 +1,36 @@
+import type { Redis, WebSocket, Closeable } from './types.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 extends Closeable {
+    /** 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;

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+export type { Context, Handler, Middleware, ErrorHandler, WsContext, WebSocket } from './types.ts';
+export { HttpError } from './types.ts';
+export { currentTraceId, currentTrace, runWithTrace, traceElapsed, trace } from './core/trace.ts';
+export type { TraceContext, TraceInjected, TraceOptions } from './core/trace.ts';
+export { loadEnv, isDev, isProd, isBundled, getPublicEnv, env } from './core/env.ts';
+export { serve, createTestServer, DEFAULT_MAX_BODY } from './core/serve.ts';
+export type { ServeOptions, Server } from './core/serve.ts';
+export { Router } from './core/router.ts';
+export type { WebSocketHandler } from './core/router.ts';
+export { logger } from './core/logger.ts';
+export type { LoggerOptions } from './core/logger.ts';
+export { cors } from './middleware/cors.ts';
+export type { CORSOptions } from './middleware/cors.ts';
+export { serveStatic } from './middleware/static.ts';
+export type { ServeStaticOptions } from './middleware/static.ts';
+export { validate } from './middleware/validate.ts';
+export type { ValidationSchemas, ValidateModule } from './middleware/validate.ts';
+export { getCookies, setCookie, deleteCookie } from './core/cookie.ts';
+export type { CookieOptions } from './core/cookie.ts';
+export { upload } from './middleware/upload.ts';
+export type { UploadOptions, UploadedFile, UploadModule } from './middleware/upload.ts';
+export { rateLimit } from './middleware/rate-limit.ts';
+export type { RateLimitOptions } from './middleware/rate-limit.ts';
+export { compress } from './middleware/compress.ts';
+export type { CompressOptions } from './middleware/compress.ts';
+export { helmet } from './middleware/helmet.ts';
+export type { HelmetOptions } from './middleware/helmet.ts';
+export { requestId } from './middleware/request-id.ts';
+export type { RequestIdOptions, RequestIdModule } from './middleware/request-id.ts';
+export { createSSEStream, formatSSE, formatSSEData } from './core/sse.ts';
+export type { SSEEvent } from './core/sse.ts';
+export { testApp, TestApp, TestRequest, createTestDb, withTestDb } from './test/test-utils.ts';
+export type { TestResponse, TestDb } from './test/test-utils.ts';
+export { graphql } from './graphql.ts';
+export type { GraphQLOptions, GraphQLHandler } from './graphql.ts';
+export { postgres, MIGRATIONS_TABLE } from './postgres/index.ts';
+export type { PostgresOptions, PostgresClient, PostgresInjected } from './postgres/types.ts';
+export { redis } from './redis/index.ts';
+export type { RedisOptions, RedisClient, RedisInjected } from './redis/types.ts';
+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 { health } from './middleware/health.ts';
+export type { HealthOptions } from './middleware/health.ts';
+export { html, raw } from './core/html.ts';
+export { theme } from './middleware/theme.ts';
+export type { ThemeOptions, ThemeInjected, ThemeModule } from './middleware/theme.ts';
+export { i18n } from './middleware/i18n.ts';
+export type { I18nOptions, I18nInjected, I18nModule } from './middleware/i18n.ts';
+export { flash } from './middleware/flash.ts';
+export type { FlashOptions, FlashInjected, FlashModule } from './middleware/flash.ts';
+export { csrf } from './middleware/csrf.ts';
+export type { CsrfOptions, CsrfInjected, CsrfModule } from './middleware/csrf.ts';