cpeak 2.4.3 → 2.6.0

package/lib/index.ts

@@ -10,19 +10,26 @@ import type {
   Middleware,
   RouteMiddleware,
   Handler,
-  RoutesMap,
+  RoutesMap
 } from "./types";
 
 // A utility function to create an error with a custom stack trace
 export function frameworkError(
   message: string,
   skipFn: Function,
-  code?: string
+  code?: string,
+  status?: number
 ) {
-  const err = new Error(message) as Error & { code?: string };
+  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;
 }
@@ -32,207 +39,241 @@ export enum ErrorCode {
   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"
 }
 
-class Cpeak {
-  private server: http.Server;
-  private routes: RoutesMap;
-  private middleware: Middleware[];
-  private _handleErr?: (
-    err: unknown,
-    req: CpeakRequest,
-    res: CpeakResponse
-  ) => void;
+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 = {};
 
-  constructor() {
-    this.server = http.createServer();
-    this.routes = {};
-    this.middleware = [];
-
-    this.server.on("request", (req: CpeakRequest, res: CpeakResponse) => {
-      // Send a file back to the client
-      res.sendFile = async (path: string, mime: string) => {
-        if (!mime) {
-          throw frameworkError(
-            'MIME type is missing. Use res.sendFile(path, "mime-type").',
-            res.sendFile,
-            ErrorCode.MISSING_MIME
-          );
-        }
-
-        try {
-          const stat = await fs.stat(path);
-          if (!stat.isFile()) {
-            throw frameworkError(
-              `Not a file: ${path}`,
-              res.sendFile,
-              ErrorCode.NOT_A_FILE
-            );
-          }
+  #query?: StringMap;
 
-          res.setHeader("Content-Type", mime);
-          res.setHeader("Content-Length", String(stat.size));
-
-          // Properly propagate stream errors and respect backpressure
-          await pipeline(createReadStream(path), res);
-        } catch (err: any) {
-          if (err?.code === "ENOENT") {
-            throw frameworkError(
-              `File not found: ${path}`,
-              res.sendFile,
-              ErrorCode.FILE_NOT_FOUND
-            );
-          }
+  // 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;
 
-          throw frameworkError(
-            `Failed to send file: ${path}`,
-            res.sendFile,
-            ErrorCode.SEND_FILE_FAIL
-          );
-        }
-      };
-
-      // Set the status code of the response
-      res.status = (code: number) => {
-        res.statusCode = code;
-        return res;
-      };
-
-      // Redirects to a new URL
-      res.redirect = (location: string) => {
-        res.writeHead(302, { Location: location });
-        res.end();
-        return res;
-      };
-
-      // Send a json data back to the client (for small json data, less than the highWaterMark)
-      res.json = (data: any) => {
-        // This is only good for bodies that their size is less than the highWaterMark value
-        res.setHeader("Content-Type", "application/json");
-        res.end(JSON.stringify(data));
-      };
-
-      // Get the url without the URL parameters
-      const urlWithoutParams = req.url?.split("?")[0];
-
-      // Parse the URL parameters (like /users?key1=value1&key2=value2)
-      // We put this here to also parse them for all the middleware functions
-      const params = new URLSearchParams(req.url?.split("?")[1]);
-
-      const paramsObject = Object.fromEntries(params.entries());
-
-      req.params = paramsObject;
-      req.query = paramsObject; // only for compatibility with frameworks built for express
-
-      // Run all the specific middleware functions for that router only and then run the handler
-      const runHandler = (
-        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 {
-            const handlerResult = cb(req, res, (error) => {
-              res.setHeader("Connection", "close");
-              this._handleErr?.(error, req, res);
-            });
-
-            if (handlerResult && typeof handlerResult.then === "function") {
-              handlerResult.catch((error) => {
-                res.setHeader("Connection", "close");
-                this._handleErr?.(error, req, res);
-              });
-            }
+    const url = this.url || "";
+    const qIndex = url.indexOf("?");
+
+    if (qIndex === -1) {
+      this.#query = {};
+    } else {
+      const searchParams = new URLSearchParams(url.substring(qIndex + 1));
+      this.#query = Object.fromEntries(searchParams.entries());
+    }
+
+    return this.#query;
+  }
+}
+
+export class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
+  // Send a file back to the client
+  async sendFile(path: string, mime: string) {
+    if (!mime) {
+      throw frameworkError(
+        'MIME type is missing. Use res.sendFile(path, "mime-type").',
+        this.sendFile,
+        ErrorCode.MISSING_MIME
+      );
+    }
+
+    try {
+      const stat = await fs.stat(path);
+      if (!stat.isFile()) {
+        throw frameworkError(
+          `Not a file: ${path}`,
+          this.sendFile,
+          ErrorCode.NOT_A_FILE
+        );
+      }
+
+      this.setHeader("Content-Type", mime);
+      this.setHeader("Content-Length", String(stat.size));
+
+      // Properly propagate stream errors and respect backpressure
+      await pipeline(createReadStream(path), this);
+    } catch (err: any) {
+      if (err?.code === "ENOENT") {
+        throw frameworkError(
+          `File not found: ${path}`,
+          this.sendFile,
+          ErrorCode.FILE_NOT_FOUND
+        );
+      }
+
+      throw frameworkError(
+        `Failed to send file: ${path}`,
+        this.sendFile,
+        ErrorCode.SEND_FILE_FAIL
+      );
+    }
+  }
+
+  // Set the status code of the response
+  status(code: number) {
+    this.statusCode = code;
+    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;
+  }
 
-            return handlerResult;
-          } catch (error) {
-            res.setHeader("Connection", "close");
-            this._handleErr?.(error, req, res);
+  // Redirects to a new URL
+  redirect(location: string) {
+    this.writeHead(302, { Location: location });
+    this.end();
+  }
+
+  // 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
+    this.setHeader("Content-Type", "application/json");
+    this.end(JSON.stringify(data));
+  }
+}
+
+export class Cpeak {
+  #server: http.Server<typeof CpeakIncomingMessage, typeof CpeakServerResponse>;
+  #routes: RoutesMap;
+  #middleware: Middleware[];
+  #handleErr?: (err: unknown, req: CpeakRequest, res: CpeakResponse) => void;
+
+  constructor() {
+    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);
+
+        const dispatchError = (error: unknown) => {
+          if (res.headersSent) {
+            req.socket?.destroy();
+            return;
+          }
+          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);
+            }
           }
-        } 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 {
-            const middlewareResult = middleware[index](
-              req,
-              res,
-              // The next function
-              (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);
+        };
+
+        // 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
+                  );
                 }
-                runHandler(req, res, middleware, cb, index + 1);
-              },
-              // Error handler for a route middleware
-              (error) => {
-                res.setHeader("Connection", "close");
-                this._handleErr?.(error, req, res);
               }
-            );
-
-            // If the middleware is async, handle the promise rejection
-            if (
-              middlewareResult &&
-              typeof middlewareResult.then === "function"
-            ) {
-              middlewareResult.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);
             }
-          } catch (error) {
-            res.setHeader("Connection", "close");
-            this._handleErr?.(error, req, res);
           }
-        }
-      };
-
-      // Run all the middleware functions (beforeEach functions) before we run the corresponding route
-      const runMiddleware = (
-        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 = urlWithoutParams?.match(route.regex);
-
-              if (match) {
-                // Parse the URL variables from the matched route (like /users/:id)
-                const vars = this.#extractVars(route.path, match);
-                req.vars = vars;
-
-                return 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} ${urlWithoutParams}` });
-        } else {
-          middleware[index](req, res, () => {
-            runMiddleware(req, res, middleware, index + 1);
-          });
-        }
-      };
-
-      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;
@@ -245,62 +286,66 @@ 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 varNames: string[] = [];
     const regexString =
-      "^" +
-      path.replace(/:\w+/g, (match, offset) => {
-        varNames.push(match.slice(1));
-        return "([^/]+)";
-      }) +
-      "$";
-
-    const regex = new RegExp(regexString);
-    return regex;
+      "^" + path.replace(/:\w+/g, "([^/]+)").replace(/\*/g, ".*") + "$";
+
+    return new RegExp(regexString);
   }
 
-  #extractVars(path: string, match: RegExpMatchArray) {
-    // Extract url variable values from the matched route
-    const varNames = (path.match(/:\w+/g) || []).map((varParam) =>
-      varParam.slice(1)
+  #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 vars: StringMap = {};
-    varNames.forEach((name, index) => {
-      vars[name] = match[index + 1];
+    const params: StringMap = {};
+    paramNames.forEach((name, index) => {
+      params[name] = match[index + 1];
     });
-    return vars;
+    return params;
   }
 }
 
 // Util functions
-export { serveStatic } from "./utils/serveStatic.js";
-export { parseJSON } from "./utils/parseJSON.js";
-export { render } from "./utils/render.js";
+export {
+  serveStatic,
+  parseJSON,
+  render,
+  swagger,
+  auth,
+  hashPassword,
+  verifyPassword,
+  cookieParser
+} from "./utils";
+export type { AuthOptions, PbkdfOptions, CookieOptions } from "./utils";
 
 export type {
-  Cpeak,
   CpeakRequest,
   CpeakResponse,
   Next,
@@ -308,9 +353,9 @@ export type {
   Middleware,
   RouteMiddleware,
   Handler,
-  RoutesMap,
+  RoutesMap
 } from "./types";
 
-export default function cpeak() {
+export default function cpeak(): Cpeak {
   return new Cpeak();
 }

package/lib/types.ts

@@ -1,26 +1,28 @@
 import { IncomingMessage, ServerResponse } from "node:http";
-import cpeak from "./index";
 
-export type Cpeak = ReturnType<typeof cpeak>;
+export type { Cpeak } from "./index";
 
 // Extending Node.js's Request and Response objects to add our custom properties
 export type StringMap = Record<string, string>;
 
-export interface CpeakRequest<ReqBody = any, ReqParams = any>
-  extends IncomingMessage {
-  params: ReqParams;
-  vars?: StringMap;
+export interface CpeakRequest<
+  ReqBody = any,
+  ReqQueries = any
+> extends IncomingMessage {
+  params: StringMap;
+  query: ReqQueries;
   body?: ReqBody;
+  cookies?: StringMap;
+  signedCookies?: Record<string, string | false>;
   [key: string]: any; // allow developers to add their onw extensions (e.g. req.test)
-
-  // For express frameworks compatibility:
-  query: ReqParams;
 }
 
 export interface CpeakResponse extends ServerResponse {
   sendFile: (path: string, mime: string) => Promise<void>;
   status: (code: number) => CpeakResponse;
-  redirect: (location: string) => CpeakResponse;
+  attachment: (filename?: string) => CpeakResponse;
+  cookie: (name: string, value: string, options?: any) => CpeakResponse;
+  redirect: (location: string) => void;
   json: (data: any) => void;
   [key: string]: any; // allow developers to add their onw extensions (e.g. res.test)
 }