cpeak 2.1.0 → 2.2.1

package/README.md

@@ -1,5 +1,7 @@
 # Cpeak
 
+[![npm version](https://badge.fury.io/js/cpeak.svg)](https://www.npmjs.com/package/cpeak)
+
 Cpeak is a minimal and fast Node.js framework inspired by Express.js.
 
 This project is designed to be improved until it's ready for use in complex production applications, aiming to be more performant and minimal than Express.js. This framework is intended for HTTP applications that primarily deal with JSON and file-based message bodies.
@@ -30,6 +32,7 @@ This is an educational project that was started as part of the [Understanding No
     - [serveStatic](#servestatic)
     - [parseJSON](#parsejson)
 - [Complete Example](#complete-example)
+- [Versioning Notice](#versioning-notice)
 
 ## Getting Started
 
@@ -39,6 +42,8 @@ Ready to dive in? Install **Cpeak** via npm:
 npm install cpeak
 ```
 
+Cpeak is a **pure ESM** package, and to use it, your project needs to be an ESM as well. You can learn more about that [here](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+
 ### Hello World App:
 
 ```javascript
@@ -132,7 +137,7 @@ Here’s how we can read both:
 // 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.get("filter");
+  const filter = req.params.filter;
 
   console.log(title); // my-title
   console.log(filter); // newest
@@ -294,7 +299,7 @@ server.route("get", "/api/document/:title", (req, res, handleErr) => {
   const title = req.vars.title;
 
   // Reading URL parameters (like /users?filter=active)
-  const filter = req.params.get("filter");
+  const filter = req.params.filter;
 
   // Reading JSON request body
   const anything = req.body.anything;
@@ -329,3 +334,18 @@ server.listen(3000, () => {
   console.log("Server has started on port 3000");
 });
 ```
+
+## Versioning Notice
+
+#### Version `1.x.x`
+
+Version `1.x.x` represents the initial release of our framework, developed during the _Understanding Node.js Core Concepts_ course. These versions laid the foundation for our project.
+
+#### Version `2.x.x`
+
+All version `2.x.x` releases are considered to be in active development, following the completion of the course. These versions include ongoing feature additions and API changes as we refine the framework. Frequent updates may require code changes, so version `2.x.x` is not recommended for production environments.
+For new features, bug fixes, and other changes that don't break existing code, the patch version will be increased. For changes that break existing code, the minor version will be increased.
+
+#### Version `3.x.x`
+
+Version `3.x.x` and beyond will be our first production-ready releases. These versions are intended for stable, long-term use, with a focus on backward compatibility and minimal breaking changes.

package/lib/index.js

@@ -34,28 +34,35 @@ class Cpeak {
         res.end(JSON.stringify(data));
       };
 
-      // Parse the URL parameters (like /users?name=John)
+      // Get the url without the URL parameters
       const urlWithoutParams = req.url.split("?")[0];
-      req.params = new URLSearchParams(req.url.split("?")[1]);
+
+      // 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]);
+      req.params = Object.fromEntries(params.entries());
 
       // Run all the middleware functions before we run the corresponding route
       const runMiddleware = (req, res, middleware, index) => {
         // Out exit point...
         if (index === middleware.length) {
-          for (const route of this.routes[req.method.toLowerCase()]) {
-            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);
-              // Call the route handler with request and URL variables
-              req.vars = vars;
-              return route.cb(req, res, (error) => {
-                res.setHeader("Connection", "close");
-                this.handleErr(error, req, res);
-              });
+          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;
+
+                // Call the route handler with the modified req and res objects
+                return route.cb(req, res, (error) => {
+                  res.setHeader("Connection", "close");
+                  this.handleErr(error, req, res);
+                });
+              }
             }
-          }
 
           // If the requested route dose not exist, return 404
           return res
@@ -88,9 +95,11 @@ class Cpeak {
   }
 
   listen(port, cb) {
-    this.server.listen(port, () => {
-      cb();
-    });
+    this.server.listen(port, cb);
+  }
+
+  close(cb) {
+    this.server.close(cb);
   }
 
   // ------------------------------

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "cpeak",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "A minimal and fast Node.js HTTP framework.",
   "type": "module",
   "main": "./lib/index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "mocha test/**/*.js"
   },
   "repository": {
     "type": "git",
@@ -22,5 +22,9 @@
     "nodejs",
     "http",
     "framework"
-  ]
+  ],
+  "devDependencies": {
+    "mocha": "^10.7.3",
+    "supertest": "^7.0.0"
+  }
 }

package/test/errors.test.js

@@ -0,0 +1,40 @@
+import assert from "node:assert";
+import supertest from "supertest";
+import cpeak from "../lib/index.js";
+
+const PORT = 7543;
+const request = supertest(`http://localhost:${PORT}`);
+
+describe("Error handling with handleErr", function () {
+  let server;
+
+  before(function (done) {
+    server = new cpeak();
+
+    server.route("patch", "/foo/:bar", (req, res, handleErr) => {
+      const bar = req.vars.bar;
+
+      if (bar === "random") {
+        return handleErr({ status: 403, message: "an error msg" });
+      }
+
+      return res.status(200).json({ bar });
+    });
+
+    server.handleErr((error, req, res) => {
+      return res.status(error.status).json({ error: error.message });
+    });
+
+    server.listen(PORT, done);
+  });
+
+  after(function (done) {
+    server.close(done);
+  });
+
+  it("should get an error using the handleErr function from a router", async function () {
+    const res = await request.patch("/foo/random");
+    assert.strictEqual(res.status, 403);
+    assert.deepStrictEqual(res.body, { error: "an error msg" });
+  });
+});

package/test/files/styles.css

@@ -0,0 +1,9 @@
+/* some styles for testing... */
+.my-class {
+  color: red;
+}
+
+.my-class-2 {
+  color: blue;
+}
+

package/test/files/test.txt

@@ -0,0 +1 @@
+This is a test file.

package/test/files.test.js

@@ -0,0 +1,35 @@
+import assert from "node:assert";
+import supertest from "supertest";
+import fs from "node:fs/promises";
+import cpeak from "../lib/index.js";
+
+const PORT = 7543;
+const request = supertest(`http://localhost:${PORT}`);
+
+describe("Returning files with sendFile", function () {
+  let server;
+
+  before(function (done) {
+    server = new cpeak();
+
+    server.route("get", "/file", (req, res) => {
+      res.status(200).sendFile("./test/files/test.txt", "text/plain");
+    });
+
+    server.listen(PORT, done);
+  });
+
+  after(function (done) {
+    server.close(done);
+  });
+
+  it("should get a file as the response with the correct MIME type", async function () {
+    const res = await request.get("/file");
+
+    const fileContent = await fs.readFile("./test/files/test.txt", "utf-8");
+
+    assert.strictEqual(res.status, 200);
+    assert.strictEqual(res.headers["content-type"], "text/plain");
+    assert.strictEqual(res.text, fileContent);
+  });
+});

package/test/middleware.test.js

@@ -0,0 +1,68 @@
+import assert from "node:assert";
+import supertest from "supertest";
+import cpeak from "../lib/index.js";
+
+const PORT = 7543;
+const request = supertest(`http://localhost:${PORT}`);
+
+describe("Middleware functions", function () {
+  let server;
+
+  before(function (done) {
+    server = new cpeak();
+
+    server.beforeEach((req, res, next) => {
+      const value = req.params.value;
+
+      if (value === "random")
+        return res.status(400).json({ error: "an error msg" });
+
+      next();
+    });
+
+    server.beforeEach((req, res, next) => {
+      req.foo = "text";
+      next();
+    });
+
+    server.beforeEach((req, res, next) => {
+      res.unauthorized = () => {
+        res.statusCode = 401;
+        return res;
+      };
+      next();
+    });
+
+    server.route("get", "/bar", (req, res) => {
+      res.status(200).json({ message: req.foo });
+    });
+
+    server.route("get", "/bar-more", (req, res) => {
+      res.unauthorized().json({});
+    });
+
+    server.listen(PORT, done);
+  });
+
+  after(function (done) {
+    server.close(done);
+  });
+
+  it("should modify the req object with a new property", async function () {
+    const res = await request.get("/bar");
+    assert.strictEqual(res.status, 200);
+    assert.strictEqual(res.body.message, "text");
+  });
+
+  it("should modify the res object with a new method", async function () {
+    const res = await request.get("/bar-more");
+    assert.strictEqual(res.status, 401);
+  });
+
+  it("should exit the middleware and route chain if a middleware wants to", async function () {
+    const res = await request.get("/bar?value=random");
+    assert.strictEqual(res.status, 400);
+    assert.strictEqual(res.body.message, undefined);
+    assert.deepStrictEqual(res.body, { error: "an error msg" });
+  });
+});

package/test/parseJSON.test.js

@@ -0,0 +1,43 @@
+import assert from "node:assert";
+import supertest from "supertest";
+import cpeak, { parseJSON } from "../lib/index.js";
+
+const PORT = 7543;
+const request = supertest(`http://localhost:${PORT}`);
+
+describe("Parsing request bodies with parseJSON", function () {
+  let server;
+
+  before(function (done) {
+    server = new cpeak();
+
+    server.beforeEach(parseJSON);
+
+    server.route("post", "/do-something", (req, res) => {
+      res.status(205).json({ receivedData: req.body });
+    });
+
+    server.listen(PORT, done);
+  });
+
+  after(function (done) {
+    server.close(done);
+  });
+
+  it("should return the same data that was sent in request body as JSON", async function () {
+    const obj = {
+      key1: "value1",
+      key2: 42,
+      key3: {
+        nestedKey1: "nestedValue1",
+        nestedKey2: ["arrayValue1", "arrayValue2", 1000],
+      },
+      key4: true,
+    };
+
+    const res = await request.post("/do-something").send(obj);
+
+    assert.strictEqual(res.status, 205);
+    assert.deepStrictEqual(res.body.receivedData, obj);
+  });
+});

package/test/router.test.js

@@ -0,0 +1,85 @@
+import assert from "node:assert";
+import supertest from "supertest";
+import cpeak from "../lib/index.js";
+
+const PORT = 7543;
+const request = supertest(`http://localhost:${PORT}`);
+
+describe("General route logic & URL variables and parameters", function () {
+  let server;
+
+  before(function (done) {
+    server = new cpeak();
+
+    server.route("get", "/hello", (req, res) => {
+      res.status(200).json({ message: "Hello, World!" });
+    });
+
+    server.route("get", "/document/:title/more/:another/final", (req, res) => {
+      const title = req.vars.title;
+      const another = req.vars.another;
+      const params = req.params;
+
+      res.status(200).json({ title, another, params });
+    });
+
+    server.listen(PORT, done);
+  });
+
+  after(function (done) {
+    server.close(done);
+  });
+
+  it("should return a simple response with no variables and parameters", async function () {
+    const res = await request.get("/hello");
+    assert.strictEqual(res.status, 200);
+    assert.deepStrictEqual(res.body, { message: "Hello, World!" });
+  });
+
+  it("should return a 404 for unknown routes", async function () {
+    const res = await request.get("/unknown");
+    assert.strictEqual(res.status, 404);
+    assert.deepStrictEqual(res.body, {
+      error: "Cannot GET /unknown",
+    });
+  });
+
+  it("should return a 404 for not handled methods", async function () {
+    const res = await request.patch("/random");
+    assert.strictEqual(res.status, 404);
+    assert.deepStrictEqual(res.body, {
+      error: "Cannot PATCH /random",
+    });
+  });
+
+  it("should return the correct URL variables and parameters", async function () {
+    const expectedResponseBody = {
+      title: "some-title",
+      another: "thisISsome__more-text",
+      params: {
+        filter: "comments-date",
+        page: "2",
+        sortBy: "date-desc",
+        tags: JSON.stringify(["nodejs", "express", "url-params"]),
+        author: JSON.stringify({ name: "John Doe", id: 123 }),
+        isPublished: "true",
+        metadata: JSON.stringify({ version: "1.0.0", language: "en" }),
+      },
+    };
+
+    const res = await request
+      .get("/document/some-title/more/thisISsome__more-text/final")
+      .query({
+        filter: "comments-date",
+        page: 2,
+        sortBy: "date-desc",
+        tags: JSON.stringify(["nodejs", "express", "url-params"]),
+        author: JSON.stringify({ name: "John Doe", id: 123 }),
+        isPublished: true,
+        metadata: JSON.stringify({ version: "1.0.0", language: "en" }),
+      });
+
+    assert.strictEqual(res.status, 200);
+    assert.deepStrictEqual(res.body, expectedResponseBody);
+  });
+});

package/test/serveStatic.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert";
+import supertest from "supertest";
+import fs from "node:fs/promises";
+import cpeak, { serveStatic } from "../lib/index.js";
+
+const PORT = 7543;
+const request = supertest(`http://localhost:${PORT}`);
+
+describe("Serving static files with serveStatic", function () {
+  let server;
+
+  before(function (done) {
+    server = new cpeak();
+
+    server.beforeEach(serveStatic("./test/files", { m4a: "audio/mp4" }));
+
+    server.listen(PORT, done);
+  });
+
+  after(function (done) {
+    server.close(done);
+  });
+
+  it("should return the correct file with the correct MIME type", async function () {
+    const textRes = await request.get("/test.txt");
+    const cssRes = await request.get("/styles.css");
+
+    const fileTextContent = await fs.readFile("./test/files/test.txt", "utf-8");
+    const fileCssContent = await fs.readFile(
+      "./test/files/styles.css",
+      "utf-8"
+    );
+
+    assert.strictEqual(textRes.status, 200);
+    assert.strictEqual(textRes.headers["content-type"], "text/plain");
+    assert.strictEqual(textRes.text, fileTextContent);
+
+    assert.strictEqual(cssRes.status, 200);
+    assert.strictEqual(cssRes.headers["content-type"], "text/css");
+    assert.strictEqual(cssRes.text, fileCssContent);
+  });
+
+  it("should return the correct file with the specified MIME type by the developer", async function () {
+    const res = await request.get("/audio.m4a");
+
+    // read the file as binary
+    const fileBuffer = await fs.readFile("./test/files/audio.m4a");
+
+    assert.strictEqual(res.status, 200);
+    assert.strictEqual(res.headers["content-type"], "audio/mp4");
+    assert.deepStrictEqual(res.body, fileBuffer);
+  });
+});