cpeak 2.4.2 → 2.5.0

package/README.md

@@ -52,7 +52,7 @@ Cpeak is a **pure ESM** package, and to use it, your project needs to be an ESM
 ```javascript
 import cpeak from "cpeak";
 
-const server = new cpeak();
+const server = cpeak();
 
 server.route("get", "/", (req, res) => {
   res.json({ message: "Hi there!" });
@@ -84,7 +84,7 @@ import cpeak, { serveStatic, parseJSON } from "cpeak";
 Initialize the Cpeak server like this:
 
 ```javascript
-const server = new cpeak();
+const server = cpeak();
 ```
 
 Now you can use this server object to start listening, add route logic, add middleware functions, and handle errors.
@@ -131,7 +131,7 @@ const requireAuth = (req, res, next, handleErr) => {
   return handleErr({ status: 401, message: "Unauthorized" });
 };
 
-server.route("get", "/profile", requireAuth, (req, res, handleErr) => {
+server.route("get", "/profile", requireAuth, (req, res) => {
   console.log(req.test); // this is a test value
 });
 ```
@@ -145,7 +145,7 @@ server.route(
   requireAuth,
   anotherFunction,
   oneMore,
-  (req, res, handleErr) => {
+  (req, res) => {
     // your logic
   }
 );
@@ -165,16 +165,15 @@ First add the HTTP method name you want to handle, then the path, and finally, t
 
 ### URL Variables & Parameters
 
-Since in HTTP these are called URL parameters: `/path?key1=value1&key2=value2&foo=900`, in Cpeak, we also call them `params` (short for HTTP URL parameters).
-We can also do custom path management, and we call them `vars` (short for URL variables).
+To be more consistent with the broader Node.js community and frameworks, we call the HTTP URL parameters (query strings) '**query**', and the path variables (route parameters) '**params**'.
 
 Here’s how we can read both:
 
 ```javascript
 // Imagine request URL is example.com/test/my-title/more-text?filter=newest
 server.route("patch", "/test/:title/more-text", (req, res) => {
-  const title = req.vars.title;
-  const filter = req.params.filter;
+  const title = req.params.title;
+  const filter = req.query.filter;
 
   console.log(title); // my-title
   console.log(filter); // newest
@@ -206,11 +205,23 @@ res.redirect("https://whatever.com");
 
 ### Error Handling
 
-If anywhere in your route functions or route middleware functions you want to return an error, it's cleaner to pass it to the `handleErr` function like this:
+If anywhere in your route functions or route middleware functions you want to return an error, you can just throw the error and let the automatic error handler catch it:
+
+```javascript
+server.route("get", "/api/document/:title", (req, res) => {
+  const title = req.params.title;
+
+  if (title.length > 500) throw { status: 400, message: "Title too long." };
+
+  // The rest of your logic...
+});
+```
+
+You can also make use of the `handleErr` callback function like this:
 
 ```javascript
 server.route("get", "/api/document/:title", (req, res, handleErr) => {
-  const title = req.vars.title;
+  const title = req.params.title;
 
   if (title.length > 500)
     return handleErr({ status: 400, message: "Title too long." });
@@ -219,7 +230,7 @@ server.route("get", "/api/document/:title", (req, res, handleErr) => {
 });
 ```
 
-And then handle all the errors like this in the `handleErr` callback:
+**Make sure** to call the `server.handleErr` and pass a function like this to have the automatic error handler work properly:
 
 ```javascript
 server.handleErr((error, req, res) => {
@@ -229,13 +240,13 @@ server.handleErr((error, req, res) => {
     // Log the unexpected errors somewhere so you can keep track of them...
     console.error(error);
     res.status(500).json({
-      error: "Sorry, something unexpected happened on our side.",
+      error: "Sorry, something unexpected happened on our side."
     });
   }
 });
 ```
 
-The error object is the object that you passed to the `handleErr` function earlier in your routes.
+_The error object is the object that you threw or passed to the `handleErr` function earlier in your routes._
 
 ### Listening
 
@@ -270,7 +281,7 @@ With this middleware function, you can automatically set a folder in your projec
 ```javascript
 server.beforeEach(
   serveStatic("./public", {
-    mp3: "audio/mpeg",
+    mp3: "audio/mpeg"
   })
 );
 ```
@@ -298,7 +309,9 @@ If you have file types in your public folder that are not one of the following,
 With this middleware function, you can easily read and send JSON in HTTP message bodies in route and middleware functions. Fire it up like this:
 
 ```javascript
-server.beforeEach(parseJSON);
+// You can pass an optional limit option to indicate the maximum
+// JSON body size that your server will accept.
+server.beforeEach(parseJSON({ limit: 1024 * 1024 })); // default value is 1024 * 1024 (1MB)
 ```
 
 Read and send JSON from HTTP messages like this:
@@ -333,7 +346,7 @@ server.route("get", "/", (req, res, next) => {
     "./public/index.html",
     {
       title: "Page title",
-      name: "Allan",
+      name: "Allan"
     },
     "text/html"
   );
@@ -360,18 +373,18 @@ Here you can see all the features that Cpeak offers, in one small piece of code:
 ```javascript
 import cpeak, { serveStatic, parseJSON, render } from "cpeak";
 
-const server = new cpeak();
+const server = cpeak();
 
 server.beforeEach(
   serveStatic("./public", {
-    mp3: "audio/mpeg",
+    mp3: "audio/mpeg"
   })
 );
 
 server.beforeEach(render());
 
 // For parsing JSON bodies
-server.beforeEach(parseJSON);
+server.beforeEach(parseJSON());
 
 // Adding custom middleware functions
 server.beforeEach((req, res, next) => {
@@ -383,7 +396,7 @@ server.beforeEach((req, res, next) => {
 const testRouteMiddleware = (req, res, next, handleErr) => {
   req.whatever = "some calculated value maybe";
 
-  if (req.vars.test !== "something special") {
+  if (req.params.test !== "something special") {
     return handleErr({ status: 400, message: "an error message" });
   }
 
@@ -396,7 +409,7 @@ server.route("get", "/", (req, res, next) => {
     "<path-to-file-relative-to-cwd>",
     {
       test: "some testing value",
-      number: "2343242",
+      number: "2343242"
     },
     "<mime-type>"
   );
@@ -406,28 +419,23 @@ server.route("get", "/old-url", testRouteMiddleware, (req, res, next) => {
   return res.redirect("/new-url");
 });
 
-server.route(
-  "get",
-  "/api/document/:title",
-  testRouteMiddleware,
-  (req, res, handleErr) => {
-    // Reading URL variables
-    const title = req.vars.title;
+server.route("get", "/api/document/:title", testRouteMiddleware, (req, res) => {
+  // Reading URL variables (route parameters)
+  const title = req.params.title;
 
-    // Reading URL parameters (like /users?filter=active)
-    const filter = req.params.filter;
+  // Reading URL parameters (query strings) (like /users?filter=active)
+  const filter = req.query.filter;
 
-    // Reading JSON request body
-    const anything = req.body.anything;
+  // Reading JSON request body
+  const anything = req.body.anything;
 
-    // Handling errors
-    if (anything === "not-expected-thing")
-      return handleErr({ status: 400, message: "Invalid property." });
+  // Handling errors
+  if (anything === "not-expected-thing")
+    throw { status: 400, message: "Invalid property." };
 
-    // Sending a JSON response
-    res.status(200).json({ message: "This is a test response" });
-  }
-);
+  // Sending a JSON response
+  res.status(200).json({ message: "This is a test response" });
+});
 
 // Sending a file response
 server.route("get", "/file", (req, res) => {
@@ -442,7 +450,7 @@ server.handleErr((error, req, res) => {
   } else {
     console.error(error);
     res.status(500).json({
-      error: "Sorry, something unexpected happened from our side.",
+      error: "Sorry, something unexpected happened from our side."
     });
   }
 });

package/dist/index.d.ts

@@ -2,12 +2,11 @@ import http, { IncomingMessage, ServerResponse } from 'node:http';
 
 type Cpeak$1 = ReturnType<typeof cpeak>;
 type StringMap = Record<string, string>;
-interface CpeakRequest<ReqBody = any, ReqParams = any> extends IncomingMessage {
-    params: ReqParams;
-    vars?: StringMap;
+interface CpeakRequest<ReqBody = any, ReqQueries = any> extends IncomingMessage {
+    params: StringMap;
+    query: ReqQueries;
     body?: ReqBody;
     [key: string]: any;
-    query: ReqParams;
 }
 interface CpeakResponse extends ServerResponse {
     sendFile: (path: string, mime: string) => Promise<void>;
@@ -33,18 +32,35 @@ interface RoutesMap {
 
 declare const serveStatic: (folderPath: string, newMimeTypes?: StringMap) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void | Promise<void>;
 
-declare const parseJSON: (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
+declare const parseJSON: (options?: {
+    limit?: number;
+}) => (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
 
 declare const render: () => (req: CpeakRequest, res: CpeakResponse, next: Next) => void;
 
-declare function frameworkError(message: string, skipFn: Function, code?: string): Error & {
+declare function frameworkError(message: string, skipFn: Function, code?: string, status?: number): Error & {
     code?: string;
+    cpeak_err?: boolean;
 };
 declare 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"
+    SEND_FILE_FAIL = "CPEAK_ERR_SEND_FILE_FAIL",
+    INVALID_JSON = "CPEAK_ERR_INVALID_JSON",
+    PAYLOAD_TOO_LARGE = "CPEAK_ERR_PAYLOAD_TOO_LARGE"
+}
+declare class CpeakIncomingMessage extends http.IncomingMessage {
+    body: any;
+    params: StringMap;
+    private _query?;
+    get query(): StringMap;
+}
+declare class CpeakServerResponse extends http.ServerResponse<CpeakIncomingMessage> {
+    sendFile(path: string, mime: string): Promise<void>;
+    status(code: number): this;
+    redirect(location: string): this;
+    json(data: any): void;
 }
 declare class Cpeak {
     #private;
@@ -56,7 +72,7 @@ declare class Cpeak {
     route(method: string, path: string, ...args: (RouteMiddleware | Handler)[]): void;
     beforeEach(cb: Middleware): void;
     handleErr(cb: (err: unknown, req: CpeakRequest, res: CpeakResponse) => void): void;
-    listen(port: number, cb?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+    listen(port: number, cb?: () => void): http.Server<typeof CpeakIncomingMessage, typeof CpeakServerResponse>;
     close(cb?: (err?: Error) => void): void;
 }
 

package/dist/index.js

@@ -65,22 +65,58 @@ var serveStatic = (folderPath, newMimeTypes) => {
   };
 };
 
-// lib/utils/parseJSON.ts
-var parseJSON = (req, res, next) => {
-  function isJSON(contentType = "") {
-    const [type] = contentType.split(";");
-    return type.trim().toLowerCase() === "application/json" || /\+json$/i.test(type.trim());
-  }
-  if (!isJSON(req.headers["content-type"])) return next();
-  let body = "";
-  req.on("data", (chunk) => {
-    body += chunk.toString("utf-8");
-  });
-  req.on("end", () => {
-    body = JSON.parse(body);
-    req.body = body;
-    return next();
-  });
+// lib/utils/paseJSON.ts
+import { Buffer } from "buffer";
+function isJSON(contentType) {
+  if (!contentType) return false;
+  if (contentType === "application/json") return true;
+  return contentType.startsWith("application/json") || contentType.includes("+json");
+}
+var parseJSON = (options = {}) => {
+  const limit = options.limit || 1024 * 1024;
+  return (req, res, next) => {
+    if (!isJSON(req.headers["content-type"])) return next();
+    const chunks = [];
+    let bytesReceived = 0;
+    const onData = (chunk) => {
+      bytesReceived += chunk.length;
+      if (bytesReceived > limit) {
+        req.pause();
+        req.removeListener("data", onData);
+        req.removeListener("end", onEnd);
+        next(
+          frameworkError(
+            "JSON body too large",
+            onData,
+            "CPEAK_ERR_PAYLOAD_TOO_LARGE" /* PAYLOAD_TOO_LARGE */,
+            413
+            // HTTP 413 Payload Too Large
+          )
+        );
+        return;
+      }
+      chunks.push(chunk);
+    };
+    const onEnd = () => {
+      try {
+        const rawBody = chunks.length === 1 ? chunks[0].toString("utf-8") : Buffer.concat(chunks).toString("utf-8");
+        req.body = rawBody ? JSON.parse(rawBody) : {};
+        next();
+      } catch (err) {
+        next(
+          frameworkError(
+            "Invalid JSON format",
+            onEnd,
+            "CPEAK_ERR_INVALID_JSON" /* INVALID_JSON */,
+            400
+            // HTTP 400 Bad Request
+          )
+        );
+      }
+    };
+    req.on("data", onData);
+    req.on("end", onEnd);
+  };
 };
 
 // lib/utils/render.ts
@@ -108,7 +144,6 @@ function renderTemplate(templateStr, data) {
   return result.join("");
 }
 var render = () => {
-  console.log("render.ts loaded");
   return function(req, res, next) {
     res.render = async (path2, data, mime) => {
       if (!mime) {
@@ -127,10 +162,12 @@ var render = () => {
 };
 
 // lib/index.ts
-function frameworkError(message, skipFn, code) {
+function frameworkError(message, skipFn, code, status) {
   const err = new Error(message);
   Error.captureStackTrace(err, skipFn);
+  err.cpeak_err = true;
   if (code) err.code = code;
+  if (status) err.status = status;
   return err;
 }
 var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
@@ -138,101 +175,123 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["FILE_NOT_FOUND"] = "CPEAK_ERR_FILE_NOT_FOUND";
   ErrorCode2["NOT_A_FILE"] = "CPEAK_ERR_NOT_A_FILE";
   ErrorCode2["SEND_FILE_FAIL"] = "CPEAK_ERR_SEND_FILE_FAIL";
+  ErrorCode2["INVALID_JSON"] = "CPEAK_ERR_INVALID_JSON";
+  ErrorCode2["PAYLOAD_TOO_LARGE"] = "CPEAK_ERR_PAYLOAD_TOO_LARGE";
   return ErrorCode2;
 })(ErrorCode || {});
+var CpeakIncomingMessage = class extends http.IncomingMessage {
+  // We define body and params here for better V8 optimization (not changing the shape of the object at runtime)
+  body = void 0;
+  params = {};
+  _query;
+  // 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() {
+    if (this._query) return this._query;
+    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;
+  }
+};
+var CpeakServerResponse = class extends http.ServerResponse {
+  // Send a file back to the client
+  async sendFile(path2, mime) {
+    if (!mime) {
+      throw frameworkError(
+        'MIME type is missing. Use res.sendFile(path, "mime-type").',
+        this.sendFile,
+        "CPEAK_ERR_MISSING_MIME" /* MISSING_MIME */
+      );
+    }
+    try {
+      const stat = await fs3.stat(path2);
+      if (!stat.isFile()) {
+        throw frameworkError(
+          `Not a file: ${path2}`,
+          this.sendFile,
+          "CPEAK_ERR_NOT_A_FILE" /* NOT_A_FILE */
+        );
+      }
+      this.setHeader("Content-Type", mime);
+      this.setHeader("Content-Length", String(stat.size));
+      await pipeline(createReadStream(path2), this);
+    } catch (err) {
+      if (err?.code === "ENOENT") {
+        throw frameworkError(
+          `File not found: ${path2}`,
+          this.sendFile,
+          "CPEAK_ERR_FILE_NOT_FOUND" /* FILE_NOT_FOUND */
+        );
+      }
+      throw frameworkError(
+        `Failed to send file: ${path2}`,
+        this.sendFile,
+        "CPEAK_ERR_SEND_FILE_FAIL" /* SEND_FILE_FAIL */
+      );
+    }
+  }
+  // Set the status code of the response
+  status(code) {
+    this.statusCode = code;
+    return this;
+  }
+  // Redirects to a new URL
+  redirect(location) {
+    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) {
+    this.setHeader("Content-Type", "application/json");
+    this.end(JSON.stringify(data));
+  }
+};
 var Cpeak = class {
   server;
   routes;
   middleware;
   _handleErr;
   constructor() {
-    this.server = http.createServer();
+    this.server = http.createServer({
+      IncomingMessage: CpeakIncomingMessage,
+      ServerResponse: CpeakServerResponse
+    });
     this.routes = {};
     this.middleware = [];
-    this.server.on("request", (req, res) => {
-      res.sendFile = async (path2, mime) => {
-        if (!mime) {
-          throw frameworkError(
-            'MIME type is missing. Use res.sendFile(path, "mime-type").',
-            res.sendFile,
-            "CPEAK_ERR_MISSING_MIME" /* MISSING_MIME */
-          );
-        }
-        try {
-          const stat = await fs3.stat(path2);
-          if (!stat.isFile()) {
-            throw frameworkError(
-              `Not a file: ${path2}`,
-              res.sendFile,
-              "CPEAK_ERR_NOT_A_FILE" /* NOT_A_FILE */
-            );
-          }
-          res.setHeader("Content-Type", mime);
-          res.setHeader("Content-Length", String(stat.size));
-          await pipeline(createReadStream(path2), res);
-        } catch (err) {
-          if (err?.code === "ENOENT") {
-            throw frameworkError(
-              `File not found: ${path2}`,
-              res.sendFile,
-              "CPEAK_ERR_FILE_NOT_FOUND" /* FILE_NOT_FOUND */
-            );
-          }
-          throw frameworkError(
-            `Failed to send file: ${path2}`,
-            res.sendFile,
-            "CPEAK_ERR_SEND_FILE_FAIL" /* SEND_FILE_FAIL */
-          );
-        }
-      };
-      res.status = (code) => {
-        res.statusCode = code;
-        return res;
-      };
-      res.redirect = (location) => {
-        res.writeHead(302, { Location: location });
-        res.end();
-        return res;
-      };
-      res.json = (data) => {
-        res.setHeader("Content-Type", "application/json");
-        res.end(JSON.stringify(data));
-      };
-      const urlWithoutParams = req.url?.split("?")[0];
-      const params = new URLSearchParams(req.url?.split("?")[1]);
-      const paramsObject = Object.fromEntries(params.entries());
-      req.params = paramsObject;
-      req.query = paramsObject;
-      const runHandler = (req2, res2, middleware, cb, index) => {
+    this.server.on("request", async (req, res) => {
+      const qIndex = req.url?.indexOf("?");
+      const urlWithoutQueries = qIndex === -1 ? req.url || "" : req.url?.substring(0, qIndex);
+      const runHandler = async (req2, res2, middleware, cb, index) => {
         if (index === middleware.length) {
           try {
-            const handlerResult = cb(req2, res2, (error) => {
+            await cb(req2, res2, (error) => {
               res2.setHeader("Connection", "close");
               this._handleErr?.(error, req2, res2);
             });
-            if (handlerResult && typeof handlerResult.then === "function") {
-              handlerResult.catch((error) => {
-                res2.setHeader("Connection", "close");
-                this._handleErr?.(error, req2, res2);
-              });
-            }
-            return handlerResult;
           } catch (error) {
             res2.setHeader("Connection", "close");
             this._handleErr?.(error, req2, res2);
           }
         } else {
           try {
-            const middlewareResult = middleware[index](
+            await middleware[index](
               req2,
               res2,
               // The next function
-              (error) => {
+              async (error) => {
                 if (error) {
                   res2.setHeader("Connection", "close");
                   return this._handleErr?.(error, req2, res2);
                 }
-                runHandler(req2, res2, middleware, cb, index + 1);
+                await runHandler(req2, res2, middleware, cb, index + 1);
               },
               // Error handler for a route middleware
               (error) => {
@@ -240,38 +299,50 @@ var Cpeak = class {
                 this._handleErr?.(error, req2, res2);
               }
             );
-            if (middlewareResult && typeof middlewareResult.then === "function") {
-              middlewareResult.catch((error) => {
-                res2.setHeader("Connection", "close");
-                this._handleErr?.(error, req2, res2);
-              });
-            }
           } catch (error) {
             res2.setHeader("Connection", "close");
             this._handleErr?.(error, req2, res2);
           }
         }
       };
-      const runMiddleware = (req2, res2, middleware, index) => {
+      const runMiddleware = async (req2, res2, middleware, index) => {
         if (index === middleware.length) {
           const routes = this.routes[req2.method?.toLowerCase() || ""];
           if (routes && typeof routes[Symbol.iterator] === "function")
             for (const route of routes) {
-              const match = urlWithoutParams?.match(route.regex);
+              const match = urlWithoutQueries?.match(route.regex);
               if (match) {
-                const vars = this.#extractVars(route.path, match);
-                req2.vars = vars;
-                return runHandler(req2, res2, route.middleware, route.cb, 0);
+                const pathVariables = this.#extractPathVariables(
+                  route.path,
+                  match
+                );
+                req2.params = pathVariables;
+                return await runHandler(
+                  req2,
+                  res2,
+                  route.middleware,
+                  route.cb,
+                  0
+                );
               }
             }
-          return res2.status(404).json({ error: `Cannot ${req2.method} ${urlWithoutParams}` });
+          return res2.status(404).json({ error: `Cannot ${req2.method} ${urlWithoutQueries}` });
         } else {
-          middleware[index](req2, res2, () => {
-            runMiddleware(req2, res2, middleware, index + 1);
-          });
+          try {
+            await middleware[index](req2, res2, async (err) => {
+              if (err) {
+                res2.setHeader("Connection", "close");
+                return this._handleErr?.(err, req2, res2);
+              }
+              await runMiddleware(req2, res2, middleware, index + 1);
+            });
+          } catch (error) {
+            res2.setHeader("Connection", "close");
+            this._handleErr?.(error, req2, res2);
+          }
         }
       };
-      runMiddleware(req, res, this.middleware, 0);
+      await runMiddleware(req, res, this.middleware, 0);
     });
   }
   route(method, path2, ...args) {
@@ -300,23 +371,23 @@ var Cpeak = class {
   // PRIVATE METHODS:
   // ------------------------------
   #pathToRegex(path2) {
-    const varNames = [];
+    const paramNames = [];
     const regexString = "^" + path2.replace(/:\w+/g, (match, offset) => {
-      varNames.push(match.slice(1));
+      paramNames.push(match.slice(1));
       return "([^/]+)";
     }) + "$";
     const regex = new RegExp(regexString);
     return regex;
   }
-  #extractVars(path2, match) {
-    const varNames = (path2.match(/:\w+/g) || []).map(
-      (varParam) => varParam.slice(1)
+  #extractPathVariables(path2, match) {
+    const paramNames = (path2.match(/:\w+/g) || []).map(
+      (param) => param.slice(1)
     );
-    const vars = {};
-    varNames.forEach((name, index) => {
-      vars[name] = match[index + 1];
+    const params = {};
+    paramNames.forEach((name, index) => {
+      params[name] = match[index + 1];
     });
-    return vars;
+    return params;
   }
 };
 function cpeak() {