weifuwu 0.27.2 → 0.27.4

package/dist/mailer.d.ts

@@ -0,0 +1,51 @@
+import { type Transporter } from 'nodemailer';
+import type { Closeable } from './types.ts';
+/** Options for sending an email. */
+export interface MailOptions {
+    /** Recipient address(es). */
+    to: string | string[];
+    /** Email subject. */
+    subject: string;
+    /** Plain text body. */
+    text?: string;
+    /** HTML body. */
+    html?: string;
+    /** Sender address (overrides `MailerOptions.from`). */
+    from?: string;
+    /** CC recipient(s). */
+    cc?: string | string[];
+    /** BCC recipient(s). */
+    bcc?: string | string[];
+}
+/** Options for {@link mailer}. */
+export interface MailerOptions {
+    /** Nodemailer transport string or pre-built transporter object. */
+    transport?: string | Transporter;
+    /** Default sender address. */
+    from?: string;
+    /** Custom send function (bypasses nodemailer). */
+    send?: (opts: MailOptions) => Promise<void>;
+}
+/** Mailer instance returned by {@link mailer}. */
+export interface Mailer extends Closeable {
+    /** Send an email. */
+    send: (opts: MailOptions) => Promise<void>;
+    /** Close the nodemailer transport. */
+    close: () => Promise<void>;
+}
+/**
+ * Create a mailer instance.
+ *
+ * ```ts
+ * import { mailer } from 'weifuwu'
+ *
+ * const email = mailer({ transport: 'smtp://user:pass@smtp.example.com' })
+ * await email.send({
+ *   to: 'user@example.com',
+ *   subject: 'Hello',
+ *   text: 'Hello from weifuwu!',
+ * })
+ * await email.close()
+ * ```
+ */
+export declare function mailer(options: MailerOptions): Mailer;

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,47 @@
+import type { Context, Middleware } from '../types.ts';
+declare module '../types.ts' {
+    interface Context {
+        csrf: CsrfInjected;
+    }
+}
+export interface CsrfInjected {
+    token: string;
+}
+/** Options for {@link csrf}. */
+/** 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.
+ *
+ * ```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.csrf.token}" />
+ *       <input type="submit" />
+ *     </form>
+ *   `, { headers: { 'content-type': 'text/html' } })
+ * })
+ * ```
+ */
+export declare function csrf(options?: CsrfOptions): Middleware<Context, Context & CsrfInjected>;

package/dist/middleware/flash.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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  // e.g. { type: 'success', text: 'Saved!' }
+ * })
+ *
+ * // Set flash + redirect
+ * app.post('/save', async (req, ctx) => {
+ *   await save()
+ *   return ctx.flash.set({ type: 'success', text: 'Saved!' }, '/articles')
+ * })
+ * ```
+ */
+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`.
+ *
+ * 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/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 type { Context, Middleware } from '../types.ts';
+import { Router } from '../core/router.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.use('/', 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 type { Context, Middleware } from '../types.ts';
+import { Router } from '../core/router.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.use('/', 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,4 @@
+export { postgres, MIGRATIONS_TABLE } from './client.ts';
+export { PgModule } from './module.ts';
+export type { PostgresOptions, PostgresClient, PostgresInjected } from './types.ts';
+export * from './schema/index.ts';

package/dist/postgres/module.d.ts

@@ -0,0 +1,16 @@
+import type { PostgresClient } from './types.ts';
+import type { SqlClient, Closeable } from '../types.ts';
+import type { ColumnBuilder, BoundTable, Table } from './schema/index.ts';
+export declare class PgModule implements Closeable {
+    protected sql: SqlClient;
+    protected pg: PostgresClient;
+    constructor(pg: PostgresClient);
+    table<R extends Record<string, unknown>>(tableOrSchema: string | Table<R>, builders?: {
+        [K in keyof R]: ColumnBuilder<R[K]>;
+    }): BoundTable<R>;
+    transaction<T>(fn: (sql: SqlClient) => Promise<T>, retryOpts?: {
+        maxRetries?: number;
+    }): Promise<T>;
+    migrate(): Promise<void>;
+    close(): Promise<void>;
+}