zero-http 0.2.5 → 0.3.1

package/lib/ws/room.js

@@ -0,0 +1,222 @@
+/**
+ * @module ws/room
+ * @description WebSocket room/channel manager.
+ *              Provides broadcast, room-based messaging, and connection
+ *              registry for WebSocket connections.
+ */
+
+/**
+ * Manages a pool of WebSocket connections with room-based grouping.
+ *
+ * @example
+ *   const pool = new WebSocketPool();
+ *   app.ws('/chat', (ws, req) => {
+ *       pool.add(ws);
+ *       pool.join(ws, 'general');
+ *       ws.on('message', msg => pool.toRoom('general', msg));
+ *       ws.on('close', () => pool.remove(ws));
+ *   });
+ */
+class WebSocketPool
+{
+    constructor()
+    {
+        /** @type {Set<import('./connection')>} All active connections. */
+        this._connections = new Set();
+        /** @type {Map<string, Set<import('./connection')>>} Room → connection sets. */
+        this._rooms = new Map();
+    }
+
+    /**
+     * Add a connection to the pool.
+     * @param {import('./connection')} ws
+     * @returns {WebSocketPool} this
+     */
+    add(ws)
+    {
+        this._connections.add(ws);
+
+        // Auto-remove on close
+        ws.once('close', () => this.remove(ws));
+
+        return this;
+    }
+
+    /**
+     * Remove a connection from the pool and all rooms.
+     * @param {import('./connection')} ws
+     * @returns {WebSocketPool} this
+     */
+    remove(ws)
+    {
+        this._connections.delete(ws);
+        for (const [room, members] of this._rooms)
+        {
+            members.delete(ws);
+            if (members.size === 0) this._rooms.delete(room);
+        }
+        return this;
+    }
+
+    /**
+     * Join a connection to a room.
+     * @param {import('./connection')} ws
+     * @param {string} room - Room name.
+     * @returns {WebSocketPool} this
+     */
+    join(ws, room)
+    {
+        if (!this._rooms.has(room)) this._rooms.set(room, new Set());
+        this._rooms.get(room).add(ws);
+        return this;
+    }
+
+    /**
+     * Remove a connection from a room.
+     * @param {import('./connection')} ws
+     * @param {string} room - Room name.
+     * @returns {WebSocketPool} this
+     */
+    leave(ws, room)
+    {
+        const members = this._rooms.get(room);
+        if (members)
+        {
+            members.delete(ws);
+            if (members.size === 0) this._rooms.delete(room);
+        }
+        return this;
+    }
+
+    /**
+     * Get all rooms a connection belongs to.
+     * @param {import('./connection')} ws
+     * @returns {string[]}
+     */
+    roomsOf(ws)
+    {
+        const result = [];
+        for (const [room, members] of this._rooms)
+        {
+            if (members.has(ws)) result.push(room);
+        }
+        return result;
+    }
+
+    /**
+     * Broadcast a message to ALL connected clients.
+     * @param {string|Buffer} data   - Payload.
+     * @param {import('./connection')} [exclude] - Optional connection to exclude (e.g. the sender).
+     */
+    broadcast(data, exclude)
+    {
+        for (const ws of this._connections)
+        {
+            if (ws !== exclude && ws.readyState === 1) ws.send(data);
+        }
+    }
+
+    /**
+     * Broadcast a JSON message to ALL connected clients.
+     * @param {*} obj - Value to serialise.
+     * @param {import('./connection')} [exclude]
+     */
+    broadcastJSON(obj, exclude)
+    {
+        const msg = JSON.stringify(obj);
+        this.broadcast(msg, exclude);
+    }
+
+    /**
+     * Send a message to all connections in a specific room.
+     * @param {string} room          - Room name.
+     * @param {string|Buffer} data   - Payload.
+     * @param {import('./connection')} [exclude]
+     */
+    toRoom(room, data, exclude)
+    {
+        const members = this._rooms.get(room);
+        if (!members) return;
+        for (const ws of members)
+        {
+            if (ws !== exclude && ws.readyState === 1) ws.send(data);
+        }
+    }
+
+    /**
+     * Send a JSON message to all connections in a specific room.
+     * @param {string} room
+     * @param {*}      obj
+     * @param {import('./connection')} [exclude]
+     */
+    toRoomJSON(room, obj, exclude)
+    {
+        this.toRoom(room, JSON.stringify(obj), exclude);
+    }
+
+    /**
+     * Get all connections in a room.
+     * @param {string} room
+     * @returns {import('./connection')[]}
+     */
+    in(room)
+    {
+        const members = this._rooms.get(room);
+        return members ? Array.from(members) : [];
+    }
+
+    /**
+     * Total number of active connections.
+     * @type {number}
+     */
+    get size()
+    {
+        return this._connections.size;
+    }
+
+    /**
+     * Number of connections in a specific room.
+     * @param {string} room
+     * @returns {number}
+     */
+    roomSize(room)
+    {
+        const members = this._rooms.get(room);
+        return members ? members.size : 0;
+    }
+
+    /**
+     * List all active room names.
+     * @returns {string[]}
+     */
+    get rooms()
+    {
+        return Array.from(this._rooms.keys());
+    }
+
+    /**
+     * Get all active connections.
+     * @returns {import('./connection')[]}
+     */
+    get clients()
+    {
+        return Array.from(this._connections);
+    }
+
+    /**
+     * Close all connections gracefully.
+     * @param {number} [code=1001] - Close code.
+     * @param {string} [reason]    - Close reason.
+     */
+    closeAll(code = 1001, reason = 'Server shutdown')
+    {
+        for (const ws of this._connections)
+        {
+            ws.close(code, reason);
+        }
+        this._connections.clear();
+        this._rooms.clear();
+    }
+}
+
+module.exports = WebSocketPool;

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "zero-http",
-  "version": "0.2.5",
-  "description": "Zero-dependency, minimal Express-like HTTP server and tiny fetch replacement",
+  "version": "0.3.1",
+  "description": "Zero-dependency backend framework with routing, ORM, WebSocket, SSE, security middleware, and more",
   "main": "index.js",
+  "types": "types/index.d.ts",
   "files": [
     "lib",
+    "types",
     "documentation",
     "index.js",
     "README.md",
@@ -13,7 +15,8 @@
   "scripts": {
     "start": "node documentation/full-server.js",
     "docs": "node documentation/full-server.js",
-    "test": "node --test"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "http",
@@ -29,10 +32,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tonywied17/zero-http-npm.git"
+    "url": "git+https://github.com/tonywied17/zero-http.git"
   },
   "bugs": {
-    "url": "https://github.com/tonywied17/zero-http-npm/issues"
+    "url": "https://github.com/tonywied17/zero-http/issues"
   },
   "homepage": "https://z-http.com",
   "engines": {
@@ -40,5 +43,12 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "better-sqlite3": "^12.8.0",
+    "mongodb": "^7.1.1",
+    "mysql2": "^3.20.0",
+    "pg": "^8.20.0",
+    "vitest": "^4.1.2"
   }
 }

package/types/app.d.ts

@@ -0,0 +1,120 @@
+/// <reference types="node" />
+
+import { Server as HttpServer } from 'http';
+import { Server as HttpsServer, ServerOptions as TlsOptions } from 'https';
+import { Request } from './request';
+import { Response } from './response';
+import { RouterInstance, RouteChain, RouteInfo, RouteOptions, RouteHandler } from './router';
+import { MiddlewareFunction, ErrorHandlerFunction, NextFunction } from './middleware';
+import { WebSocketHandler, WebSocketOptions } from './websocket';
+
+export interface App {
+    /** Internal router instance. */
+    router: RouterInstance;
+    /** Middleware stack. */
+    middlewares: MiddlewareFunction[];
+    /** Application-level locals, merged into every request/response locals. */
+    locals: Record<string, any>;
+
+    /**
+     * Register middleware or mount a sub-router.
+     */
+    use(fn: MiddlewareFunction): App;
+    use(path: string, fn: MiddlewareFunction): App;
+    use(path: string, router: RouterInstance): App;
+
+    /**
+     * Register a global error handler.
+     */
+    onError(fn: ErrorHandlerFunction): void;
+
+    /**
+     * Core request handler for use with `http.createServer()`.
+     */
+    handler(req: import('http').IncomingMessage, res: import('http').ServerResponse): void;
+
+    /**
+     * Start listening for connections.
+     */
+    listen(port?: number, cb?: () => void): HttpServer;
+    listen(port: number, opts: TlsOptions, cb?: () => void): HttpsServer;
+
+    /**
+     * Gracefully close the server.
+     */
+    close(cb?: (err?: Error) => void): void;
+
+    /**
+     * Register a WebSocket upgrade handler.
+     */
+    ws(path: string, handler: WebSocketHandler): void;
+    ws(path: string, opts: WebSocketOptions, handler: WebSocketHandler): void;
+
+    /**
+     * Return a flat list of all registered routes.
+     */
+    routes(): RouteInfo[];
+
+    /**
+     * Register a route with a specific HTTP method.
+     */
+    route(method: string, path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+
+    /**
+     * Get a setting value (1 arg) or set a setting value (2 args).
+     */
+    set(key: string): any;
+    set(key: string, val: any): App;
+
+    /**
+     * Get a setting value, or register a GET route.
+     * With 1 string arg: returns the setting value.
+     * With path + handlers: registers a GET route.
+     */
+    get(key: string): any;
+    get(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+
+    /**
+     * Enable a boolean setting (set to `true`).
+     */
+    enable(key: string): App;
+
+    /**
+     * Disable a boolean setting (set to `false`).
+     */
+    disable(key: string): App;
+
+    /**
+     * Check if a setting is truthy.
+     */
+    enabled(key: string): boolean;
+
+    /**
+     * Check if a setting is falsy.
+     */
+    disabled(key: string): boolean;
+
+    /**
+     * Register a parameter pre-processing handler.
+     */
+    param(name: string, fn: (req: Request, res: Response, next: NextFunction, value: string) => void): App;
+
+    /**
+     * Create a route group under a prefix with shared middleware.
+     */
+    group(prefix: string, ...args: [...MiddlewareFunction[], (router: RouterInstance) => void]): App;
+
+    /**
+     * Create a chainable route builder for the given path.
+     */
+    chain(path: string): RouteChain;
+
+    // HTTP method shortcuts
+    post(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    put(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    delete(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    patch(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    options(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    head(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+    all(path: string, ...handlers: (RouteOptions | RouteHandler)[]): App;
+}

package/types/env.d.ts

@@ -0,0 +1,80 @@
+// --- Env Field Definition ----------------------------------------
+
+export interface EnvFieldDef {
+    /** Value type for coercion. */
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'port' | 'array' | 'json' | 'url' | 'enum';
+    /** Field is required. */
+    required?: boolean;
+    /** Default value (or function returning a value). */
+    default?: any | (() => any);
+    /** Min value (number/integer) or min length (string). */
+    min?: number;
+    /** Max value (number/integer) or max length (string). */
+    max?: number;
+    /** Pattern match (string type). */
+    match?: RegExp;
+    /** Delimiter for array type. Default: ','. */
+    separator?: string;
+    /** Allowed values for enum type. */
+    values?: string[];
+}
+
+export type EnvSchema = Record<string, EnvFieldDef>;
+
+export interface EnvLoadOptions {
+    /** Directory to load .env files from. Default: `process.cwd()`. */
+    path?: string;
+    /** Write file values into `process.env`. Default: false. */
+    override?: boolean;
+}
+
+// --- Env Proxy ---------------------------------------------------
+
+export interface Env {
+    /**
+     * Get a variable by key.
+     */
+    (key: string): any;
+
+    /**
+     * Load environment variables, optionally with a typed schema.
+     */
+    load(schema?: EnvSchema, options?: EnvLoadOptions): Record<string, any>;
+
+    /**
+     * Get a variable by key.
+     */
+    get(key: string): any;
+
+    /**
+     * Get a variable by key, throwing if missing.
+     */
+    require(key: string): any;
+
+    /**
+     * Check if a variable exists (in store or `process.env`).
+     */
+    has(key: string): boolean;
+
+    /**
+     * Return all loaded variables.
+     */
+    all(): Record<string, any>;
+
+    /**
+     * Clear all loaded variables from the internal store.
+     */
+    reset(): void;
+
+    /**
+     * Parse a raw `.env` string into key-value pairs.
+     */
+    parse(src: string): Record<string, string>;
+
+    /**
+     * Property access for variables (e.g., `env.PORT`).
+     */
+    [key: string]: any;
+}
+
+export const env: Env;

package/types/errors.d.ts

@@ -0,0 +1,147 @@
+// --- Error Classes -----------------------------------------------
+
+export interface HttpErrorOptions {
+    code?: string;
+    details?: any;
+}
+
+export class HttpError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly name: string;
+    details?: any;
+    constructor(statusCode: number, message?: string, opts?: HttpErrorOptions);
+    toJSON(): { error: string; code: string; statusCode: number; details?: any };
+}
+
+export class BadRequestError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class UnauthorizedError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class ForbiddenError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class NotFoundError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class MethodNotAllowedError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class ConflictError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class GoneError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class PayloadTooLargeError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class UnprocessableEntityError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class ValidationError extends HttpError {
+    readonly errors: Record<string, string> | string[];
+    constructor(message?: string, errors?: Record<string, string> | string[], opts?: HttpErrorOptions);
+}
+
+export class TooManyRequestsError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class InternalError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class NotImplementedError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class BadGatewayError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export class ServiceUnavailableError extends HttpError {
+    constructor(message?: string, opts?: HttpErrorOptions);
+}
+
+export function createError(statusCode: number, message?: string, opts?: HttpErrorOptions): HttpError;
+export function isHttpError(err: any): err is HttpError;
+
+// --- Error Handler Middleware ------------------------------------
+
+import { Request } from './request';
+import { Response } from './response';
+
+export interface ErrorHandlerOptions {
+    /** Include stack traces in responses (default: true when NODE_ENV !== 'production'). */
+    stack?: boolean;
+    /** Log errors to console (default: true). */
+    log?: boolean;
+    /** Custom log function (default: console.error). */
+    logger?: (...args: any[]) => void;
+    /** Custom response formatter: (err, req, isDev) => responseBody. */
+    formatter?: (err: Error, req: Request, isDev: boolean) => any;
+    /** Callback on every error. */
+    onError?: (err: Error, req: Request, res: Response) => void;
+}
+
+export function errorHandler(opts?: ErrorHandlerOptions): (err: any, req: Request, res: Response, next: (err?: any) => void) => void;
+
+// --- Debug Logger ------------------------------------------------
+
+export interface DebugLogger {
+    (...args: any[]): void;
+    trace(...args: any[]): void;
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    fatal(...args: any[]): void;
+    readonly enabled: boolean;
+    readonly namespace: string;
+}
+
+export interface DebugLevels {
+    trace: 0;
+    debug: 1;
+    info: 2;
+    warn: 3;
+    error: 4;
+    fatal: 5;
+    silent: 6;
+}
+
+export interface Debug {
+    (namespace: string): DebugLogger;
+    /** Set minimum log level globally. */
+    level(level: keyof DebugLevels | number): void;
+    /** Enable/disable namespaces (same syntax as DEBUG env var). */
+    enable(patterns: string): void;
+    /** Disable all debug output. */
+    disable(): void;
+    /** Enable structured JSON output. */
+    json(on?: boolean): void;
+    /** Enable/disable timestamps. */
+    timestamps(on?: boolean): void;
+    /** Enable/disable colors. */
+    colors(on?: boolean): void;
+    /** Set custom output stream. */
+    output(stream: { write(s: string): void }): void;
+    /** Reset all settings to defaults. */
+    reset(): void;
+    /** Level constants. */
+    readonly LEVELS: DebugLevels;
+}
+
+export const debug: Debug;

package/types/fetch.d.ts

@@ -0,0 +1,43 @@
+import { Readable } from 'stream';
+
+export interface FetchOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | Buffer | object | Readable | URLSearchParams | ArrayBuffer | Uint8Array;
+    timeout?: number;
+    signal?: AbortSignal;
+    agent?: any;
+    onDownloadProgress?: (progress: { loaded: number; total: number | null }) => void;
+    onUploadProgress?: (progress: { loaded: number; total: number | null }) => void;
+    // TLS options
+    rejectUnauthorized?: boolean;
+    ca?: string | Buffer | Array<string | Buffer>;
+    cert?: string | Buffer;
+    key?: string | Buffer;
+    pfx?: string | Buffer;
+    passphrase?: string;
+    servername?: string;
+    ciphers?: string;
+    secureProtocol?: string;
+    minVersion?: string;
+    maxVersion?: string;
+}
+
+export interface FetchHeaders {
+    get(name: string): string | undefined;
+    raw: Record<string, string | string[]>;
+}
+
+export interface FetchResponse {
+    status: number;
+    statusText: string;
+    ok: boolean;
+    secure: boolean;
+    url: string;
+    headers: FetchHeaders;
+    arrayBuffer(): Promise<Buffer>;
+    text(): Promise<string>;
+    json(): Promise<any>;
+}
+
+export function fetch(url: string, opts?: FetchOptions): Promise<FetchResponse>;