Documentation (#5)

* updated README.md

* added JSDOC for functions

* updated README.md

Author: jainmohit2001

README.md

@@ -1,34 +1,75 @@
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+# Short URL
+
+This is a simple URL shortener project built as a part of the John Crickett's Coding Challenges [codingchallenges.fyi](https://codingchallenges.fyi/challenges/challenge-url-shortener).
+
+## Table of Contents
+
+- [Tech Stack](#tech-stack)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Testing](#testing)
+- [Deployment](#deployment)
+- [Extra commands](#extra-commands)
+
+## Tech Stack
+
+[Next.js](https://nextjs.org/), [NextAuth.js](https://next-auth.js.org/), [TypeScript](https://www.typescriptlang.org/), [React MUI](https://mui.com/), [Tailwind CSS](https://tailwindcss.com/), [Cypress](https://www.cypress.io/) and [MongoDB](https://www.mongodb.com/)
+
+## Installation
+
+```bash
+# To install dependencies
+npm ci
+
+# To install and setup husky
+npm husky install
+```
 
 ## Getting Started
 
-First, run the development server:
+Before starting the server make sure you have a `.env.local` file in the root directory with the same template as mentioned in `.env.template` file.
 
 ```bash
+# Prisma migration
+npm run prisma-dev-push
+
+# To start the development server
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
 ```
 
 Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+## Testing
 
-This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
+Before starting the test, make sure you have a `cypress.env.json` file in the root directory with the same template as mentioned in `cypress.env.template.json` file.
 
-## Learn More
+```bash
+# To use the Cypress GUI
+npm run test
 
-To learn more about Next.js, take a look at the following resources:
+# To run Cypress in headless mode
+npm run test:headless
+```
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+## Deployment
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+```bash
+# Build the optimized production build
+npm run build
 
-## Deploy on Vercel
+# Start the production server
+npm run start
+```
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+## Extra commands
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+```bash
+# To lint the code
+npm run lint
+
+# To check formatting using Prettier
+npm run check-format
+
+# To format the code using Prettier
+npm run format
+```

src/app/dashboard/page.tsx

@@ -105,6 +105,12 @@ export default function Profile() {
     setCurrentPage(page)
   }
 
+  /**
+   * Function used to add a URL.
+   * The form contains an input with name='url' containing the original URL.
+   *
+   * @param {*} e - The Form DOM element
+   */
   function addUrl(e: any) {
     setAddingUrl(true)
     e.preventDefault()
@@ -171,6 +177,8 @@ export default function Profile() {
         if (res.status === 200) {
           urlList.splice(index, 1)
           setUrlList(urlList)
+
+          // If the urlList is empty, then we need to go back one page if possible
           if (urlList.length === 0) {
             const newPage = Math.max(0, currentPage - 1)
             setCurrentPage(newPage)
@@ -245,10 +253,6 @@ export default function Profile() {
     )
   }
 
-  if (!session?.user) {
-    return <div>Invalid User</div>
-  }
-
   return (
     <>
       <div className="flex w-full flex-col gap-4">

src/components/Header.tsx

@@ -23,6 +23,8 @@ export function Header() {
         ></Image>
         <span>Home</span>
       </Link>
+      {/* Show content is user is authenticated or not authenticated.
+      Show nothing when the status is loading */}
       <div className="ml-auto mr-5">
         {status === 'loading' ? (
           <></>

src/lib/authOptions.ts

@@ -4,6 +4,13 @@ import GoogleProvider from 'next-auth/providers/google'
 import { AuthOptions } from 'next-auth'
 import { prisma } from './prisma'
 
+/**
+ * The authOptions used for NextAuth.
+ * We are using a MongoDB adapter along with GoogleProvider to store user data.
+ * In the callbacks we are making sure that the ID of the user is available in the Session object.
+ *
+ * @type {AuthOptions}
+ */
 export const authOptions: AuthOptions = {
   secret: process.env.NEXTAUTH_SECRET,
   adapter: PrismaAdapter(prisma),
@@ -15,15 +22,19 @@ export const authOptions: AuthOptions = {
   ],
   callbacks: {
     async jwt({ token, user }) {
+      // Update the token to have user id available in session callback
       if (user) {
         token.id = user.id
       }
       return token
     },
     async session({ session, token, user }) {
+      // If token is not null, use the id present in the Token
       if (token) {
         session.user.id = token.id as string
       }
+
+      // If user object is available, use the id present in it
       if (user) {
         session.user.id = user.id
       }

src/lib/copyToClipboard.ts

@@ -1,4 +1,10 @@
+/**
+ * Function to copy the text provided in the input to the User's clipboard
+ *
+ * @param {string} text
+ */
 const copyToClipboard = (text: string) => {
   navigator.clipboard.writeText(text)
 }
+
 export default copyToClipboard

src/lib/prisma.ts

@@ -1,5 +1,6 @@
 import { PrismaClient } from '@prisma/client'
 
+// Make sure that the PrismaClient is created only once
 const globalForPrisma = global as unknown as { prisma: PrismaClient }
 
 export const prisma =

src/lib/url.ts

@@ -2,6 +2,12 @@ import { Session } from 'next-auth'
 import crypto from 'crypto'
 import { prisma } from './prisma'
 
+/**
+ * Get URL by its ID otherwise
+ *
+ * @async
+ * @param {string} id
+ */
 export const getUrlById = async (id: string) => {
   const url = await prisma.url.findUnique({
     where: {
@@ -14,6 +20,15 @@ export const getUrlById = async (id: string) => {
   return url
 }
 
+/**
+ * Creates a new URL corresponding to the User ID present in the Session object.
+ * The short URL is created by making sure that it is unique in the database.
+ * Returns the URL object along with the attached User.
+ *
+ * @async
+ * @param {string} originalUrl
+ * @param {Session} session
+ */
 export const createUrl = async (originalUrl: string, session: Session) => {
   if (!session?.user?.email) {
     throw new Error('No email present in Session object')
@@ -45,6 +60,15 @@ export const createUrl = async (originalUrl: string, session: Session) => {
   return url
 }
 
+/**
+ * Function to get paginated URLs from the DB.
+ *
+ * @async
+ * @param {string} id - ID of the User
+ * @param {number} [skip=0] - Records to skip
+ * @param {number} [take=10] - Records to take after skipping
+ * @returns {Promise<IPaginatedUrls>}
+ */
 export const getUrlsForUser = async (
   id: string,
   skip: number = 0,
@@ -77,6 +101,14 @@ export const getUrlsForUser = async (
   }
 }
 
+/**
+ * Deletes a URL given its ID and the User ID
+ *
+ * @async
+ * @param {string} id - ID of the URL object
+ * @param {string} userId - User ID
+ * @returns {Promise<boolean>} - true if record was found and deleted successfully, otherwise false
+ */
 export const deleteUrl = async (
   id: string,
   userId: string
@@ -90,7 +122,14 @@ export const deleteUrl = async (
   return true
 }
 
-export const getOriginalUrlFromShortUrl = async (
+export /**
+ * Given a short URL, find if a URL object exists otherwise throw an error.
+ *
+ * @async
+ * @param {string} shortUrl
+ * @returns {Promise<string>} - the original URL corresponding to the short URL
+ */
+const getOriginalUrlFromShortUrl = async (
   shortUrl: string
 ): Promise<string> => {
   const url = await prisma.url.findFirstOrThrow({

src/types/next-auth.d.ts

@@ -1,5 +1,7 @@
 import { DefaultUser } from 'next-auth'
 
+// To make the User ID available on the client side,
+// we need to extend the Session interface provided by NextAuth
 declare module 'next-auth' {
   interface Session {
     user: DefaultUser & {

src/types/url.d.ts

@@ -1,6 +1,35 @@
+/**
+ * Interface for the Response of /api/urls GET call.
+ *
+ * @interface IPaginatedUrls
+ * @typedef {IPaginatedUrls}
+ */
 interface IPaginatedUrls {
+  /**
+   * List of URLS.
+   *
+   * @type {Url[]}
+   */
   results: Url[]
+
+  /**
+   * Total URL count for the user.
+   *
+   * @type {number}
+   */
   totalCount: number
+
+  /**
+   * The skip parameter used for the Prisma query.
+   *
+   * @type {number}
+   */
   skip: number
+
+  /**
+   * The take parameter used for the Prisma query.
+   *
+   * @type {number}
+   */
   take: number
 }