cpeak 2.5.0 → 2.7.0

package/lib/index.ts

@@ -2,9 +2,17 @@ import http from "node:http";
 import fs from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { pipeline } from "node:stream/promises";
+import type { Readable } from "node:stream";
+import type { Buffer } from "node:buffer";
+
+import {
+  resolveCompressionOptions,
+  compressAndSend
+} from "./internal/compression";
 
 import type {
   StringMap,
+  CpeakOptions,
   CpeakRequest,
   CpeakResponse,
   Middleware,
@@ -13,6 +21,8 @@ import type {
   RoutesMap
 } 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,
@@ -40,38 +50,43 @@ export enum ErrorCode {
   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"
+  PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE",
+  WEAK_SECRET = "CPEAK_ERR_WEAK_SECRET",
+  COMPRESSION_NOT_ENABLED = "CPEAK_ERR_COMPRESSION_NOT_ENABLED"
 }
 
-class CpeakIncomingMessage extends http.IncomingMessage {
+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;
   public params: StringMap = {};
 
-  private _query?: StringMap;
+  #query?: StringMap;
 
   // Parse the URL parameters (like /users?key1=value1&key2=value2)
   // We will call this query to be more familiar with other node.js frameworks.
   // This is a getter method (accessed like a property)
   get query(): StringMap {
     // This way if a developer writes req.query multiple times, we don't parse it multiple times
-    if (this._query) return this._query;
+    if (this.#query) return this.#query;
 
     const url = this.url || "";
     const qIndex = url.indexOf("?");
 
     if (qIndex === -1) {
-      this._query = {};
+      this.#query = {};
     } else {
       const searchParams = new URLSearchParams(url.substring(qIndex + 1));
-      this._query = Object.fromEntries(searchParams.entries());
+      this.#query = Object.fromEntries(searchParams.entries());
     }
 
-    return this._query;
+    return this.#query;
   }
 }
 
-class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
+export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
+  // Set per-request from the Cpeak instance. Undefined when compression isn't enabled.
+  _compression?: ResolvedCompressionConfig;
+
   // Send a file back to the client
   async sendFile(path: string, mime: string) {
     if (!mime) {
@@ -92,6 +107,17 @@ class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
         );
       }
 
+      if (this._compression) {
+        await compressAndSend(
+          this,
+          mime,
+          createReadStream(path),
+          this._compression,
+          stat.size
+        );
+        return;
+      }
+
       this.setHeader("Content-Type", mime);
       this.setHeader("Content-Length", String(stat.size));
 
@@ -120,157 +146,188 @@ class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
     return this;
   }
 
+  // Set the Content-Disposition header to prompt the user to download a file
+  attachment(filename?: string) {
+    const contentDisposition = filename
+      ? `attachment; filename="${filename}"`
+      : "attachment";
+    this.setHeader("Content-Disposition", contentDisposition);
+    return this;
+  }
+
   // Redirects to a new URL
   redirect(location: string) {
     this.writeHead(302, { Location: location });
     this.end();
-    return this;
   }
 
-  // Send a json data back to the client (for small json data, less than the highWaterMark)
-  json(data: any) {
-    // This is only good for bodies that their size is less than the highWaterMark value
+  // 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> {
+    const body = JSON.stringify(data);
+    if (this._compression) {
+      return compressAndSend(this, "application/json", body, this._compression);
+    }
     this.setHeader("Content-Type", "application/json");
-    this.end(JSON.stringify(data));
+    this.end(body);
+  }
+
+  // Explicit compression entry point. A developer can use this in any custom handler to compress arbitrary responses
+  compress(
+    mime: string,
+    body: Buffer | string | Readable,
+    size?: number
+  ): Promise<void> {
+    if (!this._compression) {
+      throw frameworkError(
+        "compression is not enabled. Pass `compression` to cpeak({ compression: true | { ... } }) to use res.compress.",
+        this.compress,
+        ErrorCode.COMPRESSION_NOT_ENABLED
+      );
+    }
+    return compressAndSend(this, mime, body, this._compression, size);
   }
 }
 
-class Cpeak {
-  private server: http.Server<
-    typeof CpeakIncomingMessage,
-    typeof CpeakServerResponse
-  >;
-  private routes: RoutesMap;
-  private middleware: Middleware[];
-  private _handleErr?: (
-    err: unknown,
-    req: CpeakRequest,
-    res: CpeakResponse
-  ) => void;
-
-  constructor() {
-    this.server = http.createServer({
+export class Cpeak {
+  #server: http.Server<typeof CpeakIncomingMessage, typeof CpeakServerResponse>;
+  #routes: RoutesMap;
+  #middleware: Middleware[];
+  #handleErr?: (err: unknown, req: CpeakRequest, res: CpeakResponse) => void;
+  #compression?: ResolvedCompressionConfig;
+
+  constructor(options: CpeakOptions = {}) {
+    this.#server = http.createServer({
       IncomingMessage: CpeakIncomingMessage,
       ServerResponse: CpeakServerResponse
     });
-    this.routes = {};
-    this.middleware = [];
-
-    this.server.on("request", async (req: CpeakRequest, res: CpeakResponse) => {
-      // Get the url without the URL parameters (query strings)
-      const qIndex = req.url?.indexOf("?");
-      const urlWithoutQueries =
-        qIndex === -1 ? req.url || "" : req.url?.substring(0, qIndex);
-
-      // Run all the specific middleware functions for that router only and then run the handler
-      const runHandler = async (
-        req: CpeakRequest,
-        res: CpeakResponse,
-        middleware: RouteMiddleware[],
-        cb: Handler,
-        index: number
-      ) => {
-        // 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.
-          try {
-            await cb(req, res, (error) => {
-              res.setHeader("Connection", "close");
-              this._handleErr?.(error, req, res);
-            });
-          } catch (error) {
-            res.setHeader("Connection", "close");
-            this._handleErr?.(error, req, res);
+    this.#routes = {};
+    this.#middleware = [];
+
+    // Resolve compression options once at app startup.
+    if (options.compression) {
+      this.#compression = resolveCompressionOptions(options.compression);
+    }
+
+    this.#server.on(
+      "request",
+      async (req: CpeakRequest, res: CpeakResponse) => {
+        res._compression = this.#compression;
+
+        // Get the url without the URL parameters (query strings)
+        const qIndex = req.url?.indexOf("?");
+        const urlWithoutQueries =
+          qIndex === -1 ? req.url || "" : req.url?.substring(0, qIndex);
+
+        const dispatchError = (error: unknown) => {
+          if (res.headersSent) {
+            req.socket?.destroy();
+            return;
           }
-        } 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.
-          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) {
-                  res.setHeader("Connection", "close");
-                  return this._handleErr?.(error, req, res);
-                }
-                await runHandler(req, res, middleware, cb, index + 1);
-              },
-              // Error handler for a route middleware
-              (error) => {
-                res.setHeader("Connection", "close");
-                this._handleErr?.(error, req, res);
-              }
-            );
-          } catch (error) {
-            res.setHeader("Connection", "close");
-            this._handleErr?.(error, req, res);
+          res.setHeader("Connection", "close");
+          this.#handleErr?.(error, req, res);
+        };
+
+        // Run all the specific middleware functions for that router only and then run the handler
+        const runHandler = async (
+          req: CpeakRequest,
+          res: CpeakResponse,
+          middleware: RouteMiddleware[],
+          cb: Handler,
+          index: number
+        ) => {
+          // 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.
+            try {
+              await cb(req, res, dispatchError);
+            } 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.
+            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
+              );
+            } catch (error) {
+              dispatchError(error);
+            }
           }
-        }
-      };
-
-      // Run all the middleware functions (beforeEach functions) before we run the corresponding route
-      const runMiddleware = async (
-        req: CpeakRequest,
-        res: CpeakResponse,
-        middleware: Middleware[],
-        index: number
-      ) => {
-        // 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
-                );
+        };
+
+        // Run all the middleware functions (beforeEach functions) before we run the corresponding route
+        const runMiddleware = async (
+          req: CpeakRequest,
+          res: CpeakResponse,
+          middleware: Middleware[],
+          index: number
+        ) => {
+          // 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
+                  );
+                }
               }
-            }
 
-          // If the requested route dose not exist, return 404
-          return res
-            .status(404)
-            .json({ error: `Cannot ${req.method} ${urlWithoutQueries}` });
-        } else {
-          try {
-            await middleware[index](req, res, async (err?: unknown) => {
-              if (err) {
-                res.setHeader("Connection", "close");
-                return this._handleErr?.(err, req, res);
-              }
-              await runMiddleware(req, res, middleware, index + 1);
-            });
-          } catch (error) {
-            res.setHeader("Connection", "close");
-            this._handleErr?.(error, req, res);
+            // If the requested route dose not exist, return 404
+            return res
+              .status(404)
+              .json({ error: `Cannot ${req.method} ${urlWithoutQueries}` });
+          } else {
+            try {
+              await middleware[index](req, res, async (err?: unknown) => {
+                if (err) {
+                  return dispatchError(err);
+                }
+                await runMiddleware(req, res, middleware, index + 1);
+              });
+            } catch (error) {
+              dispatchError(error);
+            }
           }
-        }
-      };
+        };
 
-      await runMiddleware(req, res, this.middleware, 0);
-    });
+        await runMiddleware(req, res, this.#middleware, 0);
+      }
+    );
   }
 
   route(method: string, path: string, ...args: (RouteMiddleware | Handler)[]) {
-    if (!this.routes[method]) this.routes[method] = [];
+    if (!this.#routes[method]) this.#routes[method] = [];
 
     // The last argument should always be our handler
     const cb = args.pop() as Handler;
@@ -283,40 +340,37 @@ class Cpeak {
     const middleware = args.flat() as RouteMiddleware[];
 
     const regex = this.#pathToRegex(path);
-    this.routes[method].push({ path, regex, middleware, cb });
+    this.#routes[method].push({ path, regex, middleware, cb });
   }
 
   beforeEach(cb: Middleware) {
-    this.middleware.push(cb);
+    this.#middleware.push(cb);
   }
 
   handleErr(cb: (err: unknown, req: CpeakRequest, res: CpeakResponse) => void) {
-    this._handleErr = cb;
+    this.#handleErr = cb;
   }
 
   listen(port: number, cb?: () => void) {
-    return this.server.listen(port, cb);
+    return this.#server.listen(port, cb);
+  }
+
+  address() {
+    return this.#server.address();
   }
 
   close(cb?: (err?: Error) => void) {
-    this.server.close(cb);
+    this.#server.close(cb);
   }
 
   // ------------------------------
   // PRIVATE METHODS:
   // ------------------------------
   #pathToRegex(path: string) {
-    const paramNames: string[] = [];
     const regexString =
-      "^" +
-      path.replace(/:\w+/g, (match, offset) => {
-        paramNames.push(match.slice(1));
-        return "([^/]+)";
-      }) +
-      "$";
-
-    const regex = new RegExp(regexString);
-    return regex;
+      "^" + path.replace(/:\w+/g, "([^/]+)").replace(/\*/g, ".*") + "$";
+
+    return new RegExp(regexString);
   }
 
   #extractPathVariables(path: string, match: RegExpMatchArray) {
@@ -333,12 +387,29 @@ class Cpeak {
 }
 
 // Util functions
-export { serveStatic } from "./utils/serveStatic.js";
-export { parseJSON } from "./utils/paseJSON.js";
-export { render } from "./utils/render.js";
+export {
+  serveStatic,
+  parseJSON,
+  render,
+  swagger,
+  auth,
+  hashPassword,
+  verifyPassword,
+  cookieParser,
+  cors
+} from "./utils";
+
+export type {
+  AuthOptions,
+  PbkdfOptions,
+  CookieOptions,
+  CorsOptions
+} from "./utils/types";
+
+export type { CompressionOptions } from "./internal/types";
 
 export type {
-  Cpeak,
+  CpeakOptions,
   CpeakRequest,
   CpeakResponse,
   Next,
@@ -349,6 +420,6 @@ export type {
   RoutesMap
 } from "./types";
 
-export default function cpeak() {
-  return new Cpeak();
+export default function cpeak(options?: CpeakOptions): Cpeak {
+  return new Cpeak(options);
 }