cpeak 1.4.0 → 2.1.0

package/README.md

@@ -0,0 +1,331 @@
+# 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.
+
+This is an educational project that was started as part of the [Understanding Node.js: Core Concepts](https://www.udemy.com/course/understanding-nodejs-core-concepts/?referralCode=0BC21AC4DD6958AE6A95) course. If you want to learn how to build a framework like this, and get to a point where you can build things like this yourself, check out this course!
+
+## Why Cpeak?
+
+- **Minimalism**: No unnecessary bloat, with zero dependencies. Just the core essentials you need to build fast and reliable applications.
+- **Performance**: Engineered to be fast, **Cpeak** won’t sacrifice speed for excessive customizability.
+- **Educational**: Every new change made in the project will be explained in great detail in a YouTube playlist (playlist will be added soon). Follow this project and let's see what it takes to build an industry-leading product!
+- **Express.js Compatible**: You can easily refactor from Cpeak to Express.js and vice versa. Many npm packages that work with Express.js will also work with Cpeak.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+  - [Hello World App](#hello-world-app)
+- [Documentation](#documentation)
+  - [Including](#including)
+  - [Initializing](#initializing)
+  - [Middleware](#middleware)
+  - [Route Handling](#route-handling)
+  - [URL Variables & Parameters](#url-variables--parameters)
+  - [Sending Files](#sending-files)
+  - [Error Handling](#error-handling)
+  - [Listening](#listening)
+  - [Util Functions](#util-functions)
+    - [serveStatic](#servestatic)
+    - [parseJSON](#parsejson)
+- [Complete Example](#complete-example)
+
+## Getting Started
+
+Ready to dive in? Install **Cpeak** via npm:
+
+```bash
+npm install cpeak
+```
+
+### Hello World App:
+
+```javascript
+import cpeak from "cpeak";
+
+const server = new cpeak();
+
+server.route("get", "/", (req, res) => {
+  res.json({ message: "Hi there!" });
+});
+
+server.listen(3000, () => {
+  console.log("Server has started on port 3000");
+});
+```
+
+## Documentation
+
+### Including
+
+Include the framework like this:
+
+```javascript
+import cpeak from "cpeak";
+```
+
+Because of the minimalistic philosophy, you won’t add unnecessary objects to your memory as soon as you include the framework. If at any point you want to use a particular utility function (like `parseJSON` and `serveStatic`), include it like the line below, and only at that point will it be moved into memory:
+
+```javascript
+import cpeak, { serveStatic, parseJSON } from "cpeak";
+```
+
+### Initializing
+
+Initialize the Cpeak server like this:
+
+```javascript
+const server = new cpeak();
+```
+
+Now you can use this server object to start listening, add route logic, add middleware functions, and handle errors.
+
+### Middleware
+
+If you add a middleware function, that function will run before your route logic kicks in. Here you can customize the request object, return an error, or do anything else you want to do prior to your route logic, like authentication.
+
+After calling `next`, the next middleware function is going to run if there’s any; otherwise, the route logic is going to run.
+
+```javascript
+server.beforeEach((req, res, next) => {
+  if (req.headers.authentication) {
+    // Your authentication logic...
+    req.userId = "<something>";
+    req.custom = "This is some string";
+    next();
+  } else {
+    // Return an error and close the request...
+    return res.status(401).json({ error: "Unauthorized" });
+  }
+});
+
+server.beforeEach((req, res, next) => {
+  console.log(
+    "The custom value was added from the previous middleware: ",
+    req.custom
+  );
+  next();
+});
+```
+
+### Route Handling
+
+You can add new routes like this:
+
+```javascript
+server.route("patch", "/the-path-you-want", (req, res) => {
+  // your route logic
+});
+```
+
+First add the HTTP method name you want to handle, then the path, and finally, the callback. The `req` and `res` object types are the same as in the Node.js HTTP module (`http.IncomingMessage` and `http.ServerResponse`). You can read more about them in the [official Node.js documentation](https://nodejs.org/docs/latest/api/http.html).
+
+### 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).
+
+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.get("filter");
+
+  console.log(title); // my-title
+  console.log(filter); // newest
+});
+```
+
+### Sending Files
+
+You can send a file as a Node.js Stream anywhere in your route or middleware logic like this:
+
+```javascript
+server.route("get", "/testing", (req, res) => {
+  return res.status(200).sendFile("<file-path>", "<mime-type>");
+
+  // Example:
+  // return res.status(200).sendFile("./images/sun.jpeg", "image/jpeg");
+});
+```
+
+The file’s binary content will be in the HTTP response body content. Make sure you specify a correct path relative to your CWD (use the `path` module for better compatibility) and also the correct HTTP MIME type for that file.
+
+### Error Handling
+
+If anywhere in your route functions you want to return an error, it's cleaner to pass it to the `handleErr` function like this:
+
+```javascript
+server.route("get", "/api/document/:title", (req, res, handleErr) => {
+  const title = req.vars.title;
+
+  if (title.length > 500)
+    return handleErr({ status: 400, message: "Title too long." });
+
+  // The rest of your logic...
+});
+```
+
+And then handle all the errors like this in the `handleErr` callback:
+
+```javascript
+server.handleErr((error, req, res) => {
+  if (error && error.status) {
+    res.status(error.status).json({ error: error.message });
+  } else {
+    // 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.",
+    });
+  }
+});
+```
+
+The error object is the object that you passed to the `handleErr` function earlier in your routes.
+
+### Listening
+
+Start listening on a specific port like this:
+
+```javascript
+server.listen(3000, () => {
+  console.log("Server has started on port 3000");
+});
+```
+
+### Util Functions
+
+There are utility functions that you can include and use as middleware functions. These are meant to make it easier for you to build HTTP applications. In the future, many more will be added, and you only move them into memory once you include them. No need to have many npm dependencies for simple applications!
+
+The list of utility functions as of now:
+
+- serveStatic
+- parseJSON
+
+Including any one of them is done like this:
+
+```javascript
+import cpeak, { utilName } from "cpeak";
+```
+
+#### serveStatic
+
+With this middleware function, you can automatically set a folder in your project to be served by Cpeak. Here’s how to set it up:
+
+```javascript
+server.beforeEach(
+  serveStatic("./public", {
+    mp3: "audio/mpeg",
+  })
+);
+```
+
+If you have file types in your public folder that are not one of the following, make sure to add the MIME types manually as the second argument in the function as an object where each property key is the file extension, and each value is the correct MIME type for that. You can see all the available MIME types on the [IANA website](https://www.iana.org/assignments/media-types/media-types.xhtml).
+
+```
+  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"
+```
+
+#### parseJSON
+
+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);
+```
+
+Read and send JSON from HTTP messages like this:
+
+```javascript
+server.route("put", "/api/user", (req, res) => {
+  // Reading JSON from the HTTP request:
+  const email = req.body.email;
+
+  // rest of your logic...
+
+  // Sending JSON in the HTTP response:
+  res.status(201).json({ message: "Something was created..." });
+});
+```
+
+## Complete Example
+
+Here you can see all the features that Cpeak offers, in one small piece of code:
+
+```javascript
+import cpeak, { serveStatic, parseJSON } from "cpeak";
+
+const server = new cpeak();
+
+server.beforeEach(
+  serveStatic("./public", {
+    mp3: "audio/mpeg",
+  })
+);
+
+// For parsing JSON bodies
+server.beforeEach(parseJSON);
+
+// Adding custom middleware functions
+server.beforeEach((req, res, next) => {
+  req.custom = "This is some string";
+  next();
+});
+
+// Adding route handlers
+server.route("get", "/api/document/:title", (req, res, handleErr) => {
+  // Reading URL variables
+  const title = req.vars.title;
+
+  // Reading URL parameters (like /users?filter=active)
+  const filter = req.params.get("filter");
+
+  // Reading JSON request body
+  const anything = req.body.anything;
+
+  // Handling errors
+  if (anything === "not-expected-thing")
+    return handleErr({ status: 400, message: "Invalid property." });
+
+  // Sending a JSON response
+  res.status(200).json({ message: "This is a test response" });
+});
+
+// Sending a file response
+server.route("get", "/file", (req, res) => {
+  // Make sure to specify a correct path and MIME type...
+  res.status(200).sendFile("<path-to-file-relative-to-cwd>", "<mime-type>");
+});
+
+// Handle all the errors that could happen in the routes
+server.handleErr((error, req, res) => {
+  if (error && error.status) {
+    res.status(error.status).json({ error: error.message });
+  } else {
+    console.error(error);
+    res.status(500).json({
+      error: "Sorry, something unexpected happened from our side.",
+    });
+  }
+});
+
+server.listen(3000, () => {
+  console.log("Server has started on port 3000");
+});
+```

package/lib/index.js

@@ -1,8 +1,9 @@
-const http = require("node:http");
-const fs = require("node:fs/promises");
+import http from "node:http";
+import fs from "node:fs/promises";
 
-const { parseJSON, serveStatic } = require("./util");
-class CPeak {
+import { serveStatic, parseJSON } from "./util.js";
+
+class Cpeak {
   constructor() {
     this.server = http.createServer();
     this.routes = {};
@@ -33,6 +34,7 @@ class CPeak {
         res.end(JSON.stringify(data));
       };
 
+      // Parse the URL parameters (like /users?name=John)
       const urlWithoutParams = req.url.split("?")[0];
       req.params = new URLSearchParams(req.url.split("?")[1]);
 
@@ -40,21 +42,25 @@ class CPeak {
       const runMiddleware = (req, res, middleware, index) => {
         // Out exit point...
         if (index === middleware.length) {
-          // If the routes object does not have a key of req.method + req.url, return 404
-          if (!this.routes[req.method.toLocaleLowerCase() + urlWithoutParams]) {
-            return res
-              .status(404)
-              .json({ error: `Cannot ${req.method} ${urlWithoutParams}` });
+          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);
+              });
+            }
           }
 
-          this.routes[req.method.toLowerCase() + urlWithoutParams](
-            req,
-            res,
-            (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} ${urlWithoutParams}` });
         } else {
           middleware[index](req, res, () => {
             runMiddleware(req, res, middleware, index + 1);
@@ -67,7 +73,10 @@ class CPeak {
   }
 
   route(method, path, cb) {
-    this.routes[method + path] = cb;
+    if (!this.routes[method]) this.routes[method] = [];
+
+    const regex = this.#pathToRegex(path);
+    this.routes[method].push({ path, regex, cb });
   }
 
   beforeEach(cb) {
@@ -83,9 +92,37 @@ class CPeak {
       cb();
     });
   }
+
+  // ------------------------------
+  // PRIVATE METHODS:
+  // ------------------------------
+  #pathToRegex(path) {
+    const varNames = [];
+    const regexString =
+      "^" +
+      path.replace(/:\w+/g, (match, offset) => {
+        varNames.push(match.slice(1));
+        return "([^/]+)";
+      }) +
+      "$";
+
+    const regex = new RegExp(regexString);
+    return regex;
+  }
+
+  #extractVars(path, match) {
+    // Extract url variable values from the matched route
+    const varNames = (path.match(/:\w+/g) || []).map((varParam) =>
+      varParam.slice(1)
+    );
+    const vars = {};
+    varNames.forEach((name, index) => {
+      vars[name] = match[index + 1];
+    });
+    return vars;
+  }
 }
 
-CPeak.parseJSON = parseJSON;
-CPeak.serveStatic = serveStatic;
+export { serveStatic, parseJSON };
 
-module.exports = CPeak;
+export default Cpeak;

package/lib/util.js

@@ -1,5 +1,5 @@
-const fs = require("node:fs");
-const path = require("node:path");
+import fs from "node:fs";
+import path from "node:path";
 
 const MIME_TYPES = {
   html: "text/html",
@@ -17,7 +17,7 @@ const MIME_TYPES = {
   woff2: "font/woff2",
 };
 
-exports.serveStatic = (folderPath, newMimeTypes) => {
+const serveStatic = (folderPath, newMimeTypes) => {
   // For new user defined mime types
   if (newMimeTypes) {
     Object.assign(MIME_TYPES, newMimeTypes);
@@ -75,7 +75,7 @@ exports.serveStatic = (folderPath, newMimeTypes) => {
 };
 
 // Parsing JSON
-exports.parseJSON = (req, res, next) => {
+const parseJSON = (req, res, next) => {
   // This is only good for bodies that their size is less than the highWaterMark value
   if (req.headers["content-type"] === "application/json") {
     let body = "";
@@ -92,3 +92,5 @@ exports.parseJSON = (req, res, next) => {
     next();
   }
 };
+
+export { serveStatic, parseJSON };

package/package.json

@@ -1,11 +1,26 @@
 {
   "name": "cpeak",
-  "version": "1.4.0",
-  "description": "",
+  "version": "2.1.0",
+  "description": "A minimal and fast Node.js HTTP framework.",
+  "type": "module",
   "main": "./lib/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agile8118/cpeak.git"
+  },
+  "bugs": {
+    "url": "https://github.com/agile8118/cpeak/issues"
+  },
+  "homepage": "https://github.com/agile8118/cpeak#readme",
   "author": "Cododev Technology",
-  "license": "ISC"
+  "license": "MIT",
+  "keywords": [
+    "cpeak",
+    "nodejs",
+    "http",
+    "framework"
+  ]
 }