chore(code-comments): add jsdoc comments to serverside code

[Finishes #161845354]

server/controllers/authController.js

@@ -1,7 +1,17 @@
 import bcrpyt from 'bcryptjs';
 import pool from '../db/config';
 
+/**
+ * @class Authentication and Authorization Controller
+ */
 class AuthController {
+  /**
+   * handles adding new users to the database
+   * @param {*} req
+   * @param {*} res
+   * @param {*} next
+   * @returns {Object} - next: passes execution to the next middleware
+   */
   static async signup(req, res, next) {
     const {
       name,
@@ -30,6 +40,13 @@ class AuthController {
     }
   }
 
+  /**
+   * handles confirming user existense in the database
+   * @param {*} req
+   * @param {*} res
+   * @param {*} next
+   * @returns {Object} - next: passes execution to the next middleware
+   */
   static async signin(req, res, next) {
     const { email, password } = req;
     const errResponse = {

server/controllers/menuController.js

@@ -1,6 +1,15 @@
 import pool from '../db/config';
 
+/**
+ * @class Menu Controller
+ */
 class MenuController {
+  /**
+   * handles fetching all available food items from the database
+   * @param {*} req
+   * @param {*} res
+   * @returns {Object}
+   */
   static async getMenu(req, res) {
     try {
       const menu = (await pool.query('SELECT * FROM menu')).rows;
@@ -15,6 +24,12 @@ class MenuController {
     }
   }
 
+  /**
+   * hanldes adding new food items to the database
+   * @param {*} req
+   * @param {*} res
+   * @returns {Object}
+   */
   static async addFood(req, res) {
     const { foodName, foodImage, price } = req;
     try {
@@ -31,6 +46,12 @@ class MenuController {
     }
   }
 
+  /**
+   * hnadles the removal of food items from the database
+   * @param {*} req
+   * @param {*} res
+   * @returns {Object}
+   */
   static async deleteFood(req, res) {
     const { id } = req.params;
 

server/controllers/orderController.js

@@ -1,7 +1,17 @@
 import pool from '../db/config';
 import orderFormatter from '../middleware/formatter';
 
+/**
+ * @class Order Controller
+ */
 class OrderController {
+  /**
+   * Get all placed orders
+   * @param {*} req
+   * @param {*} res
+   * @returns {Object} - response object containing the status of the
+   * request and all user orders, if any
+   */
   static async getAllOrders(req, res) {
     try {
       const dbQuery = 'SELECT orders.id, orders.items, orders.price, users.name, orders.date, orders.status FROM orders JOIN users ON orders.author = users.id';
@@ -18,6 +28,12 @@ class OrderController {
     }
   }
 
+  /**
+   * Get the details of a single order
+   * @param {*} req
+   * @param {*} res
+   * @returns {Object}
+   */
   static async getOrder(req, res) {
     const { id } = req.params;
 
@@ -43,6 +59,12 @@ class OrderController {
     }
   }
 
+  /**
+   * place a new order to the API
+   * @param {*} req
+   * @param {*} res
+   * @returns {Object}
+   */
   static async newOrder(req, res) {
     const { foodItems, foodItemsTotalPrice } = req;
 
@@ -64,6 +86,12 @@ class OrderController {
     }
   }
 
+  /**
+   * update the status of an order
+   * @param {*} req
+   * @param {*} res
+   * @returns {Object}
+   */
   static async updateOrder(req, res) {
     const { id } = req.params;
     if (!Number(id)) return res.status(400).json({ status: 'error', message: 'invalid order id provided' });
@@ -87,6 +115,12 @@ class OrderController {
     }
   }
 
+  /**
+   * get the all orders placed by all users
+   * @param {*} req
+   * @param {*} res
+   * @returns {Object}
+   */
   static async getAllUserOrders(req, res) {
     const { id } = req.params;
     if (Number.isNaN(Number(id))) return res.status(400).json({ status: 'error', message: 'invalid user id' });

server/middleware/authHandler.js

@@ -3,7 +3,16 @@ import dotenv from 'dotenv';
 
 dotenv.config();
 
+/**
+ * @class Authentication and Authorization handler
+ */
 class AuthHandler {
+  /**
+   * handles generation of valid JWTs
+   * @param {*} req
+   * @param {*} res
+   * @returns {Object}
+   */
   static async generateAuthToken(req, res) {
     const {
       userId,
@@ -29,6 +38,14 @@ class AuthHandler {
     });
   }
 
+  /**
+   * confirms that the JWT bundled with the request is a valid on
+   * plus prevents request with a valid JWT from moving forward
+   * @param {*} req
+   * @param {*} res
+   * @param {*} next
+   * @returns {Object}
+   */
   static authorize(req, res, next) {
     const token = req.header('x-auth');
 
@@ -47,6 +64,13 @@ class AuthHandler {
     }
   }
 
+  /**
+   * prevents JWTs which do not have an 'admin' user status from going forward
+   * @param {*} req
+   * @param {*} res
+   * @param {*} next
+   * @returns {Object}
+   */
   static authorizeAdmin(req, res, next) {
     if (req.userStatus !== 'admin') {
       return res.status(403).json({

server/middleware/formatter.js

@@ -1,3 +1,9 @@
+/**
+ * @function formatOrders - takes an array of orders from gotten from
+ * the database and formats them according to the API documentation.
+ * @param {Object[]} orders - an array of orders to be formatted
+ * @returns {Object[]} - the formatted array of orders, per the docs
+ */
 const formatOrders = (orders) => {
   const formattedOrder = orders.map((foundOrder) => {
     const formatted = {

server/middleware/sanitizer.js

@@ -1,6 +1,15 @@
 import Validator from '../validators/validator';
 
+/**
+ * @class Sanitization middleware
+ */
 class Sanitize {
+  /**
+   * Santizes user signup requests
+   * @param {*} req
+   * @param {*} res
+   * @param {*} next
+   */
   static signup(req, res, next) {
     const {
       name,
@@ -41,6 +50,12 @@ class Sanitize {
     return next();
   }
 
+  /**
+   * Sanitizes user email and provided password on every login request
+   * @param {*} req
+   * @param {*} res
+   * @param {*} next
+   */
   static signin(req, res, next) {
     const { email, password } = req.body;
 
@@ -82,6 +97,12 @@ class Sanitize {
     return next();
   }
 
+  /**
+   * Sanitizes food name, food image url, and food price for add food requests
+   * @param {*} req
+   * @param {*} res
+   * @param {*} next
+   */
   static addFood(req, res, next) {
     const { foodName, foodImage, price } = req.body;
 
@@ -105,6 +126,12 @@ class Sanitize {
     return next();
   }
 
+  /**
+   * Sanitizes provided array of food ids when making a new order request
+   * @param {*} req
+   * @param {*} res
+   * @param {*} next
+   */
   static async newOrder(req, res, next) {
     const { foodIds } = req.body;
 

server/validators/validator.js

@@ -1,31 +1,70 @@
 import pool from '../db/config';
 
+/**
+ * @class Validation Class
+ */
 class Validator {
+  /**
+   * Check if provided email has a valid email address formatting
+   * @param {string} email - email address to be validated
+   * @returns {boolean} - true is email is properly formatted, false if otherwise
+   */
   static isEmail(email) {
     const re = /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/ig;
     return re.test(email.trim().toLowerCase());
   }
 
+  /**
+   * Check if provided password meets the minimum secure password requirement
+   * @param {string} password - password to be validated
+   * @returns {boolean} - true if password meets minimum complexity requirements
+   */
   static isValidPassword(password) {
     return password.trim().length > 5;
   }
 
+  /**
+   * Check if the two provided passwords match
+   * @param {string} password - first password provided
+   * @param {string} confirmPassword - second provided password
+   * @returns {boolean} - true if both passwords match, false if otherwise
+   */
   static isMatchingPasswords(password, confirmPassword) {
     return password.trim() === confirmPassword.trim();
   }
 
+  /**
+   * Check if name provided is ok
+   * @param {string} name - the name to be validated
+   * @returns {boolean} - true if the name provided meets the minimum acceptance criteria
+   */
   static isValidName(name) {
     return name.trim().length >= 2;
   }
 
+  /**
+   * Check if provided argument is a valid array
+   * @param {Object[]} value
+   * @returns {boolean} - true if the provided value is an array
+   */
   static isArray(value) {
     return Array.isArray(value);
   }
 
+  /**
+   * Check if the provided array is one which contains only numbers
+   * @param {Object[]} array - array of food ids to buy
+   * @returns {boolean} - true if all the elements in the provided array are numbers
+   */
   static isArrayOfNumbers(array) {
     return array.every(element => !Number.isNaN(Number(element)));
   }
 
+  /**
+   * Check db if all food ids to be purchase actually exist.
+   * @param {Object[]} foodIds - arrays of food ids to place an order for
+   * @returns {boolean} - true if all the food ids in the provided array all exist in the database
+   */
   static async isArrayOfValidFoodIds(foodIds) {
     try {
       const allFoodItems = (await pool.query('SELECT * FROM menu')).rows;

tests/seed/seed.js

@@ -58,6 +58,12 @@ const users = {
   },
 };
 
+/**
+ * @function generateValidToken - generates a valid JWT based on the user details
+ * object passed in
+ * @param {Object} userObject - the details of the user
+ * @returns {String} - a valid, signed, JSON Web Token
+ */
 function generateValidToken(userObject) {
   return jwt.sign({
     userId: userObject.id,
@@ -67,6 +73,10 @@ function generateValidToken(userObject) {
   }, process.env.JWT_SECRET).toString();
 }
 
+/**
+ * @async
+ * @function emptyTables - purges the database data
+ */
 const emptyTables = async () => {
   const dropUsersTableQuery = 'DROP TABLE IF EXISTS users CASCADE';
   const dropMenuTableQuery = 'DROP TABLE IF EXISTS menu CASCADE';
@@ -104,6 +114,10 @@ const emptyTables = async () => {
   await pool.query(createOrdersTableQuery);
 };
 
+/**
+ * @async
+ * @function populateMenu - adds two food items to the database
+ */
 const populateMenu = async () => {
   const dbQuery = `INSERT INTO menu(food_name, price)
     VALUES