From c696a94b10111d002c88c501d4642736f68290c9 Mon Sep 17 00:00:00 2001 From: Dale Lotts Date: Tue, 16 Feb 2021 22:14:53 -0700 Subject: [PATCH] docs: update documentation (#1) --- README.md | 57 +++++++++++++- back-end/README.md | 31 +------- back-end/knexfile.js | 6 ++ back-end/src/errors/errorHandler.js | 5 +- back-end/src/errors/notFound.js | 3 + .../reservations/reservations.controller.js | 6 ++ .../src/reservations/reservations.router.js | 6 ++ front-end/README.md | 5 +- front-end/src/App.js | 4 + front-end/src/dashboard/Dashboard.js | 6 ++ front-end/src/layout/ErrorAlert.js | 8 ++ front-end/src/layout/Layout.js | 7 ++ front-end/src/layout/Menu.js | 6 ++ front-end/src/layout/NotFound.js | 7 ++ front-end/src/layout/Routes.js | 9 ++- front-end/src/utils/date-time.js | 78 +++++++++++++++++++ front-end/src/utils/dates.js | 27 ------- front-end/src/utils/formatReservationDate.js | 16 ++-- front-end/src/utils/formatReservationTime.js | 12 ++- front-end/src/utils/useQuery.js | 16 ++++ 20 files changed, 240 insertions(+), 75 deletions(-) create mode 100644 front-end/src/utils/date-time.js delete mode 100644 front-end/src/utils/dates.js create mode 100644 front-end/src/utils/useQuery.js diff --git a/README.md b/README.md index 45e63f2806..9cefd08700 100644 --- a/README.md +++ b/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 `` and ``, 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 `` and ``, which are supported by Chrome but may not work in other browsers. > > `` will store the date in `YYYY-MM-DD` format. This is a format that works well with the PostgreSQL `date` data type. > diff --git a/back-end/README.md b/back-end/README.md index 97ba333f16..f94aa33f37 100644 --- a/back-end/README.md +++ b/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. diff --git a/back-end/knexfile.js b/back-end/knexfile.js index 194ca3d7f4..eeb8157a83 100644 --- a/back-end/knexfile.js +++ b/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 { diff --git a/back-end/src/errors/errorHandler.js b/back-end/src/errors/errorHandler.js index 82ac3ada4e..6d794361b9 100644 --- a/back-end/src/errors/errorHandler.js +++ b/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 }); } diff --git a/back-end/src/errors/notFound.js b/back-end/src/errors/notFound.js index 89259ec6f2..4531bf2127 100644 --- a/back-end/src/errors/notFound.js +++ b/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}` }); } diff --git a/back-end/src/reservations/reservations.controller.js b/back-end/src/reservations/reservations.controller.js index a9c9062e5c..d153395a59 100644 --- a/back-end/src/reservations/reservations.controller.js +++ b/back-end/src/reservations/reservations.controller.js @@ -1,3 +1,9 @@ +/** + * List handler for reservation resources + * @param req + * @param res + * @returns {Promise} + */ async function list(req, res) { res.json({ data: [], diff --git a/back-end/src/reservations/reservations.router.js b/back-end/src/reservations/reservations.router.js index 7b2efea5df..0678a43f61 100644 --- a/back-end/src/reservations/reservations.router.js +++ b/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"); diff --git a/front-end/README.md b/front-end/README.md index dc96910bde..fd12a0a9fa 100644 --- a/front-end/README.md +++ b/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. diff --git a/front-end/src/App.js b/front-end/src/App.js index 9782af7f1d..4d25a1fcf4 100644 --- a/front-end/src/App.js +++ b/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 ( diff --git a/front-end/src/dashboard/Dashboard.js b/front-end/src/dashboard/Dashboard.js index cbe90128cf..2b23b90f98 100644 --- a/front-end/src/dashboard/Dashboard.js +++ b/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); diff --git a/front-end/src/layout/ErrorAlert.js b/front-end/src/layout/ErrorAlert.js index 9c713e1778..e2224cc884 100644 --- a/front-end/src/layout/ErrorAlert.js +++ b/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 && ( diff --git a/front-end/src/layout/Layout.js b/front-end/src/layout/Layout.js index 4510150517..50bce90762 100644 --- a/front-end/src/layout/Layout.js +++ b/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 (
diff --git a/front-end/src/layout/Menu.js b/front-end/src/layout/Menu.js index efd51c89d9..f505134281 100644 --- a/front-end/src/layout/Menu.js +++ b/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 (