docs: update documentation (#1)

README.md

@@ -6,6 +6,8 @@
 
 There are no user stories for deployment: it is expected that you will deploy the application to production after you finish a user story.
 
+There are no user stories for logging: it is expected that you will add logging to the application with enough detail to help you diagnose issues in production.
+
 ## Existing files
 
 This repository is set up as a monorepo, meaning that the frontend and backend projects are in one repository. This allows you to open both projects in the same editor.
@@ -16,11 +18,58 @@ The table below describes the folders in this starter repository:
 
 | Folder/file path | Description                                                      |
 | ---------------- | ---------------------------------------------------------------- |
-| `back-end`       | The backend project, which runs on `localhost:5000` by default.  |
-| `front-end`      | The frontend project, which runs on `localhost:3000` by default. |
+| `./back-end`     | The backend project, which runs on `localhost:5000` by default.  |
+| `./front-end`    | The frontend project, which runs on `localhost:3000` by default. |
 
 This starter code closely follows the best practices and patterns established in the Robust Server Structure module.
 
+### Backend Existing files
+
+The `./back-end` folder contains all the code for the backend project.
+
+The table below describes the existing files in the `./back-end` folder:
+
+| Folder/file path                                         | Description                                                                                                          |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `./back-end/knexfile.js`                                 | The Knex configuration file. You will not need to make changes to this file.                                         |
+| `./back-end/src/app.js`                                  | Defines the Express application and connects routers.                                                                |
+| `./back-end/src/db/connection.js`                        | The Knex connection file. You will not need to make changes to this file.                                            |
+| `./back-end/src/db/migrations`                           | The Knex migrations folder.                                                                                          |
+| `./back-end/src/db/seeds/`                               | The Knex seeds folder.                                                                                               |
+| `./back-end/src/errors/errorHandler.js`                  | Defined an Express API error handler.                                                                                |
+| `./back-end/src/errors/notFound.js`                      | Defined an Express API "not found" handler.                                                                          |
+| `./back-end/src/reservations/reservations.controller.js` | A controller for the reservations resource.                                                                          |
+| `./back-end/src/reservations/reservations.router.js`     | A router for the reservations resource.                                                                              |
+| `./back-end/src/server.js`                               | Defines the node server.                                                                                             |
+| `./back-end/test`                                        | A folder that contains all of the integrattion tests. You will not need to make changes to the files in this folder. |
+| `./back-end/vercel.json`                                 | A vercel deployment configuration file. You will not need to make changes to this file.                              |
+
+### Frontend Existing files
+
+The `./front-end` folder contains all the code for the frontend project.
+
+The table below describes the existing files in the `./front-end` folder:
+
+| Folder/file path                                 | Description                                                                                                        |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `./front-end/e2e`                                | A folder that contains all of the end-to-end tests. You will not need to make changes to the files in this folder. |
+| `./front-end/jest-puppeteer.config.js`           | The jest-puppeteer configuration file. You will not need to make changes to this file.                             |
+| `./front-end/src/App.js`                         | Defines the root application component. You will not need to make changes to this file.                            |
+| `./front-end/src/App.test.js`                    | Contains the tests for the root application component. You will not need to make changes to this file.             |
+| `./front-end/src/dashboard/Dashboard.js`         | Defines the Dashboard page.                                                                                        |
+| `./front-end/src/index.js`                       | The main entry point for the React application.                                                                    |
+| `./front-end/src/layout/ErrorAlert.js`           | Defines an error alert component that display only when an error is specified.                                     |
+| `./front-end/src/layout/Layout.css`              | The css for the Layout component.                                                                                  |
+| `./front-end/src/layout/Layout.js`               | Defined the main layout of the applicaiton.                                                                        |
+| `./front-end/src/layout/Menu.js`                 | Defines the menu for the application.                                                                              |
+| `./front-end/src/layout/NotFound.js`             | Defines the "Not found" component that is display when no route matches.                                           |
+| `./front-end/src/layout/Routes.js`               | Defines all the routes for the application.                                                                        |
+| `./front-end/src/utils/api.js`                   | Defines the functions uses to access the backend API                                                               |
+| `./front-end/src/utils/date-time.js`             | Defines functions to format date and time strings.                                                                 |
+| `./front-end/src/utils/formatReservationDate.js` | Defines a function to format the date on an array of reservations.                                                 |
+| `./front-end/src/utils/formatReservationTime.js` | Defines a function to format the time on an array of reservations.                                                 |
+| `./front-end/src/utils/useQuery.js`              | Defines a custom hook to parse the query parameters from the URL.                                                  |
+
 ## Database setup
 
 1. Set up four new ElephantSQL database instances - development, test, preview, and production - by following the instructions in the "PostgreSQL: Creating & Deleting Databases" checkpoint.
@@ -100,11 +149,11 @@ so that I know how many customers will arrive at the restaurant on a given day.
    - display next, previous, and today buttons that allow the user to see reservations on other dates
    - display any error messages returned from the API
 1. The `/reservations` API will have the same validations as above and will return 400, along with an informative error message, when a validation error happens.
+   - seed the reservations table with the data contained in `./back-end/src/db/seeds/00-reservations.json`
 
 > **Hint** Dates and times in JavaScript and databases can be challenging.
-> The users have confirmed that they will be using Chrome to access the site.
 >
-> This means you can use `<input type="date" />` and `<input type="time" />`, which are supported by Chrome but may not work in other browsers.
+> The users have confirmed that they will be using Chrome to access the site. This means you can use `<input type="date" />` and `<input type="time" />`, which are supported by Chrome but may not work in other browsers.
 >
 > `<input type="date" />` will store the date in `YYYY-MM-DD` format. This is a format that works well with the PostgreSQL `date` data type.
 >

back-end/README.md

@@ -1,32 +1,5 @@
-# Restaurant Reservation Backend Application
+# Capstone: Restaurant Reservation System Backend
 
 This starter code for the backend of the capstone project in the Thinkful curriculum.
 
-## Existing files
-
-As you work through the Node.js, Express & PostgreSQL module, you will be writing code that allows your controllers to connect to and query your PostgreSQL database via [Knex](http://knexjs.org/). The table below describes the files and folders in the starter code:
-
-| Folder/file path | Description                                                                      |
-| ---------------- | -------------------------------------------------------------------------------- |
-| `src/app.js`     | Directs requests to the appropriate routers.                                     |
-| `src/server.js`  | Starts the server on `localhost:5000` by default.                                |
-| `src/db/`        | A folder where you will add migration and seed files for your database later on. |
-| `src/errors/`    | A folder where you will find several functions for handle various errors         |
-| `.env.sample`    | A sample environment configuration file                                          |
-
-This starter code closely follows the best practices and patterns established in the Robust Server Structure module.
-
-## Database setup
-
-1. Set up three new ElephantSQL database instance - development, test, and production - by following the instructions in the "PostgreSQL: Creating & Deleting Databases" checkpoint.
-1. After setting up your database instances, connect DBeaver to your new database instances by following the instructions in the "PostgreSQL: Installing DBeaver" checkpoint.
-
-## Installation
-
-1. Fork and clone this repository.
-1. Run `cp .env.sample .env`.
-1. Update your `.env` file with a connection URL to your ElephantSQL database instance.
-1. Run `npm install` to install project dependencies.
-1. Run `npm run start:dev` to start your server in development mode.
-
-If you have trouble getting the server to run, reach out for assistance.
+See [../README.md](../README.md) for detailed instructions.

back-end/knexfile.js

@@ -1,3 +1,9 @@
+/**
+ * Knex configuration file.
+ *
+ * You will not need to make changes to this file.
+ */
+
 const path = require("path");
 
 const {

back-end/src/errors/errorHandler.js

@@ -1,4 +1,7 @@
-function errorHandler(error, request, response, next) {
+/**
+ * Express API error handler.
+ */
+function errorHandler(error, request, response) {
   const { status = 500, message = "Something went wrong!" } = error;
   response.status(status).json({ error: message });
 }

back-end/src/errors/notFound.js

@@ -1,3 +1,6 @@
+/**
+ * Express API "Not found" handler.
+ */
 function notFound(req, res, next) {
   next({ status: 404, message: `Path not found: ${req.originalUrl}` });
 }

back-end/src/reservations/reservations.controller.js

@@ -1,3 +1,9 @@
+/**
+ * List handler for reservation resources
+ * @param req
+ * @param res
+ * @returns {Promise<void>}
+ */
 async function list(req, res) {
   res.json({
     data: [],

back-end/src/reservations/reservations.router.js

@@ -1,3 +1,9 @@
+/**
+ * Defines the router for reservation resources.
+ *
+ * @type {Router}
+ */
+
 const router = require("express").Router({ mergeParams: true });
 const controller = require("./reservations.controller");
 

front-end/README.md

@@ -1,6 +1,5 @@
 # Capstone: Restaurant Reservation System Frontend
 
-Used by restaurant personnel when a customer calls to request a reservation.
-No online access by the customer at this point.
+This starter code for the backend of the capstone project in the Thinkful curriculum.
 
-There are no user stories for deployment, it is expected that you will deploy the application to production after you finish a user story.
+See [../README.md](../README.md) for detailed instructions.

front-end/src/App.js

@@ -2,6 +2,10 @@ import React from "react";
 import { Route, Switch } from "react-router-dom";
 import Layout from "./layout/Layout";
 
+/**
+ * Defines the root application component.
+ * @returns {JSX.Element}
+ */
 function App() {
   return (
     <Switch>

front-end/src/dashboard/Dashboard.js

@@ -2,6 +2,12 @@ import React, { useEffect, useState } from "react";
 import { listReservations } from "../utils/api";
 import ErrorAlert from "../layout/ErrorAlert";
 
+/**
+ * Defines the dashboard page.
+ * @param date
+ *  the date for which the user wants to view reservations.
+ * @returns {JSX.Element}
+ */
 function Dashboard({ date }) {
   const [reservations, setReservations] = useState([]);
   const [reservationsError, setReservationsError] = useState(null);

front-end/src/layout/ErrorAlert.js

@@ -1,5 +1,13 @@
 import React from "react";
 
+/**
+ * Defines the alert message to render if the specified error is truthy.
+ * @param error
+ *  an instance of an object with `.message` property as a string, typically an Error instance.
+ * @returns {JSX.Element}
+ *  a bootstrap danger alert that contains the message string.
+ */
+
 function ErrorAlert({ error }) {
   return (
     error && (

front-end/src/layout/Layout.js

@@ -4,6 +4,13 @@ import Routes from "./Routes";
 
 import "./Layout.css";
 
+/**
+ * Defines the main layout of the application.
+ *
+ * You will not need to make changes to this file.
+ *
+ * @returns {JSX.Element}
+ */
 function Layout() {
   return (
     <div className="container-fluid">

front-end/src/layout/Menu.js

@@ -2,6 +2,12 @@ import React from "react";
 
 import { Link } from "react-router-dom";
 
+/**
+ * Defines the menu for this application.
+ *
+ * @returns {JSX.Element}
+ */
+
 function Menu() {
   return (
     <nav className="navbar navbar-dark align-items-start p-0">

front-end/src/layout/NotFound.js

@@ -1,5 +1,12 @@
 import React from "react";
 
+/**
+ * Defines the "Not Found" page that is displayed for any unmatched route.
+ *
+ * You will not need to make changes to this file.
+ *
+ * @returns {JSX.Element}
+ */
 function NotFound() {
   return (
     <div className="NotFound">

front-end/src/layout/Routes.js

@@ -3,8 +3,15 @@ import React from "react";
 import { Redirect, Route, Switch } from "react-router-dom";
 import Dashboard from "../dashboard/Dashboard";
 import NotFound from "./NotFound";
-import { today } from "../utils/dates";
+import { today } from "../utils/date-time";
 
+/**
+ * Defines all the routes for the application.
+ *
+ * You will need to make changes to this file.
+ *
+ * @returns {JSX.Element}
+ */
 function Routes() {
   return (
     <Switch>

front-end/src/utils/date-time.js

@@ -0,0 +1,78 @@
+const dateFormat = /\d\d\d\d-\d\d-\d\d/;
+const timeFormat = /\d\d:\d\d/;
+
+/**
+ * Formats a Date object as YYYY-MM-DD.
+ *
+ * This function is *not* exported because the UI should generally avoid working directly with Date instance.
+ * You may export this function if you need it.
+ *
+ * @param date
+ *  an instance of a date object
+ * @returns {string}
+ *  the specified Date formatted as YYYY-MM-DD
+ */
+function asDateString(date) {
+  return `${date.getFullYear().toString(10)}-${(date.getMonth() + 1)
+    .toString(10)
+    .padStart(2, "0")}-${date.getDate().toString(10).padStart(2, "0")}`;
+}
+
+/**
+ * Format a date string in ISO-8601 format (which is what is returned from PostgreSQL) as YYYY-MM-DD.
+ * @param dateString
+ *  ISO-8601 date string
+ * @returns {*}
+ *  the specified date string formatted as YYYY-MM-DD
+ */
+export function formatAsDate(dateString) {
+  return dateString.match(dateFormat)[0];
+}
+
+/**
+ * Format a time string in HH:MM:SS format (which is what is returned from PostgreSQL) as HH:MM.
+ * @param timeString
+ *  HH:MM:SS time string
+ * @returns {*}
+ *  the specified time string formatted as YHH:MM.
+ */
+export function formatAsTime(timeString) {
+  return timeString.match(timeFormat)[0];
+}
+
+/**
+ * Today's date as YYYY-MM-DD.
+ * @returns {*}
+ *  the today's date formatted as YYYY-MM-DD
+ */
+export function today() {
+  return asDateString(new Date());
+}
+
+/**
+ * Subtracts one day to the specified date and return it in as YYYY-MM-DD.
+ * @param currentDate
+ *  a date string in YYYY-MM-DD format (this is also ISO-8601 format)
+ * @returns {*}
+ *  the date one day prior to currentDate, formatted as YYYY-MM-DD
+ */
+export function previous(currentDate) {
+  const date = new Date(...currentDate.split("-"));
+  date.setMonth(date.getMonth() - 1);
+  date.setDate(date.getDate() - 1);
+  return asDateString(date);
+}
+
+/**
+ * Adds one day to the specified date and return it in as YYYY-MM-DD.
+ * @param currentDate
+ *  a date string in YYYY-MM-DD format (this is also ISO-8601 format)
+ * @returns {*}
+ *  the date one day after currentDate, formatted as YYYY-MM-DD
+ */
+export function next(currentDate) {
+  const date = new Date(...currentDate.split("-"));
+  date.setMonth(date.getMonth() - 1);
+  date.setDate(date.getDate() + 1);
+  return asDateString(date);
+}

front-end/src/utils/formatReservationDate.js

@@ -1,12 +1,16 @@
-const dateFormat = /\d\d\d\d-\d\d-\d\d/;
+import { formatAsDate } from "./date-time";
 
-function formatReservationDate(reservations = []) {
+/**
+ * Formats the reservation_date property for each reservation in an array of reservations.
+ * @param reservations
+ * @returns {[reservation]}
+ *  the specified reservations array with each reservation_date property formatted as YYYY-MM-DD.
+ */
+function formatReservationsDate(reservations = []) {
   return reservations.map((reservation) => {
-    reservation.reservation_date = reservation.reservation_date.match(
-      dateFormat
-    )[0];
+    reservation.reservation_date = formatAsDate(reservation.reservation_date);
     return reservation;
   });
 }
 
-module.exports = formatReservationDate;
+module.exports = formatReservationsDate;