Then in 2024, everything started to change. We went from a stateless chatbot to an AI agent that could call tools, search the internet, and generate download links.

At this point, I started to get curious. How can an LLM search the internet? An infinite number of questions were flowing through my head. Can it create its own tools, programs, or execute its own code? It felt like we were heading toward the Skynet (Terminator) revolution.

I was just ignorant 😅. But that's when I started my research and discovered LangChain, a tool that promises all those miracles without a billion-dollar budget.

In this article, you’ll build a fully functional AI agent using LangChain and LangGraph. You’ll start by defining structured data using Zod schemas, then parsing them for AI understanding. Next, you’ll learn about summarizing data into text, creating tools the agent can call, and setting up LangGraph nodes to orchestrate workflows.

You’ll see how to compile the workflow graph, manage state, and persist conversation history using MongoDB. By the end, you’ll have a working Starbucks barista AI that demonstrates how to combine reasoning, tool execution, and memory in a single agent.

Table of Contents

• Prerequisites

• What is an LLM Agent?

• Project Setup

• Data Schematization with Zod

• How to Parse the Schema

• Data-to-Text Summarization

• How to Persist Orders with MongoDB in NestJS

• LangGraph State/Annotation Terms

• How to Create Tools for the Agent

• LangGraph Nodes (Workflow Components)

• Graph Declaration

• Workflow Compilation and State Persistence (Final Part)

• Conclusion

Prerequisites

To take full advantage of this article, you should have a basic understanding of TypeScript, Node.js, and a bit of NestJS will help, as it’s the backend framework we’ll be using.

What is an LLM Agent?

By definition, an LLM agent is a software program that’s capable of perceiving its environment, making decisions, and taking autonomous actions to achieve specific goals. It often does this by interacting with tools and systems.

Many frameworks and conventions were created to achieve this, and one of the most famous and widely used is the ReAct (Reason & Act) framework.

With this framework, the LLM receives a prompt, thinks, decides the next action (this can be calling a specific tool), and receives the tool data. Once the tool’s response has been received, the AI model observes the response, generates its own response, and plans its next actions based on the tool’s response.

You can read more about this concept on the official white paper. And here’s a diagram that summarizes the entire process:

Note that the workflow is not limited to a single tool invocation – it can proceed through several rounds before returning to the user.

But for an LLM agent to be truly human-like and act with knowledge of the past, it requires a memory. This enables it to recall previous prompts and responses, maintaining consistency within the given thread.

There’s no single source of truth for how to approach this. Most agents implement a short-term memory. This means that the agent will append each new chat to the conversation history, and when a new prompt is submitted, the agent will append the previous messages to the new prompt.

This method is very efficient and gives the LLM a strong knowledge of previous states. But it can also introduce problems, because the more the conversation grows, the more the LLM will have to go through all previous messages in order to understand what action to take next.

And this can introduce some context drift, just like humans experience. You can’t watch a two-hour podcast and remember all the spoken words, right? In this scenario, the LLM will focus on the most relevant information, eventually losing some context.

You don’t have to implement this from scratch. Many tools and frameworks have been developed to make the implementation as easy as possible. You can build it from scratch if you want, of course, but we won’t be doing that here.

In this article, we’ll build a Starbucks barista that collects order information and calls a create_order tool once the order meets the full criteria. This is a tool that we’ll create and expose to the AI.

Project Setup

Let’s start by initializing our project. We’ll use Nest.js for its efficiency and native TypeScript support. Note that nothing here is tied to Nest.js – this is just a framework preference, and everything we’ll do here can be done with Node.js and Express.js.

Here is a list of all the tools that we’ll use:

1. langchain/core - Always required

   This is the main Langchain engine that defines all core tools and fundamental functions, containing:

   • prompt templates

   • message types

   • runnables

   • tool interfaces

   • chain composition utilities, and more.

Most LangChain project need this.

2. langchain/google-genai - This package is used to interact with Google’s generative AI models, vector embedding models, and other related tools.

3. langchain/langgraph - Important for building an AI agent with total control

   Langgraph is a low-level orchestration framework for building controllable agents. It can be used to build:

   • Conversational agents.

   • Build complex task automation.

   • Agent’s context management.

4. langchain/langgraph-checkpoint-mongodb - This package provides a MongoDB-based checkpointer for LangGraph, enabling persistence of agent state and short-term memory using MongoDB.

5. @langchain/mongodb - This package provides MongoDB integrations for LangChain, allowing you to:

   • Store and retrieve vector embeddings.

   • Persist LangChain documents, agents, or memory states.

   • Easily integrate MongoDB as a database backend for your AI workflows.

6. @nestjs/mongoose - A NestJS wrapper around Mongoose for MongoDB. Provides:

   • Dependency injection support for Mongoose models.

   • Simplified schema definition and model management.

   • Seamless integration of MongoDB into NestJS applications, enabling structured data persistence for AI apps or any backend.

7. langchain - This is the main npm package that aggregates LangChain functionality. It provides:

   • Access to connectors, utilities, and core modules.

   • Easy import of different LangChain components in one place.

   • Commonly used alongside @langchain/core for building applications with minimal setup.

8. mongodb - The official MongoDB driver for Node.js. It provides:

   • Low-level, flexible access to MongoDB databases.

   • Support for CRUD operations, transactions, and indexing.

   • A required dependency if you plan to connect LangChain components or your backend directly to MongoDB.

9. mongoose - An ODM (Object Data Modeling) library for MongoDB. Offers:

   • Schema-based data modeling for MongoDB documents.

   • Middleware, validation, and hooks for MongoDB operations.

   • Ideal for structured data management in NestJS or other Node.js applications.

10. zod - A TypeScript-first schema validation library. Used for:

    • Defining strict data schemas and validating inputs/outputs.

    • Ensuring type safety at runtime.

    • Useful in AI applications to validate responses from models or enforce data consistency.

Start by initializing your Nest.js project, and installing all the required dependencies:

$ npm i -g @nestjs/cli //If you don't have Nest.js installed on your machine
$ nest new project-name

"dependencies" : {
    "@langchain/core": "^0.3.75",
    "@langchain/google-genai": "^0.2.16",
    "@langchain/langgraph": "^0.4.8",
    "@langchain/langgraph-checkpoint-mongodb": "^0.1.1",
    "@langchain/mongodb": "^0.1.0",
    "@nestjs/mongoose": "^11.0.3",
    "langchain": "^0.3.33",
    "mongodb": "^6.19.0",
    "mongoose": "^8.18.1",
    "zod": "^4.1.8"
}

//The versions may not be same at the time you are reading this, so I recommand checking
//The official documentation for each package.

Now that we have our project created and all the packages installed, let’s see what we need to do to turn our vision into a project. Think of what you’ll need in order to create a Starbucks barista:

• First, we need to define the structure of our data (creating schemas)

• Then we need to create a menu list that our agent will be referring to.

• After that, we’ll add LLM interaction

• And last but not least, we’ll add the ability to save previous conversations for conversational context.

Folder Structure

You can modify this folder structure and adapt it based on your framework of choice. But the core implementation is the same across all frameworks.

├── .env
├── .eslintrc.js
├── .gitignore
├── .prettierrc
├── nest-cli.json
├── package.json
├── README.md
├── tsconfig.build.json
├── tsconfig.json
├── src/
│   ├── app.controller.ts
│   ├── app.module.ts
│   ├── app.service.ts
│   ├── main.ts
│   ├── chat/
│   │   ├── chat.controller.ts
│   │   ├── chat.module.ts
│   │   ├── chat.service.ts
│   │   └── dtos/
│   │       └── chat.dto.ts
│   ├── data/
│   │   └── schema/
│   │       └── order.schema.ts
│   └── util/
│       ├── constants/
│       │   └── drinks_data.ts
│       ├── schemas/
│       │   ├── drinks/
│       │   │   └── Drink.schema.ts
│       │   └── orders/
│       │       └── Order.schema.ts
│       ├── summeries/
│       │   └── drink.ts
│       └── types/

Data Schematization with Zod

This file contains all our schema definitions regarding drinks and all modifications they can receive. This part is useful for defining the structure of the data that will be used by the AI agent.

Importing Zod

In the lib/util/schemas/drinks.ts file, before defining any schemas, import the Zod library, which provides tools for building TypeScript-first schemas.

// Imports the 'z' object from the 'zod' library.
// Zod is a TypeScript-first schema declaration and validation library.
// 'z' is the primary object used to define schemas (e.g., z.object, z.string, z.boolean, z.array).
import z from "zod";

Zod gives you a simple and expressive way to define and validate the structure of the data our agent will interact with.

Drink Schema

This schema represents the structure of a drink in the Starbucks-style menu. I split and explained each field so the reader clearly understands what each property controls.

export const DrinkSchema = z.object({
  name: z.string(),            // Required name of the drink
  description: z.string(),     // Required explanation of what the drink is
  supportMilk: z.boolean(),    // Whether milk options are available
  supportSweeteners: z.boolean(), // Whether sweeteners can be added
  supportSyrup: z.boolean(),   // Whether flavor syrups are allowed
  supportTopping: z.boolean(), // Whether toppings are supported
  supportSize: z.boolean(),    // Whether the drink can be ordered in sizes
  image: z.string().url().optional(), // Optional image URL
});

What this schema represents

• It ensures every drink has a proper name and a description.

• It defines which customizations apply to the drink.

• It prepares the agent to reason about drink options in a structured, validated format.

Sweetener Schema

Each sweetener option in the menu is represented with its own schema.

export const SweetenerSchema = z.object({
  name: z.string(),                // Sweetener name
  description: z.string(),         // What it is / taste description
  image: z.string().url().optional(), // Optional image URL
});

This ensures consistency across all sweetener entries and avoids malformed data.

Syrup Schema

Similar to sweeteners, but for syrup flavors:

export const SyrupSchema = z.object({
  name: z.string(),
  description: z.string(),
  image: z.string().url().optional(),
});

This can represent flavors like Vanilla, Caramel, or Hazelnut.

Topping Schema

Toppings such as whipped cream or cinnamon are defined here.

export const ToppingSchema = z.object({
  name: z.string(),
  description: z.string(),
  image: z.string().url().optional(),
});

Size Schema

Drink sizes are modeled as objects as well:

export const SizeSchema = z.object({
  name: z.string(),               // e.g. Small, Medium
  description: z.string(),        // A short explanation
  image: z.string().url().optional(),
});

Milk Schema

Represents milk types such as Whole, Skim, Almond, or Oat.

export const MilkSchema = z.object({
  name: z.string(),
  description: z.string(),
  image: z.string().url().optional(),
});

Collections of Items

Now that the individual item schemas exist, we can create collections of them. These represent all available toppings, sizes, milk types, syrups, sweeteners, and the entire menu of drinks

export const ToppingsSchema = z.array(ToppingSchema);
export const SizesSchema = z.array(SizeSchema);
export const MilksSchema = z.array(MilkSchema);
export const SyrupsSchema = z.array(SyrupSchema);
export const SweetenersSchema = z.array(SweetenerSchema);
export const DrinksSchema = z.array(DrinkSchema);

Why arrays? Because in the real world, your agent will receive lists from a database or API—not single items.

Inferred Types

Zod also allows TypeScript to infer types from schemas automatically.

This ensures:

• TypeScript types always match the schemas.

• You avoid duplicated definitions.

• The agent code stays consistent and safe.

export type Drink = z.infer<typeof DrinkSchema>;
export type SupportSweetener = z.infer<typeof SweetenerSchema>;
export type Syrup = z.infer<typeof SyrupSchema>;
export type Topping = z.infer<typeof ToppingSchema>;
export type Size = z.infer<typeof SizeSchema>;
export type Milk = z.infer<typeof MilkSchema>;

export type Toppings = z.infer<typeof ToppingsSchema>;
export type Sizes = z.infer<typeof SizesSchema>;
export type Milks = z.infer<typeof MilksSchema>;
export type Syrups = z.infer<typeof SyrupsSchema>;
export type Sweeteners = z.infer<typeof SweetenersSchema>;
export type Drinks = z.infer<typeof DrinksSchema>;

These provide the rest of your LangChain/LangGraph code with strong typing based on your schema definitions.

This entire file:

• Encodes all drink-related data structures.

• Provides validation to ensure clean, predictable data.

• Automatically generates TypeScript types.

• Helps the AI agent reason reliably about drinks and customization options.

You’ll use these schemas later and convert them into string representations for LLM prompts.

You can find the file containing all the code here.

How to Parse the Schema

As mentioned earlier, LLMs are text input–output machines. They don’t understand TypeScript types or Zod schemas directly. If you include a schema inside a prompt, the model will simply see it as plain text without understanding its structure or constraints.

Because of this, we need a way to convert schemas into a readable string format that can be embedded inside a prompt, such as:

“The output must be a JSON object with the following fields…”

This is exactly the problem solved by StructuredOutputParser from langchain/output_parsers. It takes a Zod schema and turns it into:

• A human-readable description that can be sent to an LLM.

• A validator that checks whether the model’s output matches the schema.

In short, it acts as a bridge between typed application logic and text-based AI output.

Defining the Order Schema

We’ll start with a simple Zod schema that represents a customer’s drink order. This schema defines the exact shape and constraints of the data we expect the model to produce.

export const OrderSchema = z.object({
  drink: z.string(),
  size: z.string(),
  mil: z.string(),
  syrup: z.string(),
  sweeteners: z.string(),
  toppings: z.string(),
  quantity: z.number().min(1).max(10),
});

export type OrderType = z.infer<typeof OrderSchema>;

At this point, the schema is useful only inside our TypeScript application. The LLM still has no idea what this structure means.

Parsing the Schema into Human-Readable Text

This is where schema parsing comes in. Using StructuredOutputParser.fromZodSchema, we can transform the Zod schema into:

• Instructions the LLM can understand.

• A runtime validator that ensures the response is correct.

export const OrderParser =
  StructuredOutputParser.fromZodSchema(OrderSchema as any);

The parser enables two critical workflows:

Generating prompt instructions

The parser can generate a text description of the schema that looks roughly like: “Return a JSON object with the fields drink, size, mil, syrup, sweeteners, and toppings as strings, and quantity as a number between 1 and 10.” This string can be injected directly into your prompt so the LLM knows exactly how to format its response.

Validating the model’s output

After the LLM responds, its output is still just text. The parser:

• Converts that text into a JavaScript object.

• Validates it against the original Zod schema.

• Throws an error if anything is missing, malformed, or out of bounds.

This prevents invalid AI-generated data (for example, quantity: 0) from entering your system.

Reusing the Same Approach for Other Schemas

Once you understand this pattern, applying it to other schemas is straightforward.

For example, you can do the same thing for a DrinkSchema:

export const DrinkParser =
  StructuredOutputParser.fromZodSchema(DrinkSchema as any);

Now you can confidently say something like: “Hey Gemini, this is what a drink object looks like—please respond using this structure.”

Why This Matters

Schema parsing allows you to:

• Keep strong typing in your application.

• Give clear formatting instructions to the LLM.

• Safely convert unstructured AI output into validated, production-ready data.

Without this step, working with LLMs at scale becomes unreliable and error-prone.

Data-to-Text Summarization

In the context of LLM agents, data-to-text summarization means converting structured data—such as objects returned from a database or backend API—into clear, human-readable strings that can be embedded directly into prompts.

Even the most advanced LLMs operate purely on text. They don’t reason over JavaScript objects, database rows, or JSON structures in the same way humans or programs do. The clearer and more descriptive your text input is, the more accurate and reliable the model’s output will be.

Because of this, a common and recommended pattern when building LLM-powered systems is:

Fetch structured data → summarize it into natural language → pass the summary into the prompt

To keep this article focused, we’ll store our data in constants instead of querying a real database. The technique is exactly the same whether the data comes from MongoDB, PostgreSQL, or an API.

The Core Idea

The goal of data-to-text summarization is simple:

• Take an object with fields and boolean flags

• Convert it into a short paragraph that explains what the object represents

• Remove ambiguity and guesswork for the LLM

Instead of forcing the model to infer meaning from raw data, we spell it out explicitly.

Summarizing a Drink Object

Consider the following drink object:

{
  name: 'Espresso',
  description: 'Strong concentrated coffee shot.',
  supportMilk: false,
  supportSweeteners: true,
  supportSyrup: true,
  supportTopping: false,
  supportSize: false,
}

While this structure is easy for developers to understand, it’s not ideal for an LLM prompt. Boolean flags like supportMilk: false require interpretation, which increases the chance of incorrect assumptions.

Instead, we convert this object into a descriptive paragraph:

“A drink named Espresso. It is described as a strong, concentrated coffee shot. It cannot be made with milk. It can be made with sweeteners. It can be made with syrup. It cannot be made with toppings. It cannot be made in different sizes.”

This transformation is exactly what data-to-text summarization provides.

A Standard Summarization Pattern

Below is a simplified example of how we convert a Drink object into a readable description.

export const createDrinkItemSummary = (drink: Drink): string => {
  const name = `A drink named ${drink.name}.`;
  const description = `It is described as ${drink.description}.`;

  const milk = drink.supportMilk
    ? 'It can be made with milk.'
    : 'It cannot be made with milk.';

  const sweeteners = drink.supportSweeteners
    ? 'It can be made with sweeteners.'
    : 'It cannot contain sweeteners.';

  const syrup = drink.supportSyrup
    ? 'It can be made with syrup.'
    : 'It cannot be made with syrup.';

  const toppings = drink.supportTopping
    ? 'It can be made with toppings.'
    : 'It cannot be made with toppings.';

  const size = drink.supportSize
    ? 'It can be made in different sizes.'
    : 'It cannot be made in different sizes.';

  return `${name} ${description} ${milk} ${sweeteners} ${syrup} ${toppings} ${size}`;
};

Why this works well for LLMs

• Boolean logic is converted into explicit sentences

• Every capability and limitation is clearly stated

• The output can be embedded directly into a system or user prompt

Summarizing Collections of Data

This same approach applies to lists of data such as milks, syrups, toppings, or sizes. Instead of passing an array of objects to the model, we convert them into bullet-style text summaries:

export const createSweetenersSummary = (): string => {
  return `Available sweeteners are:
${SWEETENERS.map(
  (s) => `- ${s.name}: ${s.description}`
).join('\n')}`;
};

This gives the model a complete, readable overview of available options without requiring it to interpret raw arrays.

Applying the Same Idea to Other Domains

This pattern is not limited to drinks or menus. It works for any domain. For example, here’s the same summarization technique applied to an object representing a shoe in an online ordering assistant:

export const createShoeItemSummary = (shoe: {
  name: string;
  description: string;
  genderCategory: string;
  styleType: string;
  material: string;
  availableInMultipleColors: boolean;
  limitedEdition: boolean;
  supportsCustomization: boolean;
}): string => {
  return `
A shoe named ${shoe.name}.
It is described as ${shoe.description}.
It is categorized as a ${shoe.genderCategory.toLowerCase()} shoe.
It belongs to the ${shoe.styleType.toLowerCase()} fashion style.
It is made of ${shoe.material.toLowerCase()} material.
${shoe.availableInMultipleColors ? 'It is available in multiple colors.' : 'It is available in a single color.'}
${shoe.limitedEdition ? 'It is a limited-edition release.' : 'It is not a limited-edition release.'}
${shoe.supportsCustomization ? 'It supports customization options.' : 'It does not support customization options.'}
`.trim();
};

Which produces an output like:

“A shoe named Veloria Canvas Sneaker. It is described as a minimalist everyday sneaker designed for casual wear. It is categorized as a unisex shoe. It belongs to the casual fashion style. It is made of breathable canvas material. It is available in multiple colors. It is not a limited-edition release. It supports light customization options.”

How to Persist Orders with MongoDB in NestJS

Now that we’ve established the core foundations of our application—schemas, parsers, and data-to-text summaries—it’s time to persist data. In a real-world assistant, orders and conversations shouldn’t disappear when the server restarts. They need to be stored reliably so they can be retrieved, analyzed, or continued later.

To achieve this, we’ll use MongoDB as our database and the NestJS Mongoose integration to manage data models and collections.

Connecting MongoDB to a NestJS Application

In NestJS, the AppModule is the root module of the application. This is where global dependencies—such as database connections—are configured.

@Module({
  imports: [
    MongooseModule.forRoot(process.env.MONGO_URI),
    ChatsModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

What’s happening here?

• MongooseModule.forRoot(...) establishes a global MongoDB connection.

• The connection string is read from an environment variable (MONGO_URI), which is the recommended practice for security.

• Once configured, this connection becomes available throughout the entire application.

• ChatsModule is imported so it can access the database connection and register its own schemas.

This setup ensures that every feature module can safely interact with MongoDB without creating multiple connections.

Defining an Order Schema with Mongoose

NestJS uses decorators to define MongoDB schemas in a clean, class-based way. Each class represents a MongoDB document, and each property becomes a field in the collection.

@Schema()
export class Order {
  @Prop({ required: true })
  drink: string;

  @Prop({ default: null })
  size: string;

  @Prop({ default: null })
  milk: string;

  @Prop({ default: null })
  syrup: string;

  @Prop({ default: null })
  sweeter: string;

  @Prop({ default: null })
  toppings: string;

  @Prop({ default: 1 })
  quantity: number;
}

Why this approach?

• Each @Prop() decorator maps directly to a MongoDB field.

• Default values allow partial orders to be saved incrementally.

• Required fields (like drink) enforce basic data integrity.

• The schema closely mirrors the structured output produced by the LLM.

Once the class is defined, it’s converted into a MongoDB schema:

export const OrderSchema = SchemaFactory.createForClass(Order);

This single line creates:

• A MongoDB collection

• A validation layer

• A schema that Mongoose can use to create, read, and update orders

How This Fits into the LLM Agent Architecture

At this point, we have:

• Zod schemas → for validating AI output

• Summarization functions → for converting data into readable prompts

• MongoDB schemas → for persisting finalized orders

This separation is intentional:

• Zod handles AI-facing validation

• Mongoose handles database persistence

• NestJS acts as the glue that ties everything together

Preparing for the Agent Logic

With the database in place, we’re now ready to implement the agent itself.

The agent’s responsibilities will include:

• Interpreting user messages

• Calling tools

• Generating structured orders

• Validating them

• Persisting them to MongoDB

• Maintaining conversational state

All of this logic will live inside the src/chats/chats.service.ts file. The next section introduces the agent’s core logic, and we’ll walk through it step by step so every part is easy to follow.

Start by importing the required dependencies:

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

import { tool } from '@langchain/core/tools';
import {
  ChatPromptTemplate,
  MessagesPlaceholder,
} from '@langchain/core/prompts';
import { AIMessage, BaseMessage, HumanMessage } from '@langchain/core/messages';

import { ChatGoogleGenerativeAI } from '@langchain/google-genai';
import { StateGraph } from '@langchain/langgraph';
import { ToolNode } from '@langchain/langgraph/prebuilt';
import { Annotation } from '@langchain/langgraph';
import { START, END } from '@langchain/langgraph';

import { MongoDBSaver } from '@langchain/langgraph-checkpoint-mongodb';

import z from 'zod';

import { Order } from './schemas/order.schema';
import { OrderParser, OrderSchema, OrderType } from 'src/lib/schemas/orders';
import { DrinkParser } from 'src/lib/schemas/drinks';
import { DRINKS } from 'src/lib/utils/constants/menu_data';

import {
  createSweetenersSummary,
  availableToppingsSummary,
  createAvailableMilksSummary,
  createSyrupsSummary,
  createSizesSummary,
  createDrinkItemSummary,
} from 'src/lib/summaries';

const GOOGLE_API_KEY = process.env.GOOGLE_API_KEY || '';
const client: MongoClient = new MongoClient(process.env.MONGO_URI || '');
const database_name = 'drinks_db';

LangGraph State/Annotation Terms

In LangGraph, state can be thought of as a temporary workspace that exists while the agent is running. It stores all the information that nodes (we’ll cover nodes in detail later) might need to access information like the last message, the history of the conversation, or any intermediate data generated during execution.

This state allows nodes to read from it, update it, and pass information along as the agent processes a workflow, making it the agent’s short-term memory for the duration of the run.

@Injectable()
export class ChatService {

  chatWithAgent = async ({
    thread_id,
    query,
  }: {
    thread_id: string;
    query: string;
  }) => {

    const graphState = Annotation.Root({
      messages: Annotation<BaseMessage[]>({
        reducer: (x, y) => [...x, ...y],
      }),
    });

  }

}

This code defines the LangGraph state for the chat agent. The graphState object acts as a central memory that every node in the workflow can read from and update.

The messages field specifically stores all messages in the conversation, including user messages, AI responses, and tool outputs. The reducer function [...x, ...y] appends new messages to the existing array, preserving the conversation history across multiple steps.

LangGraph’s reducer mechanism lets developers control how new state merges with old state. In this chat system, the approach is similar to updating React state with setMessages(prev => [...prev, ...newMessages]): it keeps the old messages while adding the new ones.

Together, this state enables the agent, tools, and checkpointing system to maintain a coherent conversation, allowing each node in the LangGraph workflow to access the full context and contribute incrementally.

How to Create Tools for the Agent

Modern chatbots can do more than just generate text - they can also search the internet, read files, or perform computations. While LLMs are powerful, they cannot execute code or compile programs on their own.

In the code text of LLM agents, a tool is a piece of code written by the agent developer that an LLM can invoke on the host machine. The host machine executes the code, and the LLM only receives the final output of the computation.

Here's how to create a tool that stores orders in the database. Still in the chatWithAgent function within the ChatService class. Bellow the state store definition:

const orderTool = tool(
  async ({ order }: { order: OrderType }) => {
    try {
      await this.orderModel.create(order);
      return 'Order created successfully';
    } catch (error) {
      console.log(error);
      return 'Failed to create the order';
    }
  },
  {
    schema: z.object({
      order: OrderSchema.describe('The order that will be stored in the DB'),
    }),
    name: 'create_order',
    description: 'This tool creates a new order in the database',
  }
);

const tools = [orderTool];

LangGraph Nodes (Workflow Components)

From a definition standpoint, a LangGraph node is a fundamental component of a LangGraph workflow, representing a single unit of computation or an individual step in an AI agent's process.

Each node can perform a specific task, such as generating a message, invoking a tool, or transforming data, and it interacts with the state to read inputs and write outputs. Together, nodes are connected to form the agent’s workflow or execution graph, allowing complex reasoning and multi-step operations.

In our project, we’ll have four nodes.

1. Agent node: This node is in charge of interacting with the LLM - it constructs the agent’s main message template and stacks old messages to the new prompt to create context.

2. Tools node: The tools node introduces external capabilities, which allow the workflow to interact with external APIs

3. START node: This node indicates the entry point of our workflow, or to be precise, which node to call when a user initiates a conversation with the agent. It’s quite simple to define.

4. addConditionalEdges - addConditionalEdges('agent', shouldContinue): In LangGraph, .addConditionalEdges('agent', shouldContinue) lets the workflow branch dynamically after the 'agent' node runs, based on a condition defined in shouldContinue. Unlike a fixed edge, which always goes from one node to the next, a conditional edge evaluates the agent’s output and directs the workflow to different nodes depending on the result, allowing the AI agent to make decisions and adapt its next steps.

Graph Declaration

In LangGraph, a graph is the central structure that models an AI agent’s workflow as interconnected nodes, where each node represents a computation step, tool, or decision. It orchestrates the flow of data and control between nodes, manages conditional branching, and maintains the recursive loop of execution.

Essentially, the graph is the backbone that ensures complex, stateful interactions happen in a coordinated and modular way, connecting nodes like agent, tools, and conditional edges into a coherent workflow.

With that knowledge in place, we can now create the agent graph with all its nodes.

  const callModal = async (states: typeof graphState.State) => {
    const prompt = ChatPromptTemplate.fromMessages([
      {
        role: 'system',
        content: `
            You are a helpful assistant that helps users order drinks from Starbucks.
            Your job is to take the user's request and fill in any missing details based on how a complete order should look.
            A complete order follows this structure: ${OrderParser}.

            **TOOLS**
            You have access to a "create_order" tool.
            Use this tool when the user confirms the final order.
            After calling the tool, you should inform the user whether the order was successfully created or if it failed.

            **DRINK DETAILS**
            Each drink has its own set of properties such as size, milk, syrup, sweetener, and toppings.
            Here is the drink schema: ${DrinkParser}.

            You must ask for any missing details before creating the order.

            If the user requests a modification that is not supported for the selected drink, tell them that it is not possible.

            If the user asks for something unrelated to drink orders, politely tell them that you can only assist with drink orders.

            **AVAILABLE OPTIONS**
            List of available drinks and their allowed modifications:
            ${DRINKS.map((drink) => `- ${createDrinkItemSummary(drink)}`)}

            Sweeteners: ${createSweetenersSummary()}
            Toppings: ${availableToppingsSummary()}
            Milks: ${createAvailableMilksSummary()}
            Syrups: ${createSyrupsSummary()}
            Sizes: ${createSizesSummary()}

            Order schema: ${OrderParser}

            If the user's query is unclear, tell them that the request is not clear.

            **ORDER CONFIRMATION**
            Once the order is ready, you must ask the user to confirm it.
            If they confirm, immediately call the "create_order" tool.
            Only respond after the tool completes, indicating success or failure.

            **FRONTEND RESPONSE FORMAT**
            Every response must include:

            "message": "Your message to the user",
            "current_order": "The order currently being constructed",
            "suggestions": "Options the user can choose from",
            "progress": "Order status ('completed' after creation)"

            **IMPORTANT RULES**
            - Be friendly, use emojis, and add humor.
            - Use null for unfilled fields.
            - Never omit the JSON tracking object.
        `,
      },
      new MessagesPlaceholder('messages'),
    ]);

  const formattedPrompt = await prompt.formatMessages({
    time: new Date().toISOString(),
    messages: states.messages,
  });

  const chat = new ChatGoogleGenerativeAI({
    model: 'gemini-2.0-flash',
    temperature: 0,
    apiKey: GOOGLE_API_KEY,
  }).bindTools(tools);

  const result = await chat.invoke(formattedPrompt);
  return { messages: [result] };
  };     
    const shouldContinue = (state: typeof graphState.State) => {
      const lastMessage = state.messages[
        state.messages.length - 1
      ] as AIMessage;
      return lastMessage.tool_calls?.length ? 'tools' : END;
    };

    const toolsNode = new ToolNode<typeof graphState.State>(tools);

    /**
     * Build the conversation graph.
     */
    const graph = new StateGraph(graphState)
      .addNode('agent', callModal)
      .addNode('tools', toolsNode)
      .addEdge(START, 'agent')
      .addConditionalEdges('agent', shouldContinue)
      .addEdge('tools', 'agent');

Explanation

• Graph State (graphState)
  The graphState object is the shared memory across all nodes. It stores messages, which track the conversation history including user inputs, AI responses, and tool interactions. The reducer [...x, ...y] appends new messages, preserving past context. This is similar to React state updates: old messages remain while new ones are added.

• Agent Node (callModal)
  This node handles the LLM call. It formats a prompt containing system instructions, drink schemas, available tools, and frontend response rules. By including states.messages, the AI sees the full conversation history, enabling multi-turn dialogue.

• LLM Execution
  ChatGoogleGenerativeAI generates the AI response. .bindTools(tools) allows the AI to call tools like create_order directly if needed.

• Conditional Flow (shouldContinue)
  After the AI responds, the shouldContinue function checks if the message includes tool calls. If so, execution moves to the tools node; otherwise, the workflow ends. This allows dynamic branching depending on the AI’s output.

• Tool Node (ToolNode)
  The tools node executes the requested tool, such as saving the order to the database. Once completed, control returns to the agent node, enabling the AI to respond to the user with results.

• Graph Construction (StateGraph)
  Nodes are connected in a coherent workflow:

  • START → agent begins the conversation

  • Conditional edges handle tool execution

  • tools → agent ensures the agent can respond after tools run

• Overall Flow
  Together, the graph and shared state ensure a stateful, multi-turn conversation. The AI can ask for missing details, call tools when needed, and maintain context across interactions. Every node reads and writes to the same state.

Workflow Compilation and State Persistence (Final Part)

So far, all of our states are temporary, meaning they only exist for the duration of a user’s request. However, we want our agent to remember and recall conversation context even when a new request is sent with the same thread_id or conversation ID.

To achieve this, we’ll use MongoDB in combination with the langchain/langgraph-checkpoint-mongo library. This library simplifies state persistence by associating each conversation with a unique, manually assigned ID. All operations—from retrieving previous messages to saving new ones—are handled internally, you only need to provide the conversation ID you want to work with.

const graph = new StateGraph(graphState)
  .addNode('agent', callModal)
  .addNode('tools', toolsNode)
  .addEdge(START, 'agent')
  .addConditionalEdges('agent', shouldContinue)
  .addEdge('tools', 'agent');

  const checkpointer = new MongoDBSaver({ client, dbName: database_name });

  const app = graph.compile({ checkpointer });

  /**
     * Run the graph using the user's message.
     */
    const finalState = await app.invoke(
      { messages: [new HumanMessage(query)] },
      { recursionLimit: 15, configurable: { thread_id } },
    );

  /**
   * Extract JSON payload from AI response.
   */
  function extractJsonResponse(response: any) {
    const match = response.match(/```json\\s*([\\s\\S]*?)\\s*```/i);
    if (match && match[1] && typeof response === 'string') {
      return JSON.parse(match[1].trim());
    }
    throw response;
  }

  const lastMessage = finalState.messages.at(-1) as AIMessage; // Extract the last message of the conversation
  return extractJsonResponse(lastMessage.content); //Response

The above code demonstrates how to initialize a checkpoint, compile a graph, and invoke the agent with an incoming prompt.

The extractJsonResponse method is used to grab the formatted response that we instructed the LLM to generate whenever it’s sending back something to the user.

Based on this given instruction from the main template, every response must include: "message": "Your message to the user", "current_order": "The order currently being constructed", "suggestions": "Options the user can choose from", "progress": "Order status ('completed' after creation)"

Every response from the LLM should look like this:

'```json\\n' +
  '{\\n' +
  '"message": "Got it! To make sure I get your order just right, can you clarify which coffee drink you\\'d like? We have Latte, Cappuccino, Cold Brew, and Frappuccino. 😊",\\n' +
  '"current_order": {\\n' +
  '"drink": null,\\n' +
  '"size": null,\\n' +
  '"mil": null,\\n' +
  '"syrup": null,\\n' +
  '"sweeteners": null,\\n' +
  '"toppings": null,\\n' +
  '"quantity": null\\n' +
  '},\\n' +
  '"suggestions": [\\n' +
  '"Latte",\\n' +
  '"Cappuccino",\\n' +
  '"Cold Brew",\\n' +
  '"Frappuccino"\\n' +
  '],\\n' +
  '"progress": "incomplete"\\n' +
  '}\\n' +
  '```';

This structure allows the frontend to easily render the LLM response and track the state of the current order. This is more of a design choice and less of a convention.

Conclusion

Building an autonomous AI agent with LangChain and LangGraph allows you to combine the reasoning power of LLMs with practical tool execution and persistent memory. By defining schemas, parsing data into human-readable formats, and orchestrating workflows through nodes, you can create intelligent agents capable of handling real-world tasks—like our Starbucks barista.

With MongoDB integration for state persistence, your agent can maintain context across conversations, making interactions feel more natural and human-like. This approach opens the door to building more sophisticated, domain-specific AI assistants without starting from scratch.

In short: define your data, teach your agent how to reason, and let LangGraph orchestrate the magic. ☕🤖

Source code here: https://github.com/DjibrilM/langgraph-starbucks-agent

Resources

• LangGraph documentation: https://docs.langchain.com/oss/javascript/langgraph/quickstart

• Synergizing Reasoning and Acting in Language Models: https://arxiv.org/abs/2210.03629

We just published a NestJS course on the freeCodeCamp.org YouTube channel that will help you harness it’s modular architecture, TypeScript support, and built-in tools to create clean, testable, code.

In this course, you'll explore controllers, services, modules, decorators, pipes, guards, and exception handling - all while building the profile feature for DevMatch, a dating app for developers.

You’ll implement profile creation, updates, and data retrieval while exploring the full lifecycle of a NestJS backend. By the end, you’ll have a solid foundation in NestJS fundamentals, plus the confidence to apply these skills to your own APIs and applications.

The course covers:

• Understand NestJS fundamentals: modules, decorators, and structure.

• Build controllers to handle GET, POST, PUT, and DELETE requests.

• Connect controllers to services to manage application logic.

• Implement validation and transformation with pipes.

• Handle errors gracefully with exception filters.

• Use guards to manage application security and access control.

• Solve hands-on challenges that reinforce each concept.

Watch the full course on the freeCodeCamp.org YouTube channel (2-hour watch).

If you’re coming from Angular, you’ll feel right at home with its module/controller/service structure and powerful dependency-injection system.

In this article we’ll cover both theory – why NestJS exists, how it’s structured, and when to reach for it –and practice, with bite-sized code snippets demonstrating how to bootstrap a project, define routes, inject dependencies, and more. Let’s start by understanding what NestJS is and where it came from.

Table of Contents

1. What is NestJS?

   • 1.1 History and Philosophy

2. Why Choose NestJS?

   • 2.1 Benefits and Use Cases

   • 2.2 Comparison with Other Frameworks

3. Getting Started

   • 3.1 Installing the CLI

   • 3.2 Creating Your First Project

   • 3.3 Project Structure Overview

4. Core NestJS Building Blocks

   • 4.1 Modules

   • 4.2 Controllers

   • 4.3 Providers (Services)

5. Dependency Injection

   • 5.1 How DI Works in NestJS

   • 5.2 Custom Providers and Factory Providers

6. Routing & Middleware

   • 6.1 Defining Routes

   • 6.2 Applying Middleware

7. Request Lifecycle & Pipes

   • 7.1 What Are Pipes?

   • 7.2 Built-In vs. Custom Pipes

8. Guards & Authorization

   • 8.1 Implementing Guards

   • 8.2 Role-Based Access Control

9. Exception Filters

   • 9.1 Handling Errors Gracefully

   • 9.2 Creating Custom Filters

10. Interceptors & Logging

    • 10.1 Transforming Responses

    • 10.2 Logging and Performance Metrics

11. Database Integration

    • 11.1 TypeORM with NestJS

    • 11.2 Mongoose (MongoDB)

    • 11.3 Prisma

12. Configuration Management

    • 12.1 @nestjs/config Module

    • 12.2 Environment Variables

13. Authentication

    • 13.1 JWT Strategy

    • 13.2 OAuth2 / Social Login

14. Conclusion & Further Resources

    • Summary

    • Official Docs and Community Links

1. What is NestJS?

NestJS is a framework for building server-side applications in Node.js. It’s written in TypeScript (but supports plain JavaScript as well). At its core, it:

• Wraps a mature HTTP server library (Express or Fastify)

• Standardizes application architecture around modules, controllers, and providers

• Leverages TypeScript’s type system for compile-time safety and clear APIs

• Offers built-in support for things like validation, configuration, and testing

Rather than stitching together middleware by hand, NestJS encourages a declarative, layered approach. You define modules to group related functionality, controllers to handle incoming requests, and providers (often called “services”) for your business logic. Behind the scenes, NestJS resolves dependencies via an IoC container, so you can focus on writing clean, reusable classes.

To start up a project, run the following commands:

# Install the Nest CLI globally
npm install -g @nestjs/cli

# Create a new project called 'my-app'
nest new my-app

cd my-app
npm run start:dev

Once it’s running, you have a ready-to-go HTTP server with hot reloading, strict typing, and a sensible folder layout.

1.1 History and Philosophy

NestJS first appeared in 2017, created by Kamil Myśliwiec. Its goal was to bring the architectural patterns of Angular to the backend world, providing:

1. Consistency: A single, opinionated way to structure applications.

2. Scalability: Clear boundaries (modules) make it easier to grow teams and codebases.

3. Testability: Built-in support for Jest and clear separation of concerns.

4. Extensibility: A pluggable module system makes it easy to integrate ORMs, WebSockets, GraphQL, microservices, and more.

Under the hood, NestJS embraces these principles:

• Modularity: Everything lives in a module (AppModule, UsersModule, and so on), which can import other modules or export providers.

• Dependency Injection: Services can be injected into controllers (and even into other services), which fosters loose coupling.

• Decorators and Metadata: With TypeScript decorators (@Module(), @Controller(), @Injectable()), NestJS reads metadata at runtime to wire everything together.

Here’s a tiny example showing the interplay of these pieces:

// users.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class UsersService {
  private users = [{ id: 1, name: 'Alice' }];
  findAll() {
    return this.users;
  }
}

// users.controller.ts
import { Controller, Get } from '@nestjs/common';
import { UsersService } from './users.service';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  getUsers() {
    return this.usersService.findAll();
  }
}

// users.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

• The @Module decorator groups controller + service

• The controller injects the service via its constructor

• A simple GET /users route returns an array of user objects

With that foundation laid, in the next section we’ll explore why you’d choose NestJS, comparing it to other popular Node frameworks and outlining common real-world use cases.

2. Why Choose NestJS?

NestJS isn’t just another Node.js framework – it brings a structured, enterprise-grade approach to building backend services. In this section we’ll cover benefits and real-world use cases, then compare NestJS to other popular Node frameworks so you can see where it fits best.

2.1 Benefits and Use Cases

1. Strong architectural patterns

   • Modularity: You break your app into focused modules (AuthModule, ProductsModule, and so on), each responsible for a slice of functionality.

   • Separation of concerns: Controllers handle HTTP, services encapsulate business logic, modules wire everything up.

   • Scalability: Growing teams map naturally onto modules—new features rarely touch existing code.

2. Built-in dependency injection (DI)

   • DI makes testing and swapping implementations trivial.

   • You can easily mock a service in a unit test:

    // products.controller.spec.ts
    import { Test, TestingModule } from '@nestjs/testing';
    import { ProductsController } from './products.controller';
    import { ProductsService } from './products.service';

    describe('ProductsController', () => {
      let controller: ProductsController;
      const mockService = { findAll: () => ['apple', 'banana'] };

      beforeEach(async () => {
        const module: TestingModule = await Test.createTestingModule({
          controllers: [ProductsController],
          providers: [
            { provide: ProductsService, useValue: mockService },
          ],
        }).compile();

        controller = module.get<ProductsController>(ProductsController);
      });

      it('returns a list of products', () => {
        expect(controller.getAll()).toEqual(['apple', 'banana']);
      });
    });

3. TypeScript-first

   • Full type safety at compile time.

   • Leverage interfaces and decorators (@Body(), @Param()) to validate and transform data.

4. Rich ecosystem and extensibility

   • Official integrations for WebSockets, GraphQL, microservices (RabbitMQ, Kafka), and more.

   • Hundreds of community modules (for example @nestjs/swagger for OpenAPI docs).

5. Production-grade tooling

   • CLI generates boilerplate (nest g module, nest g service).

   • Support for hot-reload in development (npm run start:dev).

   • Built-in testing setup with Jest.

Real-World Use Cases:

• Enterprise APIs with strict module boundaries and RBAC.

• Microservices architectures, where each service is a self-contained NestJS app.

• Real-time applications (chat, live dashboards) using Nest’s WebSocket gateways.

• GraphQL backends with code-first schemas.

• Event-driven systems connecting to message brokers.

2.2 Comparison with Other Frameworks

• Express is great if you want minimal layers and full control, but you’ll end up hand-rolling a lot (DI, validation, folder structure).

• Koa offers a more modern middleware approach, but still leaves architecture decisions to you.

• NestJS provides the full stack: structure, DI, validation, testing, and official integrations, which is ideal if you value consistency, type safety, and out-of-the-box best practices.

When to choose NestJS:

NextJS is great for various use cases. It’s particularly effective if you’re building a large-scale API or microservice suite, if you want a solid architecture from day one, and if you prefer TypeScript and DI to keep code testable and maintainable.

With these advantages in mind, you’ll find that NestJS can dramatically speed up development, especially on projects that need robust structure and clear boundaries.

In the next section, we’ll dive into getting started: installing the CLI, creating a project, and exploring the generated folder layout.

3. Getting Started

Let’s jump into the basics: installing the CLI, scaffolding a new project, and exploring the default folder layout.

3.1 Installing the CLI

Nest ships with an official command-line tool that helps you generate modules, controllers, services, and more. Under the hood it uses Yeoman templates to keep everything consistent.

# Install the CLI globally (requires npm ≥ 6)
npm install -g @nestjs/cli

Once installed, you can run nest --help to see available commands:

nest --help
Usage: nest <command> [options]

Commands:
  new <name>       Scaffold a new project
  generate|g <schematic> [options]  Generate artifacts (modules, controllers, ...)
  build            Build project with webpack
  ...

Options:
  -v, --version    Show version number
  -h, --help       Show help

3.2 Creating Your First Project

Scaffolding a new app is a single command. The CLI will ask whether to use npm or yarn, and whether to enable strict TypeScript settings.

# Create a new Nest app in the "my-nest-app" folder
nest new my-nest-app

After answering the prompts, you’ll have:

cd my-nest-app
npm run start:dev

This launches a development server on http://localhost:3000 with automatic reload on file changes.

3.3 Project Structure Overview

By default, you’ll see something like:

my-nest-app/
├── src/
│   ├── app.controller.ts      # example controller
│   ├── app.controller.spec.ts # unit test for controller
│   ├── app.module.ts          # root application module
│   ├── app.service.ts         # example provider
│   └── main.ts                # entry point (bootstraps Nest)
├── test/                      # end-to-end tests
├── node_modules/
├── package.json
├── tsconfig.json
└── nest-cli.json             # CLI configuration

• src/main.ts
  The “bootstrap” script. It creates a Nest application instance and starts listening on a port:

    import { NestFactory } from '@nestjs/core';
    import { AppModule } from './app.module';
  
    async function bootstrap() {
      const app = await NestFactory.create(AppModule);
      await app.listen(3000);
      console.log(`🚀 Application is running on: ${await app.getUrl()}`);
    }
    bootstrap();
  

• src/app.module.ts
  The root module. It ties together controllers and providers:

    import { Module } from '@nestjs/common';
    import { AppController } from './app.controller';
    import { AppService } from './app.service';
  
    @Module({
      imports: [],                 // other modules to import
      controllers: [AppController],
      providers: [AppService],
    })
    export class AppModule {}
  

• src/app.controller.ts / app.service.ts
  A simple example that shows dependency injection in action:

    // app.controller.ts
    import { Controller, Get } from '@nestjs/common';
    import { AppService } from './app.service';
  
    @Controller()
    export class AppController {
      constructor(private readonly appService: AppService) {}
  
      @Get()
      getHello(): string {
        return this.appService.getHello();
      }
    }
  
    // app.service.ts
    import { Injectable } from '@nestjs/common';
  
    @Injectable()
    export class AppService {
      getHello(): string {
        return 'Hello, NestJS!';
      }
    }
  

With this scaffold in place, you have a minimal – but fully functional – NestJS application. From here, you can generate new modules, controllers, and services:

# Generate a new module, controller, and service for "tasks"
nest g module tasks
nest g controller tasks
nest g service tasks

Each command will drop a new .ts file in the appropriate folder and update your module’s metadata. In the next section, we’ll dive into core Nest building blocks like modules, controllers, and providers in more detail.

4. Core NestJS Building Blocks

At the heart of every NestJS application are three pillars: Modules, Controllers, and Providers (often called Services). Let’s see what each one does, and how they fit together in theory and in practice.

4.1 Modules

A Module is a logical boundary – a container that groups related components (controllers, providers, and even other modules). Every NestJS app has at least one root module (usually AppModule), and you create feature modules (UsersModule, AuthModule, and so on) to organize code by domain.

@Module() Decorator

• imports: other modules to use

• controllers: controllers that handle incoming requests

• providers: services or values available via DI

• exports: providers that should be visible to importing modules

Here’s an example:

// cats.module.ts
import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';

@Module({
  imports: [],            // e.g. TypeOrmModule.forFeature([Cat])
  controllers: [CatsController],
  providers: [CatsService],
  exports: [CatsService], // makes CatsService available to other modules
})
export class CatsModule {}

Then in your root module:

// app.module.ts
import { Module } from '@nestjs/common';
import { CatsModule } from './cats/cats.module';

@Module({
  imports: [CatsModule],
})
export class AppModule {}

Now anything that injects CatsService will resolve to the one defined inside CatsModule.

4.2 Controllers

A Controller maps incoming HTTP requests to handler methods. It’s responsible for extracting request data (query parameters, body, headers) and returning a response. Controllers should remain thin – delegating business logic to providers.

• @Controller(path?): Defines a route prefix

• @Get, @Post, @Put, @Delete, and so on: Define method-level routes

• @Param(), @Query(), @Body(), @Headers(), @Req(), @Res(): Decorators to extract request details

Here’s an example:

// cats.controller.ts
import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { CatsService } from './cats.service';
import { CreateCatDto } from './dto/create-cat.dto';

@Controller('cats')                  // prefix: /cats
export class CatsController {
  constructor(private readonly catsService: CatsService) {}

  @Get()
  findAll() {
    return this.catsService.findAll();  // GET /cats
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.catsService.findOne(+id);  // GET /cats/1
  }

  @Post()
  create(@Body() createCatDto: CreateCatDto) {
    return this.catsService.create(createCatDto);  // POST /cats
  }
}

// dto/create-cat.dto.ts
export class CreateCatDto {
  readonly name: string;
  readonly age: number;
  readonly breed?: string;
}

4.3 Providers (Services)

Providers are classes annotated with @Injectable() that contain your business logic or data access. Anything you want to inject elsewhere must be a provider. You can provide plain values, factory functions, or classes.

• @Injectable(): Marks a class as available for DI

• Scope: Default is singleton, but you can change to request or transient

• Custom Providers: Use useClass, useValue, useFactory, or useExisting for more control

Here’s an example:

// cats.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { CreateCatDto } from './dto/create-cat.dto';

@Injectable()
export class CatsService {
  private cats = [];

  create(dto: CreateCatDto) {
    const newCat = { id: Date.now(), ...dto };
    this.cats.push(newCat);
    return newCat;
  }

  findAll() {
    return this.cats;
  }

  findOne(id: number) {
    const cat = this.cats.find(c => c.id === id);
    if (!cat) {
      throw new NotFoundException(`Cat #${id} not found`);
    }
    return cat;
  }
}

Injecting a Custom Value:

// logger.provider.ts
export const LOGGER = {
  provide: 'LOGGER',
  useValue: console,
};

// app.module.ts
import { Module } from '@nestjs/common';
import { LOGGER } from './logger.provider';

@Module({
  providers: [LOGGER],
  exports: [LOGGER],
})
export class AppModule {}

// some.service.ts
import { Inject, Injectable } from '@nestjs/common';

@Injectable()
export class SomeService {
  constructor(@Inject('LOGGER') private readonly logger: Console) {}

  logMessage(msg: string) {
    this.logger.log(`Custom log: ${msg}`);
  }
}

With modules wiring up controllers and providers, NestJS gives you a scalable, testable foundation. In the next section, we’ll explore Dependency Injection in depth – how it works under the hood and how to create custom providers and factory-based injections.

5. Dependency Injection

Nest’s built-in Dependency Injection (DI) system is the heart of how components (controllers, services, and so on) talk to each other in a loosely-coupled, testable way.

5.1 How DI Works in NestJS

When your application boots, Nest builds a module-based IoC container. Each @Injectable() provider is registered in the container under a token (by default, its class). When a class declares a dependency in its constructor, Nest looks up that token and injects the matching instance.

• Singleton scope: One instance per application (default)

• Request scope: New instance per incoming request

• Transient scope: New instance every time it’s injected

Here’s an example:

// cats.service.ts
@Injectable()
export class CatsService {
  // ...
}

// cats.controller.ts
@Controller('cats')
export class CatsController {
  constructor(private readonly catsService: CatsService) {}
  // Nest sees CatsService in the constructor,
  // finds its singleton instance, and injects it.
}

Behind the scenes, Nest collects metadata from decorators (@Injectable(), @Controller()) and builds a graph of providers. When you call NestFactory.create(AppModule), it resolves that graph and wires everything together.

5.2 Custom Providers and Factory Providers

Sometimes you need to inject non-class values (APIs, constants) or run logic at registration time. Nest lets you define custom providers using the provide syntax.

useValue

Inject a plain value or object:

// config.constant.ts
export const APP_NAME = {
  provide: 'APP_NAME',
  useValue: 'MyAwesomeApp',
};

// app.module.ts
@Module({
  providers: [APP_NAME],
  exports: ['APP_NAME'],
})
export class AppModule {}

// some.service.ts
@Injectable()
export class SomeService {
  constructor(@Inject('APP_NAME') private readonly name: string) {}

  whoAmI() {
    return `Running in ${this.name}`;
  }
}

useClass

Swap implementations easily (useful for testing or feature flags):

// logger.interface.ts
export interface Logger {
  log(msg: string): void;
}

// console-logger.ts
@Injectable()
export class ConsoleLogger implements Logger {
  log(msg: string) { console.log(msg); }
}

// file-logger.ts
@Injectable()
export class FileLogger implements Logger {
  log(msg: string) { /* write to file */ }
}

// app.module.ts
@Module({
  providers: [
    { provide: 'Logger', useClass: FileLogger }, 
  ],
})
export class AppModule {}

// any.service.ts
@Injectable()
export class AnyService {
  constructor(@Inject('Logger') private readonly logger: Logger) {}
}

useFactory

Run arbitrary factory logic (for example, async initialization, dynamic config):

// database.provider.ts
export const DATABASE = {
  provide: 'DATABASE',
  useFactory: async (configService: ConfigService) => {
    const opts = configService.getDbOptions();
    const connection = await createConnection(opts);
    return connection;
  },
  inject: [ConfigService],
};

// app.module.ts
@Module({
  imports: [ConfigModule],
  providers: [DATABASE],
  exports: ['DATABASE'],
})
export class AppModule {}

// users.service.ts
@Injectable()
export class UsersService {
  constructor(@Inject('DATABASE') private readonly db: Connection) {}
}

With custom providers and the factory pattern, you can integrate external libraries, toggle implementations, or perform async setup – all while retaining the clear, testable structure NestJS provides.

In the next section we’ll look at Routing and Middleware, showing how to define route handlers, apply global or per-route middleware, and extend your HTTP pipeline.

6. Routing & Middleware

Routing in NestJS is built on top of your controllers and decorators, while middleware lets you hook into the request/response pipeline for cross-cutting concerns like logging, authentication checks, or CORS.

6.1 Defining Routes

First, a bit of theory:

• @Controller(path?) sets a URL prefix for all routes in that class.

• @Get, @Post, @Put, @Delete, etc. define HTTP-method handlers.

• @Param(), @Query(), @Body(), @Headers(), @Req(), @Res() extract parts of the incoming request.

You can combine route decorators and parameter decorators to build expressive, type-safe endpoints.

Here’s an example:

// products.controller.ts
import { Controller, Get, Post, Param, Query, Body } from '@nestjs/common';
import { ProductsService } from './products.service';
import { CreateProductDto } from './dto/create-product.dto';

@Controller('products')                // all routes here start with /products
export class ProductsController {
  constructor(private readonly productsService: ProductsService) {}

  @Get()                              // GET /products
  findAll(
    @Query('limit') limit = '10',     // optional query ?limit=20
  ) {
    return this.productsService.findAll(+limit);
  }

  @Get(':id')                         // GET /products/123
  findOne(@Param('id') id: string) {
    return this.productsService.findOne(+id);
  }

  @Post()                             // POST /products
  create(@Body() dto: CreateProductDto) {
    return this.productsService.create(dto);
  }
}

You can also nest controllers by importing a feature module, and use @Patch, @Put, @Delete, @Head, and so on for full RESTful coverage.

6.2 Applying Middleware

Middleware are functions that run before your routes handle a request. They’re useful for logging, body-parsing (though Nest provides built-ins), authentication guards at a lower level, rate limiting, and so on.

You can implement them either as a functional middleware or a class implementing NestMiddleware.

Here’s an example (Functional Middleware):

// logger.middleware.ts
import { Request, Response, NextFunction } from 'express';

export function logger(req: Request, res: Response, next: NextFunction) {
  console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
  next();
}

// app.module.ts
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { logger } from './logger.middleware';
import { ProductsModule } from './products/products.module';

@Module({
  imports: [ProductsModule],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(logger)                 // apply logger
      .forRoutes('products');        // only for /products routes
  }
}

And here’s another example (Class-based Middleware):

// auth.middleware.ts
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';

@Injectable()
export class AuthMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    if (!req.headers.authorization) {
      return res.status(401).send('Unauthorized');
    }
    // validate token...
    next();
  }
}

// security.module.ts
import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
import { AuthMiddleware } from './auth.middleware';
import { UsersController } from './users.controller';

@Module({
  controllers: [UsersController],
})
export class SecurityModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(AuthMiddleware)
      .forRoutes(UsersController);    // apply to all routes in UsersController
  }
}

Tip: Global middleware can be applied in your main.ts before the app.listen() call via app.use(logger) if you want it on every request.

With routing and middleware set up, you have full control over how requests flow through your application. Next up, we’ll dive into Request Lifecycle and Pipes, exploring how data transforms and validations happen as part of each request.

7. Request Lifecycle & Pipes

NestJS processes each incoming request through a defined “lifecycle” of steps – routing to the correct handler, applying pipes, guards, interceptors, and finally invoking your controller method. Pipes sit between the incoming request and your handler, transforming or validating data before it reaches your business logic.

7.1 What Are Pipes?

A Pipe is a class annotated with @Injectable() that implements the PipeTransform interface. It has a single method:

transform(value: any, metadata: ArgumentMetadata): any

• Transformation: Convert input data (for example, a string "123") into the desired type (number 123).

• Validation: Check that incoming data meets certain rules and throw an exception (usually a BadRequestException) if it doesn’t.

By default, pipes run after middleware and before guards/interceptors, for each decorated parameter (@Body(), @Param(), and so on).

Here’s how it works:
Nest ships with a handy global validation pipe that integrates with class-validator:

// main.ts
import { ValidationPipe } from '@nestjs/common';
import { NestFactory }    from '@nestjs/core';
import { AppModule }      from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // Automatically validate and strip unknown properties
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true }));
  await app.listen(3000);
}
bootstrap();

With this in place, any DTO annotated with validation decorators will be checked before your handler runs:

// dto/create-user.dto.ts
import { IsEmail, IsString, MinLength } from 'class-validator';

export class CreateUserDto {
  @IsEmail()           // must be a valid email
  email: string;

  @IsString()          // must be a string
  @MinLength(8)        // at least 8 characters
  password: string;
}

// users.controller.ts
@Post()
createUser(@Body() dto: CreateUserDto) {
  // If body.email isn't an email, or password is shorter,
  // Nest throws a 400 Bad Request with details.
  return this.usersService.create(dto);
}

7.2 Built-In vs. Custom Pipes

Built-In Pipes

Nest provides several out-of-the-box pipes:

• ValidationPipe: Integrates with class-validator for DTO validation (shown above).

• ParseIntPipe: Converts a route parameter to number or throws BadRequestException.

• ParseBoolPipe, ParseUUIDPipe, ParseFloatPipe, and so on.

@Get(':id')
getById(@Param('id', ParseIntPipe) id: number) {
  // id is guaranteed to be a number here
  return this.itemsService.findOne(id);
}

Custom Pipes

You can write your own to handle any transformation or validation logic:

import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';

@Injectable()
export class ParsePositiveIntPipe implements PipeTransform<string, number> {
  transform(value: string): number {
    const val = parseInt(value, 10);
    if (isNaN(val) || val <= 0) {
      throw new BadRequestException(`"${value}" is not a positive integer`);
    }
    return val;
  }
}

Use it just like a built-in pipe:

@Get('order/:orderId')
getOrder(
  @Param('orderId', ParsePositiveIntPipe) orderId: number
) {
  // orderId is a validated, positive integer
  return this.ordersService.findById(orderId);
}

With pipes you ensure that every piece of data entering your handlers is correctly typed and valid, keeping your business logic clean and focused. In the next section, we’ll explore Guards and Authorization to control access to your endpoints.

8. Guards & Authorization

Guards sit in the request lifecycle after pipes and before interceptors/controllers. They determine whether a given request should be allowed to proceed based on custom logic. This is ideal for authentication, role checks, or feature flags.

8.1 Implementing Guards

A Guard is a class that implements the CanActivate interface, with a single method:

canActivate(context: ExecutionContext): boolean | Promise<boolean> | Observable<boolean>;

• ExecutionContext gives you access to the underlying request/response and route metadata.

• If canActivate returns true, the request continues. Returning false or throwing an exception (for example, UnauthorizedException) blocks it.

You register guards either globally, at the controller level, or on individual routes with the @UseGuards() decorator.

Here’s how guards work:

1. Creating a simple auth guard:

// auth.guard.ts
import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from '@nestjs/common';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const req = context.switchToHttp().getRequest();
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      throw new UnauthorizedException('Missing or invalid authorization header');
    }
    // Basic token check (replace with real validation)
    const token = authHeader.split(' ')[1];
    if (token !== 'valid-token') {
      throw new UnauthorizedException('Invalid token');
    }
    // Attach user info if needed:
    req.user = { id: 1, name: 'Alice' };
    return true;
  }
}

2. Applying the guard

• Globally (in main.ts):

    import { NestFactory } from '@nestjs/core';
    import { AppModule } from './app.module';
    import { AuthGuard } from './auth.guard';
  
    async function bootstrap() {
      const app = await NestFactory.create(AppModule);
      // every incoming request passes through AuthGuard
      app.useGlobalGuards(new AuthGuard());
      await app.listen(3000);
    }
    bootstrap();
  

• Controller-Level:

    import { Controller, Get, UseGuards } from '@nestjs/common';
    import { AuthGuard } from './auth.guard';
  
    @Controller('profile')
    @UseGuards(AuthGuard)       // applies to all routes in this controller
    export class ProfileController {
      @Get()
      getProfile(@Req() req) {
        return req.user;
      }
    }
  

• Route-Level:

    @Get('admin')
    @UseGuards(AdminGuard, AuthGuard)  // chain multiple guards
    getAdminData() { /* ... */ }
  

8.2 Role-Based Access Control

Beyond plain authentication, you often need authorization – ensuring a user has the correct role or permission. You can build a guard that reads metadata (for example, required roles) and verifies user claims.

Here’s how it works:

1. Define a roles decorator:

// roles.decorator.ts
import { SetMetadata } from '@nestjs/common';
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

2. Create a roles guard:

// roles.guard.ts
import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredRoles = this.reflector.get<string[]>('roles', context.getHandler());
    if (!requiredRoles) {
      return true; // no roles metadata => open route
    }
    const { user } = context.switchToHttp().getRequest();
    const hasRole = requiredRoles.some(role => user.roles?.includes(role));
    if (!hasRole) {
      throw new ForbiddenException('You do not have permission (roles)');
    }
    return true;
  }
}

3. Apply roles metadata and guard:

@Controller('projects')
@UseGuards(AuthGuard, RolesGuard)
export class ProjectsController {
  @Get()
  @Roles('user', 'admin')         // route requires either 'user' or 'admin'
  findAll() { /* ... */ }

  @Post()
  @Roles('admin')                 // only 'admin' can create
  create() { /* ... */ }
}

With this setup:

• AuthGuard ensures the request is authenticated and populates req.user.

• RolesGuard reads the @Roles() metadata to enforce role-based access.

Guards give you a powerful, declarative way to enforce security and authorization policies. In the next section, we’ll cover Exception Filters – how to catch and format errors centrally, keeping your controllers clean.

9. Exception Filters

Exception filters let you centralize error handling, transforming thrown exceptions into consistent HTTP responses or other formats. You can rely on Nest’s built-in behavior for many cases, but custom filters give you control over logging, response shape, or handling non-HTTP errors.

9.1 Handling Errors Gracefully

By default, if a controller or service throws an HttpException (or one of Nest’s built-in exceptions like NotFoundException, BadRequestException, and so on), Nest catches it and sends an appropriate HTTP response with status code and JSON body containing statusCode, message, and error.

If an unexpected error (for example, a runtime error) bubbles up, Nest uses its default exception filter to return a 500 Internal Server Error with a generic message.

Controllers/services should throw exceptions rather than return error codes manually, so the framework can format consistently.

Here’s how it works:

// users.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';

@Injectable()
export class UsersService {
  private users = [{ id: 1, name: 'Alice' }];

  findOne(id: number) {
    const user = this.users.find(u => u.id === id);
    if (!user) {
      // results in 404 with JSON { statusCode: 404, message: 'User #2 not found', error: 'Not Found' }
      throw new NotFoundException(`User #${id} not found`);
    }
    return user;
  }
}

// users.controller.ts
import { Controller, Get, Param, ParseIntPipe } from '@nestjs/common';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get(':id')
  getUser(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.findOne(id);
  }
}

If findOne throws, Nest’s default filter sends a structured JSON error. For unexpected errors (like a thrown Error), Nest wraps it into a 500 response.

9.2 Creating Custom Filters

You can implement the ExceptionFilter interface or extend BaseExceptionFilter. Just use the @Catch() decorator to target specific exception types (or leave empty to catch all).

In catch(exception, host), you can extract context (HTTP request/response) and shape your response (for example, add metadata, custom fields, or a uniform envelope). You can also log exceptions or report to external systems here.

You can apply filters globally, to a controller, or to an individual route.

Here’s how it works:

1. Simple logging filter
   Catch all exceptions, log details, then delegate to default behavior:

    // logging-exception.filter.ts
    import {
      ExceptionFilter,
      Catch,
      ArgumentsHost,
      HttpException,
      HttpStatus,
      Logger,
    } from '@nestjs/common';
    import { BaseExceptionFilter } from '@nestjs/core';
   
    @Catch() // no args = catch every exception
    export class LoggingExceptionFilter extends BaseExceptionFilter {
      private readonly logger = new Logger(LoggingExceptionFilter.name);
   
      catch(exception: unknown, host: ArgumentsHost) {
        const ctx = host.switchToHttp();
        const req = ctx.getRequest<Request>();
        const res = ctx.getResponse();
   
        // Log stack or message
        if (exception instanceof Error) {
          this.logger.error(`Error on ${req.method} ${req.url}`, exception.stack);
        } else {
          this.logger.error(`Unknown exception on ${req.method} ${req.url}`);
        }
   
        // Delegate to default filter for HTTP exceptions or generic 500
        super.catch(exception, host);
      }
    }
   

   Apply globally in main.ts:

    async function bootstrap() {
      const app = await NestFactory.create(AppModule);
      app.useGlobalFilters(new LoggingExceptionFilter(app.get(HttpAdapterHost)));
      await app.listen(3000);
    }
   

   (If extending BaseExceptionFilter, pass the adapter host to the constructor or super as needed.)

2. Custom response shape
   Suppose you want all errors to return { success: false, error: { code, message } }:

    // custom-response.filter.ts
    import {
      ExceptionFilter,
      Catch,
      ArgumentsHost,
      HttpException,
      HttpStatus,
    } from '@nestjs/common';
   
    @Catch()
    export class CustomResponseFilter implements ExceptionFilter {
      catch(exception: unknown, host: ArgumentsHost) {
        const ctx = host.switchToHttp();
        const response = ctx.getResponse();
        const request = ctx.getRequest<Request>();
   
        let status: number;
        let message: string | object;
   
        if (exception instanceof HttpException) {
          status = exception.getStatus();
          const res = exception.getResponse();
          // res might be a string or object
          message = typeof res === 'string' ? { message: res } : res;
        } else {
          status = HttpStatus.INTERNAL_SERVER_ERROR;
          message = { message: 'Internal server error' };
        }
   
        response.status(status).json({
          success: false,
          error: {
            statusCode: status,
            ...(
              typeof message === 'object'
                ? message
                : { message }
            ),
          },
          timestamp: new Date().toISOString(),
          path: request.url,
        });
      }
    }
   

   Apply at controller or route level:

    @Controller('orders')
    @UseFilters(CustomResponseFilter)
    export class OrdersController {
      // ...
    }
   

3. Catching specific exceptions
   If you have a custom exception class:

    export class PaymentFailedException extends HttpException {
      constructor(details: string) {
        super({ message: 'Payment failed', details }, HttpStatus.PAYMENT_REQUIRED);
      }
    }
   

   You can write a filter that only catches that:

    @Catch(PaymentFailedException)
    export class PaymentFailedFilter implements ExceptionFilter {
      catch(exception: PaymentFailedException, host: ArgumentsHost) {
        const ctx = host.switchToHttp();
        const res = ctx.getResponse();
        const status = exception.getStatus();
        const { message, details } = exception.getResponse() as any;
        res.status(status).json({
          error: {
            message,
            details,
          },
          help: 'Please verify your payment method and retry.',
        });
      }
    }
   

   Then apply only where payments occur:

    @Post('charge')
    @UseFilters(PaymentFailedFilter)
    charge() {
      // ...
    }
   

With exception filters in place, you ensure a consistent error contract, centralized logging or reporting, and tailored handling of different error types. Next up: Interceptors and Logging, where we’ll see how to transform responses, measure performance, and hook around method execution.

10. Interceptors & Logging

Interceptors wrap around method execution, letting you transform responses, bind extra logic before/after method calls, or measure performance. They’re ideal for cross-cutting concerns like logging, response shaping, caching, or timing metrics.

10.1 Transforming Responses

An Interceptor implements the NestInterceptor interface with an intercept(context, next) method.

Inside intercept, you typically call next.handle() which returns an Observable of the handler’s result. You can then apply RxJS operators (like map) to modify the data before it’s sent to the client.

Common uses are wrapping all responses in a uniform envelope, filtering out certain fields, or adding metadata.

Here’s how it works:

1. Basic response wrapper
   Suppose you want every successful response to be { success: true, data: <original> }.

    // response.interceptor.ts
    import {
      Injectable,
      NestInterceptor,
      ExecutionContext,
      CallHandler,
    } from '@nestjs/common';
    import { Observable } from 'rxjs';
    import { map } from 'rxjs/operators';
   
    @Injectable()
    export class ResponseInterceptor implements NestInterceptor {
      intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
        return next.handle().pipe(
          map(data => ({
            success: true,
            data,
          })),
        );
      }
    }
   

   Apply globally in main.ts:

    import { NestFactory } from '@nestjs/core';
    import { AppModule } from './app.module';
    import { ResponseInterceptor } from './common/response.interceptor';
   
    async function bootstrap() {
      const app = await NestFactory.create(AppModule);
      app.useGlobalInterceptors(new ResponseInterceptor());
      await app.listen(3000);
    }
    bootstrap();
   

   Now, if a controller method returns { id: 1, name: 'Alice' }, the client sees:

    {
      "success": true,
      "data": { "id": 1, "name": "Alice" }
    }
   

2. Filtering sensitive fields
   You might want to strip out fields like password before sending a user object:

    // sanitize.interceptor.ts
    import {
      Injectable,
      NestInterceptor,
      ExecutionContext,
      CallHandler,
    } from '@nestjs/common';
    import { Observable } from 'rxjs';
    import { map } from 'rxjs/operators';
   
    @Injectable()
    export class SanitizeInterceptor implements NestInterceptor {
      intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
        return next.handle().pipe(
          map(data => {
            if (data && typeof data === 'object') {
              const { password, ...rest } = data;
              return rest;
            }
            return data;
          }),
        );
      }
    }
   

   Apply at controller or route:

    @Controller('users')
    @UseInterceptors(SanitizeInterceptor)
    export class UsersController {
      @Get(':id')
      getUser(@Param('id') id: string) {
        // returns a user object with a password field internally,
        // but interceptor strips it before sending to client
        return this.usersService.findOne(+id);
      }
    }
   

3. Serializing with class-transformer
   If you use classes with decorators, you can integrate with class-transformer:

    // user.entity.ts
    import { Exclude, Expose } from 'class-transformer';
   
    export class User {
      id: number;
      name: string;
   
      @Exclude()
      password: string;
   
      @Expose()
      get displayName(): string {
        return `${this.name} (#${this.id})`;
      }
    }
   

    // class-transform.interceptor.ts
    import {
      Injectable,
      NestInterceptor,
      ExecutionContext,
      CallHandler,
    } from '@nestjs/common';
    import { plainToInstance } from 'class-transformer';
    import { Observable } from 'rxjs';
    import { map } from 'rxjs/operators';
   
    @Injectable()
    export class ClassTransformInterceptor<T> implements NestInterceptor {
      constructor(private dto: new (...args: any[]) => T) {}
   
      intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
        return next.handle().pipe(
          map(data => {
            return plainToInstance(this.dto, data, {
              excludeExtraneousValues: true,
            });
          }),
        );
      }
    }
   

   Apply with a DTO:

    @Controller('users')
    export class UsersController {
      @Get(':id')
      @UseInterceptors(new ClassTransformInterceptor(User))
      getUser(@Param('id') id: string) {
        // service returns a plain object; interceptor transforms to User instance
        return this.usersService.findOne(+id);
      }
    }
   

10.2 Logging and Performance Metrics

Interceptors can also measure execution time or log request/response details. You capture timestamps before and after next.handle(), logging the difference. This helps monitor slow endpoints. Combined with a logging framework or Nest’s Logger, you can standardize logs.

Here’s how it works:

1. Timing interceptor
   Logs how long each request-handler takes:

    // logging.interceptor.ts
    import {
      Injectable,
      NestInterceptor,
      ExecutionContext,
      CallHandler,
      Logger,
    } from '@nestjs/common';
    import { Observable } from 'rxjs';
    import { tap } from 'rxjs/operators';
   
    @Injectable()
    export class LoggingInterceptor implements NestInterceptor {
      private readonly logger = new Logger(LoggingInterceptor.name);
   
      intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
        const req = context.switchToHttp().getRequest();
        const method = req.method;
        const url = req.url;
        const now = Date.now();
        return next.handle().pipe(
          tap(() => {
            const elapsed = Date.now() - now;
            this.logger.log(`${method} ${url} - ${elapsed}ms`);
          }),
        );
      }
    }
   

   Apply globally:

    async function bootstrap() {
      const app = await NestFactory.create(AppModule);
      app.useGlobalInterceptors(new LoggingInterceptor());
      await app.listen(3000);
    }
   

   Now each request logs something like:

    [LoggingInterceptor] GET /users/1 - 35ms
   

2. Detailed request/response logging
   For more detail, log request body or response size (careful with sensitive data):

    // detailed-logging.interceptor.ts
    import {
      Injectable,
      NestInterceptor,
      ExecutionContext,
      CallHandler,
      Logger,
    } from '@nestjs/common';
    import { Observable } from 'rxjs';
    import { tap, map } from 'rxjs/operators';
   
    @Injectable()
    export class DetailedLoggingInterceptor implements NestInterceptor {
      private readonly logger = new Logger('HTTP');
   
      intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
        const ctx = context.switchToHttp();
        const req = ctx.getRequest<Request>();
        const { method, url, body } = req;
        const now = Date.now();
   
        this.logger.log(`Incoming ${method} ${url} - body: ${JSON.stringify(body)}`);
   
        return next.handle().pipe(
          map(data => {
            const elapsed = Date.now() - now;
            this.logger.log(`Response ${method} ${url} - ${elapsed}ms - data: ${JSON.stringify(data)}`);
            return data;
          }),
        );
      }
    }
   

   Apply conditionally: perhaps only in development:

    if (process.env.NODE_ENV !== 'production') {
      app.useGlobalInterceptors(new DetailedLoggingInterceptor());
    }
   

3. Combining with guards/pipes
   Since interceptors run after guards and before the response is sent, logging time captures the full handler including service calls, but after validation/authorization. That ensures you measure only authorized requests and valid data flows.

Interceptors offer a flexible way to wrap your handlers with extra behavior: transforming outputs, sanitizing data, timing execution, or adding headers. In the next section, we’ll explore Database integration to see how you can integrate your data layer in Nest.

11. Database Integration

In many real-world applications, persisting data is essential. NestJS offers first-class support and integrations for several database technologies. In this section we cover three common approaches:

• TypeORM with NestJS (relational databases, Active Record/Data Mapper style)

• Mongoose (MongoDB) (NoSQL document store)

• Prisma (Type-safe query builder/ORM alternative)

For each, we’ll explain the theory – when and why to choose it – and show concise practical examples of setup and usage in a NestJS context.

11.1 TypeORM with NestJS

TypeORM is a popular ORM for Node.js that supports multiple relational databases (PostgreSQL, MySQL, SQLite, SQL Server, and so on), offering both Active Record and Data Mapper patterns.

In NestJS, the @nestjs/typeorm package wraps TypeORM to provide:

• Automatic connection management via TypeOrmModule.forRoot()

• Module-scoped repositories/entities via TypeOrmModule.forFeature()

• Dependency injection for repositories and the DataSource/Connection

• Entity decorators (@Entity(), @Column(), and so on) for schema definition

• Migrations and advanced features via TypeORM CLI or programmatic usage

When to choose TypeORM

Type ORM is useful in several scenarios. Use it when your data is relational and you want a full-featured ORM with decorators and built-in migrations. It’s also great if you prefer to work with classes/entities and automatically map them to tables. And it’s a great choice if you value built-in features like eager/lazy relations, cascading, query builders, and repository patterns.

Here’s how to use it:

1. Install dependencies:

    npm install --save @nestjs/typeorm typeorm reflect-metadata
    # Also install the database driver; e.g., for Postgres:
    npm install --save pg
   

2. Configure the root module:

   In app.module.ts, import TypeOrmModule.forRoot() with connection options. These can come from environment variables (discussed later in Configuration Management).

    // src/app.module.ts
    import { Module } from '@nestjs/common';
    import { TypeOrmModule } from '@nestjs/typeorm';
    import { UsersModule } from './users/users.module';
   
    @Module({
      imports: [
        TypeOrmModule.forRoot({
          type: 'postgres',
          host: process.env.DB_HOST || 'localhost',
          port: +process.env.DB_PORT || 5432,
          username: process.env.DB_USER || 'postgres',
          password: process.env.DB_PASS || 'password',
          database: process.env.DB_NAME || 'mydb',
          entities: [__dirname + '/**/*.entity{.ts,.js}'],
          synchronize: false, // recommended false in production; use migrations
          // logging: true,
        }),
        UsersModule,
        // ...other modules
      ],
    })
    export class AppModule {}
   

   • synchronize: true can auto-sync schema in development, but in production prefer migrations.

   • Entities are auto-loaded via glob. Ensure path matches compiled output.

3. Define an entity:

   Create an entity class with decorators:

    // src/users/user.entity.ts
    import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn } from 'typeorm';
   
    @Entity({ name: 'users' })
    export class User {
      @PrimaryGeneratedColumn()
      id: number;
   
      @Column({ unique: true })
      email: string;
   
      @Column()
      password: string;
   
      @Column({ nullable: true })
      name?: string;
   
      @CreateDateColumn()
      createdAt: Date;
   
      @UpdateDateColumn()
      updatedAt: Date;
    }
   

4. Set up the feature module:

    // src/users/users.module.ts
    import { Module } from '@nestjs/common';
    import { TypeOrmModule } from '@nestjs/typeorm';
    import { UsersService } from './users.service';
    import { UsersController } from './users.controller';
    import { User } from './user.entity';
   
    @Module({
      imports: [TypeOrmModule.forFeature([User])],
      providers: [UsersService],
      controllers: [UsersController],
      exports: [UsersService], // if other modules need UsersService
    })
    export class UsersModule {}
   

5. Inject the repository:

   In the service, inject the Repository<User>:

    // src/users/users.service.ts
    import { Injectable, NotFoundException } from '@nestjs/common';
    import { InjectRepository } from '@nestjs/typeorm';
    import { Repository } from 'typeorm';
    import { User } from './user.entity';
    import { CreateUserDto } from './dto/create-user.dto';
   
    @Injectable()
    export class UsersService {
      constructor(
        @InjectRepository(User)
        private readonly userRepository: Repository<User>,
      ) {}
   
      async create(dto: CreateUserDto): Promise<User> {
        const user = this.userRepository.create(dto); // maps DTO fields to entity
        return this.userRepository.save(user);
      }
   
      async findAll(): Promise<User[]> {
        return this.userRepository.find();
      }
   
      async findOne(id: number): Promise<User> {
        const user = await this.userRepository.findOne({ where: { id } });
        if (!user) {
          throw new NotFoundException(`User #${id} not found`);
        }
        return user;
      }
   
      async update(id: number, dto: Partial<CreateUserDto>): Promise<User> {
        const user = await this.findOne(id);
        Object.assign(user, dto);
        return this.userRepository.save(user);
      }
   
      async remove(id: number): Promise<void> {
        await this.userRepository.delete(id);
      }
    }
   

6. Use in controller:

    // src/users/users.controller.ts
    import { Controller, Get, Post, Body, Param, ParseIntPipe, Put, Delete } from '@nestjs/common';
    import { UsersService } from './users.service';
    import { CreateUserDto } from './dto/create-user.dto';
   
    @Controller('users')
    export class UsersController {
      constructor(private readonly usersService: UsersService) {}
   
      @Post()
      create(@Body() dto: CreateUserDto) {
        return this.usersService.create(dto);
      }
   
      @Get()
      findAll() {
        return this.usersService.findAll();
      }
   
      @Get(':id')
      findOne(@Param('id', ParseIntPipe) id: number) {
        return this.usersService.findOne(id);
      }
   
      @Put(':id')
      update(
        @Param('id', ParseIntPipe) id: number,
        @Body() dto: Partial<CreateUserDto>,
      ) {
        return this.usersService.update(id, dto);
      }
   
      @Delete(':id')
      remove(@Param('id', ParseIntPipe) id: number) {
        return this.usersService.remove(id);
      }
    }
   

7. Migrations (optional but recommended)

   • Use TypeORM CLI or programmatic migrations.

   • Configure a separate ormconfig or supply options in code.

   • Generate and run migrations to evolve schema without data loss.

11.2 Mongoose (MongoDB)

Mongoose is a widely used ODM (Object Document Mapper) for MongoDB. In NestJS, @nestjs/mongoose integrates Mongoose to:

• Define schemas via classes and decorators (@Schema(), @Prop())

• Register models in modules with MongooseModule.forFeature()

• Manage the MongoDB connection with MongooseModule.forRoot()

• Inject Mongoose Model instances into services

• Work with documents in a type-safe way (with interfaces/types)

• Leverage features like hooks, virtuals, and validation at schema level

When to choose Mongoose

Mongoose is a good choice if you need a document-oriented, schema-less/ schematized NoSQL store. It’s also great if your data shapes may vary, or you prefer MongoDB’s flexible schema. And it’s helpful if you want features like middleware hooks in schema (pre/post save), virtuals, and so on.

Here’s how to use it:

1. Install dependencies:

    npm install --save @nestjs/mongoose mongoose
   

2. Configure root module:

    // src/app.module.ts
    import { Module } from '@nestjs/common';
    import { MongooseModule } from '@nestjs/mongoose';
    import { CatsModule } from './cats/cats.module';
   
    @Module({
      imports: [
        MongooseModule.forRoot(process.env.MONGO_URI || 'mongodb://localhost/nest'),
        CatsModule,
        // ...other modules
      ],
    })
    export class AppModule {}
   

3. Define a schema and document:

   Use decorators and interfaces:

    // src/cats/schemas/cat.schema.ts
    import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
    import { Document } from 'mongoose';
   
    @Schema({ timestamps: true })
    export class Cat extends Document {
      @Prop({ required: true })
      name: string;
   
      @Prop()
      age: number;
   
      @Prop()
      breed: string;
    }
   
    export const CatSchema = SchemaFactory.createForClass(Cat);
   

   • Extending Document gives the Mongoose document methods and properties.

   • timestamps: true auto-adds createdAt and updatedAt.

   • You can add hooks:

       CatSchema.pre<Cat>('save', function (next) {
         // e.g., modify data or log before saving
         next();
       });
     

4. Set up feature module:

    // src/cats/cats.module.ts
    import { Module } from '@nestjs/common';
    import { MongooseModule } from '@nestjs/mongoose';
    import { CatsService } from './cats.service';
    import { CatsController } from './cats.controller';
    import { Cat, CatSchema } from './schemas/cat.schema';
   
    @Module({
      imports: [
        MongooseModule.forFeature([{ name: Cat.name, schema: CatSchema }]),
      ],
      controllers: [CatsController],
      providers: [CatsService],
    })
    export class CatsModule {}
   

5. Inject the model:

   In the service, inject Model<Cat>:

    // src/cats/cats.service.ts
    import { Injectable, NotFoundException } from '@nestjs/common';
    import { InjectModel } from '@nestjs/mongoose';
    import { Model } from 'mongoose';
    import { Cat } from './schemas/cat.schema';
    import { CreateCatDto } from './dto/create-cat.dto';
    import { UpdateCatDto } from './dto/update-cat.dto';
   
    @Injectable()
    export class CatsService {
      constructor(
        @InjectModel(Cat.name) private readonly catModel: Model<Cat>,
      ) {}
   
      async create(dto: CreateCatDto): Promise<Cat> {
        const created = new this.catModel(dto);
        return created.save();
      }
   
      async findAll(): Promise<Cat[]> {
        return this.catModel.find().exec();
      }
   
      async findOne(id: string): Promise<Cat> {
        const cat = await this.catModel.findById(id).exec();
        if (!cat) {
          throw new NotFoundException(`Cat ${id} not found`);
        }
        return cat;
      }
   
      async update(id: string, dto: UpdateCatDto): Promise<Cat> {
        const updated = await this.catModel
          .findByIdAndUpdate(id, dto, { new: true })
          .exec();
        if (!updated) {
          throw new NotFoundException(`Cat ${id} not found`);
        }
        return updated;
      }
   
      async remove(id: string): Promise<void> {
        const res = await this.catModel.findByIdAndDelete(id).exec();
        if (!res) {
          throw new NotFoundException(`Cat ${id} not found`);
        }
      }
    }
   

6. Use in controller:

    // src/cats/cats.controller.ts
    import { Controller, Get, Post, Body, Param, Put, Delete } from '@nestjs/common';
    import { CatsService } from './cats.service';
    import { CreateCatDto } from './dto/create-cat.dto';
    import { UpdateCatDto } from './dto/update-cat.dto';
   
    @Controller('cats')
    export class CatsController {
      constructor(private readonly catsService: CatsService) {}
   
      @Post()
      create(@Body() dto: CreateCatDto) {
        return this.catsService.create(dto);
      }
   
      @Get()
      findAll() {
        return this.catsService.findAll();
      }
   
      @Get(':id')
      findOne(@Param('id') id: string) {
        return this.catsService.findOne(id);
      }
   
      @Put(':id')
      update(
        @Param('id') id: string,
        @Body() dto: UpdateCatDto,
      ) {
        return this.catsService.update(id, dto);
      }
   
      @Delete(':id')
      remove(@Param('id') id: string) {
        return this.catsService.remove(id);
      }
    }
   

7. Advanced Mongoose features

   • Virtuals: define computed properties not stored in DB.

   • Indexes: via schema options or @Prop({ index: true }).

   • Populate: reference other collections with @Prop({ type: Types.ObjectId, ref: 'OtherModel' }).

   • Transactions: use MongoDB sessions for multi-document atomic operations.

11.3 Prisma

Prisma is a modern ORM/Query Builder that generates a type-safe client based on a schema definition. It supports relational databases (PostgreSQL, MySQL, SQLite, SQL Server, and more).

Here are some of its key features:

• Type-safe queries: Autogenerated TypeScript definitions prevent many runtime errors.

• Prisma schema: A declarative .prisma file to define models, relations, and enums.

• Migrations: prisma migrate for evolving schema.

• Performance: Lean query builder without heavy runtime overhead.

• Flexibility: Supports raw queries when needed.

When to choose Prisma

Prisma is a great choice if you prefer a schema-first approach with a clear DSL and auto-generated type-safe client. It’s also great if you want modern features like efficient migrations, rich type inference, and a straightforward developer experience. And it’s a solid choice if you don’t need Active Record pattern. Instead, you use the Prisma client in services.

Here’s how it works:

1. Install dependencies and initialize:

    npm install @prisma/client
    npm install -D prisma
    npx prisma init
   

   This creates a prisma/schema.prisma file and a .env with DATABASE_URL.

2. Define the schema:

   In prisma/schema.prisma:

    datasource db {
      provider = "postgresql"
      url      = env("DATABASE_URL")
    }
   
    generator client {
      provider = "prisma-client-js"
    }
   
    model User {
      id        Int      @id @default(autoincrement())
      email     String   @unique
      name      String?
      posts     Post[]
      createdAt DateTime @default(now())
      updatedAt DateTime @updatedAt
    }
   
    model Post {
      id        Int      @id @default(autoincrement())
      title     String
      content   String?
      author    User     @relation(fields: [authorId], references: [id])
      authorId  Int
      published Boolean  @default(false)
      createdAt DateTime @default(now())
      updatedAt DateTime @updatedAt
    }
   

3. Run migrations and generate client:

    npx prisma migrate dev --name init
    npx prisma generate
   

   This updates the database schema and regenerates the TypeScript client.

4. Create a PrismaService in NestJS:

   A common pattern is to wrap the PrismaClient in an injectable service, handling lifecycle hooks.

    // src/prisma/prisma.service.ts
    import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
    import { PrismaClient } from '@prisma/client';
   
    @Injectable()
    export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
      async onModuleInit() {
        await this.$connect();
      }
   
      async onModuleDestroy() {
        await this.$disconnect();
      }
    }
   

5. Register PrismaService in a module:

    // src/prisma/prisma.module.ts
    import { Module } from '@nestjs/common';
    import { PrismaService } from './prisma.service';
   
    @Module({
      providers: [PrismaService],
      exports: [PrismaService],
    })
    export class PrismaModule {}
   

   Then import PrismaModule in any feature module needing DB access.

6. Use in a feature service:

    // src/users/users.service.ts
    import { Injectable } from '@nestjs/common';
    import { PrismaService } from '../prisma/prisma.service';
    import { CreateUserDto } from './dto/create-user.dto';
   
    @Injectable()
    export class UsersService {
      constructor(private readonly prisma: PrismaService) {}
   
      async create(dto: CreateUserDto) {
        return this.prisma.user.create({ data: dto });
      }
   
      async findAll() {
        return this.prisma.user.findMany();
      }
   
      async findOne(id: number) {
        return this.prisma.user.findUnique({ where: { id } });
      }
   
      async update(id: number, dto: Partial<CreateUserDto>) {
        return this.prisma.user.update({
          where: { id },
          data: dto,
        });
      }
   
      async remove(id: number) {
        await this.prisma.user.delete({ where: { id } });
        return { deleted: true };
      }
    }
   

   Note: DTO fields must align with Prisma schema types. Prisma client methods return typed results.

7. Inject in controller:

    // src/users/users.controller.ts
    import { Controller, Get, Post, Body, Param, ParseIntPipe, Put, Delete } from '@nestjs/common';
    import { UsersService } from './users.service';
    import { CreateUserDto } from './dto/create-user.dto';
   
    @Controller('users')
    export class UsersController {
      constructor(private readonly usersService: UsersService) {}
   
      @Post()
      create(@Body() dto: CreateUserDto) {
        return this.usersService.create(dto);
      }
   
      @Get()
      findAll() {
        return this.usersService.findAll();
      }
   
      @Get(':id')
      findOne(@Param('id', ParseIntPipe) id: number) {
        return this.usersService.findOne(id);
      }
   
      @Put(':id')
      update(
        @Param('id', ParseIntPipe) id: number,
        @Body() dto: Partial<CreateUserDto>,
      ) {
        return this.usersService.update(id, dto);
      }
   
      @Delete(':id')
      remove(@Param('id', ParseIntPipe) id: number) {
        return this.usersService.remove(id);
      }
    }
   

8. Advanced Prisma usage

   • Relations and nested writes: for example, create a post with nested author connect/create.

   • Transactions: this.prisma.$transaction([...]) for atomic operations.

   • Raw queries: this.prisma.$queryRaw when needed.

   • Middleware: Prisma supports middlewares on the client side.

   • Performance tuning: select only needed fields, use pagination patterns.

With these three approaches, you can choose the database integration strategy that best fits your application’s needs:

• TypeORM for a full-fledged ORM with decorators and migrations support in relational databases.

• Mongoose for flexible document schemas in MongoDB.

• Prisma for a modern, type-safe query builder/ORM alternative with excellent developer ergonomics.

In the next section, we’ll cover Configuration Management – how to handle environment variables and config modules in NestJS.

12. Configuration Management

Managing configuration cleanly is crucial for applications to behave correctly across environments (development, staging, production). NestJS provides the @nestjs/config module to centralize configuration loading, validation, and injection.

12.1 @nestjs/config Module

The @nestjs/config module is a powerful utility for managing application configuration settings. Here are some of its key features:

• Centralized config: Instead of sprinkling process.env throughout your code, it uses a dedicated service that loads and validates configuration once at startup.

• Environment agnostic: It loads variables from .env files, environment variables, or other sources, with support for different files per environment.

• Validation: It integrates a schema (for example, via Joi) to ensure required variables are present and correctly typed, failing fast if misconfigured.

• Config Namespacing: It organizes related settings into logical groups (for example, database, auth, third-party APIs) via configuration factories.

• Injection: It injects a ConfigService to read config values in services or modules, with type safety when using custom typed wrappers.

Here’s how it works:

1. Install the package

    npm install @nestjs/config
    npm install joi    # if you plan to validate via Joi schemas
   

2. Import and initialize ConfigModule

   In your root module (AppModule), import ConfigModule.forRoot(). Typical options:

    // src/app.module.ts
    import { Module } from '@nestjs/common';
    import { ConfigModule } from '@nestjs/config';
    import configuration from './config/configuration';
    import { validationSchema } from './config/validation';
   
    @Module({
      imports: [
        ConfigModule.forRoot({
          // Load .env automatically; specify envFilePath if custom:
          isGlobal: true,           // makes ConfigService available app-wide
          envFilePath: ['.env.development.local', '.env.development', '.env'], 
          load: [configuration],    // optional: load custom config factory(s)
          validationSchema,         // optional: Joi schema to validate env vars
          validationOptions: {
            allowUnknown: true,
            abortEarly: true,
          },
        }),
        // ...other modules
      ],
    })
    export class AppModule {}
   

   • isGlobal: true avoids importing ConfigModule in every feature module.

   • envFilePath: an array lets you try multiple files (for example, local overrides before default).

   • load: array of functions returning partial config objects – see next step.

   • validationSchema: a Joi schema ensuring required variables exist and are correct type/format.

3. Define a configuration factory

   Organize related settings into a typed object:

    // src/config/configuration.ts
    export default () => ({
      port: parseInt(process.env.PORT, 10) || 3000,
      database: {
        host: process.env.DB_HOST,
        port: parseInt(process.env.DB_PORT, 10) || 5432,
        user: process.env.DB_USER,
        pass: process.env.DB_PASS,
        name: process.env.DB_NAME,
      },
      jwt: {
        secret: process.env.JWT_SECRET,
        expiresIn: process.env.JWT_EXPIRES_IN || '1h',
      },
      // add other namespaces as needed
    });
   

4. Validate environment variables

   Using Joi for validation:

    // src/config/validation.ts
    import * as Joi from 'joi';
   
    export const validationSchema = Joi.object({
      NODE_ENV: Joi.string()
        .valid('development', 'production', 'test', 'staging')
        .default('development'),
      PORT: Joi.number().default(3000),
      DB_HOST: Joi.string().required(),
      DB_PORT: Joi.number().default(5432),
      DB_USER: Joi.string().required(),
      DB_PASS: Joi.string().required(),
      DB_NAME: Joi.string().required(),
      JWT_SECRET: Joi.string().min(32).required(),
      JWT_EXPIRES_IN: Joi.string().default('1h'),
      // add other variables...
    });
   

   If validation fails at startup, the application will error out with details, preventing misconfigured deployments.

5. Inject ConfigService

   Anywhere you need config, inject ConfigService:

    // src/some/some.service.ts
    import { Injectable } from '@nestjs/common';
    import { ConfigService } from '@nestjs/config';
   
    @Injectable()
    export class SomeService {
      constructor(private readonly configService: ConfigService) {}
   
      getDbConfig() {
        const host = this.configService.get<string>('database.host');
        const port = this.configService.get<number>('database.port');
        // Use these values to configure a database client, etc.
        return { host, port };
      }
    }
   

   • Use dot notation for nested config: for example, 'jwt.secret'.

   • You can also read raw env vars via configService.get<string>('DB_HOST') if needed, but preferring structured config is clearer.

6. Typed wrapper for ConfigService (optional)

   For stronger typing, create an interface matching your configuration and a wrapper:

    // src/config/config.interface.ts
    export interface AppConfig {
      port: number;
      database: {
        host: string;
        port: number;
        user: string;
        pass: string;
        name: string;
      };
      jwt: {
        secret: string;
        expiresIn: string;
      };
    }
   

    // src/config/typed-config.service.ts
    import { Injectable } from '@nestjs/common';
    import { ConfigService } from '@nestjs/config';
    import { AppConfig } from './config.interface';
   
    @Injectable()
    export class TypedConfigService {
      constructor(private readonly configService: ConfigService) {}
   
      get appConfig(): AppConfig {
        return {
          port: this.configService.get<number>('port'),
          database: {
            host: this.configService.get<string>('database.host'),
            port: this.configService.get<number>('database.port'),
            user: this.configService.get<string>('database.user'),
            pass: this.configService.get<string>('database.pass'),
            name: this.configService.get<string>('database.name'),
          },
          jwt: {
            secret: this.configService.get<string>('jwt.secret'),
            expiresIn: this.configService.get<string>('jwt.expiresIn'),
          },
        };
      }
    }
   

   Register TypedConfigService in a module if you prefer injecting it instead of raw ConfigService.

7. Dynamic module registration using config

   Many Nest modules accept dynamic options. For example, TypeORM:

    // src/database/database.module.ts
    import { Module } from '@nestjs/common';
    import { TypeOrmModule } from '@nestjs/typeorm';
    import { ConfigService } from '@nestjs/config';
   
    @Module({
      imports: [
        TypeOrmModule.forRootAsync({
          inject: [ConfigService],
          useFactory: (config: ConfigService) => ({
            type: 'postgres',
            host: config.get<string>('database.host'),
            port: config.get<number>('database.port'),
            username: config.get<string>('database.user'),
            password: config.get<string>('database.pass'),
            database: config.get<string>('database.name'),
            entities: [__dirname + '/../**/*.entity{.ts,.js}'],
            synchronize: config.get('NODE_ENV') !== 'production',
          }),
        }),
      ],
    })
    export class DatabaseModule {}
   

   Using forRootAsync with useFactory ensures config is loaded before the module initializes.

12.2 Environment Variables

Environment variables serve as the bridge between code and its runtime environment, letting you decouple configuration (like database URLs, API keys, or feature flags) from your source.

By relying on environment variables, you ensure that the same application bundle can run safely across development, staging, and production – each providing its own sensitive or environment-specific settings without changing code. This is how it works:

• 12-Factor app principle: Stores config in the environment. Avoids hard-coding secrets or environment-specific settings in code.

• Separation of concerns: Code remains the same across environments. Behavior is driven by env vars or config files.

• Security: Keeps secrets (API keys, DB passwords) out of source control. Uses environment variables or secure vaults.

• Overrides and precedence: You may have multiple .env files (for example, .env, .env.local, .env.production) or CI/CD provided vars. It controls the order of loading.

• Defaults and fallbacks: Provides sensible defaults in code or config factories so the app can run in development without requiring every variable.

Here’s how to use it:

1. .env files

   • Create a .env file at project root with key-value pairs:

       PORT=3000
       DB_HOST=localhost
       DB_PORT=5432
       DB_USER=postgres
       DB_PASS=secret
       DB_NAME=mydb
       JWT_SECRET=supersecretjwtkey
       JWT_EXPIRES_IN=2h
     

   • Optionally create .env.development, .env.test, .env.production, and load them based on NODE_ENV.

   • Ensure .env files are in .gitignore to avoid committing secrets.

2. Loading order

   • With @nestjs/config, specify envFilePath as an array, for example:

       ConfigModule.forRoot({
         envFilePath: [
           `.env.${process.env.NODE_ENV}.local`,
           `.env.${process.env.NODE_ENV}`,
           `.env`,
         ],
         isGlobal: true,
       });
     

   • This tries .env.development.local, then .env.development, then .env. CI/CD can set actual environment variables that override values in files.

3. Accessing raw environment variables

   • While structured config is preferred, sometimes you need direct access:

       const raw = process.env.SOME_VAR;
     

   • Avoid scattering process.env in multiple places. Instead, prefer reading once in configuration factory and injecting via ConfigService.

4. Default values

   • In configuration factory or when reading via ConfigService, provide defaults:

       const port = configService.get<number>('PORT', 3000);
     

     or in factory:

       port: parseInt(process.env.PORT, 10) || 3000
     

5. Type coercion

   • Environment variables are strings by default. Convert to numbers or booleans as needed:

       const isProd = configService.get<string>('NODE_ENV') === 'production';
       const enableFeature = configService.get<string>('FEATURE_FLAG') === 'true';
       const timeout = parseInt(configService.get<string>('TIMEOUT_MS'), 10) || 5000;
     

6. Secret management

   • For sensitive data in production, consider using secret managers (AWS Secrets Manager, Vault) instead of plain .env. In that case, load secrets at startup (for example, via a custom provider or factory) and merge into the configuration.

   • Example: in useFactory, asynchronously fetch secrets and return a config object including them.

7. Runtime configuration changes

   • Generally configs are static at startup. If you need to reload config without restarting, implement a custom mechanism (for example, read from a database or remote config service periodically). Inject a service that fetches and caches values, but note this departs from 12-factor principles.

8. Validation in production

   • Always validate required env vars at startup so misconfigurations fail early. Use validationSchema with Joi or another validator.

   • Example error: if JWT_SECRET is missing or too short, the app should refuse to start, logging a clear error.

With configuration managed via @nestjs/config and environment variables, your NestJS app can adapt seamlessly across environments, keep secrets secure, and avoid environment-specific code changes. In the next section, we’ll cover Authentication strategies (JWT, OAuth2/social login).

13. Authentication

Handling authentication securely is a common requirement. In NestJS, you typically use Passport strategies alongside the @nestjs/jwt module for JWT-based flows, or OAuth2 strategies for social login.

Here, we’ll cover two common approaches:

• JWT Strategy: token-based authentication for APIs.

• OAuth2 / Social Login: integrating providers like Google or GitHub.

13.1 JWT Strategy

JSON Web Tokens (JWTs) are a compact, URL-safe means of representing claims between two parties. In an authentication context, the server issues a signed token containing user identity and possibly other claims, while the client stores and sends this token on subsequent requests (typically in the Authorization: Bearer <token> header).

Because the token is signed (and optionally encrypted), the server can verify its integrity and authenticity without needing to maintain session state in memory or a database. This stateless nature simplifies scaling and decouples services.

Tokens include an expiration (exp) so they automatically become invalid after a certain time. For longer-lived sessions, you can layer a refresh-token pattern on top.

In NestJS, we leverage @nestjs/jwt to sign and verify tokens and @nestjs/passport with passport-jwt to integrate a guard that checks incoming tokens. Below is how it works.

• JWT (JSON Web Token): a signed token containing claims (for example, user ID) that clients send in the Authorization header.

• Stateless: the server verifies the token signature without storing session state.

• Expiration: embed expiry (exp) so tokens auto-expire; possibly use refresh tokens for long-lived sessions.

• In NestJS, you use @nestjs/jwt to sign/verify tokens and @nestjs/passport with passport-jwt to implement the guard.

Here’s how to use it:

1. Install dependencies

    npm install @nestjs/jwt passport-jwt @nestjs/passport passport
   

2. Configuration

   Use ConfigService (from previous section) to load secrets and TTL:

    // src/auth/auth.config.ts
    export default () => ({
      jwt: {
        secret: process.env.JWT_SECRET || 'default-secret',
        expiresIn: process.env.JWT_EXPIRES_IN || '1h',
      },
    });
   

   Ensure ConfigModule.forRoot({ load: [authConfig], isGlobal: true, validationSchema: ... }) is set in AppModule.

3. AuthModule setup

    // src/auth/auth.module.ts
    import { Module } from '@nestjs/common';
    import { JwtModule } from '@nestjs/jwt';
    import { PassportModule } from '@nestjs/passport';
    import { ConfigService, ConfigModule } from '@nestjs/config';
    import { JwtStrategy } from './jwt.strategy';
    import { AuthService } from './auth.service';
    import { UsersModule } from '../users/users.module'; // assumes a UsersService
   
    @Module({
      imports: [
        UsersModule,
        PassportModule.register({ defaultStrategy: 'jwt' }),
        JwtModule.registerAsync({
          imports: [ConfigModule],
          inject: [ConfigService],
          useFactory: (config: ConfigService) => ({
            secret: config.get<string>('jwt.secret'),
            signOptions: { expiresIn: config.get<string>('jwt.expiresIn') },
          }),
        }),
      ],
      providers: [AuthService, JwtStrategy],
      exports: [AuthService],
    })
    export class AuthModule {}
   

4. AuthService

   Responsible for validating credentials and issuing tokens:

    // src/auth/auth.service.ts
    import { Injectable, UnauthorizedException } from '@nestjs/common';
    import { JwtService } from '@nestjs/jwt';
    import { UsersService } from '../users/users.service';
    import * as bcrypt from 'bcrypt';
   
    @Injectable()
    export class AuthService {
      constructor(
        private readonly usersService: UsersService,
        private readonly jwtService: JwtService,
      ) {}
   
      // Validate user credentials (email/password)
      async validateUser(email: string, pass: string) {
        const user = await this.usersService.findByEmail(email);
        if (user && (await bcrypt.compare(pass, user.password))) {
          // exclude password before returning
          const { password, ...result } = user;
          return result;
        }
        return null;
      }
   
      // Called after validateUser succeeds
      async login(user: any) {
        const payload = { sub: user.id, email: user.email };
        return {
          access_token: this.jwtService.sign(payload),
        };
      }
    }
   

5. JwtStrategy

    // src/auth/jwt.strategy.ts
    import { Injectable } from '@nestjs/common';
    import { PassportStrategy } from '@nestjs/passport';
    import { ExtractJwt, Strategy } from 'passport-jwt';
    import { ConfigService } from '@nestjs/config';
   
    @Injectable()
    export class JwtStrategy extends PassportStrategy(Strategy) {
      constructor(private readonly configService: ConfigService) {
        super({
          jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
          ignoreExpiration: false,
          secretOrKey: configService.get<string>('jwt.secret'),
        });
      }
   
      async validate(payload: any) {
        // payload.sub is user ID
        return { userId: payload.sub, email: payload.email };
        // returned value is assigned to req.user
      }
    }
   

6. Auth Controller

   Expose login endpoint:

    // src/auth/auth.controller.ts
    import { Controller, Post, Body, Request, UseGuards } from '@nestjs/common';
    import { AuthService } from './auth.service';
    import { LocalAuthGuard } from './local-auth.guard'; // optional if using local strategy
   
    @Controller('auth')
    export class AuthController {
      constructor(private readonly authService: AuthService) {}
   
      // Example: using a local strategy for email/password
      @UseGuards(LocalAuthGuard)
      @Post('login')
      async login(@Request() req) {
        // LocalAuthGuard attaches user to req.user
        return this.authService.login(req.user);
      }
   
      // Alternatively, implement login logic directly:
      @Post('login-basic')
      async loginBasic(@Body() body: { email: string; password: string }) {
        const user = await this.authService.validateUser(body.email, body.password);
        if (!user) {
          throw new UnauthorizedException('Invalid credentials');
        }
        return this.authService.login(user);
      }
    }
   

   • LocalAuthGuard would use a LocalStrategy to validate credentials via Passport.

7. Protecting routes

   Use the JwtAuthGuard:

    // src/auth/jwt-auth.guard.ts
    import { Injectable } from '@nestjs/common';
    import { AuthGuard } from '@nestjs/passport';
   
    @Injectable()
    export class JwtAuthGuard extends AuthGuard('jwt') {}
   

   Apply to controllers or routes:

    // src/profile/profile.controller.ts
    import { Controller, Get, UseGuards, Request } from '@nestjs/common';
    import { JwtAuthGuard } from '../auth/jwt-auth.guard';
   
    @Controller('profile')
    export class ProfileController {
      @UseGuards(JwtAuthGuard)
      @Get()
      getProfile(@Request() req) {
        return req.user; // { userId, email }
      }
    }
   

8. Refresh Tokens (optional)

   • Issue a refresh token (longer expiry) and store it (for example, in DB or as HTTP-only cookie).

   • Create a separate endpoint to issue new access token when the access token expires.

   • Verify refresh token validity (for example, compare stored token or a hashed version).

   • Implementation details vary – consider security best practices (rotate tokens, revoke on logout).

13.2 OAuth2 / Social Login

Social login via OAuth2 lets users authenticate with third-party providers (Google, GitHub, Facebook, and so on) without creating a separate password for your service.

Under the Authorization Code Flow, the user is redirected to the provider’s consent screen. After granting permission, the provider redirects back with a temporary code. The backend exchanges this code for access (and optionally refresh) tokens, fetches the user’s profile, and then you can link or create a local user record. Finally, you typically issue your own JWT (or session) so the client can call your secured APIs.

Keeping OAuth client IDs/secrets in environment variables (via ConfigService) ensures security and flexibility. Here’s how it works:

• OAuth2 Authorization Code Flow: Redirect the user to the provider’s consent screen. The provider redirects back with a code. The back-end exchanges code for tokens and retrieves user info.

• In server-side (NestJS) you use Passport strategies (for example, passport-google-oauth20, passport-github2).

• After getting user profile from provider, you look up or create a matching local user record, then issue your own JWT or session.

• Keep secrets (client ID/secret) in environment variables and load via ConfigService.

Here’s how to use it:

1. Install dependencies

    npm install @nestjs/passport passport passport-google-oauth20
    # or passport-facebook, passport-github2, etc.
   

2. Configuration

   Add OAuth credentials to env and ConfigModule:

    GOOGLE_CLIENT_ID=your-google-client-id
    GOOGLE_CLIENT_SECRET=your-google-client-secret
    GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback
   

3. OAuth Strategy

   Example: Google

    // src/auth/google.strategy.ts
    import { Injectable } from '@nestjs/common';
    import { PassportStrategy } from '@nestjs/passport';
    import { Strategy, VerifyCallback } from 'passport-google-oauth20';
    import { ConfigService } from '@nestjs/config';
    import { AuthService } from './auth.service';
   
    @Injectable()
    export class GoogleStrategy extends PassportStrategy(Strategy, 'google') {
      constructor(configService: ConfigService, private readonly authService: AuthService) {
        super({
          clientID: configService.get<string>('GOOGLE_CLIENT_ID'),
          clientSecret: configService.get<string>('GOOGLE_CLIENT_SECRET'),
          callbackURL: configService.get<string>('GOOGLE_CALLBACK_URL'),
          scope: ['email', 'profile'],
        });
      }
   
      async validate(accessToken: string, refreshToken: string, profile: any, done: VerifyCallback): Promise<any> {
        const { id, emails, displayName } = profile;
        const email = emails && emails[0]?.value;
        // Delegate to AuthService to find or create local user
        const user = await this.authService.validateOAuthLogin('google', id, email, displayName);
        done(null, user);
      }
    }
   

   In AuthService:

    // src/auth/auth.service.ts (add method)
    async validateOAuthLogin(provider: string, providerId: string, email: string, name?: string) {
      // Find existing user by provider+providerId or email
      let user = await this.usersService.findByProvider(provider, providerId);
      if (!user) {
        // Optionally check by email: if exists, link accounts; otherwise create new
        user = await this.usersService.createOAuthUser({ provider, providerId, email, name });
      }
      // Issue JWT or return user object; here we return minimal payload for login
      return user;
    }
   

4. AuthController endpoints

    // src/auth/auth.controller.ts
    import { Controller, Get, Req, UseGuards } from '@nestjs/common';
    import { AuthGuard } from '@nestjs/passport';
    import { AuthService } from './auth.service';
   
    @Controller('auth')
    export class AuthController {
      constructor(private readonly authService: AuthService) {}
   
      @Get('google')
      @UseGuards(AuthGuard('google'))
      async googleAuth(@Req() req) {
        // Initiates Google OAuth2 flow
      }
   
      @Get('google/callback')
      @UseGuards(AuthGuard('google'))
      async googleAuthRedirect(@Req() req) {
        // Google redirects here after consent; req.user set by GoogleStrategy.validate
        const user = req.user;
        // Issue JWT or set a cookie, then redirect or return token
        const jwt = await this.authService.login(user);
        // E.g., redirect with token as query, or set cookie:
        // res.redirect(`http://frontend-app.com?token=${jwt.access_token}`);
        return { access_token: jwt.access_token };
      }
    }
   

   • The first endpoint (/auth/google) triggers redirect to Google.

   • The callback endpoint handles the response, then issues your JWT.

5. Session vs. Stateless

   • Many examples use sessions and @nestjs/passport session support, but for APIs you often skip sessions: Passport still invokes validate, returns user, and you issue JWT immediately.

   • Ensure you disable sessions in PassportModule registration: PassportModule.register({ session: false }).

6. Multiple Providers

   • Repeat strategy setup for each provider (for example, GitHubStrategy).

   • In validateOAuthLogin, handle provider parameter to distinguish logic.

   • You can store in your user entity fields like googleId, githubId, and so on, or a separate table for OAuth accounts.

7. Protecting routes post-login

   • Clients use the issued JWT in Authorization: Bearer <token> to access protected endpoints via JwtAuthGuard.

   • If you prefer sessions/cookies, configure Nest to use sessions and Passport's session features, but for SPAs or mobile clients JWT is common.

8. Frontend considerations

   • Redirect URIs must match those configured in the OAuth provider console.

   • After receiving JWT, store it securely (for example, HTTP-only cookie or secure storage on client).

   • Handle token expiry: possibly combine OAuth refresh tokens or your own refresh token flow.

With JWT and OAuth2 strategies set up, your NestJS backend can support secured endpoints, user registration/login flows, and social logins.

Conclusion & Further Resources

Summary

We’ve walked through key aspects of building a NestJS application: its architectural patterns, core building blocks (modules, controllers, providers), dependency injection, routing and middleware, request lifecycle with pipes, guards, exception filters, interceptors, database integration options (TypeORM, Mongoose, Prisma), configuration management, authentication strategies (JWT, OAuth2), and strategies for migrating existing apps.

NestJS provides a structured, TypeScript-first framework that accelerates development of scalable, maintainable backends. By leveraging its module system and built-in integrations, you get consistency, testability, and clear separation of concerns out of the box.

Whether you choose a relational database via TypeORM, a document store with Mongoose, or Prisma’s type-safe client, you can plug these into Nest’s DI container and configuration module. Authentication flows – both JWT-based and social login – fit naturally into Nest’s Passport integration.

Overall, NestJS is well-suited for APIs, microservices, real-time apps, and enterprise backends where maintainability and developer experience matter.

Official Docs and Community Links

• NestJS Official Documentation: Comprehensive guide and API reference for all core features.

  • https://docs.nestjs.com

• GitHub Repository: Source code, issue tracker, and community contributions.

  • https://github.com/nestjs/nest

After looking at some examples, I have gained a clearer understanding of how to approach testing. So I wrote an article to record and share my learning to help others who may be facing similar confusion.

In addition, I have put together a demo project with the relevant unit and E2E tests completed, which may be of interest. I’ve uploaded the code to Github here.

Table of Contents

1. Prerequisites

2. Difference Between Unit Testing and E2E Testing

3. Writing Unit Tests

   • The First Test Case

   • The Second Test Case

   • Unit Test Coverage

4. Writing E2E Tests

5. Whether to Write Tests

   • Enhancing System Robustness

   • Enhancing Maintainability

   • Enhancing Development Efficiency

6. When Not to Write Tests?

7. Conclusion

8. Reference Materials

Prerequisites

Before diving into this tutorial, you should have:

• Basic knowledge of TypeScript and Node.js

• Familiarity with NestJS fundamentals

• Understanding of RESTful APIs

• MongoDB installed (as the example uses MongoDB)

• Node.js and npm/yarn installed on your system

• Basic understanding of testing concepts

You can find the complete code examples in the demo repository. You can clone it to follow along with the examples.

Difference Between Unit Testing and E2E Testing

Unit tests and E2E tests are methods of software testing, but they have different goals and scopes.

Unit testing involves checking and verifying the smallest testable unit within the software. A function or a method, for example, can be considered a unit. In unit testing, you provide expected outputs for various inputs of a function and validate the correctness of its operation. The goal of unit testing is to quickly identify bugs within the function, and they are easy to write and execute rapidly.

On the other hand, E2E tests often simulate real-world user scenarios to test the entire application. For instance, the frontend typically uses a browser or headless browser for testing, while the backend does so by simulating API calls.

Within a NestJS project, unit tests might assess a specific service or a method of a controller, such as verifying if the update method in the Users module correctly updates a user. An E2E test, however, may examine a complete user journey, from creating a new user to updating their password and eventually deleting the user, which involves multiple services and controllers.

How to Write Unit Tests

Writing unit tests for a utility function or method that doesn't involve interfaces is relatively straightforward. You only need to consider the various inputs and write the corresponding test code. But the situation becomes more complex once interfaces come into play. Let's use code as an example:

async validateUser(
  username: string,
  password: string,
): Promise<UserAccountDto> {
  const entity = await this.usersService.findOne({ username });
  if (!entity) {
    throw new UnauthorizedException('User not found');
  }
  if (entity.lockUntil && entity.lockUntil > Date.now()) {
    const diffInSeconds = Math.round((entity.lockUntil - Date.now()) / 1000);
    let message = `The account is locked. Please try again in ${diffInSeconds} seconds.`;
    if (diffInSeconds > 60) {
      const diffInMinutes = Math.round(diffInSeconds / 60);
      message = `The account is locked. Please try again in ${diffInMinutes} minutes.`;
    }
    throw new UnauthorizedException(message);
  }
  const passwordMatch = bcrypt.compareSync(password, entity.password);
  if (!passwordMatch) {
    // $inc update to increase failedLoginAttempts
    const update = {
      $inc: { failedLoginAttempts: 1 },
    };
    // lock account when the third try is failed
    if (entity.failedLoginAttempts + 1 >= 3) {
      // $set update to lock the account for 5 minutes
      update['$set'] = { lockUntil: Date.now() + 5 * 60 * 1000 };
    }
    await this.usersService.update(entity._id, update);
    throw new UnauthorizedException('Invalid password');
  }
  // if validation is sucessful, then reset failedLoginAttempts and lockUntil
  if (
    entity.failedLoginAttempts > 0 ||
    (entity.lockUntil && entity.lockUntil > Date.now())
  ) {
    await this.usersService.update(entity._id, {
      $set: { failedLoginAttempts: 0, lockUntil: null },
    });
  }
  return { userId: entity._id, username } as UserAccountDto;
}

The code above is a method validateUser in the auth.service.ts file, primarily used to verify whether the username and password entered by the user during login are correct. It contains the following logic:

1. Check if the user exists based on username. If not, throw a 401 exception (a 404 exception is also feasible).

2. See if the user is locked out. If so, throw a 401 exception with a relevant message.

3. Encrypt the password and compare it with the password in the database. If it's incorrect, throw a 401 exception (three consecutive failed login attempts will lock the account for 5 minutes).

4. If the login is successful, clear any previously failed login attempt counts (if applicable) and return the user id and username to the next stage.

As you can see, the validateUser method includes four processing logics. So we need to write corresponding unit test code for these four points to ensure that the entire validateUser function is operating correctly.

The First Test Case

When we start writing unit tests, we encounter a problem: the findOne method needs to interact with the database, and it looks for corresponding users in the database through username. But if every unit test has to interact with the database, the testing will become very cumbersome. So we can mock fake data to achieve this.

For example, assume we have registered a user named woai3c. Then, during login, the user data can be retrieved in the validateUser method through const entity = await this.usersService.findOne({ username });. As long as this line of code can return the desired data, there is no problem, even without database interaction. We can achieve this through mock data.

Now, let's look at the relevant test code for the validateUser method:

import { Test } from '@nestjs/testing';
import { AuthService } from '@/modules/auth/auth.service';
import { UsersService } from '@/modules/users/users.service';
import { UnauthorizedException } from '@nestjs/common';
import { TEST_USER_NAME, TEST_USER_PASSWORD } from '@tests/constants';
describe('AuthService', () => {
  let authService: AuthService; // Use the actual AuthService type
  let usersService: Partial<Record<keyof UsersService, jest.Mock>>;
  beforeEach(async () => {
    usersService = {
      findOne: jest.fn(),
    };
    const module = await Test.createTestingModule({
      providers: [        AuthService,
        {
          provide: UsersService,
          useValue: usersService,
        },
      ],
    }).compile();
    authService = module.get<AuthService>(AuthService);
  });
  describe('validateUser', () => {
    it('should throw an UnauthorizedException if user is not found', async () => {
      await expect(
        authService.validateUser(TEST_USER_NAME, TEST_USER_PASSWORD),
      ).rejects.toThrow(UnauthorizedException);
    });
    // other tests...
  });
});

We get the user data by calling the findOne method of usersService, so we need to mock the findOne method of usersService in the test code:

beforeEach(async () => {
    usersService = {
      findOne: jest.fn(), // mock findOne method
    };
    const module = await Test.createTestingModule({
      providers: [        AuthService, // real AuthService, because we are testing its methods
        {
          provide: UsersService, // use mock usersService instead of real usersService
          useValue: usersService,
        },
      ],
    }).compile();
    authService = module.get<AuthService>(AuthService);
  });

We use jest.fn() to return a function to replace the real usersService.findOne(). If usersService.findOne() is called now, there will be no return value, so the first unit test case will pass:

it('should throw an UnauthorizedException if user is not found', async () => {
  await expect(
    authService.validateUser(TEST_USER_NAME, TEST_USER_PASSWORD),
  ).rejects.toThrow(UnauthorizedException);
});

Since findOne in const entity = await this.usersService.findOne({ username }); of the validateUser method is a mocked fake function with no return value, the 2nd to 4th lines of code in the validateUser method could execute:

if (!entity) {
  throw new UnauthorizedException('User not found');
}

It throws a 401 error, which is as expected.

The Second Test Case

The second logic in the validateUser method is to determine if the user is locked, with the corresponding code as follows:

if (entity.lockUntil && entity.lockUntil > Date.now()) {
  const diffInSeconds = Math.round((entity.lockUntil - Date.now()) / 1000);
  let message = `The account is locked. Please try again in ${diffInSeconds} seconds.`;
  if (diffInSeconds > 60) {
    const diffInMinutes = Math.round(diffInSeconds / 60);
    message = `The account is locked. Please try again in ${diffInMinutes} minutes.`;
  }
  throw new UnauthorizedException(message);
}

As you can see, we can determine that the current account is locked if there is a lock time lockUntil in the user data and the lock end time is greater than the current time. So we need to mock a user data with the lockUntil field:

it('should throw an UnauthorizedException if the account is locked', async () => {
  const lockedUser = {
    _id: TEST_USER_ID,
    username: TEST_USER_NAME,
    password: TEST_USER_PASSWORD,
    lockUntil: Date.now() + 1000 * 60 * 5, // The account is locked for 5 minutes
  };
  usersService.findOne.mockResolvedValueOnce(lockedUser);
  await expect(
    authService.validateUser(TEST_USER_NAME, TEST_USER_PASSWORD),
  ).rejects.toThrow(UnauthorizedException);
});

In the test code above, an object lockedUser is first defined, which contains the lockUntil field we need. Then, it is used as the return value for findOne, achieved by usersService.findOne.mockResolvedValueOnce(lockedUser);. Thus, when the validateUser method is executed, the user data within it is the mocked data, successfully allowing the second test case to pass.

Unit Test Coverage

Unit test coverage (Code Coverage) is a metric used to describe how much of the application code has been covered or tested by unit tests. It is typically expressed as a percentage, indicating how much of all possible code paths have been covered by test cases.

Unit test coverage usually includes the following types:

• Line Coverage: How many lines of code are covered by the tests.

• Function Coverage: How many functions or methods are covered by the tests.

• Branch Coverage: How many code branches are covered by the tests (for example, if/else statements).

• Statement Coverage: How many statements in the code are covered by the tests.

Unit test coverage is an important metric to measure the quality of unit tests, but it is not the only metric. A high coverage rate can help to detect errors in the code, but it does not guarantee the quality of the code. A low coverage rate may mean that there is untested code, potentially with undetected errors.

The image below shows the unit test coverage results for a demo project:

For files like services and controllers, it's generally better to have a higher unit test coverage, while for files like modules there's no need to write unit tests – nor is it possible to write them, as it's meaningless.

This is because NestJS modules are primarily configuration files that define the structure of your application by connecting controllers, services, and other components together. They don't contain actual business logic to test, but rather serve as wiring instructions for the dependency injection system. Testing modules would only verify that NestJS's core functionality works correctly, which is already tested by the NestJS team themselves.

The above image represents the overall metrics for the entire unit test coverage. If you want to view the test coverage for a specific function, you can open the coverage/lcov-report/index.html file in the project's root directory. For example, I want to see the specific test situation for the validateUser method:

As you can see, the original unit test coverage for the validateUser method is not 100%, and there are still two lines of code that were not executed. But it doesn't matter much, as it does not affect the four key processing nodes, and we shouldn’t pursue high test coverage unidimensionally.

How to Write E2E Tests

In the unit tests section, you learned how to write unit tests for each feature of the validateUser() function, using mocked data to ensure that each feature could be tested.

In e2E testing, we need to simulate real user scenarios, so connecting to a database for testing is necessary. So, the methods in the auth.service.ts module that we'll be testing all interact with the database.

The auth module primarily includes the following features:

• Registration

• Login

• Token refresh

• Reading user information

• Changing password

• Deleting users

E2E tests need to test these six features one by one, starting with registration and ending with deleting users. During testing, we can create a dedicated test user to conduct the tests and then delete this test user upon completion, so we don’t leave any unnecessary information in the test database.

beforeAll(async () => {
  const moduleFixture: TestingModule = await Test.createTestingModule({
    imports: [AppModule],
  }).compile()
  app = moduleFixture.createNestApplication()
  await app.init()
  // Perform a login to obtain a token
  const response = await request(app.getHttpServer())
    .post('/auth/register')
    .send({ username: TEST_USER_NAME, password: TEST_USER_PASSWORD })
    .expect(201)
  accessToken = response.body.access_token
  refreshToken = response.body.refresh_token
})
afterAll(async () => {
  await request(app.getHttpServer())
    .delete('/auth/delete-user')
    .set('Authorization', `Bearer ${accessToken}`)
    .expect(200)
  await app.close()
})

The beforeAll hook function runs before all tests begin, so we can register a test account TEST_USER_NAME here. The afterAll hook function runs after all tests end, so it's suitable to delete the test account TEST_USER_NAME here. It also conveniently tests the registration and deletion functions.

In the previous section's unit tests, we wrote relevant unit tests around the validateUser method. Actually, this method is executed during login to validate if the user's account and password are correct. So this E2E test will also use the login process to demonstrate how to compose the E2E test cases.

The entire login test process includes five small tests:

describe('login', () => {
    it('/auth/login (POST)', () => {
      // ...
    })
    it('/auth/login (POST) with user not found', () => {
      // ...
    })
    it('/auth/login (POST) without username or password', async () => {
      // ...
    })
    it('/auth/login (POST) with invalid password', () => {
      // ...
    })
    it('/auth/login (POST) account lock after multiple failed attempts', async () => {
      // ...
    })
  })

These five tests are as follows:

1. Successful login, return 200

2. If the user does not exist, throw a 401 exception

3. If password or username is not provided, throw a 400 exception

4. Login with the wrong password, throw a 401 exception

5. If the account is locked, throw a 401 exception

Now let's start writing the E2E tests:

// login success
it('/auth/login (POST)', () => {
  return request(app.getHttpServer())
    .post('/auth/login')
    .send({ username: TEST_USER_NAME, password: TEST_USER_PASSWORD })
    .expect(200)
})
// if user not found, should throw 401 exception
it('/auth/login (POST) with user not found', () => {
  return request(app.getHttpServer())
    .post('/auth/login')
    .send({ username: TEST_USER_NAME2, password: TEST_USER_PASSWORD })
    .expect(401) // Expect an unauthorized error
})

Writing E2E test code is relatively straightforward: you simply call the interface and then verify the result. For example, for the successful login test, we just need to verify that the returned result is 200.

The first four tests are quite simple. Now let's look at a slightly more complicated E2E test, which is to verify whether an account is locked.

it('/auth/login (POST) account lock after multiple failed attempts', async () => {
  const moduleFixture: TestingModule = await Test.createTestingModule({
    imports: [AppModule],
  }).compile()
  const app = moduleFixture.createNestApplication()
  await app.init()
  const registerResponse = await request(app.getHttpServer())
    .post('/auth/register')
    .send({ username: TEST_USER_NAME2, password: TEST_USER_PASSWORD })
  const accessToken = registerResponse.body.access_token
  const maxLoginAttempts = 3 // lock user when the third try is failed
  for (let i = 0; i < maxLoginAttempts; i++) {
    await request(app.getHttpServer())
      .post('/auth/login')
      .send({ username: TEST_USER_NAME2, password: 'InvalidPassword' })
  }
  // The account is locked after the third failed login attempt
  await request(app.getHttpServer())
    .post('/auth/login')
    .send({ username: TEST_USER_NAME2, password: TEST_USER_PASSWORD })
    .then((res) => {
      expect(res.body.message).toContain(
        'The account is locked. Please try again in 5 minutes.',
      )
    })
  await request(app.getHttpServer())
    .delete('/auth/delete-user')
    .set('Authorization', `Bearer ${accessToken}`)
  await app.close()
})

When a user fails to log in three times in a row, the account will be locked. So in this test, we cannot use the test account TEST_USER_NAME, because if the test is successful, this account will be locked and unable to continue the following tests. We need to register another new user TEST_USER_NAME2 specifically to test account locking, and delete this user after the test is successful.

So, as you can see, the code for this E2E test is quite substantial, requiring a lot of setup and teardown work, but the actual test code is just these few lines:

// login three times
for (let i = 0; i < maxLoginAttempts; i++) {
  await request(app.getHttpServer())
    .post('/auth/login')
    .send({ username: TEST_USER_NAME2, password: 'InvalidPassword' })
}
// test if the account is locked
await request(app.getHttpServer())
  .post('/auth/login')
  .send({ username: TEST_USER_NAME2, password: TEST_USER_PASSWORD })
  .then((res) => {
    expect(res.body.message).toContain(
      'The account is locked. Please try again in 5 minutes.',
    )
  })

Writing E2E test code is relatively simple. You don't need to consider mock data or test coverage. It's sufficient if the entire system process runs as expected.

When to Write Tests

If possible, I generally recommend writing tests. Doing so can enhance the robustness, maintainability, and development efficiency of the system. Here are some key reasons why writing tests is useful:

Enhancing System Robustness

When writing code, you usually focus on the program flow under normal inputs to ensure the core functionality works properly. But you might often overlook some edge cases, such as abnormal inputs.

Writing tests changes this, as it forces you to consider how to handle these cases and respond appropriately, thus preventing crashes. So we can say that writing tests indirectly improves system robustness.

Enhancing Maintainability

Taking over a new project that includes comprehensive tests can be very pleasant. They act as a guide, helping you quickly understand the various functionalities. Just by looking at the test code, you can easily grasp the expected behavior and boundary conditions of each function without having to go through each line of the function's code.

Enhancing Development Efficiency

Imagine a project that hasn't been updated for a while suddenly receives new requirements. After making changes, you might worry about introducing bugs. Without tests, you would need to manually test the entire project again — wasting time and being inefficient.

With complete tests, a single command can tell you whether the code changes have impacted existing functionalities. Even if there are errors, you can quickly locate them and address them.

When Not to Write Tests

For short-term projects and projects with very fast requirement iterations, it's not recommended to write tests.

For example, a project built for an event that will be useless after the event ends doesn't need tests. Also, for projects that undergo very fast requirement iterations, writing tests could enhance development efficiency, but that's based on the premise that function iterations are slow. If the function you just completed changes in a day or two, the related test code must be rewritten.

So, it's better not to write tests at all in these cases and rely on the testing team instead – because writing tests is very time-consuming and not worth the effort for these situations.

Conclusion

I’ve explained in detail how to write unit tests and E2E tests for NestJS projects. But I still want to reiterate the importance of testing. It can enhance the robustness, maintainability, and development efficiency of the system.

If you don't have the opportunity to write tests, I suggest you start a practice project yourself or participate in some open-source projects and contribute code to them. Open-source projects generally have stricter code requirements. Contributing code may require you to write new test cases or modify existing ones.

Reference Materials

• NestJS: A framework for building efficient, scalable Node.js server-side applications.

• MongoDB: A NoSQL database used for data storage.

• Jest: A testing framework for JavaScript and TypeScript.

• Supertest: A library for testing HTTP servers.

We just published a course on the freeCodeCamp.org YouTube channel that will teach you how to build microservices using Nest.js. Taught by Hhaider Malik, this course walks you through building a delivery service application that tracks rider activity by saving their coordinates every three hours. You'll develop two microservices—a Login Service and a Rider Service—and enable seamless communication between them. By the end of the course, you'll have the skills to design, develop, and deploy scalable microservices using Nest.js and MongoDB.

What You’ll Learn

This hands-on course covers essential topics for building microservices, including:

• Setting up a Nest.js microservices project – Learn how to scaffold and structure a Nest.js application for microservices.

• Using MongoDB with Docker – Understand the importance of Docker, run MongoDB in a container, and use Docker Compose for setup.

• Schema design and data validation – Define schemas using Mongoose and validate request bodies to ensure data integrity.

• Inter-microservice communication – Implement TCP-based communication between services and use events for interaction.

• Testing and debugging – Learn how to test microservices and fix common issues to ensure reliability.

Why This Course?

Nest.js is a powerful framework that simplifies building scalable server-side applications with TypeScript. This course provides practical, real-world experience by guiding you through building and testing a real microservices-based project.

Watch the full course now on the freeCodeCamp.org YouTube channel (2-hour watch).

In this guide, we’ll walk through the steps to create a resource dedicated to file uploads, ensuring that your application can easily manage user files. You'll configure your application to handle files securely and seamlessly.

Prerequisites

This is a hands-on guide. To follow along, you must have the following things:

• Node.js (v14 and above)

• Node package manager

• Basic understanding of Node.js and NestJS

• A code editor, like VS Code

• NestJS CLI. You can use the npm install -g @nestjs/cli command to install the CLI.

How to Set up the Project

Create a new NestJS project:

$ nest new file-upload-example

Then navigate to your project directory and run:

$ cd file-upload-example

Next, install the multer package—the middleware that will handle your file uploads:

$ npm install @nestjs/platform-express multer

Lastly, install the @types/express and @types/multer packages:

$ npm install -save-dev @types/express @types/multer

With the project set up and dependencies installed, let’s create the resource for the file upload feature.

How to Create a Resource for File Upload

Using the NestJS CLI, generate the resource to handle file uploads:

nest generate resource file-upload

This command creates a resource file-upload in the src directory: module, controller and service, to manage file uploads.

file-upload.module.ts organizes the file upload logic, file-upload.controller.ts handles incoming file upload requests, and file-upload.service.ts handles the file upload operations. With the resource created, let’s configure the module, service and controller.

How to Configure the File Upload Resource

In this section we’ll configure the file-upload.module.ts, file-upload.controller.ts and file-upload.service.ts files.

Module configuration:

import { Module } from '@nestjs/common';
import { FileUploadService } from './file-upload.service';
import { FileUploadController } from './file-upload.controller';
import { MulterModule } from '@nestjs/platform-express';
import { diskStorage } from 'multer';
@Module({
  imports: [
    MulterModule.register({
      storage: diskStorage({
        destination: './uploads',
        filename: (req, file, cb) => {
          const filename = `${Date.now()}-${file.originalname}`;
          cb(null, filename);
        },
      }),
    }),
  ],
  controllers: [FileUploadController],
  providers: [FileUploadService],
})
export class FileUploadModule {}

Above is the file-upload.module.ts file, where we configured the MulterModule to specify the upload destination and how it should name the file.

Controller configuration:

import {
  Controller,
  Post,
  UseInterceptors,
  UploadedFile,
} from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';
import { FileUploadService } from './file-upload.service';

@Controller('file-upload')
export class FileUploadController {
  constructor(private readonly fileUploadService: FileUploadService) {}

  @Post('upload')
  @UseInterceptors(FileInterceptor('file'))
  uploadFile(@UploadedFile() file: Express.Multer.File) {
    return this.fileUploadService.handleFileUpload(file);
  }
}

Is the file-upload.controller.ts file above, a POST route is created to handle file uploads. The route listens for file uploads and passes the file to the service for processing

Service configuration:

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

@Injectable()
export class FileUploadService {
  handleFileUpload(file: Express.Multer.File) {
    return { message: 'File uploaded successfully', filePath: file.path };
  }
}

The service processes the file and returns a response with the file’s path.

Now that the module, service and controller has been configured, we can now add some validation to check the file size and file type.

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

@Injectable()
export class FileUploadService {
  handleFileUpload(file: Express.Multer.File) {
    if (!file) {
      throw new BadRequestException('no file uploaded');
    }

    // validate file type
    const allowedMimeTypes = ['image/jpeg', 'image/png', 'application/pdf'];
    if (!allowedMimeTypes.includes(file.mimetype)) {
      throw new BadRequestException('invalid file type');
    }

    // validate file size (e.g., max 5mb)
    const maxSize = 5 * 1024 * 1024;
    if (file.size > maxSize) {
      throw new BadRequestException('file is too large!');
    }

    return { message: 'File uploaded successfully', filePath: file.path };
  }
}

We have done the necessary configurations to test the file upload.

How to Test the File Upload

Testing is an important part of building features, in this section we’ll test the file-upload feature using Postman, but you can use any similar tool to test the file upload endpoint. Let’s see our API in action!

Post an image file with the /file-upload/upload endpoint:

After sending the request, check your response to ensure the file was uploaded successfully. And to further confirm the upload, check the file-upload-example and you’ll see the uploads directory already created with the file you uploaded.

Conclusion

Congratulations to you now that you’ve successfully set up a file upload feature with Multer and NestJS. You configured the module, controller, and service to handle the files securely, and tested the endpoint.

You should understand that these are basic and essential steps to uploading files. You can add to these by building more complex features like handling multiple file uploads, storage in cloud services, and so on.

I really enjoyed working on this demo, and I hope you also find it helpful. For your convenience, the project repository is avalilable on Github. You can also connect with me on Twitter. I’d love to hear from you.

Authentication ensures that only authorized individuals access specific resources or perform certain actions within a system. It provides accountability by enabling the tracking of user actions and holding individuals responsible for their activities.

It also gives companies data on the number of people using their products. Without proper authentication of your software, you may face security risks. Proper implementation prevents unauthorized access and protects sensitive data.

This tutorial will guide you through building a JWT-based user authentication in NestJS and MongoDb.

NestJS is a powerful Node.js framework for building server-side applications. MongoDB is popular NoSQL database and we’ll use it to build the basic authentication endpoints.

In this tutorial, we'll cover the following topics:

• How to creating a new NestJS project and install the necessary dependencies.
• How to create user models and schemas.
• How to implementing login and signup with JWT token.
• How to test the endpoints with postman.

Prerequisites

This tutorial is a hands-on demo. To follow along, you must have the following:

• Node.js v14 and above

• Node package manager

• MongoDB compass

• Basic understanding of Node.js and preferably ExpressJs

• A code editor (for example: VS Code)

How to Set Up the Project.

In this section, we’ll set up the project to build our REST API with NestJS and MongoDB. We’ll start by installing the NestJS CLI and use it to generate new projects.

Install Nest CLI:

$ npm i -g @nestjs/cli

Then create a new NestJS project with this command:

$ nest new project-name

Let’s call the project authentication:

$ nest new authentication

You will see options about which package manager you prefer to install. I used npm.

After successful installation, move into the created directory and open the project with your preferred code editor.

Before we go into creating resources and configuring the project, let’s take a quick look at the src directory and its files:

• src: The root directory for the source code.

• src/app.module.ts: The application's main module for configuring and integrating other modules.

• src/app.controller.ts: Contains a default controller with a single route.

• src/app.service.ts: This includes a basic service using a single method.

• src/main.ts: The entry point of the application.

Next, install dependencies to set up and connect the database. You will have to install the mongoose package, bcrypt:

$ npm i -save @nestjs/mongoose @types/bcrypt mongoose bcrypt

Next, set up your database. The MongooseModule from the @nestjs/mongoose dependency will be used to set up the database.

Go to src/app.module.ts file:

import { AppController } from './app.controller';
import { AppService } from './app.service';
import { MongooseModule } from '@nestjs/mongoose';
import { UsersModule } from './users/users.module';
import { AuthModule } from './auth/auth.module';
import { ConfigModule } from '@nestjs/config';

@Module({
imports: [
MongooseModule.forRoot('mongodb://localhost:27017/auth-workshop'),
UsersModule,
AuthModule,
ConfigModule.forRoot({
envFilePath: '.env',
isGlobal: true,
}),
],
controllers: [AppController],
providers: [AppService],
})
export class AppModule {}

Let's breakdown the code above. The app.module.ts is the root module of the nestjs application and it is responsible for importing dependecies and other modules required by the application, configuring the application such as database connections and environment variables.

We first specified the app.module.ts file as a module by using the @Module({}) decorator:

@Module({})

The imports array specifies the module that this module depends on. We have the MongooseModule.forRoot('') for database connection using mongoose, ConfigModule.forRoot import sets up the configuration module to read from a .env file:

import { MongooseModule } from '@nestjs/mongoose';
import { UsersModule } from './users/users.module';
import { AuthModule } from './auth/auth.module';
import { ConfigModule } from '@nestjs/config';

imports: [
MongooseModule.forRoot('mongodb://localhost:27017/auth-workshop'),
UsersModule,
AuthModule,
ConfigModule.forRoot({
envFilePath: '.env',
isGlobal: true,
}),
]

You can replace the MongooseModule.forRoot() URI string with your own database string.

The controllers array specifies the controller that belongs to this module:

controllers: [AppController]

The providers array specifies the services that belongs to this module:

providers: [AppService]

With these configurations, you can start your application by using the npm run start:dev.

User models and schemas

In this section, we'll define the User model and schema using mongoose. The User model will represent the users of the application, and the schema will define the structure of the data stored in MongoDB. Let’s start by creating a resource module for the users API:

First, create a users resource with the nest CLI:

$ nest generate res users

This command will create a new users resource in the src/users directory with a basic structure of controllers and services.

Then define the schema for the Users in src/users/entities/users.entity.ts:

import { Prop, Schema, SchemaFactory }
from '@nestjs/mongoose';
@Schema()
export class User {
@Prop()
name: string;
@Prop({ unique: true })
email: string;

@Prop()
password: string;
}
export const UserSchema = SchemaFactory.createForClass(User);

The @Schema decorator is what makes the class a schema. This schema defines three fields for the users: name, email, and password. They are all typed string.

Next, register the schema in the users.module.ts file located in src/users/users.module.ts:

import { Module } from '@nestjs/common';
import { UsersService } from './users.service';
import { UsersController } from './users.controller';
import { MongooseModule } from '@nestjs/mongoose';
import { UserSchema, User } from './entities/user.entity';

@Module({
imports: [MongooseModule.forFeature([{ name: User.name, schema:
UserSchema }])],
controllers: [UsersController],
providers: [UsersService],
})
export class UsersModule {}

By importing the MongooseModule.forFeature([{}]), this configures mongoose to use the UserSchema for the User model.

By registering the schema with Mongoose, we created a model that's ready to use in our application. This sets the stage for building services and controllers that can interact with our data and handle incoming requests.

Lastly, define the DTO (data transfer object). This object transfers data between systems. It is a simple object that contains only data and has no behaviour.

Create your CreateUserDto in the src/users/dto/create-user.dto.ts directory:

export class CreateUserDto {
username: string;
email: string;
password: string;
}

User Services and Controllers

We have connected to the database and created the schema and model of Users. Let’s write the basic CRUD methods for the users.

Update your users.service.ts located in src/users/users.service.ts:

import { Injectable, NotFoundException
} from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';
import { InjectModel } from '@nestjs/mongoose';
import { User } from './entities/user.entity';
import { Model } from 'mongoose';

@Injectable()
export class UsersService {
constructor(@InjectModel(User.name) private userModel:
Model<User>) {}
async createUsers(createUserDto: CreateUserDto) {
const user = await this.userModel.create(createUserDto);
return user.save();
}
async findAllUsers() {
const users = this.userModel.find();
return users;
}
async findUser(id: number) {
const user = await this.userModel.findById(id);
if (!user) throw new NotFoundException('could not find the user');
return user;
}
updateUser(id: number, updateUserDto: UpdateUserDto) {
return this.userModel.findByIdAndUpdate(id, updateUserDto, { new: true
});
}
removeUser(id: number) {
return this.userModel.findByIdAndDelete(id);
};
}

Update your users.controller.ts located in src/users/users.controller.ts:

import { Controller, Get, Post, Body, Patch, Param, Delete, } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';

@Controller('users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}

@Post()
async create(@Body() createUserDto: CreateUserDto) {
return await this.usersService.createUsers(createUserDto);
}

@Get()
async findAll() {
return await this.usersService.findAllUsers();
}

@Get(':id')
async findOne(@Param('id') id: string) {
return await this.usersService.findOneUser(+id);
}

@Patch(':id')
async update(@Param('id') id: string, @Body() updateUserDto:
UpdateUserDto) {
return await this.usersService.updateUser(+id, updateUserDto);
}

@Delete(':id')
async remove(@Param('id') id: string) {
return await this.usersService.removeUser(+id);
}
}

We created RESTful APIs using mongoose. The methods include:

• findAllUsers: Retrieves all user documents from the collection.

• getUserById: Finds a single user document by ID.

• createUsers: Adds a new user document to the collection.

• updateUser: Updates details of existing user in the collection.

• removeUser: Removes user document by ID.

How to Implement Sign-up and Log-in

In this section, we'll create an authentication service that generates JSON Web Tokens (JWTs).

This service will have two methods: signup and login. The signup method will take a signup request object containing name, email, and password),and the login method will take a login request object containing email and password. Both methods will return a JWT.

Let’s start by creating a resource module for the authentication APIs.

Create auth resource with Nest CLI:

$ nest generate res auth

Then define the DTO for both signup and login. Go to the dto folder in the src/auth/dto folder:

signup.dto.ts:

export class SignUpDto {
name: string;
email: string;
password: string;
}

login.dto.ts:

export class Login {
email: string;
password: string;
}

Next, create a .env file in the root directory:

JWT_SECRET=secret
JWT_EXPIRES=3d

Then add the PassportModule, JwtModule and JwtStrategy to AuthModule. We'll start by installing these packages:

$ npm i @nestjs/passport @nestjs/jwt passport passport-jwt bcryptjs

Go to src/auth/auth.module.ts and import these packages:

import { Module } from '@nestjs/common';
import { AuthService } from './auth.service';
import { AuthController } from './auth.controller';
import { PassportModule } from '@nestjs/passport';
import { JwtModule } from '@nestjs/jwt';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { MongooseModule } from '@nestjs/mongoose';
import { UserSchema } from 'src/users/entities/user.entity';


@Module({
imports: [
PassportModule.register({ defaultStrategy: 'jwt' }),
JwtModule.registerAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (config: ConfigService) => {
return {
secret: config.get<string>('JWT_SECRET'),
signOptions: {
expiresIn: config.get<string | number>('JWT_EXPIRES'),
},
};
},
}),
MongooseModule.forFeature([{ name: 'User', schema: UserSchema }]),
],
controllers: [AuthController],
providers: [AuthService],
})
export class AuthModule {}

The PassportModule.register configures the Passport module to use the JWT strategy as the authentication mechanism.

The JwtModule.registerAsync configures the JWT module using asynchronous registration process, such a the token expiration time.

The MongooseModule.forFeature() configures mongoose to us the UserSchema for the User model

These imports enable the authentication module to manage user authentication, JWT generation, and database interaction.

Next, create the AuthServices for signup and login in the src/auth/auth.service.ts directory:

import { Injectable, UnauthorizedException} from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { InjectModel } from '@nestjs/mongoose';
import { Model } from 'mongoose';
import { User } from 'src/users/entities/user.entity';
import { SignUpDto } from './dto/signup.dto';
import * as bcrypt from 'bcryptjs';
import { LoginDto } from './dto/login.dto';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class AuthService {
constructor(
@InjectModel(User.name) private userModel: Model<User>,
private jwtService: JwtService,
private configService: ConfigService,
) {}

async signUp(signupDto: SignUpDto) {
const { name, email, password } = signupDto;

const hashedPassword = await bcrypt.hash(password, 10);
const user = await this.userModel.create({
name,
email,
password: hashedPassword,
});

await user.save();

const token = await this.jwtService.sign(
{ id: user.id },
{
secret: this.configService.get('JWT_SECRET'),
expiresIn: this.configService.get('JWT_EXPIRES'),
},
);
return { token };
}

async login(loginDto: LoginDto) {
const { email, password } = loginDto;
const user = await this.userModel.findOne({
email,
});

if (!user) throw new UnauthorizedException('invalid email or
password');
const passwordMatch = await bcrypt.compare(password,
user.password);
if (!passwordMatch)
throw new UnauthorizedException('invalid email or password');
const token = await this.jwtService.sign(
{ id: user.id },
{
secret: this.configService.get('JWT_SECRET'),
},
);
return { token };
}
}

In the AuthService, the signUp method facilitates user registration by:

• Destructuring the SignupDto object to extract user credentials.
• Hashing the password using bcrypt for secure storage.
• Creating a new user document in the database via the userModel.
• Saving the user document to the database.
• Generating a JWT token using jwtService upon successful registration.
• Returning the JWT token to the client.

The login method authenticates users by:

• Destructuring the LoginDto object to verify user credentials.
• Comparing the input password with the stored hash to ensure a match.
• Throwing an UnauthorizedException error if the passwords do not match.
• Utilizing the jwtService to sign the user and generate a JWT token upon successful authentication.
• Returning the JWT token to the client.

Update the AuthController for signup and login in the src/auth/auth.controller.ts directory:

import { Controller, Post, Body } from '@nestjs/common';
import { AuthService } from './auth.service';
import { SignUpDto } from './dto/signup.dto';
import { LoginDto } from './dto/login.dto';

@Controller('auth')
export class AuthController {
constructor(private readonly authService: AuthService) {}

@Post('signup')
signUp(@Body() signupDto: SignUpDto) {
return this.authService.signUp(signupDto);
}

@Post('login')
signin(@Body() loginDto: LoginDto) {
return this.authService.login(loginDto);
}
}

With these steps, you’ve implemented a basic user login and signup in your application. In the next sections, we’ll test the login and signup routes.

Testing in Postman

Now that we've set up our endpoints, it's time to put them to the test. For this example, I'll be using Postman as my API client, but feel free to use any tool or client that suits your needs. Let's see our API in action!

How to Create a User With the /signup Endpoint:

After sending a POST request to the /signup endpoint using Postman, we received a response containing the accessToken. You can verify that a new user has been successfully created by checking the database.

Login as an existing user with the /login endpoint:

Conclusion

Congratulations, you've successfully implemented comprehensive authentication using NestJS, Mongoose, and Passport. We designed a secure signup and login process, and generated JSON Web Tokens (JWTs).

To further improve and expand your knowledge on authentication, look into authorization, protecting routes with authentication middleware, and implementing email verification and password reset functionality.

This foundation provides a solid starting point for building a robust and scalable authentication system. This project was a pleasure to work on, and I hope you found it equally enjoyable.

For your convenience, the project repository is available on Github.

Please don't hesitate to connect with me on Twitter at @Adedot1Abimbola. I'd love to hear from you

Alright, before we dive in, let's try to understand what TypeORM and NestJS are.

Table of contents:

• What is TypeORM?
• What is NestJS?
• Tutorial Prerequisites
• How to Set Up a NestJS Project
• How to Set Up TypeORM DataSource for Data Persistency
• Extending The DataSource Repository For Custom Methods
• Conclusion
• Resources

What is TypeORM?

TypeORM is an Object-Relational Mapping (ORM) tool that simplifies working with databases in Node.js and TypeScript applications. It supports various databases like MySQL, PostgreSQL, SQLite, and more, allowing developers to use object-oriented programming concepts instead of dealing with low-level SQL queries.

TypeORM also provides features like schema migrations, query building, and managing relationships between tables.

What is NestJS?

NestJS is a progressive Node.js framework designed for building efficient, reliable, and scalable server-side applications. It leverages TypeScript's features to enable developers to write structured, maintainable code.

NestJS adopts a modular architecture pattern, allowing you to organize your code into modules, controllers, services, and providers. It provides built-in support for features like dependency injection, middleware, and GraphQL, making it a popular choice for building modern web applications and APIs.

Additionally, NestJS integrates seamlessly with other libraries and frameworks, including TypeORM, to streamline development workflows. Under the hood, it uses a robust HTTP server framework like Express (default) and can be configured to use other Node.js HTTP server frameworks.

Alright, that's a lot, right? Well, before we move on, let's try to break down the phrase, 'NestJS is a progressive Node.js framework,' which simply means that NestJS leverages the latest features of the JavaScript language and server frameworks, thereby providing flexibility for developers to write code in the most suitable language for their projects.(Source)

Tutorial Prerequisites

• Node.js. At least version 18
• npm. Atleast Version 8
• Postgresql. Download Here
• Basic familiarity with Typescirpt and Nestjs
• Pgadmin 4. Download Here

How to Set Up a NestJS Project

Run the following commands to install your NestJS project:

npm i -g @nestjs/cli # install nestj cli globally
nest new simple-crm # start a new nestjs project

After installation, run the development server:

npm run start:dev # start the app in watch mode

Now, let's test our project to see if the nest-cli has properly set up all boiler plate code, by sending a get request to the root URL /

_inittest

Nice! Our project is up and running.

How to Set Up TypeORM DataSource for Data Persistency

npm install --save @nestjs/typeorm typeorm # nestjs typeorm drivers
npm install --save pg # typeorm postgressql driver

Let's create the database for the project from Pgadmin 4 interface

Open the Pgadmin 4 interface and right click on the Databases tab to create new database, like so 👇.

_createdb-1

_createdb-2

Confirm your database has been created successfully.

_confirmdb

Great, it's time to add the database to our NestJS app using TypeORM.

Create new folder, datasource in the src/ folder of your app, like so 👇

_confirmfolder

Create a new file typeorm.module.ts, in the datasource folder, and add the following code:

import { DataSource } from 'typeorm';
import { Global, Module } from '@nestjs/common';

@Global() // makes the module available globally for other modules once imported in the app modules
@Module({
  imports: [],
  providers: [
    {
      provide: DataSource, // add the datasource as a provider
      inject: [],
      useFactory: async () => {
        // using the factory function to create the datasource instance
        try {
          const dataSource = new DataSource({
            type: 'postgres',
            host: 'localhost',
            port: 5432,
            username: 'ayo',
            password: 'haywon',
            database: 'simple-crm_db',
            synchronize: true,
            entities: [`${__dirname}/../**/**.entity{.ts,.js}`], // this will automatically load all entity file in the src folder
          });
          await dataSource.initialize(); // initialize the data source
          console.log('Database connected successfully');
          return dataSource;
        } catch (error) {
          console.log('Error connecting to database');
          throw error;
        }
      },
    },
  ],
  exports: [DataSource],
})
export class TypeOrmModule {}

Add the TypeORM module to the App module imports array, like so 👇

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { TypeOrmModule } from './datasource/typeorm.module';

@Module({
  imports: [TypeOrmModule],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Then save and confirm from your console if the database has been connected successfully.

_show_db_successconn

If you see the database connected successfully, good job! Otherwise, go back to the previous steps to see if you followed the configurations correctly.

Now, we can continue to consume our datasource service leveraging the TypeORM.

Let's create users module, controller, provider and entity to interact with our newly connected database.

nest g module users && nest g service users && nest g controller users

The above command will generate the users module, service and controller and update the app.module.ts with the users module.

Add the following code inside the users.entity.ts file and restart your development server to create the user table in the database.

import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity('user')
export class UserEntity {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ unique: true })
  username: string;

  @Column()
  password: string;
}

Check your Pgadmin 4 interface and confirm that TypeORM has automatically loaded the UserEntity and created the user table in your database, like so 👇.

_confirm_usertable

You might want to refresh the database if you don't see it at first.

Now let's implement our first users service handler, add the following code to your users.service.ts file:

import {
  HttpException,
  HttpStatus,
  Injectable,
  InternalServerErrorException,
  Logger,
} from '@nestjs/common';
import { DataSource } from 'typeorm';
import { UserEntity } from './users.entity';

export interface CreateUser {
  username: string;
  password: string;
}

@Injectable()
export class UsersService {
  private userRepository;
  private logger = new Logger();
  //   inject the Datasource provider
  constructor(private dataSource: DataSource) {
    // get users table repository to interact with the database
    this.userRepository = this.dataSource.getRepository(UserEntity);
  }
  //  create handler to create new user and save to the database
  async createUser(createUser: CreateUser): Promise<UserEntity> {
    try {
      const user = await this.userRepository.create(createUser);
      return await this.userRepository.save(user);
    } catch (err) {
      if (err.code == 23505) {
        this.logger.error(err.message, err.stack);
        throw new HttpException('Username already exists', HttpStatus.CONFLICT);
      }
      this.logger.error(err.message, err.stack);
      throw new InternalServerErrorException(
        'Something went wrong, Try again!',
      );
    }
  }
}

We've added the createUser method to handle creating a user when a POST request is sent with the required request body to the endpoint controller that utilizes the createUser service method.

The function takes an object createUser as an argument of type CreateUser interface. Usually, this should be a DTO (Data Transfer Object) for the data type structure and validation, but since it is out of the scope of this tutorial, we're using the interface just for the data shape.

We called the create method of the userRepository then assigned it's return to the user variable to hold the newly created user object. We then called the save method to save the object to the database.

Now, let's utilize the createUser service handler in our users controller that handles the POST request to create new user.

import { Body, Controller, Post } from '@nestjs/common';
import { CreateUser, UsersService } from './users.service';

@Controller('users')
export class UsersController {
  constructor(private userService: UsersService) {}

  @Post('/create')
  //   handles the post request to /users/create endpoint to create new user
  async signUp(@Body() user: CreateUser) {
    return await this.userService.createUser(user);
  }
}

Test the newly created endpoint, by sending a POST request to http://localhost:3000/users/create with the username and password as the request body.

_test_user_createendpoint

Alright, let's check the database just to be sure that's all, because we already got a 201 response status code which should be enough to know that our application is smoothly interacting with our database using the TypeORM Datasource.

_confirm_userdb

Extending The DataSource Repository For Custom Methods

Whether you're looking to optimize database queries, introduce new data manipulation operations, or integrate with third-party services, extending the DataSource repository with custom methods can be a game-changer interacting with the database seamlessly.

Here, we'll explore the benefits of custom methods, and provide a step-by-step guide to implementing them in your NestJS applications. So, let's dive in and unlock the full potential of the DataSource repository!

Some of the basic benefits of repository custom methods are:

Tailored Functionality: Custom methods allow developers to introduce specific functionalities that are not available in the standard DataSource repository. By tailoring the DataSource repository with custom methods, developers can address unique use cases, data manipulation operations and aggregations, or optimizations that are essential for their project requirements.

Optimized Performance: Custom methods can be designed to optimize database queries, data retrieval, and data manipulation operations, leading to improved performance and efficiency. By leveraging custom methods, developers can implement optimized algorithms, caching mechanisms, or query optimizations tailored to the specific needs and characteristics of their applications.

Improved Code Reusability and Maintainability: Custom methods promote code reusability by encapsulating specific logic, algorithms, or operations within reusable components. By modularizing the custom methods, developers can maintain cleaner, more organized, and maintainable codebases, making it easier to manage, debug, and enhance the DataSource repository in the long run.

Ok, That's that, let's move to the action. So, we have a simple CRM application that has to do with user management. Let's add a custom repository method that can help us filter users by username.

To implement this, let's create our datasource module and datasource service. We're going to create these files to to align with the modularity principles of the NestJS architectural pattern.

Create the files inside your previously created datasource folder and add the following code:

// datasource.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from './typeorm.module';
import { DataSourceService } from './datasource.service';

@Module({
  imports: [TypeOrmModule],
  providers: [DataSourceService],
  exports: [DataSourceService],
})
export class DataSourceModule {}

// datasource.service.ts
import { Injectable } from '@nestjs/common';
import { UserEntity } from 'src/users/users.entity';
import { DataSource } from 'typeorm';

export interface UsernameQuery {
  username: string;
}

@Injectable()
export class DataSourceService {
  constructor(private dataSource: DataSource) {}

  //   extend userRepository to add custom methods
  userCustomRepository = this.dataSource.getRepository(UserEntity).extend({
    async filterUser(usernameQuery: UsernameQuery): Promise<UserEntity[]> {
      const { username } = usernameQuery;
      console.log(username);
      // initialize a query builder for the userrepository
      const query = this.createQueryBuilder('user');
      //   filter user where username is like the passed username
      query.where('(LOWER(user.username) LIKE LOWER(:username))', {
        username: `%${username}%`,
      });
      return await query.getMany();
    },
  });
}

From the above datasource.service.ts code, we've extended the UserRepository, by calling the getRepository method on the dataSource service and passing UserEntity as an argument to get the repository for the particular table.

Then we called the extend method on the userRepository we got back from our getRepository to add our custom method. In our extend method, we passed an object that will contain all our custom methods for the custom repository we've assigned to the userCustomRepository. Here, we've simply added just one custom method to our custom user repository which is filterUser. It runs a filter query on the user table by the username provided.

Since our DataSourseService is an injectable, we can inject it in our UserService and consume the newly created filterUser method after adding the DataSourceModule to the imports array of the user module like so 👇

// users.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';
import { DataSourceModule } from 'src/datasource/datasource.module';

@Module({
  imports: [DataSourceModule], // add the DataSourceModule to the import array 
  providers: [UsersService],
  controllers: [UsersController],
})
export class UsersModule {}

Let's consume the filter method from CustomUserRepository in our UserService to filter users by any username passed as our query argument when sending the request.

// users.service.ts
import {
  HttpException,
  HttpStatus,
  Injectable,
  InternalServerErrorException,
  Logger,
} from '@nestjs/common';
import { DataSource } from 'typeorm';
import { UserEntity } from './users.entity';
import {
  DataSourceService,
  UsernameQuery,
} from 'src/datasource/datasource.service';

export interface CreateUser {
  username: string;
  password: string;
}

@Injectable()
export class UsersService {
  private userRepository;
  private customUserRepository;
  private logger = new Logger();
  //   inject the Datasource provider
  constructor(
    private dataSource: DataSource,
    private dataSourceService: DataSourceService, // inject our datasource service
  ) {
    // get users table repository to interact with the database
    this.userRepository = this.dataSource.getRepository(UserEntity);
    // assigning the dataSourceService userCustomRepository to the class customUserRepository
    this.customUserRepository = this.dataSourceService.userCustomRepository;
  }
  //  create handler to create new user and save to the database
  async createUser(createUser: CreateUser): Promise<UserEntity> {
    try {
      const user = await this.userRepository.create(createUser);
      return await this.userRepository.save(user);
    } catch (err) {
      if (err.code == 23505) {
        this.logger.error(err.message, err.stack);
        throw new HttpException('Username already exists', HttpStatus.CONFLICT);
      }
      this.logger.error(err.message, err.stack);
      throw new InternalServerErrorException(
        'Something went wrong, Try again!',
      );
    }
  }
  // the userService filterByUsername handler
  async filterByUsername(usernameQuery: UsernameQuery): Promise<UserEntity[]> {
    try {
    // calling the customUserRepository filterUser custom method
      return await this.customUserRepository.filterUser(usernameQuery);
    } catch (err) {
      this.logger.error(err.message, err.stack);
      throw new InternalServerErrorException(
        'Something went wrong, Try again!',
      );
    }
  }
}

From the above, code we've injected our custom DataSourceService by adding the following to the class constructor private dataSourceService: DataSourceService,.

The filterByUsername service handles the request we consume in our custom filterUser method await _this_.customUserRepository.filterUser(usernameQuery);, which will return a promise.

Now, let's utilize this service handler in our user controller to filter users by their username.

// users.controller.ts
import { Body, Controller, Get, Post, Query } from '@nestjs/common';
import { CreateUser, UsersService } from './users.service';
import { UserEntity } from './users.entity';
import { UsernameQuery } from 'src/datasource/datasource.service';

@Controller('users')
export class UsersController {
  constructor(private userService: UsersService) {}

  @Post('/create')
  //   handles the post request to /users/create endpoint to create new user
  async signUp(@Body() user: CreateUser): Promise<UserEntity> {
    return await this.userService.createUser(user);
  }

  @Get('') // get request handler that returns the filtered results of the users table
  async filterUser(
    @Query() usernameQuery: UsernameQuery // extracts the username query param for the endpoint url,
  ): Promise<UserEntity[]> {
    return await this.userService.filterByUsername(usernameQuery);
  }
}

Test our filter endpoint,

_test_filterendpoint

Here, we got back a list with one user object with username like the username we passed as a query.

Conclusion

Voila! That's it, now you ready to start working with NestJS, TypeORM, and DataSource.

Thanks for reading!

If you've found it helpful, please share it with your friends and colleagues! Stay tuned for more insightful content, and let's continue learning and growing together. Cheers to building smarter, more efficient solutions with NestJS!

Resources

• NestJS Docs Page
• TypeORM Docs Page
• Learn NestJS Complete Course

Contact Links

• Twitter
• LinkedIn
• GitHub

While learning Nestjs, I wanted to be able to send test emails with Nodemailer but I had difficulty doing this in the context of a NestJS application. I searched the internet for a solution and after much research, I found one. It turned out to be really simple.

In this article, I will share my solution so you can use it in your NestJS projects.

Table of Contents

• How to Set Up a NestJS Project
• How to Configure Nodemailer in Your App
• How to Send emails with Nodemailer
• Conclusion

How to Set Up a NestJS Project

Ideally, when a user clicks on a forget password route, a link should be sent to the user's email, and through that link, the user should be able to reset their password. This article will demonstrate a test case scenario of how this works using Nodemailer.

Open your favorite IDE or navigate to the terminal and paste the following command:

$ npm i -g @nestjs/cli
$ nest new nodemailer-app

The above commands generates a new project called nodemailer-app.

After doing this, navigate to your project folder and install the Nodemailer packages, npm i --save @nestjs-modules/mailer nodemailer and types, npm i --save-dev @types/nodemailer.

How to Configure Nodemailer in Your App

Before moving on, make sure you have an account on mailtrap.io. If you do, just login and navigate to Email Testing. Create your own inbox if you don't have one. Navigate to the inbox and you should see your credentials which will be used to configure Nodemailer in your application.

In your project directory, go to the app module file and configure the package:

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { AuthModule } from './auth/auth.module';
import { MailerModule } from '@nestjs-modules/mailer';

@Module({
  imports: [
    AuthModule,
    MailerModule.forRoot({
      transport: {
        host: process.env.EMAIL_HOST,
        auth: {
          user: process.env.EMAIL_USERNAME,
          pass: process.env.EMAIL_PASSWORD,
        },
      },
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

In the above code, you imported the MailerModule from @nestjs-modules/mailer. Then you called a forRoot() method on it. Inside the forRoot() method, you specified a transport property which contains the host and auth properties.

Do not forget to get the host, port, username and password from your credentials in your inbox on mailtrap.io.

You can create a .env file which would house all your credential details. It is advisable to do so. To be able to load the appropriate .env file in NestJS, install this:

$ npm i --save @nestjs/config

Then in your app.module.ts file, import a ConfigModule:

import { ConfigModule } from '@nestjs/config';

Still in your app.module.ts

// include the config module in your imports array

@Module({
  imports: [
    ConfigModule.forRoot({ envFilePath: '.env', isGlobal: true }),
  ],
  controllers: [AppController],
  providers: [AppService],
})

How to Send Emails with NodeMailer

After configuring Nodemailer, it is time to send emails with it.

In your app.service.ts file, paste the following code:

import { MailerService } from '@nestjs-modules/mailer';
import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  constructor(private readonly mailService: MailerService) {}

  sendMail() {
    const message = `Forgot your password? If you didn't forget your password, please ignore this email!`;

    this.mailService.sendMail({
      from: 'Kingsley Okure <kingsleyokgeorge@gmail.com>',
      to: 'joanna@gmail.com',
      subject: `How to Send Emails with Nodemailer`,
      text: message,
    });
  }
}

In the app.service.ts file, the MailerService is injected and then used in the class to send the email. Inside the class, the MailerService has a sendMail function which takes in an object as a parameter. The object contains a from, to, subject and text property.

Once you have done this, in the app.controller.ts file, paste the following code:

import { Controller, Get, Res } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  sendMailer(@Res() response: any) {
    const mail = this.appService.sendMail();

    return response.status(200).json({
      message: 'success',
      mail,
    });
  }
}

All that is done in the controller is to create a Get request which will call the sendMail function you have created in the service.

Ideally, in a real world application, all this will be done in a forgot password function. And an email will be sent to the user once they click on a forgot password route.

To test this little setup, open your Postman and go to localhost:3000 and hit send.

Then go to your mailtrap.io inbox and see your message.

Conclusion

In this article, you have learned how to send emails with Nodemailer, a software designed to help developers send emails to multiple people at once.

You have also learned how to configure and set it up in the context of a NestJs application.

If you want to connect with me, you can follow me on Twitter or on Linkedin

Learning NestJS can significantly enhance your ability to create structured, maintainable, and testable backend applications, offering a robust toolkit that integrates seamlessly with other modern technologies and methodologies.

We just posted a comprehensive NestJS course on the freeCodeCamp.org YouTube channel. This course, crated by the experienced Haider Malik, will help you master the creation of robust backend APIs for real-world applications.

In this course, Haider Malik, a seasoned web developer and open-source advocate, will guide you through the process of developing Spotify clone backend. Starting from database design to REST API development and deployment, this course is structured to provide a deep understanding of backend architecture using a blend of NestJS, Node.js, PostgreSQL, and MongoDB.

The course contains multiple modules, each designed to tackle different aspects of backend development with NestJS. From understanding the basics of NestJS, creating REST APIs, handling middlewares and exception filters, to implementing authentication and authorization, the course is a deep dive into backend development.

Further modules cover advanced topics like connecting with databases using TypeORM, implementing relationships in databases, and securing APIs with JWT authentication. Learners will also get hands-on experience with migrations, seeding, debugging, and even deploying NestJS applications to cloud services.

The course does not stop at REST APIs; it also introduces GraphQL, showcasing how to build and authenticate GraphQL APIs. Advanced concepts like WebSocket integration, file handling, custom decorators, and even real-time subscriptions with GraphQL are covered, ensuring learners are well-versed in the latest backend development practices.

Here is the full course outline.

Module 0

• What is Nestjs
• Create NestJs Project
• Nestjs Directory Structure

Module 1

• Creating Controller
• Creating a Service
• Creating Module

Module 2

• Middleware
• Exception Filter
• Transform param using ParseIntPipe
• Validate Request Body using class validator

Module 3

• Custom Providers
• Injection Scopes
• One To Many Relation

Module 4

• Establish Database Connection
• Create an Entity
• Create and Fetch records from Database
• Pagination

Module 5

• One to One
• Many to Many relation

Module 6

• User Signup
• User Login
• Authenticate User with Passport JWT
• Role Based Authentication
• Two Factor Authentication
• API Key Authentication

Module 7

• Debug Nestjs Application
• Migrations
• Seeding

Module 8

• Custom Configuration
• Validate Env Variables
• Hot Module Reloading

Module 9

• Swagger Setup
• Document Signup Route
• Create Schema using ApiProperty
• Test JWT Authentication

Module 10

• Install MongoDB using Docker Compose
• Connect with MongoDB
• Create Schema
• Save Record in Mongo Collection
• Find and Delete
• Populate

Module 11

• Configure Dev and Production Env
• Push Source Code to Github Repo
• Deploy Nestjs Project to Railway
• Install Dotenv to work with TypeORM migrations
• Fixing Env Bugs

Module 12

• Getting started with Jest
• Auto Mocking
• SpyOn Function
• Unit Test Controller
• Unit Test Service
• E2E Testing

Module 13

• Speedy Web Compiler with Nestjs v10
• Creating Websocket Server
• Send Message from Frontend app

Module 14

• GraphQL Server Setup
• Define Queries and Mutations
• Resolve Queries
• Resolve Mutations
• Error Handling

Module 15

• Define Schema for Authentication
• Resolve Auth Queries and Mutations
• Apply Authentication using Auth Guard

Module 16

• Implement Real time Subscription

Module 17

• Unit Test Resolver
• End to End Testing GraphQL APIs

Module 18

• Server Side Caching using Apollo
• Optimize Query Performance using Data Loader
• Fetching Data from External REST API

Module 19

• Setup Prisma
• Models and Migrations
• Generate Prisma Client
• Create, Find and FindOne
• Update and Delete Operation.mov
• One to Many Relation
• One to One Relation
• Many to Many Relation
• Bulk or Batch Operations
• Implement Transaction using Nested Queries
• Interactive Transactions

Module 20

• File Upload
• Custom Decorator
• Scheduling CRON Task with Nest.js
• Cookies
• Queues
• Event Emitter
• Streaming
• Session

Each lesson is designed to be highly practical, ensuring that learners not only understand the theoretical aspects but also get to implement what they've learned in real-world scenarios. This hands-on approach, combined with Haider's expert guidance, ensures that by the end of the course, participants will be confident in building and deploying robust backend systems.

Watch the full course on the freeCodeCamp.org YouTube channel (14-hour watch).

If you are reading this article, you are probably a developer who has used an API to call data for your application. You may have also used features such as filtering and pagination to limit the amount of data you want to receive.

These API features are important when building your own API. They help ensure that your API is fast, secure, and easily understandable by the people using it.

In this article, you will build a simple expense API with Nest.js and MongoDB for a database. You will then implement filtering, sorting, limiting, and pagination to make your API faster and easy to use. Let's begin!

Here's what we'll cover:

• What is an API?
• How to set up a Nest.js app
• How to configure MongoDB
• How to set up the expense endpoints
• How to implement filtering and sorting
• How to implement limiting and pagination
• Conclusion

What is an API?

APIs are the backbone of modern software development. API stands for Application Programming Interface, and it allows one piece of software to communicate with another piece of software.

Web APIs use the HTTP communication protocols to communicate with computers. There are different types of APIs, but we won't get into them here.

These days, it's common for web APIs to have design features such as filtering, sorting, limiting, and pagination to make the API faster, easier to use, and more secure. You will learn how to implement these features to make a better API in this article.

How to Set Up a Nest.js App

First of all, you will be building a simple expense CRUD API in Nestjs. Nestjs is a progressive Node.js framework for building modern APIs that's pretty easy to use.

To get started, open your command line and type out the following commands:

$ npm i -g @nestjs/cli
$ nest new expense-app

Follow the installation guide. This will generate a few boilerplate files for you. Then you can open your Nest.js app in an IDE of your choice.

How to Configure MongoDB

Since MongoDB is our preferred database, it's important to configure it so you can use it in your app. First install the @nestjs/mongoose package:

$ npm i @nestjs/mongoose mongoose

Once the installation is complete, go into your app module file and import the MongooseModule:

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { MongooseModule } from '@nestjs/mongoose';

@Module({
  imports: [MongooseModule.forRoot(`mongodb+srv://*******:*******@cluster0.30vt0jd.mongodb.net/expense-test-app`)],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

If you don't want to expose your string that way, you can create a .env file and store your database connection string in it. You will then need to install the @nestjs/config package which uses dotenv internally.

Inside your app module file, import the ConfigModule:

@Module({
  imports: [
    ConfigModule.forRoot({ envFilePath: '.env', isGlobal: true }),
    MongooseModule.forRoot(process.env.DATABASE),
  ],
  controllers: [AppController],
  providers: [AppService],
})

isGlobal: true is to make the module available everywhere in your application. envFilePath specifies the path to your .env file.

How to Set Up the Expense Endpoints

You have configured MongoDB. Now it's time to set up the expense endpoints.

You can create a module in Nest.js by typing the following into the terminal: nest generate module expenses. You can also generate the controller like this: nest generate controller expenses and the service like this: nest generate service expenses. You should do all this in the src folder.

Go ahead and generate an expenses.schema.ts file. Inside the expenses.schema.ts file, create an expense schema with some validation.

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

export type ExpenseDocument = HydratedDocument<Expense>;

@Schema()
export class Expense {
  @Prop({
    trim: true,
    required: [true, 'Title is required'],
  })
  title: string;

  @Prop({
    min: 0,
    required: [true, 'Amount is required'],
  })
  amount: number;

  @Prop({
    type: String,
    trim: true,
    required: [true, 'Category is required'],
  })
  category: string;

  @Prop({
    type: Date,
    default: Date.now,
  })
  incurred: Date;

  @Prop({ type: String, trim: true })
  notes: string;

  @Prop()
  slug: string;

  @Prop()
  updated: Date;

  @Prop({
    type: Date,
    default: Date.now,
  })
  created: Date;
}

export const ExpenseSchema = SchemaFactory.createForClass(Expense);

The properties in this schema include title, amount, category, notes, and slug.

After doing this, you want to register the expense model in the expenses.module.ts file:

import { Module } from '@nestjs/common';
import { ExpensesController } from './expenses.controller';
import { ExpensesService } from './expenses.service';
import { MongooseModule } from '@nestjs/mongoose';
import { Expense, ExpenseSchema } from './expenses.schema';

@Module({
  imports: [
    MongooseModule.forFeature([{ name: Expense.name, schema: ExpenseSchema }]),
  ],
  controllers: [ExpensesController],
  providers: [ExpensesService],
})
export class ExpensesModule {}

Once you've registered the schema, you can then inject the Expense model into the ExpensesService by using an @InjectModel() decorator.

import { Injectable } from '@nestjs/common';
import { InjectModel } from '@nestjs/mongoose';
import { Expense } from './expenses.schema';
import { Model } from 'mongoose';
import { ExpenseDto } from './dto/expense.dto';

@Injectable()
export class ExpensesService {
  constructor(
    @InjectModel(Expense.name) private expenseModel: Model<Expense>,
  ) {}

  async createExpense(data: ExpenseDto) {
    const expense = this.expenseModel.create(data);

    return expense;
  }

  async getExpenses() {
    const expenses = await this.expenseModel.find();

    return expenses;
  }
}

In the ExpensesService file, we injected the Expense model as a dependency using the @InjectModel() decorator. Once you've done this, you then go ahead and define a function that creates an expense and a function that gets all expenses.

In your controller, add the following code:

import { Body, Controller, Get, Post, Res } from '@nestjs/common';
import { ExpensesService } from './expenses.service';
import { ExpenseDto } from './dto/expense.dto';

@Controller('expenses')
export class ExpensesController {
  constructor(private readonly expenseService: ExpensesService) {}

  @Post()
  async createExpense(@Body() data: ExpenseDto, @Res() response: any) {
    const expense = await this.expenseService.createExpense(data);
    console.log(expense);

    return response.status(201).json({
      message: 'success',
      data: expense,
    });
  }

  @Get()
  async getExpenses(@Res() response: any) {
    const expenses = await this.expenseService.getExpenses();

    return response.status(200).json({
      message: 'success',
      data: expenses,
    });
  }
}

If you're getting a dependency error, navigate to your app.module.ts file and remove ExpenseController from the controllers array.

You can test the endpoint on Postman.

How to Implement Filtering and Sorting

Now that you have successfully set up the expense endpoints, it's time to implement filtering and sorting features in the API.

Filtering

Filtering is essentially done in the same way we do it in Node.js.

Inside your src directory, create a new folder called Utils and inside that folder create a new file called apiFeatures.ts.

Inside this file, define a class called APIFeatures. This class will contain methods that will house the API features you'll implement.

export class APIFeatures {
  mongooseQuery: any;
  queryString: any;

  constructor(mongooseQuery: any, queryString: any) {
    this.mongooseQuery = mongooseQuery;
    this.queryString = queryString;
  }

  filter() {
    // 1) Filtering
    const queryObj = { ...this.queryString };
    const excludedFields = ['page', 'sort', 'limit', 'fields'];
    excludedFields.forEach((fields) => {
      delete queryObj[fields];
    });
    // console.log(queryObj);

    //2) Advanced filtering
    let queryStr = JSON.stringify(queryObj);
    queryStr = queryStr.replace(/\b(gte|gt|lte|lt)\b/g, (match) => `$${match}`);
    //console.log(JSON.parse(queryStr));

    this.mongooseQuery = this.mongooseQuery.find(JSON.parse(queryStr));

    return this;
  }
}

In the filter method, you created a hard copy of the req.query. It's passed as an argument in the form of queryString.

Before filtering, you want to exclude certain special fileds such as page, sort, limits and fields. These fields are deleted from the hard copy of the object which is stored in the variable queryObj. You also want to use MongoDB operators such as gt or gte.

For example, on Postman this is how you type in the query: ?amount[gt]=100 In MongoDB, It'll look like this: { amount: { $gt: 100 } }. In the filter method, we added a $ sign to the operators using a regular expression.

After that, the object is parsed using JSON.parse() method and it is then passed into the Mongoose query function. Make sure you return the whole class itself by typing return this.

Sorting

As you can see, implementing fitering is quite easy in Nest.js as it is in Node.js.

Now it's time to implement sorting. Inside the APIFeatures class, define another function called sorting.

  sorting() {
    if (this.queryString.sort) {
      const sortBy = this.queryString.sort.split(',').join(' ');
      // console.log(sortBy);
      this.mongooseQuery = this.mongooseQuery.sort(sortBy);
    } else {
      this.mongooseQuery = this.mongooseQuery.sort('-created');
    }

    return this;
  }

The above method checks if a sort property exists on the query object. If it does, you split the string by a , in case there are multiple sort queries. Then you join it by a ' '.

Once you've done this, you chain it to the Mongoose query with a sort method which exists on all documents. The else block sorts the document by the date it was created in case the user does not specify any sort query.

How to Implement Limiting and Pagination

Congrats! You have implemented filtering and sorting. Now it's time to implement limiting and pagination.

Limiting

To limit fields, you can call the select() method on the Mongoose query.

Define another method in the class:

 limit() {
    if (this.queryString.fields) {
      const fields = this.queryString.fields.split(',').join(' ');

      this.mongooseQuery = this.mongooseQuery.select(fields);
    } else {
      this.mongooseQuery = this.mongooseQuery.select('-__v');
    }

    return this;
  }

And there you go.

Pagination

To implement pagination, you want to get the page and limit from the query object. You then want to skip certain number of documents to get to the page you want. There is a skip() method and a limit() method on the Mongoose query.

  pagination() {
    // get the page and convert it to a number. If no page set default to 1
    const page = this.queryString.page * 1 || 1;

    // get limit and if no limit, set limit to 100
    const limit = this.queryString.limit * 1 || 100;

    // calculate skip value
    const skip = (page - 1) * limit;

    // chain it to the mongoose query.
    this.mongooseQuery = this.mongooseQuery.skip(skip).limit(limit);

    // return the object
    return this;
  }

Once you've done this, you want to call the APIfeatures class in your ExpensesService class in your expenses.service.ts file.

Replace your getExpenses function with this code:

 async getExpenses(query?: any) {
    const features = new APIFeatures(this.expenseModel.find(), query)
      .filter()
      .sort()
      .limit()
      .pagination();
    //Execute the query
    const expenses = await features.mongooseQuery;

    return expenses;
  }

In the function, it is possible to chain all these methods in the APIFeatures class because each method returns the object.

In your expenses.controller.ts file, your getExpenses function should look like this:

  @Get()
  async getExpenses(@Res() response: any, @Req() request: any) {
    const expenses = await this.expenseService.getExpenses(request.query);

    return response.status(200).json({
      message: 'success',
      data: expenses,
    });
  }

Now run the application with npm start:dev and test your API features in Postman.

Conclusion

In this guide, you have learned how to implement sorting, filtering, limiting, and pagination in your Nest.js applications.

With this knowledge, you can go ahead and implement these features in your personal projects built using Nest.js.

In this journey, we'll be creating a delightful recipe management system. We'll explore the power of NestJS, Docker, Swagger, and Prisma, and harness these cutting-edge technologies to implement CRUD (Create, Read, Update, Delete) operations for managing recipes.

But this tutorial isn't just for the culinary enthusiasts or recipe collectors out there. It's for anyone who's passionate about learning and growing their development skills.

So, buckle up and get ready for an exciting coding adventure as we dive in and start building your very own recipe management system together.

This is what we'll build:

A snapshot of the Swagger UI showcasing all the implemented endpoints.

And here's what we'll cover:

Table of Contents

• Technologies
• Prerequisites
• Development Environment
• How to Set Up the NestJS Project
• How to Create a PostgreSQL Instance with Docker
• How to Set Up Prisma
• How to Initialize Prisma
• How to Set Your Environment Variable
• Understanding the Prisma Schema
• How to Model the Data
• How to Migrate the Database
• How to Seed the Database
• How to Create a Prisma Service
• How to Set Up Swagger
• How to Implement CRUD Operations for the Recipe Model
• How to Generate REST Resources with NestJS CLI
• How to Add PrismaClient to the Recipe Module
• How to Define the GET /recipes Endpoint
• How to Define the GET /recipes/:id Endpoint
• How to Define the POST /recipes Endpoint
• How to Define the PATCH /recipes/:id Endpoint
• How to Define the DELETE /recipes/:id Endpoint
• Summary and Final Remarks

Technologies

To build this application, we'll be leveraging the power of the following tools:

• NestJS: A progressive Node.js framework for building efficient, reliable, and scalable server-side applications.
• Prisma: An open-source database toolkit that makes it easy to reason about your data and how you interact with it.
• PostgreSQL: A powerful, open source object-relational database system.
• Docker: An open platform for developing, shipping, and running applications. Docker enables you to separate your applications from your infrastructure so you can deliver software quickly.
• Swagger: A tool for designing, building, and documenting RESTful APIs.
• TypeScript: A statically typed superset of JavaScript that adds optional types, classes, and modules to the language.

Each of these technologies plays a crucial role in creating a robust, scalable, and maintainable application. We'll dive deeper into each one as we proceed.

Prerequisites

Assumed Knowledge

This tutorial is designed to be beginner-friendly, but I do make a few assumptions about what you already know:

• Fundamentals of TypeScript
• Basics of NestJS
• Docker

If you're not familiar with these, don't fret! I've got you covered. This tutorial will guide you through everything you need to know.

But here are some more resources if you'd like to learn more:

• For a deeper dive into NestJS, feel free to explore the official NestJS documentation.
• To learn more about Docker, here's a full handbook for beginners.
• And for more info on TypeScript, here's a helpful crash course.

Development Environment

Tools and Technologies

In this tutorial, we'll use the following tools:

• Node.js – Our runtime environment
• Docker – For containerizing our database
• Visual Studio Code – Our code editor
• PostgreSQL – Our database
• NestJS – Our Node.js framework

Note: Don't forget to install the Prisma extension for Visual Studio Code. It enhances your coding experience by highlighting Prisma-specific syntax and keywords.

How to Set Up the NestJS Project

NestJS is a progressive Node.js framework that comes with a plethora of advantages, including a powerful Command Line Interface (CLI). This CLI simplifies the process of creating a new NestJS application, making it easy to start a new project anytime, anywhere.

One of the key benefits of NestJS is its rich set of built-in functionalities that significantly streamline the development process, making your life as a developer much easier.

Let's begin by installing the NestJS CLI on your system:

npm i -g @nestjs/cli

With the NestJS CLI installed, you're all set to whip up our recipe project. The CLI streamlines the creation of a new NestJS application, making it simple to get started.

To spin up a new project, execute the following command:

nest new recipe

After running this command, you'll encounter a prompt like the one you see below:

The Nest CLI prompting for a package manager selection during project setup.

As illustrated in the image, the Nest CLI will prompt you to select a package manager. For this project, we'll opt for npm. Once you've made your selection, the CLI will proceed with the project setup, and you'll see a series of operations being performed in your terminal.

Now you can open you project in VSCode (or the editor of your choice). You should see the following files:

The folder structure of the project after it has been created using Nest CLI.

Let break down the project structure:

The src directory is the nerve center of our application, hosting the bulk of our codebase. The NestJS CLI has already set the stage for us with several key files:

• src/app.module.ts: This is the root module of our application, serving as the main junction for all other modules.
• src/app.controller.ts: This file houses a basic controller with a single route: /. When accessed, this route will return a simple 'Hello World!' message.
• src/main.ts: This is the gateway to our application. It's tasked with bootstrapping and launching the NestJS application.

To start your project and see the 'Hello World!' message in action, execute the following command:

npm run start:dev

This command triggers a live-reload development server. It vigilantly monitors your files, and if it spots any modifications, it automatically recompile your code and refreshes the server. This ensures that you can see your changes in real-time, eliminating the need for manual restarts.

To verify that your server is operational, head over to http://localhost:3000/ in your web browser or Postman. You should be welcomed by a minimalist page showcasing the message Hello World. This is your application's default landing page, a pristine canvas awaiting your creative touch.

How to Create a PostgreSQL Instance with Docker

To store our recipes REST API, we'll use a PostgreSQL database. Docker will help us containerize this database, ensuring a smooth setup and execution, regardless of the environment.

First, ensure Docker is installed on your system. If not, follow the instructions here.

Next, you'll need to create a docker-compose.yml file.

Open the terminal and run the following command:

touch docker-compose.yml

This command creates a new docker-compose.yml file in your project's root directory.

Open the docker-compose.yml file and add the following code:

# docker-compose.yml

version: '3.8'
services:
  postgres:
    image: postgres:13.5
    restart: always
    environment:
      - POSTGRES_USER=recipe
      - POSTGRES_PASSWORD=RecipePassword
    volumes:
      - postgres:/var/lib/postgresql/data
    ports:
      - '5432:5432'
volumes:
  postgres:

Here's a quick breakdown of this configuration:

• image: postgres:13.5: Specifies the Docker image for the PostgreSQL database.
• restart: always: Ensures the container restarts if it stops.
• environment: Sets the username and password for the database.
• volumes: Mounts a volume to persist database data, even if the container is stopped or removed.
• ports: Exposes port 5432 on both the host machine and the container for database access.

Note: If you wish to use a different port, simply change the host machine port. For example, to use port 5433, modify the ports section as follows:

ports:
  - '5444:5432'

Note: Before proceeding, ensure port 5432 is free on your machine. To fire up the PostgreSQL container, execute the following command in your project's root directory (and also make sure you have open the docker desktop app and it is running):

docker-compose up

This command spins up the PostgreSQL container and makes it accessible on port 5432 of your machine. If all goes according to plan, you should see output similar to this:

...
 | PostgreSQL init process complete; ready for start up.
postgres-1  |
postgres-1  | 2024-01-12 14:59:33.519 UTC [1] LOG:  starting PostgreSQL 13.5 (Debian 13.5-1.pgdg110+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
postgres-1  | 2024-01-12 14:59:33.520 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
postgres-1  | 2024-01-12 14:59:33.520 UTC [1] LOG:  listening on IPv6 address "::", port 5432
postgres-1  | 2024-01-12 14:59:33.526 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
postgres-1  | 2024-01-12 14:59:33.533 UTC [62] LOG:  database system was shut down at 2024-01-12 14:59:33 UTC
postgres-1  | 2024-01-12 14:59:33.550 UTC [1] LOG:  database system is ready to accept connections

Remember, if you've changed the port number, the output will reflect your chosen port.

If the port is already in use, you'll encounter an error message like this:

Error starting userland proxy: listen tcp 0.0.0.0:5432: bind: address already in use

In such a case, free up the port or choose a different one in your docker-compose.yml file.

Note: if you close the terminal window, it will also stop the container. To prevent this, you can run the container in detached mode. This mode allows the container to run indefinitely in the background.

To do this, add a -d option at the end of the command, like so:

docker-compose up -d

To stop the container, use the following command:

docker-compose down

Congratulations 🎉. You now have your own PostgreSQL database to play around with.

How to Set Up Prisma

Now that we have our PostgreSQL database up and running, we're ready to set up Prisma. Prisma is an open-source database toolkit that makes it easy to reason about your data and how you interact with it.

Prisma is a powerful tool that offers a wide range of features, including:

• Database Migrations: Prisma makes it easy to evolve your database schema over time, without losing any data.
• Database Seeding: Prisma allows you to seed your database with test data.
• Database Access: Prisma provides a powerful API for accessing your database.
• Database Schema Management: Prisma allows you to define your database schema using the Prisma Schema Language.
• Database Querying: Prisma provides a powerful API for querying your database.
• Database Relationships: Prisma allows you to define relationships between your database tables.

You can learn more about Prisma here.

How to Initialize Prisma

To get started with Prisma, we'll need to install the Prisma CLI. This CLI allows us to interact with our database, making it easy to perform database migrations, seeding, and more.

To install the Prisma CLI, execute the following command:

npm install prisma -D

This command installs the Prisma CLI as a development dependency in your project. The -D flag tells npm to install the package as a development dependency.

Next, initialize Prisma in your project by executing the following command:

npx prisma init

This will create a new prisma directory with a schema.prisma file. This is the main configuration file that contains your database schema. This command also creates a .env file inside your project.

How to Set Your Environment Variable

The .env file contains the environment variables required to connect to your database. Open this file and replace the contents with the following:

DATABASE_URL="postgres://recipe:RecipePassword@localhost:5444/recipe"

Note: If you changed the port number in your docker-compose.yml file, ensure you update the port number in the DATABASE_URL environment variable with the port number you used.

This environment variable contains the connection string for your database. It's used by Prisma to connect to your database in the docker container.

Understanding the Prisma Schema

The schema.prisma file contains the schema for your database. It's written in the Prisma Schema Language, a declarative language for defining your database schema. The prisma/schema.prisma file is the main configuration file for your Prisma setup. It defines your database connection and the Prisma Client generator.

// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

This file is written in the Prisma Schema Language, which is a language that Prisma uses to define your database schema. The schema.prisma file has three main components:

• Generator: This section defines the Prisma Client generator. The Prisma Client generator is responsible for generating the Prisma Client, a powerful API for accessing your database.
• Datasource: This section defines the database connection. It specifies the database provider and the connection string. It use DATABASE_URL environment variable to connect to your database.
• Model: This section defines the database schema. It specifies the database tables and their fields.

How to Model the Data

Now that we have set up our Prisma, we're ready to model our data. We'll be building a recipe management system, so we'll need to define a Recipe model. This model will have various fields.

Open the schema.prisma file and add the following code:

 // prisma/schema.prisma
 // ...
model Recipe {
  id           Int      @id @default(autoincrement())
  title        String   @unique
  description  String?
  ingredients  String
  instructions String
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt
}

Here's a quick breakdown of this model:

• id: This is the primary key of the Recipe model. It's an auto-incrementing integer that uniquely identifies each recipe. It has the @id attribute, which tells Prisma that this field is the primary key. It also has the @default(autoincrement()) attribute, which tells Prisma to auto-increment this field.
• title: This is the title of the recipe. It's a unique string that's used to identify the recipe.
• description: This is the description of the recipe. It's an optional string that describes the recipe.
• ingredients: This is the list of ingredients used in the recipe. It's a string that contains a comma-separated list of ingredients.
• instructions: This is the list of instructions for preparing the recipe. It's a string that contains a comma-separated list of instructions.
• createdAt: This is the date and time the recipe was created. It's set to the current date and time by default. It has the @default(now()) attribute, which tells Prisma to set this field to the current date and time by default.
• updatedAt: This is the date and time the recipe was last updated. It's set to the current date and time by default.

How to Migrate the Database

Now that we've defined our database schema, we're ready to migrate our database. This will create the database tables and fields defined in our schema.prisma file.

To migrate your database, execute the following command:

npx prisma migrate dev --name init

This command will do three things:

Save the migration: Prisma Migrate will take a snapshot of your schema and figure out the SQL commands necessary to carry out the migration. Prisma will save the migration file containing the SQL commands to the newly created prisma/migrations folder.

Execute the migration: Prisma Migrate will execute the SQL commands in the migration file, creating the database tables and fields defined in your schema.prisma file.

Generate Prisma Client: Prisma will generate Prisma Client based on your latest schema. Since you did not have the Client library installed, the CLI will install it for you as well. You should see the @prisma/client package inside dependencies in your package.json file.

Prisma Client is a TypeScript query builder auto-generated from your Prisma schema. It is tailored to your Prisma schema and will be used to send queries to the database.

If all goes according to plan, you should see output similar to this:

The following migration(s) have been created and applied from new schema changes:

migrations/
  └─ 20220528101323_init/
    └─ migration.sql

Your database is now in sync with your schema.
...
✔ Generated Prisma Client (3.14.0 | library) to ./node_modules/@prisma/client in 31ms

Check the generated migration file to get an idea about what Prisma Migrate is doing behind the scenes:

-- prisma/migrations/20220528101323_init/migration.sql

CREATE TABLE "Recipe" (
    "id" SERIAL NOT NULL,
    "title" TEXT NOT NULL,
    "description" TEXT,
    "ingredients" TEXT NOT NULL,
    "instructions" TEXT NOT NULL,
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" TIMESTAMP(3) NOT NULL,

    CONSTRAINT "Recipe_pkey" PRIMARY KEY ("id")
);

-- CreateIndex
CREATE UNIQUE INDEX "Recipe_title_key" ON "Recipe"("title");

This migration file contains the SQL commands necessary to create the Recipe table. It also contains the SQL commands necessary to create the title field, which is a unique field. This ensures that the title field is unique, preventing duplicate recipes from being created.

How to Seed the Database

Now that we've migrated our database, we're ready to seed it with some test data. This will allow us to test our application without having to manually create recipes.

Firstly, create a seed file called prisma/seed.ts. This file will contain the dummy data and queries needed to seed your database.

Open the terminal and run the following command:

touch prisma/seed.ts

This command creates a new prisma/seed.ts file in your project's root directory.

Next, populate this file with the following code:

// prisma/seed.ts
import { PrismaClient } from '@prisma/client';

// initialize Prisma Client
const prisma = new PrismaClient();

async function main() {
  // create two dummy recipes
  const recipe1 = await prisma.recipe.upsert({
    where: { title: 'Spaghetti Bolognese' },
    update: {},
    create: {
      title: 'Spaghetti Bolognese',
      description: 'A classic Italian dish',
      ingredients:
        'Spaghetti, minced beef, 
        tomato sauce, onions, garlic, olive oil, salt, pepper',
      instructions:
        '1. Cook the spaghetti. 2. Fry the minced beef. 3.
        Add the tomato sauce to the beef.
        4. Serve the spaghetti with the sauce.'
    }
  });

  const recipe2 = await prisma.recipe.upsert({
    where: { title: 'Chicken Curry' },
    update: {},
    create: {
      title: 'Chicken Curry',
      description: 'A spicy Indian dish',
      ingredients:
        'Chicken, curry powder, onions, garlic, 
        coconut milk, olive oil, salt, pepper',
      instructions:
        '1. Fry the chicken. 2. Add the curry powder to the
        chicken. 3. Add the coconut milk.
        4. Serve the curry with rice.'
    }
  });

  console.log({ recipe1, recipe2 });
}

// execute the main function
main()
  .catch(e => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    // close Prisma Client at the end
    await prisma.$disconnect();
  });

This file contains the dummy data and queries needed to seed your database. Let's break it down:

• import { PrismaClient } from '@prisma/client';: This imports the Prisma Client, which is used to send queries to the database.
• const prisma = new PrismaClient();: This initializes the Prisma Client, allowing us to send queries to the database.
• async function main() { ... }: This is the main function that contains the dummy data and queries needed to seed your database.
• const recipe1 = await prisma.recipe.upsert({ ... });: This creates a new recipe. It uses the upsert method, which creates a new recipe if it doesn't exist, or updates the existing recipe if it does.
• const recipe2 = await prisma.recipe.upsert({ ... });: This creates a new recipe. It uses the upsert method, which creates a new recipe if it doesn't exist, or updates the existing recipe if it does.
• console.log({ recipe1, recipe2 });: This logs the newly created recipes to the console.
• main().catch((e) => { ... });: This executes the main function and catches any errors that occur.
• await prisma.$disconnect();: This closes the Prisma Client at the end.

Now before we can seed our database, we need add a script to our package.json file. Open the package.json file and add the following script:

// package.json

// ...
  "scripts": {
    // ...
  },
  "dependencies": {
    // ...
  },
  "devDependencies": {
    // ...
  },
  "jest": {
    // ...
  },
  // pasting the prisma script here
  "prisma": {
    "seed": "ts-node prisma/seed.ts"
  }

The seed command will execute the prisma/seed.ts script that you previously defined. This command should work automatically because ts-node is already installed as a dev dependency in your package.json.

Now that we've defined our seed script, we're ready to seed the database. To seed your database, execute the following command:

npx prisma db seed

This command will seed your database with the dummy data defined in your prisma/seed.ts file. If all goes according to plan, you should see output similar to this:

Running seed command `ts-node prisma/seed.ts` ...
{
  recipe1: {
    id: 1,
    title: 'Spaghetti Bolognese',
    description: 'A classic Italian dish',
    ingredients: 'Spaghetti, minced beef, tomato sauce, onions, garlic, olive oil, salt, pepper',
    instructions: '1. Cook the spaghetti. 2. Fry the minced beef. 3. Add the tomato sauce to the beef. 4. Serve the spaghetti with the sauce.',
    createdAt: 2024-01-12T16:21:09.133Z,
    updatedAt: 2024-01-12T16:21:09.133Z
  },
  recipe2: {
    id: 2,
    title: 'Chicken Curry',
    description: 'A spicy Indian dish',
    ingredients: 'Chicken, curry powder, onions, garlic, coconut milk, olive oil, salt, pepper',
    instructions: '1. Fry the chicken. 2. Add the curry powder to the chicken. 3. Add the coconut milk. 4. Serve the curry with rice.',
    createdAt: 2024-01-12T16:21:09.155Z,
    updatedAt: 2024-01-12T16:21:09.155Z
  }
}

The seed command has been executed.

Congratulations 🎉. You now have a fully functional database with dummy data.

How to Create a Prisma Service

Now that we've set up Prisma, we're ready to create a Prisma service. This service will act as a wrapper around the Prisma Client, making it easy to send queries to the database.

The Nest CLI gives you an easy way to generate modules and services directly from the CLI. Run the following command in your terminal:

npx nest generate module prisma
npx nest generate service prisma

Note that the generate command can be shortened to g. So, you can also run the following command:

npx nest g module prisma
npx nest g service prisma

This command generates a new module called prisma and a new service called prisma. It also imports the PrismaModule into the AppModule.

So you should see something like this:

  src/prisma/prisma.service.spec.ts
  src/prisma/prisma.service.ts
  src/prisma/prisma.module.ts

Note: In some cases, you may need to restart your server for the changes to take effect.

Next, open the prisma.service.ts file and replace the contents with the following:

// src/prisma/prisma.service.ts

import { Injectable } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient {}

This service is a wrapper around the Prisma Client, making it easy to send queries to the database. It's also a NestJS provider, which means it can be injected into other modules.

Next, open the prisma.module.ts file and replace the contents with the following:

// src/prisma/prisma.module.ts
import { Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Module({
  providers: [PrismaService],
  exports: [PrismaService]
})
export class PrismaModule {}

Note: The PrismaModule is a NestJS module that imports the PrismaService, making it readily available for use across other modules in your application. This setup allows seamless integration of the Prisma service throughout your project.

Congratulations 🎉! You've successfully set up your Prisma service.

Before we dive into writing our application logic, let's set up Swagger. Swagger is an industry-standard tool for designing, building, and documenting RESTful APIs. It empowers developers to create elegant and comprehensive API documentation effortlessly.

How to Set Up Swagger

To configure Swagger, we'll leverage the @nestjs/swagger package. This package offers a suite of decorators and methods specifically designed to generate Swagger documentation.

To install this package, run the following command:

npm install --save @nestjs/swagger swagger-ui-express

This command adds the @nestjs/swagger package as a dependency in your project. It also installs the swagger-ui-express package, which serves the Swagger UI.

Next, navigate to the main.ts file and append the following code:

// src/main.ts

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

// Define the bootstrap function
async function bootstrap() {
  // Create a NestJS application instance by passing the AppModule to the NestFactory
  const app = await NestFactory.create(AppModule);

  // Use DocumentBuilder to create a new Swagger document configuration
  const config = new DocumentBuilder()
    .setTitle('Recipes API') // Set the title of the API
    .setDescription('Recipes API description') // Set the description of the API
    .setVersion('0.1') // Set the version of the API
    .build(); // Build the document

  // Create a Swagger document using the application instance and the document configuration
  const document = SwaggerModule.createDocument(app, config);

  // Setup Swagger module with the application instance and the Swagger document
  SwaggerModule.setup('api', app, document);

  // Start the application and listen for requests on port 3000
  await app.listen(3000);
}

// Call the bootstrap function to start the application
bootstrap();

This code initializes Swagger and generates the Swagger documentation. Let's break it down:

• const config = new DocumentBuilder() ... .build();: This creates a new Swagger document builder. It sets the title, description, and version of the Swagger document. It also builds the Swagger document.
• const document = SwaggerModule.createDocument(app, config);: This creates a new Swagger document. It uses the Swagger document builder to generate the Swagger document.
• SwaggerModule.setup('api', app, document);: This sets up the Swagger UI. It uses the Swagger document to generate the Swagger UI.