DEV Community: GrocStock

Introduction to React

Rohith Poyyeri — Thu, 20 Jul 2023 23:32:42 +0000

Are you new to React or in need of a refresher? Look no further! In this blog post, we will guide you through the process of building a ToDo application from scratch. React has gained immense popularity as a JavaScript library for building user interfaces, and by following this step-by-step guide, you'll embark on a journey to becoming a React developer. This app serves as the User Interface (UI) for the ToDo API, that we have built in my previous blog. Let's dive in and get started!

Prerequisites

Before we dive into the development process, let's make sure we have everything we need. Ensure that you have the following installed:
Node.js and npm (Node Package Manager)
npx

Order of execution

In a React app that utilises TypeScript and functional components without relying on class components, the order of execution follows a specific sequence:

Initialisation: When the React app is loaded, the React library initialises by creating the virtual DOM (VDOM), which is a lightweight representation of the actual DOM.

Mounting: The mounting phase begins by creating an instance of the root component specified in the ReactDOM.render() method. This component, written using TypeScript or pure JS/TS functions, is mounted onto the actual DOM, replacing the target HTML element.

Component Rendering: React traverses the component tree, starting from the root component. Each functional component's body is executed, returning a description of the component's user interface as React elements. This applies to both TypeScript and pure JS/TS functions used to define components.

Diffing and Reconciliation: React performs a diffing algorithm to determine the differences between the previous and new versions of the virtual DOM. This process, applicable to both TypeScript and pure JS/TS functions-based components, is called reconciliation. It identifies the minimal set of changes needed to efficiently update the actual DOM.

Updating: Once the differences are identified, React applies the necessary updates to the actual DOM, ensuring it reflects the new state of the application. The update process, which includes inserting, updating, or removing elements, is performed for both TypeScript and pure JS/TS functions-based components.

Unmounting: If a component is removed from the component tree, React cleans up any resources associated with that component. This is automatically handled by React when using functional components.

Event Handling: React attaches event handlers, whether defined in TypeScript or pure JS/TS functions, to the appropriate elements in the actual DOM. When an event occurs, React triggers the corresponding event handler defined in the component, allowing us to respond to user interactions.

State and Props Updates: When a component's state or props change, React re-invokes the body of the functional component, resulting in a re-rendering of that component and its child components. This applies to both TypeScript and pure JS/TS functions-based components.

It's important to note that the execution order in React may vary depending on the specific circumstances of the application, the usage of TypeScript or pure JS/TS functions, and the hooks employed. However, the outlined sequence provides a general overview of the typical execution flow in a React app utilising TypeScript and functional components without relying on class components.

Creating a new React project

To create a new React app with TypeScript and SCSS (Sass), we can use the create-react-app tool and specify the necessary configurations.

npx create-react-app todo-react-ui --template typescript

Node version

Lets start by creating a new .nvmrc file in the root of the project. This defines what version of node we are using. We are going to use the ‘lts/Gallium’ version. Add the following line to the file.

lts/Gallium

Run the following command and might prompt us to install the version if it is missing.
nvm use

Clean up and initial set-up

npm install node-sass
npm install @mui/icons-material @mui/material

Let us create a new App.scss file and import that in the App.tsx file. Now this acts as a global stylesheet and all the generic SCSS classes can go in here.

Let's add FontAwesome and flexboxgrid in the public/index.html. Add the following in the <head> tag.

<link rel="stylesheet" type="text/css" href="https://use.fontawesome.com/releases/v6.2.1/css/all.css" defer/>
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/flexboxgrid/6.3.1/flexboxgrid.min.css" defer/>

FontAwesome is a powerful icon library that provides a wide range of visually appealing icons that can enhance the visual appearance of our application. By utilising FontAwesome, we can easily incorporate these icons into various parts of our application, adding a touch of style and clarity.

FlexBoxGrid, on the other hand, is a flexible grid system that leverages the power of the CSS flex display property. With FlexBoxGrid, we can easily create responsive and dynamic layouts for our application. It simplifies the process of arranging elements on the page, allowing us to achieve desired layouts with ease. By utilising the capabilities of FlexBoxGrid, we can ensure that our application's layout remains consistent across different screen sizes and devices.

Environment

In our project, we have introduced a configuration file named "config.json" located in the "public" folder. This file contains environment variables that are utilised throughout the application, excluding any sensitive information. To handle the retrieval of these variables, we will implement a ConfigContext that will read the "config.json" file and provide access to these variables within our components. However, in the production environment, we need to override this configuration by introducing a separate production config file. This allows us to customise the variables specifically for the production environment, ensuring proper configuration and security measures are in place. By adopting this approach, we can effectively manage and utilise environment variables across different environments in our application.

To achieve a build-once, deploy-many scenario and ensure appropriate configuration for different environments such as staging, testing, and production, we can utilise multiple config.env.json files. Each environment can have its dedicated configuration file, allowing us to define specific settings and variables tailored to that particular environment.

By maintaining separate configuration files, we can easily switch between environments during the build or deployment process. This ensures that the correct configuration is used for each environment, avoiding any potential conflicts or inconsistencies.

Having separate config files for different environments simplifies the management of environment-specific settings, making it easier to maintain and update configurations without affecting other environments. This approach enhances the flexibility and scalability of our application, enabling smooth deployments and ensuring that the appropriate configurations are utilised based on the target environment.

Connecting to backend API

Our React application has been configured to send API requests to a specific target URL, which in this case is the todo-api server running on port 3000. This setup enables smooth communication between the frontend and backend, facilitating the retrieval and manipulation of data from the todo-api server within our React application. To handle the API requests, we will utilise React hooks and the axios library. React hooks provide a convenient way to manage state and side effects, while the axios library simplifies the process of sending XMLHttpRequest (XHR) requests to the API.
Component and its lifecycle
In a pure JavaScript/TypeScript React component, also known as a functional component, the order of execution follows a specific sequence. Let's outline the order of execution for such components:

Function Body: The function body contains the logic and JSX code that defines the component's UI and behaviour.

Initial Render: When the component is first rendered, the function body is executed, and the JSX elements are returned. This initial render creates the initial representation of the component's UI.

Props Update: If the component receives new props from its parent component, it triggers a re-render. The function body is executed again, and the JSX elements are updated based on the new props.

State Updates: If the component's state is updated using hooks like useState, the function body is executed again, and the JSX elements are re-rendered based on the new state values.

It's important to note that in functional components, there is no concept of lifecycle methods like componentDidMount or componentDidUpdate. Instead, React provides hooks like useEffect, useState, useContext, etc., to handle side effects, manage state, and access context.

The useEffect hook allows us to perform side effects, such as fetching data from an API or subscribing to events, after the component has rendered or when specific dependencies change.

The order of execution in a pure JavaScript/TypeScript React component involves the execution of the function body during the initial render and subsequent re-renders triggered by prop or state updates. By utilising hooks like useEffect and useState, we can control the component's behaviour and manage side effects effectively.

Shared Components

Let us create a set of shared components that promote component reusability and maintain consistency throughout the application. These shared components reside in the 'src/components/' directory and are imported wherever required.

Header serves as the navigation bar of the application, providing users with easy access to different sections or pages of the app. It typically contains menus, links, or buttons for navigation purposes.

Footer is responsible for displaying a footer at the bottom of the application, providing additional information, copyright notices, or links to relevant pages.

Heading is a reusable component used to display a heading or title for each page. It helps to maintain consistent styling and structure across different pages of the application.

Empty is designed to be displayed when a list or data set is empty. It provides a message or placeholder content to inform users that there is no data available.

TextModal is a dialog or modal component used to add or input data in the application. It typically includes form fields, buttons, and validation to gather user input and save it to the system.

TodoCard is responsible for displaying individual ToDos as aesthetically pleasing card designs.

The full code of these components is available in github.

Pages

Now let’s create the other pages that we are after.

We should create a directory with the name of the page, along with its SCSS styles, and TypeScript code.

The HomePage serves as the welcome or homepage of our application, acting as the landing page that users first encounter when accessing our site. It provides an overview of our app's features, highlights, or any relevant information we want to showcase to users right from the start. This component is designed to provide a visually appealing and engaging user experience, making a positive first impression.

On the other hand, the NotFoundPage plays a crucial role as a fallback page. Whenever users navigate to a route that doesn't exist or provide an incorrect route, they will be redirected to the NotFoundComponent. This component serves as an error page, informing users that the requested page or resource cannot be found. It helps to improve the user experience by gracefully handling such scenarios and providing a clear message to users about the issue encountered.

Elephant in the room, ToDo

ToDo Modal

Let us create a new modal, Todo.ts.

export interface Todo {
 _id: string;
 description: string;
 is_active: boolean;
 updatedAt: string;
}

ToDo hook

Let us create a React hook, src/hooks.todo.ts where we can define various functions to interact with the ToDo data. By utilising the power of React hooks, we can create a custom hook that encapsulates the logic for managing ToDo items. Within this hook, we can define functions such as getAllTodo, createTodo, updateTodo, and deleteTodo. The getAllTodo function retrieves all existing ToDo items, createTodo adds a new ToDo item to the list, updateTodo updates the details of a specific ToDo item, and deleteTodo removes a ToDo item from the list. By returning these functions as an object from the hook, we provide a convenient interface for other components to interact with the ToDo data. This approach promotes reusability and separation of concerns, allowing components to focus on rendering and user interactions while the hook handles the underlying ToDo data operations.

ToDo Page

Let's create a new ToDo Page with TodoPage.tsx inside the src/pages/TodoPage directory.
Within the TodoPage, we define several state variables using the useState hook, including activeTodos, inactiveTodos, activeTab, and modalOpen. The useEffect hook is used to fetch Todo data using the getAllTodo function from the useTodo hook when the component mounts. The retrieved data is then filtered into active and inactive Todo items, which are stored in the activeTodos and inactiveTodos states, respectively.

The component also includes various event handler functions that are responsible for handling tab changes, opening and closing the modal, submitting new Todo items, marking Todo items as active or inactive, deleting Todo items, and updating the Todo list.

The return statement consists of JSX elements that render the TodoPage’s UI. It includes a heading, a button to open the modal, tabs to switch between active and inactive Todo lists, and conditional rendering of TodoCard components or an Empty component based on the selected tab and the existence of Todo items. Finally, it renders the TextModal component if modalOpen is true.

ToDo Style

To make our ToDo app visually appealing, we can apply custom styles using SCSS. Modify the SCSS file (TodoPage.scss) in the same directory to match our desired design and import this to TodoPage.tsx.

Style

Our application incorporates the powerful features of FontAwesome and FlexBoxGrid libraries, enhancing the visual aesthetics and layout capabilities. By integrating FontAwesome, we gain access to an extensive collection of icons that can be easily incorporated into our UI, allowing for visually appealing and intuitive designs. Additionally, the integration of FlexBoxGrid provides us with a responsive grid system, enabling us to create flexible and adaptive layouts that adapt to different screen sizes. Furthermore, we have seamlessly integrated Material UI and its associated material icons, enriching our application with pre-designed components and a vast library of visually pleasing icons. Together, these integrations enhance the user experience and provide us with a rich set of tools to create visually appealing and responsive interfaces.

Routing

To enhance the navigation of our project, let's incorporate routes with the following configuration:
Assign the empty routes to the Home page, providing users with a welcoming starting point.
Direct the todo routes to the Todo page.
Map the 404 routes to an Error Page, ensuring a user-friendly experience when encountering unexpected routes.
For any other routes that don't match the defined paths, gracefully redirect users to the Error Page, maintaining a consistent flow throughout the app.

Let us create a AppRoutes.tsx component and import this in the App.tsx

export function AppRoutes() {
 return (
  <Routes>
   <Route path="/" element={<HomePage />} />
   <Route path="/todo" element={<TodoPage />} />
   <Route path="/404" element={<NotFoundPage />} />
   <Route path="*" element={<NotFoundPage />} />
  </Routes>
 );
}

Running the app

Let’s us run the app and have a look at it spinning up at http://localhost:3000

yarn start

HomePage

ToDoPage

NotFoundPage

It works!!!

Testing and Debugging

During the development phase of our React app, it is vital to thoroughly test and debug it to ensure proper functionality. React offers robust testing tools such as React Testing Library, Enzyme and Cypress, which empowers us to conduct comprehensive testing. Create unit tests for our components and services to validate their behaviour and identify any potential issues that may arise. By running these tests, we can ensure that our React app functions as intended and maintains the desired level of quality and reliability. The combination of Jest, React Testing Library, and Enzyme is often a popular choice for comprehensive testing in React applications.

Building and Deploying the App

Once we are ready with our ToDo app, it's time to proceed with the build and deployment process. React provides a seamless way to achieve this. Execute the following command in our terminal:

npm run build
This command initiates the build process and generates a production-ready build of our app. The resulting build files can then be deployed to a web server or hosting platform of our preference.

Conclusion

Great job! We have accomplished the task of building and configuring our very own React ToDo app. Throughout the process, we gained valuable insights into creating a new React project, establishing components, integrating functionality, styling the app, and deploying it. This marks the start of our exciting journey with React, and there's a multitude of possibilities and knowledge awaiting us.

Continue to practise and delve into React's extensive ecosystem, as well as leverage the official React documentation for further assistance. Embrace the joy of coding and relish in the convenience of using our newly created ToDo app.

Happy coding!

Code: https://github.com/rohithart/todo-react-ui
API Code: https://github.com/rohithart/nestjs-todo
React Documentation: https://react.dev/learn

Introduction to Angular

Rohith Poyyeri — Sun, 02 Jul 2023 23:33:20 +0000

In this blog post, we will walk you through the step-by-step process of building a ToDo application from scratch. Whether you are new to Angular or just looking for a refresher, this guide will help you get started on your journey to become an Angular developer. This app serves as the User Interface (UI) for the ToDo API, that we have built in my previous blog.

Prerequisites

Before we dive into the development process, let's make sure we have everything we need. Ensure that we have the following installed:

Node.js and npm (Node Package Manager)
Angular CLI (Command Line Interface)

Order of execution

In Angular, understanding the order of execution is essential for developing robust and efficient applications. The following is a brief overview of the typical order of execution in an Angular application.

Bootstrap: Angular starts by bootstrapping the root module of the application. This triggers the initialisation process.

Module Loading: Angular loads the required modules and their dependencies. It traverses the module tree, starting from the root module, and loads each module as needed.

Component Initialisation: Once the modules are loaded, Angular initialises the components defined in the templates. It creates component instances, sets up bindings, and resolves dependencies.

Template Compilation: Angular compiles the component templates to generate the corresponding views. During this process, it combines HTML templates with component logic, transforms directives and bindings, and creates the necessary data structures for rendering.

Change Detection: Angular performs change detection to detect and propagate changes throughout the application. It checks for changes in component properties, bindings, and other data sources, and updates the views accordingly. This ensures that the UI reflects the latest state of the application.

Rendering: After change detection, Angular renders the updated views based on the application state. It updates the DOM with the changes and applies any necessary styling or layout adjustments.

Event Handling and User Interaction: Angular listens for user interactions and handles events triggered by user actions. It responds to user input, executes the corresponding logic, and updates the application state as needed.

Destruction and Cleanup: When a component is no longer needed or gets destroyed, Angular performs cleanup operations. It unsubscribes from event listeners, releases resources, and performs any necessary teardown tasks to prevent memory leaks and ensure efficient resource utilisation.

Understanding the order of execution in Angular helps developers in optimising performance, identifying potential issues, and ensuring smooth application behaviour. It allows for better control over the application lifecycle and facilitates the implementation of complex application logic.

Creating a new Angular project

To kickstart our ToDo app, we'll begin by creating a new Angular project. Open our terminal or command prompt and run the following command:

ng new todo-ui

As we embark on setting up our ToDo app, a few important considerations come to mind. Firstly, we need to determine if routing is required for seamless navigation within our app (and the answer is a resounding "yes!"). Additionally, choosing the appropriate stylesheet format is crucial, and in this case, I recommend utilising SCSS for its flexibility and enhanced capabilities. To kickstart our project, navigate to the new directory called "todo-ui" which will serve as the foundation for our Angular project's basic structure.

Node version

lts/Gallium

Run the following command and might prompt us to install the version if it is missing.
nvm use

Clean up and initial set-up

Remove the static content of app.component.html and add the following.

<app-nav-bar></app-nav-bar>
<div class="app-container">
<router-outlet></router-outlet>
</div>
<app-footer></app-footer>

Now, lets add Flex layout and Angular Material packages to the project.

ng add @angular/material npm install @angular/flex-layout

Let's add FontAwesome and flexboxgrid in the index.html. Add the following in the <head> tag

<link rel="stylesheet" type="text/css" href="https://use.fontawesome.com/releases/v6.2.1/css/all.css" defer/>
 <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/flexboxgrid/6.3.1/flexboxgrid.min.css" defer/>

Environment

The environment.ts and environment.prod.ts files play a crucial role in managing environment-specific configuration settings. The environment.ts file contains configuration variables specific to the development environment, while the environment.prod.ts file contains configuration variables for the production environment.

The environment.ts file is used during development and allows developers to define environment-specific settings such as API endpoints, debug flags, or other variables that are required during the development and testing phases. These variables can be easily accessed throughout the application using the Angular environment service.

On the other hand, the environment.prod.ts file is used for the production build of the application. It contains configuration variables optimised for the production environment, such as production API endpoints, analytics keys, or any other settings that differ from the development environment. These variables are used when the application is built for deployment to ensure proper functionality and performance in the production environment.

By maintaining separate environment files, developers can easily switch between different environments and ensure that the application behaves correctly in each environment. It allows for seamless deployment and configuration management, as the appropriate environment file is automatically selected based on the build target.

Please do keep in mind not to add any secrets/passwords in these environment files.

Connecting to backend API

When connecting to the todo-api that we built earlier, which is running on port 3000, we can encounter Cross-Origin Resource Sharing (CORS) issues due to browser security restrictions. To overcome this, we can utilise a proxy configuration in our Angular project.

The proxy configuration allows us to forward requests from our Angular application to the todo-api server, avoiding the CORS restrictions imposed by the browser. By configuring the proxy, we can send requests to the desired API endpoint without encountering any CORS-related errors.

To set up the proxy, we need to create a file named "proxy.conf.json" in the src directory of our Angular project. Inside this file, we define the proxy configuration by specifying the target URL, which in our case is "http://localhost:3000".

{
 "/api/*": {
  "target": "http://localhost:3000",
  "secure": false,
  "logLevel": "debug"
 }
}

Once the proxy configuration file is set up, we need to modify the "angular.json" file in our project's root directory. Under the "architect" section, we locate the "serve" options for our project, and inside that, we add the "proxyConfig" property, pointing to the "proxy.conf.json" file we created earlier.

"serve": {
 "options": {
  "browserTarget": "todo-ui:build",
  "proxyConfig": "src/proxy.conf.json"
 },
 ...
},

By configuring the proxy, our Angular application will send API requests to the specified target URL (todo-api running on port 3000) without encountering CORS issues. This enables seamless communication between our frontend and backend, allowing us to retrieve and manipulate data from the todo-api server within our Angular application.

Modules

Modules in Angular play a crucial role in organising and structuring our application. They act as containers that group related components, services, directives, and other resources together. Modules provide a way to manage the complexity of larger applications by breaking them down into smaller, more manageable parts.

Angular modules serve several purposes. They facilitate component encapsulation and provide a clear boundary for component dependencies. This promotes modularity, reusability, and maintainability. Modules also enable lazy loading, allowing us to load specific parts of our application only when needed, optimising performance.

In addition to organising our code, modules define the context in which components and services are created and used. They handle dependency injection, allowing components to access the required services and dependencies.

Angular provides different types of modules, including the root module (AppModule) and feature modules that focus on specific parts of our application. We can also create shared modules to encapsulate commonly used components, directives, and pipes, promoting code reuse across different parts of the application.

By leveraging modules effectively, we can build scalable, maintainable Angular applications with clear separation of concerns, better code organisation, and improved developer productivity.

In this project, we have followed some best practices to ensure modular abstraction and maintainability:

Shared Modules: We have created a Shared Module to gather all the shared components, directives, and pipes that are commonly used across different modules. This promotes reusability and reduces code duplication.
Material Module: To streamline the usage of Angular Material components, we have created a dedicated Material Module. Here, we import and configure all the necessary material modules to keep them isolated and easily manageable.
Feature Modules: Major components such as TodoModule have their own dedicated modules. This encapsulation ensures better separation of concerns and modularity. Each feature module contains the components, services, and other resources specific to that particular feature.
AppModule: Finally, in our AppModule, we import all the necessary modules, including the Shared Module, Material Module, and feature modules. This centralises the module imports and allows the components and services from different modules to interact seamlessly.

By adhering to these norms, we promote code organisation, reusability, and maintainability, making our project more scalable and easier to maintain in the long run.

Component and its lifecycle

In Angular components, the order of code execution follows a predefined sequence to ensure proper initialisation and functionality. Here is an overview of the typical order of execution within an Angular component:

Constructor: The component's constructor is the first code block that executes when an instance of the component is created. It is used for dependency injection and initialising local variables. However, it is important to note that the constructor should not be used for complex logic or data manipulation.

ngOnChanges: If the component has input properties bound to its template, the ngOnChanges lifecycle hook is triggered whenever the input values change. This hook allows us to respond to changes and perform actions based on the updated input values.

ngOnInit: The ngOnInit lifecycle hook is called after the constructor and ngOnChanges. It is commonly used for initialisation tasks that require the component to be fully set up. This is a good place to fetch data from a service, set default values, or perform other setup operations.

ngDoCheck: The ngDoCheck lifecycle hook is invoked during every change detection cycle. It allows us to implement custom change detection logic and perform actions based on changes detected in the component's state.

ngAfterContentInit: This lifecycle hook is called after the component's content, such as projected content or child components, has been initialised. It is useful for accessing and manipulating the component's content.

ngAfterViewInit: The ngAfterViewInit hook is triggered after the component's view and child views have been initialised. It is commonly used for interacting with the DOM or performing operations that require the view to be fully rendered.

ngOnDestroy: The ngOnDestroy lifecycle hook is called just before a component is destroyed. It provides an opportunity to perform any necessary cleanup tasks, such as unsubscribing from observables, releasing resources, or cancelling timers.

By following this order of execution, Angular ensures that components are properly initialised, their dependencies are resolved, and their lifecycle hooks are triggered at the appropriate times. Understanding this order allows developers to organise their code effectively and ensure that components function as intended throughout their lifecycle.

Shared Components

Let us create a set of shared components that promote component reusability and maintain consistency throughout the application. These shared components reside in the 'src/app/shared/components' directory and are imported and exported from the SharedModule.

NavBarComponent serves as the navigation bar of the application, providing users with easy access to different sections or pages of the app. It typically contains menus, links, or buttons for navigation purposes.

FooterComponent is responsible for displaying a footer at the bottom of the application, providing additional information, copyright notices, or links to relevant pages.

HeadingComponent is a reusable component used to display a heading or title for each page. It helps to maintain consistent styling and structure across different pages of the application.

EmptyComponent is designed to be displayed when a list or data set is empty. It provides a message or placeholder content to inform users that there is no data available.

LoadingComponent is used to show a loading spinner or animation while the application is fetching data or performing asynchronous operations. It provides visual feedback to the users, indicating that the app is working in the background.

TextModalComponent is a dialog or modal component used to add or input data in the application. It typically includes form fields, buttons, and validation to gather user input and save it to the system.

By extracting and centralising these components in the SharedModule, we can easily import and use them in various other modules and components without duplicating code. Please do find the full code of these components in github.

Other Components

Now let’s create the other components that we are after. We can make use of the Angular CLI commands for that, which is really handy.

ng g c components/home ng g c components/not-found

This will generate the necessary files for our component, including the HTML template, SCSS styles, and TypeScript code. We need to add these components into the declaration section of AppModule.

The HomeComponent serves as the welcome or homepage of our application, acting as the landing page that users first encounter when accessing our site. It provides an overview of our app's features, highlights, or any relevant information we want to showcase to users right from the start. This component is designed to provide a visually appealing and engaging user experience, making a positive first impression.

On the other hand, the NotFoundComponent plays a crucial role as a fallback page. Whenever users navigate to a route that doesn't exist or provide an incorrect route, they will be redirected to the NotFoundComponent. This component serves as an error page, informing users that the requested page or resource cannot be found. It helps to improve the user experience by gracefully handling such scenarios and providing a clear message to users about the issue encountered.

Elephant in the room, ToDo

ToDo Modal
Let us create a new modal, Todo.ts.

export interface Todo {
 _id: string;
 description: string;
 is_active: boolean;
 updatedAt: string;
}

ToDo Service
The TodoService is a crucial component in the ToDo application, responsible for handling the data management and communication with the backend API. It encapsulates the logic and functionality related to retrieving, updating, deleting, and adding new ToDo items.

It includes the following functions: getAllToDos (retrieve all ToDo items), update (modify and update a ToDo item), delete (remove a ToDo item), and addNewTodo (create and add a new ToDo item). These functions handle the necessary HTTP requests.

By utilising the TodoService and its functions, the application can interact with the backend server effectively, ensuring seamless data management and synchronisation between the client-side and server-side components.
ToDo Component
Let's create a new ToDo component.

ng g c components/todo

As mentioned previously, this will create all the associated components.

Let us design this component so that this consists of two tabs: one for displaying active ToDos and another for inactive ToDos. The component utilises Angular Material's TabGroup component to handle the tab switching functionality.

Within each tab, we incorporate a loading spinner using Angular Material's ProgressSpinner component. This spinner is displayed while the application is fetching data from the server, providing a visual indicator of the loading process.

To handle the case when the ToDo list is empty, we employ the EmptyComponent. This component is shown within the corresponding tab when there are no ToDos to display. It provides a clear message to the user that the list is empty, enhancing the user experience.
ToDo Card Component
In addition to the TodoComponent, we will create a TodoCardComponent to enhance the visual representation of each ToDo item.

ng g c components/todo/todo-card

The TodoCardComponent is responsible for displaying individual ToDos as aesthetically pleasing card designs.
ToDo Module
To maintain a modular and organised structure for our ToDo components, it is advisable to create a dedicated ToDo module. The ToDo module will be responsible for declaring and encapsulating all the related ToDo components, providing a clear separation of concerns and promoting reusability.

By creating a ToDo module, we can easily manage the dependencies and interactions between different ToDo components. This module acts as a container that groups together all the necessary components, services, and other related entities specific to ToDo functionality.

The ToDo module also enables us to take advantage of Angular's dependency injection system. We can provide services and other dependencies within the module, allowing components to access and utilise them seamlessly.

While it may seem like overkill in the initial stages of the application, adopting this modular approach early on lays the foundation for scalability and maintainability. As the application grows and more features are added, having a dedicated module for ToDo components ensures a clean and organised codebase, making it easier to manage and extend the application in the future.

import { NgModule } from '@angular/core';

import { SharedModule } from 'src/app/shared/modules/shared.module';
import { TodoComponent } from './todo.component';
import { TodoCardComponent } from './todo-card/todo-card.component';

@NgModule({
 declarations: [TodoComponent, TodoCardComponent],
 imports: [SharedModule],
 exports: [TodoComponent]
})
export class TodoModule {
}

ToDo Style
To make our ToDo app visually appealing, we can apply custom styles using CSS. Modify the generated CSS file (todo.component.scss and todo-card.component.scss) to match our desired design.

Style

In our project, we've taken care of incorporating various essential dependencies and resources to enhance the overall design and functionality. FontAwesome and FlexBoxGrid have been integrated, providing access to a wide range of icons and a responsive grid system respectively. We've also seamlessly integrated Angular Material, empowering us to utilise the vast collection of Material design components to enhance the visual appeal and user experience. Additionally, we've implemented custom styles, colours, and functions to further refine the app's aesthetics and extend its capabilities. Feel free to explore the source code for a closer look at these enhancements.

Angular Material

Angular Material is a valuable tool that saves us from reinventing the wheel by providing a comprehensive library of pre-built Material design components. To streamline the usage of these components, we have created a dedicated Material Module where all the necessary material modules are imported and configured. By injecting this Material Module into our AppModule, we ensure that the Material components are readily available throughout our application, simplifying the development process and maintaining consistency in the UI design. This approach allows us to harness the power of Angular Material and leverage its extensive range of components without the need for manual implementation from scratch.

Routing

To enhance the navigation of our project, let's incorporate routes with the following configuration:
Assign the empty routes to the Home page, providing users with a welcoming starting point.
Direct the todo routes to the Todo page, enabling seamless task management and organisation.
Map the 404 routes to an Error Page, ensuring a user-friendly experience when encountering unexpected routes.
For any other routes that don't match the defined paths, gracefully redirect users to the Error Page, maintaining a consistent flow throughout the app.

const routes: Routes = [
{ path: '', component: HomeComponent, pathMatch: 'full' },
{ path: AppConfig.routes.todo, component: TodoComponent, pathMatch: 'full' },
{ path: AppConfig.routes.error404, component: NotFoundComponent },
{ path: '**', redirectTo: '/' + AppConfig.routes.error404 }
];

Running the app

Let’s us run the app and have a look at it spinning up at http://localhost:4200

yarn start

HomePage

ToDoPage

NotFoundPage

It works!!!

Testing and Debugging

Throughout the development process, it's crucial to test and debug our app to ensure it functions as intended. Angular provides powerful testing tools like Karma and Jasmine. Write unit tests for our components and services to verify their behaviour and catch any potential issues.
Building and Deploying the App
Once we are satisfied with our ToDo app, it's time to build and deploy it. Angular CLI makes this process straightforward. Run the following command:

ng build --prod

This will generate a production-ready build of our app, which can be deployed to a web server or hosting platform of our choice.

Conclusion

Congratulations! We have successfully built and set up our own Angular ToDo app. We have learned how to create a new Angular project, set up components, implement functionality, style the app, and deploy it. This is just the beginning of our Angular journey, and there's much more to explore and learn.

Remember to keep practising, exploring Angular's vast ecosystem, and referring to the official Angular documentation for additional guidance. Happy coding and enjoy using the new ToDo app!

Happy coding!

Code: https://github.com/rohithart/todo-ui
API Code: https://github.com/rohithart/nestjs-todo
Angular Documentation: https://angular.io/docs

NestJS – Data persistence with MongoDB

Rohith Poyyeri — Wed, 21 Jun 2023 23:09:47 +0000

Introduction

NestJS seamlessly integrates with MongoDB, a popular NoSQL database known for its flexibility and scalability. This combination empowers developers to efficiently store and retrieve data, ensuring robust and reliable data persistence for their applications.

With NestJS and MongoDB, developers can leverage the benefits of a document-based database that allows for dynamic and schema-less data storage. MongoDB's flexible nature makes it well-suited for applications that handle unstructured or evolving data, offering the freedom to store and query data without the constraints of traditional relational databases. Leveraging the power of TypeScript, NestJS enables developers to define models, schemas, and repositories, providing a solid foundation for working with MongoDB collections.

Whether you're building a simple REST API or a complex enterprise-grade application, NestJS and MongoDB make data persistence a breeze. You can effortlessly create, read, update, and delete documents, perform advanced queries, and apply various data manipulation operations using MongoDB's rich query language.

In this blog post, we will delve into the fundamentals of data persistence with NestJS and MongoDB. Building upon the previous article on setting up a NestJS application, we will explore how to implement MongoDB and cover essential topics including establishing a MongoDB connection, defining models and schemas, executing CRUD operations, and querying data. By combining our knowledge of NestJS with MongoDB integration, we will unlock the power of data persistence in this API-driven environment.

Configuration

To configure the tests, let’s start by installing some dependencies.

npm install @nestjs/mongoose mongoose npm install @nestjs/config

Create an environment file. This is where environment variables can be placed locally. These values can then be injected into the pipeline for the production environment.

.env

MONGO_DB_URL=mongodb://127.0.0.1:27017

Let’s update the app.module to include Mongoose and ConfigModule. ConfigModule is for us to access the environment variable.

app.module.ts

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { MongooseModule } from '@nestjs/mongoose';
import { TodoModule } from './modules/todo/todo.module';

@Module({
 imports: [
   ConfigModule.forRoot(),
   MongooseModule.forRoot(process.env.MONGO_DB_URL),
   TodoModule,
 ],
 controllers: [],
 providers: [],
})
export class AppModule {}

Model

Let’s start by updating the existing ToDo model.

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { HydratedDocument } from 'mongoose';

export type ToDoDocument = HydratedDocument<ToDo>;

@Schema({ timestamps: true })
export class ToDo {
 @Prop({ required: true })
 description: string;

 @Prop({ default: true })
 is_active: boolean;
}

export const ToDoSchema = SchemaFactory.createForClass(ToDo);

We have removed a couple of fields here. id and created_at have been removed as the _id is added and updated automatically, and @Schema({ timestamps: true }) will create the timestamps for us out of the box.

Module

Now, it's time to create a dedicated module for MongoDB. This module will serve as a centralised hub where we can inject and export all the features provided by MongooseModule, essentially representing our database tables. Once the MongoModule is set up, we can easily inject it into any other modules that require access to the Mongo tables. This modular approach ensures efficient organisation and seamless integration of MongoDB across our application. There might be scenarios where we might have multiple databases and this modular approach can help create a good level of abstraction.

mongo.module.ts

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';

import { ToDo, ToDoSchema } from 'src/models/ToDo';

@Module({
 imports: [
   MongooseModule.forFeature([{ name: ToDo.name, schema: ToDoSchema }]),
 ],
 exports: [
   MongooseModule.forFeature([{ name: ToDo.name, schema: ToDoSchema }]),
 ],
})
export class MongoModule {}

Let’s inject MongoModule in the ToDoModule.

todo.module.ts

import { Module } from '@nestjs/common';
import { MongoModule } from 'src/shared/mongo.module';
import { TodoController } from './todo.controller';
import { TodoService } from './todo.service';

@Module({
 imports: [MongoModule],
 controllers: [TodoController],
 providers: [TodoService],
})
export class TodoModule {}

Service

Firstly, we have to nuke the database.service.ts as we don’t need this anymore. We have to now update the todo.service.ts to replace DatabaseService with MongoModel.

todo.service.ts

import { Injectable } from '@nestjs/common';
import { InjectModel } from '@nestjs/mongoose';
import { Model } from 'mongoose';

import { ToDo, ToDoDocument } from 'src/models/ToDo';

@Injectable()
export class TodoService {
 constructor(@InjectModel(ToDo.name) private todoModel: Model<ToDoDocument>) {}

 getAll(): Promise<ToDo[]> {
   return this.todoModel.find().exec();
 }

 get(id: string): Promise<ToDo> {
   return this.todoModel.findOne({ _id: id }).exec();
 }

 create(todo: ToDo): Promise<ToDo> {
   const newToDo = new this.todoModel(todo);
   return newToDo.save();
 }

 update(id: string, body: unknown): Promise<ToDo> {
   return this.todoModel
     .findOneAndUpdate({ _id: id }, body, { new: true })
     .exec();
 }

 delete(id: string): Promise<unknown> {
   return this.todoModel
     .findOneAndRemove({
       _id: id,
     })
     .exec();
 }

 // we can remove this and use the existing update function itself.
 markAsInActive(id: string): Promise<ToDo> {
   return this.todoModel
     .findOneAndUpdate(
       { _id: id },
       { $set: { is_active: true } },
       { new: true },
     )
     .exec();
 }
}

Controller

There are minor changes to the controller as well. Let’s update the controller.

todo.controller.ts

import { Body, Controller, Delete, Get, Param, Post, Put } from '@nestjs/common';
import { ApiBody, ApiParam, ApiTags } from '@nestjs/swagger';

import { ToDo } from 'src/models/ToDo';
import { TodoService } from './todo.service';

@ApiTags('ToDo')
@Controller('todo')
export class TodoController {
 constructor(private readonly todoService: TodoService) {}

 @Get(':id')
 @ApiParam({ name: 'id', required: true })
 get(@Param() params: { id: string }): Promise<ToDo> {
   return this.todoService.get(params.id);
 }

 @Get()
 getAll(): Promise<ToDo[]> {
   return this.todoService.getAll();
 }

 @Post()
 @ApiBody({})
 create(@Body() body: ToDo): Promise<ToDo> {
   return this.todoService.create(body);
 }

 @Put(':id')
 @ApiParam({ name: 'id', required: true })
 @ApiBody({})
 update(@Param() params: { id: string }, @Body() body: any): Promise<ToDo> {
   return this.todoService.update(params.id, body);
 }

 @Put('inactive/:id')
 @ApiParam({ name: 'id', required: true })
 markAsInActive(@Param() params: { id: string }): Promise<ToDo> {
   return this.todoService.markAsInActive(params.id);
 }

 @Delete(':id')
 @ApiParam({ name: 'id', required: true })
 delete(@Param() params: { id: string }): Promise<unknown> {
   return this.todoService.delete(params.id);
 }
}

Let’s Swagger this

Let’s start by running the application locally using yarn start.

Now let us use the POST endpoint to create a new todo.

We can see that the request came back with a HTTP 201 along with the data and let’s use the _id here to fetch the data.

It worked!

MongoDB Account

Now that we have successfully integrated MongoDB into our application, deploying it is a breeze. All you need to do is inject the MONGO_DB_URL into your production pipeline. By creating a free account on MongoDB, you can obtain the public URL required for deployment. With this in place, our API is ready to be deployed to production with ease.

Conclusion

In conclusion, NestJS and MongoDB provide a powerful combination for data persistence in your NestJS applications. With NestJS's robust framework and MongoDB's flexible NoSQL database, you can store, retrieve, and manipulate data with ease.

Throughout this blog, we have explored the essentials of integrating NestJS with MongoDB. We have learned how to establish a connection to the MongoDB database, define models and schemas, and perform various CRUD operations. We have also delved into querying data, handling relationships, and implementing data validation and business logic.

Now that you have a solid understanding of NestJS - Data persistence with MongoDB, you can confidently embark on your journey to build scalable, efficient, and maintainable applications.

MongoBD: https://www.mongodb.com/
Code: https://github.com/rohithart/nestjs-todo
NestJS Documentation: https://docs.nestjs.com/

NestJS - Unit and E2E testing

Rohith Poyyeri — Wed, 08 Mar 2023 22:03:45 +0000

Testing is a fundamental aspect of development that helps build trust in the code and ensures it can handle various scenarios. It also serves as an early warning system when changes are made to the code. If a test fails, it indicates that an unintended change has occurred, which either requires fixing the code or updating the test.

In this post, we take a look at implementing testing in a NestJS application which was set up previously in this post - NestJS – Supercharging Node.js Applications. Now that we have a basic understanding of NestJS, this post will explore how to test the API.

Test Types

There are three main recommendations for testing:
Unit testing
End-to-end (E2E) testing
SuperTest

Unit testing
It is best for a JavaScript function to be kept short, ideally with no more than three lines of code. However, this can be difficult to adhere to. Unit testing involves testing a function on its own, to ensure it is isolated and functioning properly. This allows for thorough testing of each part of the code, independently, and without interference from other functions or services. It is highly recommended to have as many tests as possible, as there is no such thing as too many tests.

E2E testing
As mentioned in my first blog, NestJS has a designated entry point module. In the example provided, the TodoModule was the entry point, responsible for setting up routes, injecting controllers, and services. End-to-end (E2E) testing can be used to verify the functionality of this module. The test bed injects the TodoModule and sets up routes, controllers, and services. By testing the module end-to-end, we can ensure that it works as intended throughout the entire process.

Supertest
We need a solution that can test the API regardless of the framework it is built on. The API can be built using NodeJS, NestJS, or any other framework. Supertest provides a framework-agnostic testing suite that allows for end-to-end testing of the API.

Configuration

To configure the tests, let us start by installing some dependencies.
$ yarn add supertest jest-sonar jest-junit @jest-performance-reporter/core --save-dev

Now, let’s set up an initial base configuration.

jest.config.js
This is the base configuration for all the tests.

module.exports = {
 testEnvironment: 'node',
 preset: 'ts-jest',
 rootDir: './',
 modulePaths: ['<rootDir>'],
 moduleNameMapper: {
   '^src$': '<rootDir>/src',
   '^src/(.+)$': '<rootDir>/src/$1',
 },
 modulePathIgnorePatterns: ['src/typings'],
 testPathIgnorePatterns: [
   '/node_modules./',
   '<rootDir>/(coverage|dist|lib|tmp)./',
 ],
};

jest.unit.js
This is the configuration for unit tests, which inherits the base configuration. The coverage has been set to low for the time being. Ideally, this has to be above 80.

const sharedConfig = require('./jest.config');

module.exports = {
 ...sharedConfig,
 coverageDirectory: 'coverage',
 coverageReporters: ['text', 'lcov', 'cobertura'],
 collectCoverageFrom: [
   'src/**/*.ts',
   '!*/node_modules/**',
   '!<rootDir>/src/main.ts',
   '!<rootDir>/src/modules/database/database.service.ts',
 ],
 reporters: [
   'default',
   'jest-sonar',
   [
     'jest-junit',
     {
       outputDirectory: 'junit',
       outputName: 'test-results.xml',
     },
   ],
   [
     '@jest-performance-reporter/core',
     {
       errorAfterMs: 1000,
       warnAfterMs: 500,
       logLevel: 'warn',
       maxItems: 5,
       jsonReportPath: 'performance-report.json',
       csvReportPath: 'performance-report.csv',
     },
   ],
 ],
 coverageThreshold: {
   global: {
     branches: 10,
     functions: 10,
     lines: 10,
     statements: 10,
   },
 },
};

jest.e2e.js
This is the configuration for E2E tests, which inherits the base configuration.

const sharedConfig = require('./jest.config');

module.exports = {
 ...sharedConfig,
 moduleFileExtensions: ['js', 'json', 'ts'],
 testRegex: '.e2e-spec.ts$',
 transform: {
   '^.+\\.(t|j)s$': 'ts-jest',
 },
};

jest.supertest.js
This is the configuration for supertest tests, which inherits the base configuration.

const sharedConfig = require('./jest.config');

module.exports = {
 ...sharedConfig,
 moduleFileExtensions: ['js', 'json', 'ts'],
 testRegex: '.supertest-spec.ts$',
 transform: {
   '^.+\\.(t|j)s$': 'ts-jest',
 },
};

Now that we have all the configurations in place, we need to update our scripts in package.json. All/update the following scripts.

   "test": "jest --config ./jest.unit.js",
   "test:cov": "yarn test --coverage",
   "test:e2e": "jest --config ./jest.e2e.js",
   "test:supertest": "jest --config ./jest.supertest.js"

Testing

Now let’s look at our previous sample code repo and get our hands dirty with some testing. Before we start, let us mock the database service. We will look into implementing MongoDB as a separate blog.

import { Injectable } from '@nestjs/common';
import { ToDo } from 'src/models/ToDo';

@Injectable()
export class DataBaseService {
 data: ToDo[] = [
   {
     id: '1',
     description: 'Cook pasta',
     is_active: true,
     created_at: new Date(),
   },
   {
     id: '2',
     description: 'Do laundry',
     is_active: true,
     created_at: new Date(),
   },
   {
     id: '3',
     description: 'Clean kitchen',
     is_active: false,
     created_at: new Date(),
   },
 ];

 getAll(): Promise<ToDo[]> {
   return Promise.resolve(this.data);
 }

 get(id: string): Promise<ToDo> {
   return Promise.resolve(this.data.filter((t) => t.id === id)[0]);
 }

 create(todo: ToDo): Promise<ToDo> {
   this.data.push(todo);
   return Promise.resolve(todo);
 }

 update(todo: ToDo): Promise<ToDo> {
   const dataIndex = this.data.findIndex((t) => t.id === todo.id);
   this.data[dataIndex] = todo;
   return Promise.resolve(this.data[dataIndex]);
 }

 delete(id: string): Promise<boolean> {
   this.data = this.data.filter((t) => t.id !== id);
   return Promise.resolve(true);
 }
}

Unit testing
Before we start, let us run the tests and coverage so we can compare the before and after results.

$ yarn test:cov

Let us start by adding unit tests to the controller, service and module.

Unit testing service
This is an example of what unit tests for a service may look like. Although it may appear extensive for a small service, it has several benefits. Each function is tested individually and, in the event of a failure, the test can pinpoint the specific point of failure. The use of "describe" blocks isolates each test, providing a level of abstraction and assurance they are not affected by other neighbouring tests.

import { Test, TestingModule } from '@nestjs/testing';
import { ToDo } from 'src/models/ToDo';
import { DataBaseService } from 'src/modules/database/database.service';
import { TodoModule } from './todo.module';
import { TodoService } from './todo.service';

describe('TodoService', () => {
 let service: TodoService;

 const mockDataBaseService = {
   getAll: jest.fn(),
   get: jest.fn(),
   create: jest.fn(),
   update: jest.fn(),
   delete: jest.fn(),
 };

 beforeEach(async () => {
   const module: TestingModule = await Test.createTestingModule({
     imports: [TodoModule],
   })
     .overrideProvider(DataBaseService)
     .useValue(mockDataBaseService)
     .compile();

   service = module.get<TodoService>(TodoService);
 });

 it('should have the service defined', () => {
   expect(service).toBeDefined();
 });

 describe('#getAll', () => {
   beforeEach(() => {
     jest.spyOn(mockDataBaseService, 'getAll');
   });

   it('should be defined', () => {
     expect(service.getAll).toBeDefined();
   });

   it('should call the database', () => {
     service.getAll();
     expect(mockDataBaseService.getAll).toBeCalledTimes(1);
   });
 });

 describe('#get', () => {
   beforeEach(() => {
     jest.spyOn(mockDataBaseService, 'get');
   });

   it('should be defined', () => {
     expect(service.get).toBeDefined();
   });

   it('should call the database', () => {
     service.get('1');
     expect(mockDataBaseService.get).toBeCalledTimes(1);
   });
 });

 describe('#create', () => {
   beforeEach(() => {
     jest.spyOn(mockDataBaseService, 'create');
   });

   it('should be defined', () => {
     expect(service.create).toBeDefined();
   });

   it('should call the database', () => {
     service.create({} as ToDo);
     expect(mockDataBaseService.create).toBeCalledTimes(1);
   });
 });

 describe('#update', () => {
   beforeEach(() => {
     jest.spyOn(mockDataBaseService, 'update');
   });

   it('should be defined', () => {
     expect(service.update).toBeDefined();
   });

   it('should call the database', () => {
     service.update({} as ToDo);
     expect(mockDataBaseService.update).toBeCalledTimes(1);
   });
 });

 describe('#delete', () => {
   beforeEach(() => {
     jest.spyOn(mockDataBaseService, 'delete');
   });

   it('should be defined', () => {
     expect(service.delete).toBeDefined();
   });

   it('should call the database', () => {
     service.delete('1');
     expect(mockDataBaseService.delete).toBeCalledTimes(1);
   });
 });

 describe('#markAsInActive', () => {
   beforeEach(() => {
     jest.spyOn(mockDataBaseService, 'get');
     jest.spyOn(mockDataBaseService, 'update');
   });

   it('should be defined', () => {
     expect(service.markAsInActive).toBeDefined();
   });

   describe('when inactive is called', () => {
     it('should call the databaseService.get', () => {
       expect(mockDataBaseService.get).toBeCalledTimes(1);
     });

     it('should call the databaseService.update', () => {
       expect(mockDataBaseService.update).toBeCalledTimes(1);
     });
   });
 });
});

Unit testing controller
Unit tests for controllers are similar to a service. Let us have a closer look at the get function, specifically.

get(@Param() params: { id: string }): Promise<ToDo> {
   return this.todoService.get(params.id);
 }

This function is responsible for reading the id from params, and invoking and returning the get function from service. So in our unit test, we test exactly the same. We are making sure when this function in the controller is being invoked, the relevant function in service is being called once.

import { Test, TestingModule } from '@nestjs/testing';
import { ToDo } from 'src/models/ToDo';
import { TodoController } from './todo.controller';
import { TodoService } from './todo.service';

describe('TodoController', () => {
 let controller: TodoController;
 let service: TodoService;

 const mockTodoService = {
   getAll: jest.fn(),
   get: jest.fn(),
   create: jest.fn(),
   update: jest.fn(),
   delete: jest.fn(),
   markAsInActive: jest.fn(),
 };

 beforeEach(async () => {
   const module: TestingModule = await Test.createTestingModule({
     providers: [TodoService],
     controllers: [TodoController],
   })
     .overrideProvider(TodoService)
     .useValue(mockTodoService)
     .compile();

   controller = module.get<TodoController>(TodoController);
   service = module.get<TodoService>(TodoService);
 });

 it('should be defined', () => {
   expect(controller).toBeDefined();
 });

 describe('#getAll', () => {
   beforeEach(() => {
     jest.spyOn(service, 'getAll');
   });

   it('should be defined', () => {
     expect(service.getAll).toBeDefined();
   });

   it('should call service.getAll', () => {
     controller.getAll();
     expect(service.getAll).toBeCalledTimes(1);
   });
 });

 describe('#get', () => {
   beforeEach(() => {
     jest.spyOn(service, 'get');
   });

   it('should be defined', () => {
     expect(service.get).toBeDefined();
   });

   it('should call service.get', () => {
     controller.get({ id: '1' });
     expect(service.get).toBeCalledTimes(1);
   });
 });

 describe('#create', () => {
   beforeEach(() => {
     jest.spyOn(service, 'create');
   });

   it('should be defined', () => {
     expect(service.create).toBeDefined();
   });

   it('should call service.create', () => {
     controller.create({} as ToDo);
     expect(service.create).toBeCalledTimes(1);
   });
 });

 describe('#update', () => {
   beforeEach(() => {
     jest.spyOn(service, 'update');
   });

   it('should be defined', () => {
     expect(service.update).toBeDefined();
   });

   it('should call service.update', () => {
     controller.update({} as ToDo);
     expect(service.update).toBeCalledTimes(1);
   });
 });

 describe('#delete', () => {
   beforeEach(() => {
     jest.spyOn(service, 'delete');
   });

   it('should be defined', () => {
     expect(service.delete).toBeDefined();
   });

   it('should call service.delete', () => {
     controller.delete({ id: '1' });
     expect(service.delete).toBeCalledTimes(1);
   });
 });

 describe('#markAsInActive', () => {
   beforeEach(() => {
     jest.spyOn(service, 'markAsInActive');
   });

   it('should be defined', () => {
     expect(service.markAsInActive).toBeDefined();
   });

   it('should call service.markAsInActive', () => {
     controller.markAsInActive({ id: '1' });
     expect(service.markAsInActive).toBeCalledTimes(1);
   });
 });
});

Unit testing module
Unit testing modules are comparatively easier. The responsibility of this test is to make sure that the relevant controllers and services are injected.

import { Test, TestingModule } from '@nestjs/testing';

import { TodoController } from './Todo.controller';
import { TodoModule } from './Todo.module';
import { TodoService } from './Todo.service';

describe('TodoModule', () => {
 let module: TestingModule;

 beforeAll(async () => {
   module = await Test.createTestingModule({
     imports: [TodoModule],
   }).compile();
 });

 it('should compile the module', async () => {
   expect(module).toBeDefined();
 });

 it('should have Todo components', async () => {
   expect(module.get(TodoController)).toBeInstanceOf(TodoController);
   expect(module.get(TodoService)).toBeInstanceOf(TodoService);
 });
});

Now that we are finished with unit testing, let us run the coverage and compare the results. We can see that the coverage for statements, branches, functions and lines have increased significantly. We can talk a bit more about the coverage and jest setting at the end.

This coverage report shows us a clear picture of the coverage of tests on each file. The most important column is that labelled ‘Uncovered Lines’. You’ll see that, for example, todo.service.ts has uncovered lines of code from 32 to 34. We now have to write unit tests to make sure those lines are also covered. In certain scenarios, it might not be possible to get 100% coverage. The goal is to get maximum coverage, and 80% or higher is considered good. If we can achieve 90% or more, we have a very confident test suite. However, it’s worth noting that we should not achieve these results by excluding files in the config.

E2E testing

NestJS E2E testing involves testing the application end-to-end, starting from main.ts all the way to service. This is an easy way to test whether all the components are wired up correctly. This ensures the modules and its injections are in order, all the dependency injections are correct in controller and service, and confirms the routing is done as expected.

E2E testing Todo Module
E2E tests are written for each module. We have to make sure that we hit all the controller endpoints, which are technically all the routes configured through a module. So, now we are going to test the Todo Module end-to-end. We will be mocking the DatabaseService for the time being. Similar to the NestJS functions, we don’t need to test the database, as it is implied it works as expected.

import { INestApplication } from '@nestjs/common';
import { Test, TestingModule } from '@nestjs/testing';
import * as request from 'supertest';

import { TodoService } from 'src/modules/todo/todo.service';
import { AppModule } from 'src/app.module';

describe('TodoModule', () => {
 let app: INestApplication;

 const mockTodoService = {
   getAll: jest.fn(),
   get: jest.fn(),
   create: jest.fn(),
   update: jest.fn(),
   delete: jest.fn(),
   markAsInActive: jest.fn(),
 };

 beforeEach(async () => {
   const moduleFixture: TestingModule = await Test.createTestingModule({
     imports: [AppModule],
   })
     .overrideProvider(TodoService)
     .useValue(mockTodoService)
     .compile();

   app = moduleFixture.createNestApplication();
   await app.init();
 });

 afterEach(() => {
   jest.clearAllMocks();
 });

 describe('GET: todo/:id', () => {
   beforeEach(() => {
     jest.spyOn(mockTodoService, 'get');
   });

   it('should return OK', async () => {
     await request(app.getHttpServer()).get('/todo/1').expect(200, {});
   });
 });

 describe('GET: todo/all', () => {
   beforeEach(() => {
     jest.spyOn(mockTodoService, 'getAll');
   });

   it('should return OK', async () => {
     await request(app.getHttpServer()).get('/todo/all').expect(200, {});
   });
 });

 describe('POST: todo', () => {
   beforeEach(() => {
     jest.spyOn(mockTodoService, 'create');
   });

   it('should return OK', async () => {
     await request(app.getHttpServer()).post('/todo').expect(201, {});
   });
 });

 describe('PUT: todo', () => {
   beforeEach(() => {
     jest.spyOn(mockTodoService, 'update');
   });

   it('should return OK', async () => {
     await request(app.getHttpServer()).put('/todo').expect(200, {});
   });
 });

 describe('PUT: todo/inactive/:id', () => {
   beforeEach(() => {
     jest.spyOn(mockTodoService, 'update');
   });

   it('should return OK', async () => {
     await request(app.getHttpServer())
       .put('/todo/inactive/:id')
       .expect(200, {});
   });
 });

 describe('DELETE: todo/:id', () => {
   beforeEach(() => {
     jest.spyOn(mockTodoService, 'delete');
   });

   it('should return OK', async () => {
     await request(app.getHttpServer()).delete('/todo/:id').expect(200, {});
   });
 });
});

Now we can run the E2E tests.
$ yarn test:e2e

Super test

In the above E2E test set up, we can see that we are injecting the test bed with the modules. The E2E is not agnostic of NestJS and its components. We might have to override the components and services to make sure that the test can pass.

Now we need a test set up that is agnostic of the language or framework we have used. So we will run the application and our test will run against the running application. These tests can also be used to run against different environments. Since this test is framework agnostic, it will come handy if we decide to change the framework, for instance from NestJS to C#. This can also help us avoid regressions as it can be run against multiple environments.

import * as request from 'supertest';

const baseURL = 'http://localhost:3000/';

describe('Todo', () => {
 const apiRequest = request(baseURL);

 describe('GET: todo/:id', () => {
   it('should have the response', async () => {
     const response = await apiRequest.get('todo/1');

     expect(response.status).toBe(200);
   });
 });

 describe('GET: todo/all', () => {
   it('should have the response', async () => {
     const response = await apiRequest.get('todo/all');

     expect(response.status).toBe(200);
   });
 });

 describe('POST: todo', () => {
   it('should have the response', async () => {
     const response = await apiRequest.post('todo').send({});

     expect(response.status).toBe(201);
   });
 });

 describe('PUT: todo', () => {
   it('should have the response', async () => {
     const response = await apiRequest.put('todo').send({});

     expect(response.status).toBe(200);
   });
 });

 describe('PUT: todo/inactive/:id', () => {
   it('should have the response', async () => {
     const response = await apiRequest.put('todo').send({});

     expect(response.status).toBe(200);
   });
 });

 describe('DELETE: todo/:id', () => {
   it('should have the response', async () => {
     const response = await apiRequest.delete('todo/1');

     expect(response.status).toBe(200);
   });
 });
});

Before we run the tests, we have to run the application. This is because this test will be hitting the actual endpoints of the application rather than the code itself. Note that in cases of authenticated endpoints, we might have to pass header or token so that the test can pass.

$ yarn test:supertest

There are a few things to keep an eye on here. Firstly, we are only checking the status of the response, however we can and should also check the response in here, which increases the reliability of the test.

You can also configure a helper which gives you a response to compare against while running on different environments. I have hardcoded the base URL here for the ease of the demo. Ideally, we need the base URL to be read from an environment config file.

Conclusion

Now that we have three sets of tests, we have achieved a higher level of confidence in updating existing implementations and introducing more features. These tests will help us in multiple ways. Firstly, they act like a technical documentation of what the expected behaviour is. Secondly, this will help us in alerting any unwanted bugs or regression that we might have been accidentally introduced. These tests should be added to the CI/CD pipelines so they can run against every change. The supertests can be very handy if we set them to run against all environments, if possible.

In upcoming blogs, we will explore how these tests can become even more helpful when we start to add new features to this existing code base.

Code: https://github.com/rohithart/nestjs-todo/tree/9bd7580e3ac43417cb49184b20919889d3b45bbc
NestJS Documentation: https://docs.nestjs.com/

NestJS - Node.js Application on steroids

Rohith Poyyeri — Tue, 31 Jan 2023 04:00:56 +0000

Introduction

NestJS, a progressive Node.js framework, can be used to build an efficient, scalable, flexible, enterprise-ready NodeJS server-side application, which provides structure and releases APIs directly to the developer. The architecture is heavily inspired by the Angular framework, making it easy for any Angular developers to understand and learn. Behind the scenes, Nest makes use of the robust HTTP server framework, Express, by default. Nest also uses progressive JavaScript that fully supports TypeScript, enabling developers to code in pure JavaScript, and combines elements of object oriented programming (OOP), functional programming (FP), and functional reactive programming (FRP).

In this post, we will explore the architecture of NestJS, and set up a basic API using Typescript including its components, and a landing page using Swagger to gain an overview of all exposed endpoints.

CLI
NestJS has one the most powerful CLI tools. The CLI can be used to create any part of the framework automatically, and develop applications with NestJS without much of the graphical user interface (GUI) interactions. CLI can be used to create modules, controllers and services using command line, and is also consistent with Angular CLI.

Support
NestJS supports many popular tools under the hood like Swagger, TypeORM, Mongoose, GraphQL, Logging, Routing, Validation, Caching, WebSockets, and much more, with little to no configurations. The NestJS website provides very detailed documentation so there’s no need to reinvent the wheel.

Architecture

NestJS has three architecture tiers, which are:

Controller - Handles the routing.
Service - Handles the business logic.
Data access layer - Handles the access of data from the data source.

The order of execution gives developers access to more functionality and application control, allowing them to implement some complex logics such as authentication, error handling, logging and validation, without writing custom logic.

This order of execution is an important consideration, as it will allow us to implement some solutions and business logic higher up the ladder, rather than in the service itself.

Middleware
A middleware is a function that is executed before the route handler, which has access to the request, the response, and the next function. It can be used to change a request and response object, and end a request response cycle. For instance, if we needed to validate the auth token in the request header, we can use a middleware to read and validate the token.

Guard
Guards are a single responsibility class which, as the name suggests, is responsible for guarding the routes. The guards are responsible for confirming the request has the required permissions, role or ACL to access the route. Developers can use this alongside authentication in use cases such as role-based access.

Interceptor
Interceptors are functions that can bind extra functionality before and after execution. Interceptors are really powerful as they are capable of updating the result, providing an exception, or even completely overriding the execution of a function.

Pipe
Pipes can be used to transform or validate any data member. In simpler terms, pipes can be used to transform a string to a number, or to validate if the member is not empty. By default, NestJS offers nine out-of-the-box pipes.

Controller
The controller is the entry point of the request to the main application using dependency injection, and is in charge of invoking the relevant service to handle the business logic. It’s worth noting that the controller is not to be used to implement any business logic, however there might be times where we need to break this convention. If required, a controller can inject multiple services.

Service
Service is the main brain of the application, and is where the business logic will be implemented. The service invokes the data access layer to receive data from the data source, apply any relevant business logic or data transformations, modifications or filtrations, and returns the response back to the controller. A servicer can also inject other services using dependency injection.

There is a fine line between what has to be used and where the concept should lie. Considerations should be made, such as doing justice to the implementation, while ensuring not to exploit any services. For instance, header validation can be done using both an interceptor and a middleware. Developers should be careful with what they use, depending on the use case.

Set Up

That’s enough of the boring theory, now let’s look at some cool stuff. Yes, code.

Let’s create a new to-do list app.

npm i -g @nestjs/cli
nest new todo
This creates the following scaffold files:

main.ts The main entry point of application. This has the main core bootstrap function that creates a single instance NestFactory for the NestJS application.
app.module.ts The root module of application. All global modules that will be used by the application have to be injected here.
app.service.ts A basic injectable service with a single function.
app.controller.ts A basic controller with a single function
app.controller.spec.ts Unit tests for app.controller.

Here are a few useful commands:
npm run start // start the application in the default port
npm run start:dev // start the application in the default port with hot reload
Now, let’s create the basic modules and components.

Let’s start with an interface.

// models/ToDo.ts
export interface TodoList {
 id: string;
 description: string;
 is_active: boolean;
 created_at: Date;
}

Now we have to create new module, controller and service for ToDo.

nest generate module modules/todo
nest generate controller modules/todo
nest generate service modules/todo

This will create the following files:

src/modules/todo/todo.controller.spec.ts
src/modules/todo/todo.controller.ts
src/modules/todo/todo.module.ts
src/modules/todo/todo.service.spec.ts
src/modules/todo/todo.service.ts

Let's clean up before we start. We can now remove app.controller.ts, app.controller.spec.ts and app.service.ts since we need to create a level of abstraction between all the modules. We need to remove their reference from app.module.ts as well. The app.module.ts would already be updated by injecting todo.module.ts into it. This ensures the module is available for consumption by the app and if we run the app, we can hit the todo controller.

TodoService
This is a Singleton Injectable service that is responsible for all the business logic and getting the data from database or source systems. Here, we update the service to have basic CRUD operations.

import { Injectable } from '@nestjs/common';

import { ToDo } from 'src/models/ToDo';

@Injectable()
export class TodoService {
 private readonly database: any; // We have to inject this through constructor.
 // constructor(private readonly database: any) {}

 getAll(): Promise<ToDo[]> {
   return this.database.getAll();
 }

 get(id: string): Promise<ToDo> {
   return this.database.get(id);
 }

 create(todo: ToDo): Promise<ToDo> {
   return this.database.new(todo);
 }

 update(todo: ToDo): Promise<ToDo> {
   return this.database.update(todo);
 }

 delete(id: string): Promise<ToDo> {
   return this.database.delete(id);
 }

 // we can remove this and use the existing update function itself.
 markAsInActive(id: string): Promise<ToDo> {
   return this.get(id).then((todo: ToDo) => {
     todo.is_active = false;
     return this.update(todo);
   });
 }
}

ToDoController
ToDoController is the controller function that will expose the endpoints in the app. This controller injects the relevant service and calls the necessary actions.

import {
 Body,
 Controller,
 Delete,
 Get,
 Param,
 Post,
 Put,
} from '@nestjs/common';
import { ToDo } from 'src/models/ToDo';
import { TodoService } from './todo.service';

@Controller('todo')
export class TodoController {
 constructor(private readonly todoService: TodoService) {}

 @Get(':id')
 get(@Param() params: { id: string }): Promise<ToDo> {
   return this.todoService.get(params.id);
 }

 @Get('all')
 getAll(): Promise<ToDo[]> {
   return this.todoService.getAll();
 }

 @Post()
 create(@Body() body: ToDo): Promise<ToDo> {
   return this.todoService.create(body);
 }

 @Put()
 update(@Body() body: ToDo): Promise<ToDo> {
   return this.todoService.update(body);
 }

 @Put('inactive/:id')
 markAsInActive(@Param() params: { id: string }): Promise<ToDo> {
   return this.todoService.markAsInActive(params.id);
 }

 @Delete()
 delete(@Param() params: { id: string }): Promise<ToDo> {
   return this.todoService.delete(params.id);
 }
}

Now let's start the application. This will start the application in port 3000.

From here, the available endpoints are unknown. We can make use of another handy package, Swagger.

Swagger

Let’s start by adding the Swagger package.
npm install --save @nestjs/swagger

We can now modify the main.ts to include Swagger and point it to the main page.

import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
 const app = await NestFactory.create(AppModule);

 const config = new DocumentBuilder()
   .setTitle('ToDo API')
   .setDescription('The REST API for ToDo application')
   .setVersion('1.0')
   .build();
 const document = SwaggerModule.createDocument(app, config);
 SwaggerModule.setup('/', app, document); // Pointing to the main page.

 await app.listen(3000);
 console.log(`ToDo API is running on: ${await app.getUrl()}`);
}
bootstrap();

We can make a few more tweaks to clean up Swagger. The updated controller code will look like this.

import {
 Body,
 Controller,
 Delete,
 Get,
 Param,
 Post,
 Put,
} from '@nestjs/common';
import { ApiBody, ApiParam, ApiTags } from '@nestjs/swagger';

import { ToDo } from 'src/models/ToDo';
import { TodoService } from './todo.service';

@ApiTags('ToDo')
@Controller('todo')
export class TodoController {
 constructor(private readonly todoService: TodoService) {}

 @Get(':id')
 @ApiParam({ name: 'id', required: true })
 get(@Param() params: { id: string }): Promise<ToDo> {
   return this.todoService.get(params.id);
 }

 @Get('all')
 getAll(): Promise<ToDo[]> {
   return this.todoService.getAll();
 }

 @Post()
 @ApiBody({})
 create(@Body() body: ToDo): Promise<ToDo> {
   return this.todoService.create(body);
 }

 @Put()
 @ApiBody({})
 update(@Body() body: ToDo): Promise<ToDo> {
   return this.todoService.update(body);
 }

 @Put('inactive/:id')
 @ApiParam({ name: 'id', required: true })
 markAsInActive(@Param() params: { id: string }): Promise<ToDo> {
   return this.todoService.markAsInActive(params.id);
 }

 @Delete()
 @ApiParam({ name: 'id', required: true })
 delete(@Param() params: { id: string }): Promise<ToDo> {
   return this.todoService.delete(params.id);
 }
}

Now we can run the app again.

Now that we have a complete component with all the CRUD operations, we can continue creating more components in a similar fashion. The next stage would be to add authentication to protect the routes, add unit tests, validations, using middlewares and interceptors. There is much more that the Swagger is capable of, but all of that is for another day.

Code: https://github.com/rohithart/nestjs-todo
NestJS Documentation: https://docs.nestjs.com/