weifuwu 0.28.2 → 0.30.1

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';