cpeak 2.7.0 → 2.9.0

package/lib/index.ts

@@ -2,6 +2,8 @@ import http from "node:http";
 import fs from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { pipeline } from "node:stream/promises";
+
+import type net from "node:net";
 import type { Readable } from "node:stream";
 import type { Buffer } from "node:buffer";
 
@@ -9,52 +11,29 @@ import {
   resolveCompressionOptions,
   compressAndSend
 } from "./internal/compression";
+import { MIME_TYPES } from "./internal/mimeTypes";
+import { Router } from "./internal/router";
+import {
+  frameworkError,
+  ErrorCode,
+  isClientDisconnect
+} from "./internal/errors";
+
+export { frameworkError, ErrorCode, isClientDisconnect };
 
 import type {
   StringMap,
+  CpeakHttpServer,
   CpeakOptions,
   CpeakRequest,
   CpeakResponse,
   Middleware,
   RouteMiddleware,
-  Handler,
-  RoutesMap
+  Handler
 } from "./types";
 
 import type { ResolvedCompressionConfig } from "./internal/types";
 
-// A utility function to create an error with a custom stack trace
-export function frameworkError(
-  message: string,
-  skipFn: Function,
-  code?: string,
-  status?: number
-) {
-  const err = new Error(message) as Error & {
-    code?: string;
-    cpeak_err?: boolean;
-  };
-  Error.captureStackTrace(err, skipFn);
-
-  err.cpeak_err = true;
-
-  if (code) err.code = code;
-  if (status) (err as any).status = status;
-
-  return err;
-}
-
-export enum ErrorCode {
-  MISSING_MIME = "CPEAK_ERR_MISSING_MIME",
-  FILE_NOT_FOUND = "CPEAK_ERR_FILE_NOT_FOUND",
-  NOT_A_FILE = "CPEAK_ERR_NOT_A_FILE",
-  SEND_FILE_FAIL = "CPEAK_ERR_SEND_FILE_FAIL",
-  INVALID_JSON = "CPEAK_ERR_INVALID_JSON",
-  PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE",
-  WEAK_SECRET = "CPEAK_ERR_WEAK_SECRET",
-  COMPRESSION_NOT_ENABLED = "CPEAK_ERR_COMPRESSION_NOT_ENABLED"
-}
-
 export class CpeakIncomingMessage extends http.IncomingMessage {
   // We define body and params here for better V8 optimization (not changing the shape of the object at runtime)
   public body: any = undefined;
@@ -88,13 +67,19 @@ export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessag
   _compression?: ResolvedCompressionConfig;
 
   // Send a file back to the client
-  async sendFile(path: string, mime: string) {
+  async sendFile(path: string, mime?: string) {
+    if (this.headersSent) return;
     if (!mime) {
-      throw frameworkError(
-        'MIME type is missing. Use res.sendFile(path, "mime-type").',
-        this.sendFile,
-        ErrorCode.MISSING_MIME
-      );
+      const dotIndex = path.lastIndexOf(".");
+      const fileExtension = dotIndex >= 0 ? path.slice(dotIndex + 1) : "";
+      mime = MIME_TYPES[fileExtension];
+      if (!mime) {
+        throw frameworkError(
+          `MIME type is missing for "${path}". Pass it as the second argument or register the extension via cpeak({ mimeTypes: { ${fileExtension || "ext"}: "..." } }).`,
+          this.sendFile,
+          ErrorCode.MISSING_MIME
+        );
+      }
     }
 
     try {
@@ -135,7 +120,9 @@ export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessag
       throw frameworkError(
         `Failed to send file: ${path}`,
         this.sendFile,
-        ErrorCode.SEND_FILE_FAIL
+        ErrorCode.SEND_FILE_FAIL,
+        undefined,
+        isClientDisconnect(err)
       );
     }
   }
@@ -163,14 +150,23 @@ export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessag
 
   // Send a json data back to the client.
   // This is only good for bodies that their size is less than the highWaterMark value.
-  // Branches into compressAndSend (async) when compression was enabled at cpeak() construction.
-  json(data: any): void | Promise<void> {
+  json(data: any): Promise<void> {
+    if (this.headersSent) return Promise.resolve();
     const body = JSON.stringify(data);
     if (this._compression) {
       return compressAndSend(this, "application/json", body, this._compression);
     }
     this.setHeader("Content-Type", "application/json");
     this.end(body);
+    return Promise.resolve();
+  }
+
+  render(): Promise<void> {
+    throw frameworkError(
+      "render middleware not registered. Add render() via app.beforeEach(render()) to use res.render.",
+      this.render,
+      ErrorCode.RENDER_NOT_ENABLED
+    );
   }
 
   // Explicit compression entry point. A developer can use this in any custom handler to compress arbitrary responses
@@ -179,6 +175,7 @@ export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessag
     body: Buffer | string | Readable,
     size?: number
   ): Promise<void> {
+    if (this.headersSent) return Promise.resolve();
     if (!this._compression) {
       throw frameworkError(
         "compression is not enabled. Pass `compression` to cpeak({ compression: true | { ... } }) to use res.compress.",
@@ -191,10 +188,11 @@ export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessag
 }
 
 export class Cpeak {
-  #server: http.Server<typeof CpeakIncomingMessage, typeof CpeakServerResponse>;
-  #routes: RoutesMap;
+  #server: CpeakHttpServer;
+  #router: Router;
   #middleware: Middleware[];
   #handleErr?: (err: unknown, req: CpeakRequest, res: CpeakResponse) => void;
+  #fallback?: Handler;
   #compression?: ResolvedCompressionConfig;
 
   constructor(options: CpeakOptions = {}) {
@@ -202,7 +200,7 @@ export class Cpeak {
       IncomingMessage: CpeakIncomingMessage,
       ServerResponse: CpeakServerResponse
     });
-    this.#routes = {};
+    this.#router = new Router();
     this.#middleware = [];
 
     // Resolve compression options once at app startup.
@@ -210,6 +208,9 @@ export class Cpeak {
       this.#compression = resolveCompressionOptions(options.compression);
     }
 
+    // Merge developer-supplied mime types with the defaults once at startup
+    if (options.mimeTypes) Object.assign(MIME_TYPES, options.mimeTypes);
+
     this.#server.on(
       "request",
       async (req: CpeakRequest, res: CpeakResponse) => {
@@ -220,13 +221,37 @@ export class Cpeak {
         const urlWithoutQueries =
           qIndex === -1 ? req.url || "" : req.url?.substring(0, qIndex);
 
-        const dispatchError = (error: unknown) => {
+        // Routes every error path through the registered handleErr. Awaits
+        // handleErr so its own async work (or a rejecting res.json under
+        // compression) is caught. If handleErr itself fails, we log and send a
+        // bare 500 so the client never gets a hung socket. Returns a Promise
+        // that never rejects to avoid unhandled promise rejections in case of errors in handleErr.
+        const dispatchError = async (error: unknown) => {
           if (res.headersSent) {
             req.socket?.destroy();
-            return;
+          } else {
+            res.setHeader("Connection", "close");
+          }
+
+          if (isClientDisconnect(error) && !(error as any).clientDisconnect) {
+            (error as any).clientDisconnect = true;
+          }
+          try {
+            await this.#handleErr?.(error, req, res);
+          } catch (handlerFailure) {
+            console.error(
+              "[cpeak] handleErr failed while processing:",
+              error,
+              "\nReason:",
+              handlerFailure
+            );
+            if (!res.headersSent) {
+              try {
+                res.statusCode = 500;
+                res.end();
+              } catch {}
+            }
           }
-          res.setHeader("Connection", "close");
-          this.#handleErr?.(error, req, res);
         };
 
         // Run all the specific middleware functions for that router only and then run the handler
@@ -240,29 +265,22 @@ export class Cpeak {
           // Our exit point...
           if (index === middleware.length) {
             // Call the route handler with the modified req and res objects.
-            // Also handle the promise errors by passing them to the handleErr to save developers from having to manually wrap every handler in try catch.
+            // Also handle the promise errors by passing them to handleErr to save developers from having to manually wrap every handler in try/catch.
             try {
-              await cb(req, res, dispatchError);
+              await cb(req, res);
             } catch (error) {
               dispatchError(error);
             }
           } else {
-            // Handle the promise errors by passing them to the handleErr to save developers from having to manually wrap every handler middleware in try catch.
+            // Handle the promise errors by passing them to handleErr to save developers from having to manually wrap every route middleware in try/catch.
             try {
-              await middleware[index](
-                req,
-                res,
-                // The next function
-                async (error) => {
-                  // this function only accepts an error argument to be more compatible with NPM modules that are built for express
-                  if (error) {
-                    return dispatchError(error);
-                  }
-                  await runHandler(req, res, middleware, cb, index + 1);
-                },
-                // Error handler for a route middleware
-                dispatchError
-              );
+              await middleware[index](req, res, async (error?: unknown) => {
+                // this function only accepts an error argument to be more compatible with NPM modules that are built for express
+                if (error) {
+                  return dispatchError(error);
+                }
+                await runHandler(req, res, middleware, cb, index + 1);
+              });
             } catch (error) {
               dispatchError(error);
             }
@@ -278,32 +296,30 @@ export class Cpeak {
         ) => {
           // Our exit point...
           if (index === middleware.length) {
-            const routes = this.#routes[req.method?.toLowerCase() || ""];
-            if (routes && typeof routes[Symbol.iterator] === "function")
-              for (const route of routes) {
-                const match = urlWithoutQueries?.match(route.regex);
-
-                if (match) {
-                  // Parse the URL path variables from the matched route (like /users/:id)
-                  const pathVariables = this.#extractPathVariables(
-                    route.path,
-                    match
-                  );
-
-                  // We will call this params to be more familiar with other node.js frameworks.
-                  req.params = pathVariables;
-
-                  return await runHandler(
-                    req,
-                    res,
-                    route.middleware,
-                    route.cb,
-                    0
-                  );
-                }
+            const method = req.method?.toLowerCase() || "";
+            const found = this.#router.find(method, urlWithoutQueries || "");
+
+            if (found) {
+              req.params = found.params;
+              return await runHandler(
+                req,
+                res,
+                found.middleware,
+                found.handler,
+                0
+              );
+            }
+
+            // If a fallback handler is registered, run it before falling back to the default 404
+            if (this.#fallback) {
+              try {
+                return await this.#fallback(req, res);
+              } catch (error) {
+                return dispatchError(error);
               }
+            }
 
-            // If the requested route dose not exist, return 404
+            // If the requested route dose not exist, and developer has not registered the fallback handler, return 404
             return res
               .status(404)
               .json({ error: `Cannot ${req.method} ${urlWithoutQueries}` });
@@ -327,8 +343,6 @@ export class Cpeak {
   }
 
   route(method: string, path: string, ...args: (RouteMiddleware | Handler)[]) {
-    if (!this.#routes[method]) this.#routes[method] = [];
-
     // The last argument should always be our handler
     const cb = args.pop() as Handler;
 
@@ -339,8 +353,7 @@ export class Cpeak {
     // Rest will be our middleware functions
     const middleware = args.flat() as RouteMiddleware[];
 
-    const regex = this.#pathToRegex(path);
-    this.#routes[method].push({ path, regex, middleware, cb });
+    this.#router.add(method, path, middleware, cb);
   }
 
   beforeEach(cb: Middleware) {
@@ -351,8 +364,24 @@ export class Cpeak {
     this.#handleErr = cb;
   }
 
-  listen(port: number, cb?: () => void) {
-    return this.#server.listen(port, cb);
+  // This will handle any request that doesn't match any of the routes and middleware functions
+  fallback(cb: Handler) {
+    if (this.#fallback) {
+      throw frameworkError(
+        "Fallback handler is already registered. Only one fallback can be set per app.",
+        this.fallback,
+        ErrorCode.DUPLICATE_FALLBACK
+      );
+    }
+    this.#fallback = cb;
+  }
+
+  // The first 3 listens are just TS overloads for better type inference and editor autocompletion. The last one is the actual implementation.
+  listen(port: number, cb?: () => void): CpeakHttpServer;
+  listen(port: number, host: string, cb?: () => void): CpeakHttpServer;
+  listen(options: net.ListenOptions, cb?: () => void): CpeakHttpServer;
+  listen(...args: any[]) {
+    return this.#server.listen(...args);
   }
 
   address() {
@@ -360,29 +389,12 @@ export class Cpeak {
   }
 
   close(cb?: (err?: Error) => void) {
-    this.#server.close(cb);
+    return this.#server.close(cb);
   }
 
-  // ------------------------------
-  // PRIVATE METHODS:
-  // ------------------------------
-  #pathToRegex(path: string) {
-    const regexString =
-      "^" + path.replace(/:\w+/g, "([^/]+)").replace(/\*/g, ".*") + "$";
-
-    return new RegExp(regexString);
-  }
-
-  #extractPathVariables(path: string, match: RegExpMatchArray) {
-    // Extract path url variable values from the matched route
-    const paramNames = (path.match(/:\w+/g) || []).map((param) =>
-      param.slice(1)
-    );
-    const params: StringMap = {};
-    paramNames.forEach((name, index) => {
-      params[name] = match[index + 1];
-    });
-    return params;
+  // A getter for developers who want to access the underlying http server instance for advanced use cases that aren't covered by Cpeak
+  get server() {
+    return this.#server;
   }
 }
 
@@ -409,15 +421,14 @@ export type {
 export type { CompressionOptions } from "./internal/types";
 
 export type {
+  CpeakHttpServer,
   CpeakOptions,
   CpeakRequest,
   CpeakResponse,
   Next,
-  HandleErr,
   Middleware,
   RouteMiddleware,
-  Handler,
-  RoutesMap
+  Handler
 } from "./types";
 
 export default function cpeak(options?: CpeakOptions): Cpeak {

package/lib/internal/errors.ts

@@ -0,0 +1,51 @@
+// A utility function to create an error with a custom stack trace
+export function frameworkError(
+  message: string,
+  skipFn: Function,
+  code?: string,
+  status?: number,
+  clientDisconnect?: boolean
+) {
+  const err = new Error(message) as Error & {
+    code?: string;
+    cpeak_err?: boolean;
+    clientDisconnect?: boolean;
+  };
+  Error.captureStackTrace(err, skipFn);
+
+  err.cpeak_err = true;
+
+  if (code) err.code = code;
+  if (status) (err as any).status = status;
+  if (clientDisconnect) err.clientDisconnect = true;
+
+  return err;
+}
+
+const CLIENT_DISCONNECT_CODES = new Set([
+  "ERR_STREAM_PREMATURE_CLOSE",
+  "ERR_STREAM_DESTROYED",
+  "ECONNRESET",
+  "EPIPE"
+]);
+
+export function isClientDisconnect(err: unknown): boolean {
+  return CLIENT_DISCONNECT_CODES.has((err as any)?.code);
+}
+
+export enum ErrorCode {
+  MISSING_MIME = "CPEAK_ERR_MISSING_MIME",
+  FILE_NOT_FOUND = "CPEAK_ERR_FILE_NOT_FOUND",
+  NOT_A_FILE = "CPEAK_ERR_NOT_A_FILE",
+  SEND_FILE_FAIL = "CPEAK_ERR_SEND_FILE_FAIL",
+  INVALID_JSON = "CPEAK_ERR_INVALID_JSON",
+  PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE",
+  WEAK_SECRET = "CPEAK_ERR_WEAK_SECRET",
+  COMPRESSION_NOT_ENABLED = "CPEAK_ERR_COMPRESSION_NOT_ENABLED",
+  RENDER_NOT_ENABLED = "CPEAK_ERR_RENDER_NOT_ENABLED",
+  // For router:
+  DUPLICATE_ROUTE = "CPEAK_ERR_DUPLICATE_ROUTE",
+  INVALID_ROUTE = "CPEAK_ERR_INVALID_ROUTE",
+  DUPLICATE_FALLBACK = "CPEAK_ERR_DUPLICATE_FALLBACK",
+  RENDER_FAIL = "CPEAK_ERR_RENDER_FAIL"
+}

package/lib/internal/mimeTypes.ts

@@ -0,0 +1,31 @@
+import type { StringMap } from "../types";
+
+// Developers can expand this if needed in the cpeak() constructor
+export const MIME_TYPES: StringMap = {
+  html: "text/html",
+  css: "text/css",
+  js: "application/javascript",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  svg: "image/svg+xml",
+  txt: "text/plain",
+  eot: "application/vnd.ms-fontobject",
+  otf: "font/otf",
+  ttf: "font/ttf",
+  woff: "font/woff",
+  woff2: "font/woff2",
+  gif: "image/gif",
+  ico: "image/x-icon",
+  json: "application/json",
+  map: "application/json",
+  webmanifest: "application/manifest+json",
+  xml: "application/xml",
+  pdf: "application/pdf",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  webp: "image/webp",
+  avif: "image/avif"
+};