weifuwu 0.28.2 → 0.30.0

package/dist/middleware/compress.d.ts

@@ -0,0 +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/middleware/cors.d.ts

@@ -0,0 +1,25 @@
+import type { Middleware, Context } 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<Context, Context>;

package/dist/middleware/csrf.d.ts

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

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

@@ -0,0 +1,24 @@
+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/helmet.d.ts

@@ -0,0 +1,33 @@
+import type { Middleware, Context } 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<Context, Context>;

package/dist/middleware/i18n.d.ts

@@ -0,0 +1,39 @@
+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/rate-limit.d.ts

@@ -0,0 +1,44 @@
+import type { Redis, Context, Middleware, Closeable } from '../types.ts';
+/** Options for {@link rateLimit}. */
+export interface RateLimitOptions {
+    /** Maximum requests within the window (default: 100). */
+    max?: number;
+    /** Window duration in ms (default: 60000 = 1 minute). */
+    window?: number;
+    /** Custom key function. Default: IP from `x-forwarded-for` or `x-real-ip` or `cf-connecting-ip`. */
+    key?: (req: Request, ctx: Context) => string;
+    /** Custom 429 response body." */
+    message?: string;
+    /** Store backend. `'memory'` (default) or `'redis'`. */
+    store?: 'memory' | 'redis';
+    /** Redis client (required when `store: 'redis'`). */
+    redis?: Redis;
+    /** Redis key prefix (default: `'ratelimit:'`). */
+    prefix?: string;
+}
+/** Rate limit module — middleware + stats. */
+export interface RateLimitModule extends Middleware<Context, Context>, Closeable {
+    stats(): {
+        store: string;
+        entries?: number;
+        maxEntries: number;
+    };
+}
+/**
+ * Rate limiting middleware (in-memory or Redis-backed).
+ *
+ * Limits requests per key (default: client IP) within a rolling window.
+ * Returns 429 when the limit is exceeded, with `Retry-After` header.
+ *
+ * ```ts
+ * import { rateLimit } from 'weifuwu'
+ *
+ * // In-memory (single process)
+ * app.use(rateLimit({ max: 60, window: 60_000 }))
+ *
+ * // Redis-backed (multi-process)
+ * import { Redis } from 'ioredis'
+ * app.use(rateLimit({ store: 'redis', redis: new Redis(), max: 100 }))
+ * ```
+ */
+export declare function rateLimit(options?: RateLimitOptions): RateLimitModule;

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

@@ -0,0 +1,40 @@
+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/static.d.ts

@@ -0,0 +1,23 @@
+import type { Handler } from '../types.ts';
+/** Options for {@link serveStatic}. */
+export interface ServeStaticOptions {
+    /** Directory index filename (default: `'index.html'`). */
+    index?: string;
+    /** `Cache-Control max-age` in seconds. */
+    maxAge?: number;
+    /** Add `immutable` to `Cache-Control` (requires `maxAge`). */
+    immutable?: boolean;
+}
+/**
+ * Static file serving handler.
+ *
+ * Serves files from a root directory. Supports ETag/304, directory index,
+ * Content-Type detection by extension, and directory traversal protection.
+ *
+ * ```ts
+ * import { serveStatic, Router } from 'weifuwu'
+ * const app = new Router()
+ * app.get('/static/*', serveStatic('./public'))
+ * ```
+ */
+export declare function serveStatic(root: string, options?: ServeStaticOptions): Handler;

package/dist/middleware/theme.d.ts

@@ -0,0 +1,31 @@
+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/upload.d.ts

@@ -0,0 +1,55 @@
+import type { Context, Middleware } from '../types.ts';
+declare module '../types.ts' {
+    interface Context {
+        parsed: Record<string, unknown>;
+    }
+}
+/** Upload middleware — a {@link Middleware} that injects `ctx.parsed` with file fields. */
+export type UploadModule = Middleware<Context, Context & {
+    parsed: Record<string, unknown>;
+}>;
+/** A parsed file from a multipart upload. */
+export interface UploadedFile {
+    /** Original filename from the client. */
+    name: string;
+    /** MIME type from the `Content-Type` part header. */
+    type: string;
+    /** File size in bytes. */
+    size: number;
+    /** Path where the file was saved (when `dir` option is set). */
+    path?: string;
+    /** File content as Buffer (when `dir` option is not set). */
+    buffer?: Buffer;
+}
+/** Options for {@link upload}. */
+export interface UploadOptions {
+    /** Directory to save uploaded files. If not set, files stay in memory via `.buffer`. */
+    dir?: string;
+    /** Maximum file size in bytes. Default: 10 MB. Set `0` to allow unlimited. */
+    maxFileSize?: number;
+    /** Allowed MIME types (e.g. `['image/jpeg', 'image/png']`). Empty array allows all. */
+    allowedTypes?: string[];
+}
+/**
+ * Multipart file upload middleware.
+ *
+ * Parses `multipart/form-data` requests, extracting files and fields.
+ * Files can be saved to disk (`dir` option) or kept in memory as Buffers.
+ * Parsed fields are available in `ctx.parsed`.
+ *
+ * ```ts
+ * import { upload } from 'weifuwu'
+ *
+ * // Save to disk
+ * app.use(upload({ dir: './uploads', maxFileSize: 5_000_000 }))
+ *
+ * // In-memory
+ * app.post('/upload', async (req, ctx) => {
+ *   const file = ctx.parsed?.file as UploadedFile
+ *   console.log(file.name, file.type, file.buffer!.length)
+ * })
+ * ```
+ */
+export declare function upload(options?: UploadOptions): Middleware<Context, Context & {
+    parsed: Record<string, unknown>;
+}>;

package/dist/middleware/validate.d.ts

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

package/dist/postgres/client.d.ts

@@ -0,0 +1,4 @@
+import type { PostgresOptions, PostgresClient } from './types.ts';
+/** Migration tracking table name. Created automatically on first migrate(). */
+export declare const MIGRATIONS_TABLE = "_weifuwu_migrations";
+export declare function postgres(opts?: string | PostgresOptions): PostgresClient;

package/dist/postgres/index.d.ts

@@ -0,0 +1,3 @@
+export { postgres, MIGRATIONS_TABLE } from './client.ts';
+export { PgModule } from './module.ts';
+export type { PostgresOptions, PostgresClient, PostgresInjected } from './types.ts';

package/dist/postgres/module.d.ts

@@ -0,0 +1,12 @@
+import type { SqlClient, Closeable } from '../types.ts';
+import type { PostgresClient } from './types.ts';
+export declare class PgModule implements Closeable {
+    protected sql: SqlClient;
+    protected pg: PostgresClient;
+    constructor(pg: PostgresClient);
+    transaction<T>(fn: (sql: SqlClient) => Promise<T>, retryOpts?: {
+        maxRetries?: number;
+    }): Promise<T>;
+    migrate(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/postgres/types.d.ts

@@ -0,0 +1,42 @@
+import type { SqlClient, Context, Middleware, Closeable } from '../types.ts';
+declare module '../types.ts' {
+    interface Context {
+        sql: SqlClient;
+    }
+}
+export interface PostgresInjected {
+    sql: SqlClient;
+}
+export interface PostgresOptions {
+    connection?: string | Record<string, unknown>;
+    signal?: AbortSignal;
+    closeTimeout?: number;
+    max?: number;
+    ssl?: boolean | Record<string, unknown>;
+    idle_timeout?: number;
+    connect_timeout?: number;
+    /** Per-statement timeout in ms. Set to 0 to disable. Default: 30_000. */
+    statementTimeout?: number;
+    /** Called after every query completes. Receives query text, duration in ms, and row count. */
+    onQuery?: (query: string, durationMs: number, rowCount: number) => void;
+}
+export interface PostgresClient extends Middleware<Context, Context & PostgresInjected>, Closeable {
+    sql: SqlClient;
+    /** Creates the migration tracking table (_weifuwu_migrations). Called once at startup. */
+    migrate: () => Promise<void>;
+    /** Record that a module's migration has been applied (idempotent). */
+    markMigrated: (moduleName: string) => Promise<void>;
+    /** Check whether a module has already been migrated. */
+    isMigrated: (moduleName: string) => Promise<boolean>;
+    transaction: <T>(fn: (sql: any) => Promise<T>, retryOpts?: {
+        maxRetries?: number;
+    }) => Promise<T>;
+    /** Snapshot of connection pool state: active, idle, waiting, max connections. */
+    poolStats: () => {
+        active: number;
+        idle: number;
+        waiting: number;
+        max: number;
+    };
+    close: () => Promise<void>;
+}

package/dist/queue/cron.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Cron expression parsing utilities (moved from cron-utils.ts).
+ * Used internally by queue for scheduled job execution.
+ *
+ * All functions operate in local timezone.
+ */
+export declare function parsePattern(pattern: string): Set<number>[];
+export declare function matches(fields: Set<number>[], date: Date): boolean;
+export declare function cronNext(expr: string, from?: Date): number;

package/dist/queue/index.d.ts

@@ -0,0 +1,2 @@
+import type { Queue, QueueOptions } from './types.ts';
+export declare function queue(opts?: QueueOptions): Queue;

package/dist/queue/types.d.ts

@@ -0,0 +1,61 @@
+import type { Redis, Context, Middleware, Closeable } from '../types.ts';
+declare module '../types.ts' {
+    interface Context {
+        queue: Queue;
+    }
+}
+export interface QueueJob<T = unknown> {
+    id: string;
+    type: string;
+    payload: T;
+    createdAt: number;
+    runAt: number;
+    schedule?: string;
+}
+export interface QueueOptions {
+    /** Backend store. Default: 'memory'. */
+    store?: 'memory' | 'pg' | 'redis';
+    redis?: Redis;
+    url?: string;
+    prefix?: string;
+    pollInterval?: number;
+    /** PostgreSQL client (required when store: 'pg'). */
+    pg?: {
+        sql: import('../types.ts').SqlClient;
+    };
+}
+export interface QueueInjected {
+    queue: Queue;
+}
+export interface QueueJobWithError<T = unknown> extends QueueJob<T> {
+    error: string;
+    failedAt: number;
+}
+export interface Queue extends Middleware<Context, Context & QueueInjected>, Closeable {
+    /** Register a cron job. Uses queue's backend (memory/pg/redis) for execution. */
+    cron(pattern: string, handler: () => void | Promise<void>): {
+        stop: () => void;
+    };
+    add<T>(type: string, payload: T, opts?: {
+        delay?: number;
+        schedule?: string;
+    }): Promise<string>;
+    process<T>(type: string, handler: (job: QueueJob<T>) => Promise<void>): void;
+    run(): Promise<void>;
+    stats(): {
+        running: boolean;
+        inflight: number;
+        processed: number;
+        failed: number;
+        handlers: number;
+        maxConcurrent: number;
+    };
+    jobs(limit?: number): Promise<QueueJob[]>;
+    failedJobs(limit?: number): Promise<QueueJobWithError[]>;
+    retryFailed(jobId: string): Promise<boolean>;
+    retryAllFailed(type?: string): Promise<number>;
+    dashboard(): import('../core/router.ts').Router;
+    /** Create the jobs table (PG mode only; safe to call multiple times). */
+    migrate?(): Promise<void>;
+    close(): Promise<void>;
+}