zero-http 0.2.4 → 0.3.1

package/types/request.d.ts

@@ -0,0 +1,99 @@
+import { IncomingMessage, IncomingHttpHeaders } from 'http';
+import { App } from './app';
+
+export interface RangeResult {
+    type: string;
+    ranges: Array<{ start: number; end: number }>;
+}
+
+export interface Request {
+    /** Original Node request. */
+    raw: IncomingMessage;
+    /** HTTP method (e.g. 'GET'). */
+    method: string;
+    /** Full request URL including query string. */
+    url: string;
+    /** URL path without query string. */
+    path: string;
+    /** Lower-cased request headers. */
+    headers: IncomingHttpHeaders;
+    /** Parsed query-string key/value pairs. */
+    query: Record<string, string>;
+    /** Route parameters populated by the router. */
+    params: Record<string, string>;
+    /** Request body (set by body-parsing middleware). */
+    body: any;
+    /** Remote IP address. */
+    ip: string | null;
+    /** `true` when the connection is over TLS. */
+    secure: boolean;
+    /** Protocol string — `'https'` or `'http'`. */
+    protocol: 'http' | 'https';
+    /** Parsed cookies (populated by cookieParser middleware). */
+    cookies: Record<string, string>;
+    /** Verified signed cookies (populated by cookieParser middleware). */
+    signedCookies?: Record<string, string>;
+    /** Request-scoped locals store. */
+    locals: Record<string, any>;
+    /** Request ID (populated by requestId middleware). */
+    id?: string;
+    /** Whether the request timed out (populated by timeout middleware). */
+    timedOut?: boolean;
+    /** The original URL as received — never rewritten by middleware. */
+    originalUrl: string;
+    /** The URL path on which the current router was mounted. */
+    baseUrl: string;
+    /** Reference to the parent App instance. */
+    app: App | null;
+    /** CSRF token (populated by csrf middleware). */
+    csrfToken?: string;
+    /** First signing secret (populated by cookieParser middleware). */
+    secret?: string;
+    /** All signing secrets (populated by cookieParser middleware). */
+    secrets?: string[];
+
+    /**
+     * Get a specific request header (case-insensitive).
+     */
+    get(name: string): string | undefined;
+
+    /**
+     * Check if the request Content-Type matches the given type.
+     */
+    is(type: string): boolean;
+
+    /**
+     * Get the hostname from the Host header.
+     */
+    readonly hostname: string;
+
+    /**
+     * Get the subdomains as an array.
+     */
+    subdomains(offset?: number): string[];
+
+    /**
+     * Content negotiation — check which types the client accepts.
+     */
+    accepts(...types: string[]): string | false;
+
+    /**
+     * Check if the request is "fresh" (client cache valid).
+     */
+    readonly fresh: boolean;
+
+    /**
+     * Inverse of `fresh`.
+     */
+    readonly stale: boolean;
+
+    /**
+     * Check whether this request was made with XMLHttpRequest.
+     */
+    readonly xhr: boolean;
+
+    /**
+     * Parse the Range header.
+     */
+    range(size: number): RangeResult | -1 | -2;
+}

package/types/response.d.ts

@@ -0,0 +1,142 @@
+import { ServerResponse } from 'http';
+import { App } from './app';
+import { SSEStream, SSEOptions } from './sse';
+
+export interface SendFileOptions {
+    headers?: Record<string, string>;
+    root?: string;
+}
+
+export interface CookieOptions {
+    domain?: string;
+    path?: string;
+    expires?: Date | number;
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    /** Auto-sign the cookie value using req.secret. */
+    signed?: boolean;
+    /** Cookie priority: 'Low', 'Medium', or 'High'. */
+    priority?: 'Low' | 'Medium' | 'High';
+    /** Partitioned attribute (CHIPS). Requires secure: true. */
+    partitioned?: boolean;
+}
+
+export interface Response {
+    /** Original Node response. */
+    raw: ServerResponse;
+    /** Request-scoped locals store. */
+    locals: Record<string, any>;
+    /** Reference to the parent App instance. */
+    app: App | null;
+
+    /**
+     * Set HTTP status code. Chainable.
+     */
+    status(code: number): Response;
+
+    /**
+     * Set a response header. Chainable.
+     */
+    set(name: string, value: string): Response;
+
+    /**
+     * Get a previously-set response header.
+     */
+    get(name: string): string | undefined;
+
+    /**
+     * Append a value to a header.
+     */
+    append(name: string, value: string): Response;
+
+    /**
+     * Add a field to the Vary response header.
+     */
+    vary(field: string): Response;
+
+    /**
+     * Set the Content-Type header. Chainable.
+     */
+    type(ct: string): Response;
+
+    /**
+     * Whether headers have been sent.
+     */
+    readonly headersSent: boolean;
+
+    /**
+     * Send a response body and finalize.
+     */
+    send(body?: string | Buffer | object | null): void;
+
+    /**
+     * Send a JSON response.
+     */
+    json(obj: any): void;
+
+    /**
+     * Send a plain-text response.
+     */
+    text(str: string): void;
+
+    /**
+     * Send an HTML response.
+     */
+    html(str: string): void;
+
+    /**
+     * Send only the status code with reason phrase.
+     */
+    sendStatus(code: number): void;
+
+    /**
+     * Send a file as the response.
+     */
+    sendFile(filePath: string, opts?: SendFileOptions, cb?: (err: Error | null) => void): void;
+    sendFile(filePath: string, cb?: (err: Error | null) => void): void;
+
+    /**
+     * Prompt a file download.
+     */
+    download(filePath: string, filename?: string, cb?: (err: Error | null) => void): void;
+    download(filePath: string, cb?: (err: Error | null) => void): void;
+
+    /**
+     * Set a cookie. Objects are auto-serialized as JSON cookies (j: prefix).
+     */
+    cookie(name: string, value: string | object, opts?: CookieOptions): Response;
+
+    /**
+     * Clear a cookie.
+     */
+    clearCookie(name: string, opts?: CookieOptions): Response;
+
+    /**
+     * Redirect to a URL.
+     */
+    redirect(url: string): void;
+    redirect(status: number, url: string): void;
+
+    /**
+     * Open a Server-Sent Events stream.
+     */
+    sse(opts?: SSEOptions): SSEStream;
+
+    /**
+     * Content-negotiated response based on Accept header.
+     * Keys are MIME types, values are handler functions.
+     */
+    format(types: Record<string, () => void> & { default?: () => void }): void;
+
+    /**
+     * Set the Link header from a map of rel → URL.
+     */
+    links(links: Record<string, string>): Response;
+
+    /**
+     * Set the Location response header.
+     */
+    location(url: string): Response;
+}

package/types/router.d.ts

@@ -0,0 +1,78 @@
+import { Request } from './request';
+import { Response } from './response';
+import { MiddlewareFunction, NextFunction } from './middleware';
+
+export interface RouteOptions {
+    /** When `true`, route matches only HTTPS; when `false`, only HTTP. */
+    secure?: boolean;
+}
+
+export type RouteHandler = (req: Request, res: Response, next?: NextFunction) => void | Promise<void>;
+
+export interface RouteEntry {
+    method: string;
+    path: string;
+    regex: RegExp;
+    keys: string[];
+    handlers: RouteHandler[];
+    secure?: boolean;
+}
+
+export interface RouteInfo {
+    method: string;
+    path: string;
+    secure?: boolean;
+    maxPayload?: number;
+    pingInterval?: number;
+}
+
+export interface RouteChain {
+    get(...handlers: (RouteOptions | RouteHandler)[]): RouteChain;
+    post(...handlers: (RouteOptions | RouteHandler)[]): RouteChain;
+    put(...handlers: (RouteOptions | RouteHandler)[]): RouteChain;
+    delete(...handlers: (RouteOptions | RouteHandler)[]): RouteChain;
+    patch(...handlers: (RouteOptions | RouteHandler)[]): RouteChain;
+    options(...handlers: (RouteOptions | RouteHandler)[]): RouteChain;
+    head(...handlers: (RouteOptions | RouteHandler)[]): RouteChain;
+    all(...handlers: (RouteOptions | RouteHandler)[]): RouteChain;
+}
+
+export interface RouterInstance {
+    /** Registered routes. */
+    routes: RouteEntry[];
+
+    /**
+     * Register a route.
+     */
+    add(method: string, path: string, handlers: RouteHandler[], options?: RouteOptions): void;
+
+    /**
+     * Mount a child router under a path prefix.
+     */
+    use(prefix: string, router: RouterInstance): void;
+
+    /**
+     * Match and handle request.
+     */
+    handle(req: Request, res: Response): void;
+
+    /**
+     * Chainable route builder.
+     */
+    route(path: string): RouteChain;
+
+    /**
+     * Return a flat list of all registered routes.
+     */
+    inspect(prefix?: string): RouteInfo[];
+
+    // HTTP method shortcuts
+    get(path: string, ...handlers: (RouteOptions | RouteHandler)[]): RouterInstance;
+    post(path: string, ...handlers: (RouteOptions | RouteHandler)[]): RouterInstance;
+    put(path: string, ...handlers: (RouteOptions | RouteHandler)[]): RouterInstance;
+    delete(path: string, ...handlers: (RouteOptions | RouteHandler)[]): RouterInstance;
+    patch(path: string, ...handlers: (RouteOptions | RouteHandler)[]): RouterInstance;
+    options(path: string, ...handlers: (RouteOptions | RouteHandler)[]): RouterInstance;
+    head(path: string, ...handlers: (RouteOptions | RouteHandler)[]): RouterInstance;
+    all(path: string, ...handlers: (RouteOptions | RouteHandler)[]): RouterInstance;
+}

package/types/sse.d.ts

@@ -0,0 +1,78 @@
+export interface SSEOptions {
+    retry?: number;
+    headers?: Record<string, string>;
+    keepAlive?: number;
+    keepAliveComment?: string;
+    autoId?: boolean;
+    startId?: number;
+    pad?: number;
+    status?: number;
+}
+
+export interface SSEStream {
+    /** Whether the stream is still open. */
+    readonly connected: boolean;
+    /** The Last-Event-ID from client reconnection. */
+    lastEventId: string | null;
+    /** Total events sent. */
+    eventCount: number;
+    /** Total bytes written. */
+    bytesSent: number;
+    /** Timestamp when stream was opened. */
+    connectedAt: number;
+    /** Milliseconds since opened. */
+    readonly uptime: number;
+    /** Whether connection is over TLS. */
+    secure: boolean;
+    /** Arbitrary user-data store. */
+    data: Record<string, any>;
+
+    /**
+     * Send an unnamed data event.
+     */
+    send(data: string | object, id?: string | number): SSEStream;
+
+    /**
+     * Send a JSON event (alias for send).
+     */
+    sendJSON(obj: any, id?: string | number): SSEStream;
+
+    /**
+     * Send a named event.
+     */
+    event(eventName: string, data: string | object, id?: string | number): SSEStream;
+
+    /**
+     * Send a comment line.
+     */
+    comment(text: string): SSEStream;
+
+    /**
+     * Send or update the retry interval.
+     */
+    retry(ms: number): SSEStream;
+
+    /**
+     * Start/restart keep-alive timer.
+     */
+    keepAlive(intervalMs: number, comment?: string): SSEStream;
+
+    /**
+     * Flush buffered data.
+     */
+    flush(): SSEStream;
+
+    /**
+     * Close the SSE connection.
+     */
+    close(): void;
+
+    // Event emitter
+    on(event: 'close', fn: () => void): SSEStream;
+    on(event: 'error', fn: (err: Error) => void): SSEStream;
+    once(event: 'close', fn: () => void): SSEStream;
+    once(event: 'error', fn: (err: Error) => void): SSEStream;
+    off(event: string, fn: Function): SSEStream;
+    removeAllListeners(event?: string): SSEStream;
+    listenerCount(event: string): number;
+}

package/types/websocket.d.ts

@@ -0,0 +1,119 @@
+import { IncomingMessage, IncomingHttpHeaders } from 'http';
+
+export interface WebSocketOptions {
+    /** Maximum incoming frame size in bytes (default 1 MB). */
+    maxPayload?: number;
+    /** Auto-ping interval in ms. Set `0` to disable. */
+    pingInterval?: number;
+    /** Return false to reject the upgrade. */
+    verifyClient?: (req: IncomingMessage) => boolean;
+}
+
+export type WebSocketHandler = (ws: WebSocketConnection, req: IncomingMessage) => void;
+
+export interface WebSocketConnection {
+    /** Unique connection identifier. */
+    id: string;
+    /** Current ready state (0-3). */
+    readyState: number;
+    /** Negotiated sub-protocol. */
+    protocol: string;
+    /** Requested extensions. */
+    extensions: string;
+    /** Request headers from the upgrade. */
+    headers: IncomingHttpHeaders;
+    /** Remote IP address. */
+    ip: string | null;
+    /** Parsed query params from the upgrade URL. */
+    query: Record<string, string>;
+    /** Full upgrade URL. */
+    url: string;
+    /** Whether connection is over TLS. */
+    secure: boolean;
+    /** Maximum incoming payload bytes. */
+    maxPayload: number;
+    /** Timestamp when connected. */
+    connectedAt: number;
+    /** Arbitrary user-data store. */
+    data: Record<string, any>;
+    /** Bytes waiting in send buffer. */
+    readonly bufferedAmount: number;
+    /** Milliseconds since connected. */
+    readonly uptime: number;
+
+    /**
+     * Send a text or binary message.
+     */
+    send(data: string | Buffer, opts?: { binary?: boolean; callback?: Function }): boolean;
+
+    /**
+     * Send a JSON-serialised message.
+     */
+    sendJSON(obj: any, cb?: Function): boolean;
+
+    /**
+     * Send a ping frame.
+     */
+    ping(payload?: string | Buffer, cb?: Function): boolean;
+
+    /**
+     * Send a pong frame.
+     */
+    pong(payload?: string | Buffer, cb?: Function): boolean;
+
+    /**
+     * Close the connection.
+     */
+    close(code?: number, reason?: string): void;
+
+    /**
+     * Forcefully destroy the socket.
+     */
+    terminate(): void;
+
+    // Event emitter
+    on(event: 'message', fn: (data: string | Buffer) => void): WebSocketConnection;
+    on(event: 'close', fn: (code: number, reason: string) => void): WebSocketConnection;
+    on(event: 'error', fn: (err: Error) => void): WebSocketConnection;
+    on(event: 'pong', fn: (payload: Buffer) => void): WebSocketConnection;
+    on(event: 'ping', fn: (payload: Buffer) => void): WebSocketConnection;
+    on(event: 'drain', fn: () => void): WebSocketConnection;
+    once(event: string, fn: Function): WebSocketConnection;
+    off(event: string, fn: Function): WebSocketConnection;
+    removeAllListeners(event?: string): WebSocketConnection;
+    listenerCount(event: string): number;
+}
+
+export interface WebSocketPool {
+    /** Total active connections. */
+    readonly size: number;
+    /** All active room names. */
+    readonly rooms: string[];
+    /** All active connections. */
+    readonly clients: WebSocketConnection[];
+
+    /** Add a connection to the pool. */
+    add(ws: WebSocketConnection): WebSocketPool;
+    /** Remove a connection from the pool. */
+    remove(ws: WebSocketConnection): WebSocketPool;
+    /** Join a connection to a room. */
+    join(ws: WebSocketConnection, room: string): WebSocketPool;
+    /** Remove a connection from a room. */
+    leave(ws: WebSocketConnection, room: string): WebSocketPool;
+    /** Get all rooms a connection belongs to. */
+    roomsOf(ws: WebSocketConnection): string[];
+    /** Broadcast to ALL connections. */
+    broadcast(data: string | Buffer, exclude?: WebSocketConnection): void;
+    /** Broadcast JSON to ALL connections. */
+    broadcastJSON(obj: any, exclude?: WebSocketConnection): void;
+    /** Send to all connections in a room. */
+    toRoom(room: string, data: string | Buffer, exclude?: WebSocketConnection): void;
+    /** Send JSON to all connections in a room. */
+    toRoomJSON(room: string, obj: any, exclude?: WebSocketConnection): void;
+    /** Get all connections in a room. */
+    in(room: string): WebSocketConnection[];
+    /** Number of connections in a room. */
+    roomSize(room: string): number;
+    /** Close all connections. */
+    closeAll(code?: number, reason?: string): void;
+}