DEV Community: Dilum Darshana

Building an AI-Powered FAQ Assistant with Redis 8 and OpenAI

Dilum Darshana — Sat, 02 Aug 2025 14:32:36 +0000

What I Built

I built an AI-powered FAQ assistant that delivers instant, context-aware answers to user questions using Redis 8 and OpenAI. It supports semantic search with Redis Vector similarity and intelligently caches responses using RedisJSON to speed up repeated queries. Users can interact with a friendly chat interface that retrieves and returns answers in real time.

The goal of this project is to demonstrate how Redis can be used as a real-time AI data layer to power conversational interfaces, specifically for use cases like FAQs, support bots, and knowledge assistants.

Note that the cache duration is set to 15 mins due to the limited storage

Demo

Live App: https://master.d15ripqxac0b7u.amplifyapp.com

Initial page load:

Response from app:

With cached data:

From Redis Insight

Github: https://github.com/dilumdarshana/ai-faq-memory-assistant

How I Used Redis 8

Redis 8 was the core engine that powered both performance and intelligence in this project. Here’s how I used its features:

Redis Stack (RedisJSON + RediSearch + Vector Similarity Search):
I stored FAQ documents in Redis using the JSON data type. Each FAQ includes fields like question, answer, source, and a createdAt timestamp. The documents are indexed for full-text and semantic search using FT.CREATE.

Vector Search for Semantic Understanding:
Each question was embedded into a 1536-dimensional vector using OpenAI's embedding model. These vectors were stored in Redis and indexed using the HNSW algorithm. When a user asks a question, the assistant searches Redis using vector similarity to retrieve the most relevant context.

Intelligent Caching with RedisJSON:
Before sending a user query to the LLM, I check if a cached answer already exists for a similar query using Redis. This reduces token usage and cost while improving response time.

FT.SEARCH Sorting by Date:
For the "Recently Asked Questions" section, I used FT.SEARCH with sorting on the createdAt field to show the latest activity. (15 mins cache duration)

Redis not only made the solution real-time and scalable, but it also gave me a flexible and powerful way to combine structured, vector, and text search in one place.

Design:

Final Thoughts

This project shows how Redis 8 can be a game-changer for real-time AI applications. Whether you're building FAQ bots, search interfaces, or RAG-based assistants, Redis offers a powerful and developer-friendly solution.

Tech Stack:

Redis 8 (Vector Store, RediSearch, RedisJSON)
OpenAI (gpt-4o, embeddings)
Next.js (LangChain, TypeScript)
pnpm
AWS Amplify

How to Self-Host n8n and Access It from Anywhere

Dilum Darshana — Mon, 28 Jul 2025 18:17:12 +0000

Hello devs,

If you are building workflows and automations using n8n, you have probably thought:

“Can I run this on my own server and access it from anywhere?”

The answer is yes — and in this guide, I'll show you how to self-host n8n with Docker, securely expose it using ngrok, and run your automations from anywhere in the world.

Installing and Running n8n Locally

Running n8n with Docker is the easiest and most consistent way to set it up locally. It keeps your environment isolated, reproducible, and production-ready. No need to worry about system dependencies.

Create a directory for n8n:

$ mkdir n8n-local && cd n8n-local

Create a docker-compose.yml file:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    container_name: my-n8n-workflow
    restart: always
    ports:
      - "5678:5678"
    environment:
      # - DOMAIN_NAME=example.com
      # - SUBDOMAIN=n8n
      # - N8N_HOST=n8n.example.com
      # - N8N_PROTOCOL=https
      # - N8N_PORT=5678
      # - NODE_ENV=production
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - N8N_SECURE_COOKIE=false
      # - N8N_EDITOR_BASE_URL=<ngrok url>
      - N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
      # - WEBHOOK_URL=<ngrok url>
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem

    volumes:
      - ./n8n_data:/home/node/.n8n

Create .env file

GENERIC_TIMEZONE=Asia/Colombo

Start container

Note: There can be a user ownership issue in the n8n_data folder. Run the following command from the folder where container running,

$ sudo chown -R 1000:1000 ./n8n_data

$ docker-compose up -d

Test from local

Open your browser and navigate to:

http://localhost:5678

Complete the registration and survey (if prompted), and you’ll land on the n8n dashboard:

Setting up ngrok

Now let’s expose your local n8n instance to the internet using ngrok.

Signup at ngrok
https://dashboard.ngrok.com/signup
Install ngrok
Follow the instructions for your OS:

https://dashboard.ngrok.com/get-started/setup/macos

Add auth token

$ ngrok config add-authtoken xxxxxx

Your auth token can be found at: https://dashboard.ngrok.com/get-started/your-authtoken

Start a tunnel to port 5678

ngrok http --url=xxxxx.ngrok-free.app 5678

ngrok will provide a public HTTPS domain like https://xxxxx.ngrok-free.app.

Binding everything together

Now it’s time to update your Docker setup with the ngrok URL.

We need to stop the existing docker container, if it is running,

$ docker-compose down

Replace the environment variables with the ngrok domain:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    container_name: my-n8n-workflow
    restart: always
    ports:
      - "5678:5678"
    environment:
      # - DOMAIN_NAME=example.com
      # - SUBDOMAIN=n8n
      # - N8N_HOST=n8n.example.com
      # - N8N_PROTOCOL=https
      # - NODE_ENV=production
      - N8N_PORT=5678
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - N8N_SECURE_COOKIE=false
      - N8N_EDITOR_BASE_URL=xxxxx.ngrok-free.app
      - N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
      - WEBHOOK_URL=xxxxx.ngrok-free.app
      - N8N_DEFAULT_BINARY_DATA_MODE=filesystem

    volumes:
      - ./n8n_data:/home/node/.n8n

Start container again:

$ docker-compose up -d

That’s it! Visit:

https://xxxxx.ngrok-free.app

You now have full access to your local n8n instance from anywhere in the world.

Conclusion

Self-hosting n8n with Docker and exposing it using ngrok is a powerful way to:

Rapidly test webhooks and integrations
Run automations privately and securely
Avoid deploying to cloud platforms for quick experiments

This setup gives you the flexibility to develop and demo from anywhere — perfect for both learning and production prototypes. You can always enhance it later with a custom domain, HTTPS via Let's Encrypt, or move to a VPS if needed.

If you're exploring automation workflows or integrating n8n into your stack, give this setup a try — and let me know how it goes!

Cheers...

Build Visual Workflows with n8n and Automate Everything

Dilum Darshana — Mon, 14 Jul 2025 06:00:45 +0000

Hello devs,

As a full-stack developer working mostly with JavaScript, I often build internal tools and data pipelines. I found myself writing a lot of boilerplate Node.js code to glue together APIs and databases — until I discovered n8n.

This blog is my personal reference and a shared guide for anyone looking to get serious about workflow automation

Installing and Running n8n Locally

docker-compose.yml

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    container_name: my-n8n-workflow
    restart: always
    ports:
      - "5678:5678"
    environment:
      # - DOMAIN_NAME=example.com
      # - SUBDOMAIN=n8n
      # - N8N_HOST=n8n.example.com
      # - N8N_PROTOCOL=https
      # - N8N_PORT=5678
      # - WEBHOOK_URL=https://n8n.example.com
      # - NODE_ENV=production
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - N8N_SECURE_COOKIE=false
    volumes:
      - ./n8n_data:/home/node/.n8n

.env

GENERIC_TIMEZONE=Asia/Colombo

Note: There can be a user ownership issue in the n8n_data folder. Run the following command from the folder where container running,

$ sudo chown -R 1000:1000 ./n8n_data

Now, do the composer up,

$ docker-compose up -d

If everything goes well, n8n should be runs on http://localhost:5678. Fill the user registration to create an account, then fill the survey (as of now) to go into the dashboard.

n8n UI and Core Concepts

Workflow Canvas: The drag-and-drop editor where you build automation flows step by step.
Nodes: The building blocks of workflows—each node performs a task like sending an email, calling an API, or transforming data.
Triggers: Nodes that start workflows (e.g., Cron, Webhook, Manual).
Actions: Nodes that perform operations, like HTTP requests, database inserts, or sending notifications.
Data Flow: Data moves between nodes in JSON format, and you can map, modify, or branch the flow at each step.
Function Node: Use JavaScript for advanced logic and data manipulation directly inside n8n.
Set Node: Quickly add or modify fields without writing code.

Building a Real-World Workflow

To understand how triggers, API calls, data transformation, and external services come together in n8n, let’s build a simple real-world workflow.

Use Case: Send a random joke to your email every 5 minutes using Resend

Workflow: [Cron Node] → [Fetch Joke (HTTP Request)] → [Send Email (Resend HTTP Request)]

Step 1: Create a New Workflow

Open the n8n editor.
Click “New Workflow” and give it a name, for example: Send Joke to Email

Step 2: Add a Cron Trigger

Click “+” Add Node.
Search for Schedule Trigger and select the Schedule Trigger Node.
Configure it to run every 5 minutes, continuously.

Step 3: Fetch a Joke via HTTP Request

Click “+” Add Node.
Search for HTTP Request.
Configure it with response format as JSON. URL: https://icanhazdadjoke.com/, method: GET

This should return a json something like this:

{
  "joke": "I once lost a banana at court but then I appealed."
}

Step 4: Send the Joke via Email Using Resend

Now send the joke to email using Resend's email API. To do this, need to create a Resend account and API key.

https://resend.com

Configure the Email Node,

Since n8n doesn’t have a native Resend node, use HTTP Request again.

Click “+” Add Node.
Select HTTP Request.
Configure it,

URL: https://api.resend.com/emails
Method: POST
Headers:

Authorization: Bearer RESEND_API_KEY
Content-Type: application/json

Send body:

{
  "from": "Jokes <onboarding@resend.dev>",
  "to": "dilum.dar@gmail.com",
  "subject": "Here's Your Joke",
  "text": "{{$json.joke}}"
}

Now, everything ready for test. The whole workflow looks like this,

Run the workflow manually by clicking “Execute Workflow”. Should receive an email with a joke :)

If it works, click “Activate” to make it run automatically every 5 minutes.

Final Thoughts
Whether you're automating your daily tasks, integrating multiple services, or building your own AI pipelines—n8n gives you the flexibility of code with the simplicity of a visual editor.

This was just the beginning.

Cheers....

Building My First MCP Server with TypeScript: A Beginner’s Journey

Dilum Darshana — Mon, 07 Jul 2025 06:16:52 +0000

Hello backend devs,

As someone deeply interested in LLM-based Agentic workflows, I recently took into a new challenge: building my first Model Context Protocol (MCP) server using TypeScript. This post walks through the process—from zero to a working MCP server—and what I learned along the way. There are many articles in the internet which is explained in Python. Here, I wanted to use my most familiar JavaScript as a programming language.

Why we need MCP?
Extending the capabilities of large language models (LLMs) has become increasingly important. While there are many ways to integrate external tools or services with LLMs, these methods are often ad hoc and lack consistency. When building scalable and reusable solutions, it's crucial to have a standardised way to define and expose tools that LLMs can interact with.

This is where Model Context Protocol (MCP) comes into the picture. MCP provides a protocol-driven approach to tool integration, making it easier to define, discover, and use external tools in a consistent and structured manner—regardless of the environment or framework.

If you’re familiar with RAG (Retrieval-Augmented Generation), you can think of MCP as a more secure and controllable alternative for tool execution. With RAG, the model often has access to unstructured or semi-structured data sources. In contrast, with MCP, tools are invoked by an MCP client, and only the results are passed back to the LLM. This provides a more secure and sandboxed execution flow—keeping tool logic and sensitive operations isolated from the LLM.

In short, MCP helps extend the power of LLMs through a common standard, promoting reusability, interoperability, and better developer experience.

Technical approach
To implement my first MCP server, I chose the official @modelcontextprotocol/sdk npm package. This SDK provides a clean and TypeScript-friendly interface to build MCP-compliant servers and tools. It includes everything needed to handle standard MCP request types, define tools with schema validation, and manage communication over stdin/stdout (which is how many LLM runtimes expect to interact with tools).

The SDK abstracts away many of the low-level details, letting you focus on defining what your tools do, rather than how they are wired into the protocol. This made it a great choice for a first-time MCP implementation.

While I went with the official SDK for simplicity and clarity, there are other approaches available too.

[Documentation]https://github.com/modelcontextprotocol/typescript-sdk

Setting up the project
To keep things simple and focused, I used a minimal folder structure and pnpm as my package manager. Since this was a TypeScript-based CLI-style MCP server, I didn’t need a complex build system or runtime framework.

Here's the basic folder structure I followed:

package.json

{
  "name": "mcp-currency-converter",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "bin": {
    "mcp-currency-converter": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', '755')\"",
    "inspector": "pnpx @modelcontextprotocol/inspector node ./dist/index.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "packageManager": "pnpm@10.7.0",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.15.0",
    "zod": "^3.25.67"
  },
  "devDependencies": {
    "@types/node": "^20",
    "typescript": "^5.8.3"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "moduleResolution": "node",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Tool
Tools are the heart of an MCP server. Each tool exposes a specific piece of functionality that the LLM can invoke via the MCP client. You can register multiple tools in the same MCP server, each serving different—but often related—business purposes.

In my case, I implemented two tools to demonstrate a basic currency conversion use case:

Currency Converter – Converts a given amount from one currency to another.
List Available Currencies – Returns a list of supported currency codes.

Both tools are defined using the @modelcontextprotocol/sdk along with zod for schema validation.

Here’s how they are implemented:

types.ts

import { z } from 'zod';

export interface MCPTool<TInput extends z.ZodTypeAny = any> {
  name: string;
  description: string;
  schema: TInput;
  handler: (input: z.infer<TInput>) => Promise<any>;
};

tools/convertCurrency.ts


/**
 * Convert given amount from one currency to another using the Free Currency API.
 */
import { z } from 'zod';
import { MCPTool } from '../types';

const schema = z.object({
  fromCurrency: z.string().describe('The currency to convert from (e.g., USD, EUR)'),
  toCurrency: z.string().describe('The currency to convert to (e.g., USD, EUR)'),
  amount: z.number().positive().describe('The amount to convert'),
});

export const convertCurrencyTool: MCPTool<typeof schema> = {
  name: 'convert-currency',
  description: 'Converts an amount from one currency to another',
  schema,
  handler: async ({ fromCurrency, toCurrency, amount }: any) => {
    const currencyFinderKey = process.env.FREE_CURRENCY_KEY;
    if (!currencyFinderKey) throw new Error('Missing FREE_CURRENCY_KEY');

    console.log(`Converting ${amount} ${fromCurrency} to ${toCurrency}`);

    const response = await fetch(
      `https://api.freecurrencyapi.com/v1/latest?apikey=${currencyFinderKey}&base_currency=${fromCurrency}&currencies=${toCurrency}`
    );

    const data = await response.json();
    const exchangeRate = data.data?.[toCurrency];

    if (!exchangeRate) throw new Error('Invalid exchange rate');

    const convertedAmount = exchangeRate * amount;

    return {
      content: [
        {
          type: 'text',
          text: `Converted ${amount} ${fromCurrency} to ${toCurrency}: ${convertedAmount} ${toCurrency}`,
        },
      ],
    };
  }
};

tools/listCurrencies.ts

/**
 * List avaible currencies tool. Available currencies are fetched from freecurrencyapi.com
 */
import { z } from 'zod';
import { MCPTool } from '../types';

// Schema
const schema = z.object({});

// List currencies tool
export const listCurrenciesTool: MCPTool<typeof schema> = {
  name: 'list-currencies',
  description: 'Lists all supported currencies',
  schema,
  handler: async () => {
    const currencyFinderKey = process.env.FREE_CURRENCY_KEY;
    if (!currencyFinderKey) throw new Error('Missing FREE_CURRENCY_KEY');

    console.log('Listing supported currencies');

    const response = await fetch(
      `https://api.freecurrencyapi.com/v1/currencies?apikey=${currencyFinderKey}`
    );
    const data = await response.json();

    return {
      content: [
        {
          type: 'text',
          text: `Supported currencies: ${Object.keys(data).join(', ')}`,
        },
      ],
    };
  }
};

Wiring Up the MCP Server
Now that the tools are ready, the next step is to create the MCP server and integrate those tools using the @modelcontextprotocol/sdk.

In this setup, I defined a simple MCP server using the StdioServerTransport, which allows tools to be called locally through stdin and stdout—ideal for testing or local agent interactions.

After initialising the server, I registered both tools so they can be listed and executed via standard MCP requests.

Here is the implementation:

index.ts

#!/usr/bin/env node
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { convertCurrencyTool } from './tools/convertCurrency.js';
import { listCurrenciesTool } from './tools/listCurrencies.js';

const server = new McpServer({
  name: 'currencyConverter',
  version: '1.0.0',
});

// Tool no: 1
server.tool(
  convertCurrencyTool.name,
  convertCurrencyTool.description,
  convertCurrencyTool.schema.shape,
  convertCurrencyTool.handler,
);

// Tool no: 2
server.tool(
  listCurrenciesTool.name,
  listCurrenciesTool.description,
  listCurrenciesTool.schema.shape,
  listCurrenciesTool.handler,
);

const transport = new StdioServerTransport();

server.connect(transport);

Testing it
That is it! Now it’s time to test whether everything works as expected.

For this, I used the official modelcontextprotocol/inspector tool. It provides a simple way to inspect and interact with your local MCP server via a CLI interface.

I added it as a dependency and defined a script in package.json for convenience. To run the test, navigate into your project directory and execute the following command:

$ pnpm inspector

This will launch the inspector (See the console output for the URL), which connects to your MCP server and lists the available tools. You can then invoke each tool, provide input, and view the structured output—all directly from your terminal.

It’s a great way to quickly validate your server’s setup and ensure tool execution is working correctly.

In here, we can type different inputs to see how it works:

Step 1: Connect the Inspector
Click the "Connect" button in the bottom left corner of the UI.

Step 2: Load and Test Tools
After connecting, go to the “Tools” tab.

Click on “List Tools” to load the available tools from your MCP server.

You can now select a tool (e.g., convertCurrency or listCurrencies), enter the required parameters, and run it.

If everything is working correctly, you should receive a valid and expected response from your tool.

💡 Note: If your MCP server relies on any environment variables (e.g., API keys), make sure to set them inside the Inspector UI before running the tools.
In my case, I had to set FREE_CURRENCY_KEY for the currency conversion API to work properly.

Key takeaways

MCP encourages clean, reusable, and structured tool development.
The @modelcontextprotocol/sdk abstracts a lot, but understanding what's happening under the hood helps when debugging.
The Inspector tool is incredibly helpful—but only if the server and tools are defined correctly.
Type safety and schema validation are your best friends—don’t skip on them!

Conclusion
Building my first MCP server in TypeScript was a rewarding experience. It not only helped me understand how to expose tools to LLMs in a structured way, but also gave me a glimpse into the future of AI integrations—where standards like MCP can bring consistency, security, and reusability to the developer ecosystem.

The @modelcontextprotocol/sdk made it approachable, and using tools like the Inspector helped validate everything with confidence.

If you're working with LLMs and looking for a clean way to plug in external capabilities, I highly recommend exploring MCP. Start small, build a simple tool, and see how easily it can scale.

What's Next?
In my next post, I'll walk through how to use the MCP server from code using an MCP client—so you can see how to invoke tools programmatically and integrate them into your own AI workflows.

Cheers... Happy coding!!!

API Documentation for NestJS

Dilum Darshana — Mon, 26 May 2025 03:06:20 +0000

This time we are going to learn about how to create API documentation for NestJS application using Swagger. There are many ways in the world, let's focus on Swagger which is NestJS official preference.

First, install the dependency,

$ pnpm add @nestjs/swagger

Then, initialise the Swagger in bootstrap which is main.ts file,

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  // Set up Swagger documentation for the API
  const swaggerConfig = new DocumentBuilder()
    .setTitle('Taskify API documentation')
    .setDescription('Taskify API documentation')
    .setVersion('1.0')
    .addTag('api')
    .build();
  const documentFactory = SwaggerModule.createDocument(app, swaggerConfig);
  SwaggerModule.setup('api-docs', app, documentFactory);

  // Start the application and listen on the specified port
  await app.listen(port || 3000);
}

Basically, that's it. http://localhost:3000/api-docs will be showing the elegant documentation structure with separate sections.

Sections are automatically split based on the controller name. It is possible to give a custom name though. Use ApiTags decorator

import { ApiTags } from '@nestjs/swagger';

@ApiTags('Task APIs')
@Controller('task')
export class TaskController {
  constructor(private readonly taskService: TaskService) {}

}

By default, the API definitions are empty. We need to improve further. Let's do it.

The schema and example section take from the DTO file. Im my example, create task API and createTaskDTO which is validate the task create inputs. We can use this file to improve the documentation using ApiProperty decorator.

// create-task.dto.ts file
import { Priority, TaskStatus } from '@prisma/client';
import { IsNotEmpty, IsString } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

export class CreateTaskDto {
  @ApiProperty({
    description: 'Title of the task',
    example: 'Complete the project report',
  })
  @IsString()
  @IsNotEmpty()
  title: string;

  @ApiProperty({
    description: 'Description of the task',
    example: 'Write a detailed report on the project progress',
  })
  @IsString()
  description: string;

  @ApiProperty({
    description: 'Priority level of the task',
    example: 'HIGH',
    enum: Priority,
  })
  @IsString()
  @IsNotEmpty()
  priority: Priority;

  @ApiProperty({
    description: 'Status of the task',
    example: 'TODO',
    enum: TaskStatus,
  })
  @IsString()
  @IsNotEmpty()
  status: TaskStatus;
}

Then, the response section in the API can be filled with ApiResponse decorator from the controller file. Note that the CreateTaskResponseDto type. This should be a DTO for the response. Let's modify the create-task.dto file for that,

// create-task.dto.ts
export class CreateTaskResponseDto {
  @ApiProperty()
  id: string;

  @ApiProperty()
  title: string;

  @ApiProperty()
  description: string;

  @ApiProperty()
  priority: Priority;

  @ApiProperty()
  status: TaskStatus;
}

Now, need to call the ApiResponse decorator from the controller

// task.controller.ts file
@ApiResponse({ status: HttpStatus.CREATED, description: 'Task created successfully', type: CreateTaskResponseDto }) // Swagger response documentation.
@HttpCode(HttpStatus.CREATED) // Sets the HTTP status code to 201 (Created).
@UseInterceptors(ResponseInterceptor) // Intercepts the response to format it consistently.
@Post() // Handles POST requests to the /task endpoint.
async createTask(@Body() createTaskDto: CreateTaskDto, @CurrentUser() user: User) {
    const task = await this.taskService.create(createTaskDto, user.id);

    return {
      message: 'Task created successfully',
      data: task,
    };
}

Additionally, if we want to add description for each API, can be used ApiOperation decorator from the controller. Example,

@ApiOperation({ summary: 'Some description about this API' }) // Swagger documentation for the endpoint.
@ApiResponse({ status: HttpStatus.CREATED, description: 'Task created successfully', type: CreateTaskResponseDto }) // Swagger response documentation.
@HttpCode(HttpStatus.CREATED) // Sets the HTTP status code to 201 (Created).
@UseInterceptors(ResponseInterceptor) // Intercepts the response to format it consistently.
@Post() // Handles POST requests to the /task endpoint.
async createTask(@Body() createTaskDto: CreateTaskDto, @CurrentUser() user: User) {
    const task = await this.taskService.create(createTaskDto, user.id);

    return {
      message: 'Task created successfully',
      data: task,
    };
 }

It is possible to add multiple response types, example error responses. Just use the different decorators as bellow,

@ApiOperation({ summary: 'Create a new task' }) // Swagger documentation for the endpoint.
@ApiCreatedResponse({
  description: 'Task created successfully',
  type: CreateTaskResponseDto,
}) // Swagger response documentation.
@ApiBadRequestResponse({ description: 'Bad Request'  }) // Swagger error response documentation.
@ApiUnauthorizedResponse({ description: 'Unauthorized' }) // Swagger error response documentation.
@HttpCode(HttpStatus.CREATED) // Sets the HTTP status code to 201 (Created).
@UseInterceptors(ResponseInterceptor) // Intercepts the response to format it consistently.
@Post() // Handles POST requests to the /task endpoint.
async createTask(@Body() createTaskDto: CreateTaskDto, @CurrentUser() user: User) {
  const task = await this.taskService.create(createTaskDto, user.id);

  return {
    message: 'Task created successfully',
    data: task,
  };
}

Conclusion

From my perspective, this approach allow us to create useful API documentation with minimal effort. The big advantage of having such a documentation is improve team collaboration specially for front-end teams.

Cheers... Happy coding!!!

How to Use Redis with Replication and Automatic Failover

Dilum Darshana — Wed, 09 Apr 2025 17:44:24 +0000

Redis is an in memory storing giant in the industry.

Why so fast?

Redis store data in the memory. In general, reading and writing data from memory faster than reading/writing data from the disk. Redis store everything as a key/value pairs in a hash map.

Most Redis commands are operate in O(1) or O(log N) time complexity regardless of the size of the data.

Redis architecture

Redis uses Single-Threaded Event Loop architecture. In general, Redis can handle 10,000 concurrent requests. This can be change using redis.conf maxclients directive.

Persistence of data?

Since, Redis uses memory to store data, data will be lost upon the server crash. Redis provides two approaches to persistence the data

RDB - Redis Database
In this way, snapshot will be written to the disk periodically. Can be restore data form them. But, it has few cons as well. Until data restore complete, there will be a significant latency. This would not ideal in the production.
AOF (Append Only File)
In this way, AOF persistence logs every write operation received by the server. These operations can then be replayed again at server startup, reconstructing the original dataset. There is a cons here, recovery time will be higher, when the file become larger and larger over the time

The recommended approach is use the combination of RDB and AOF

Read Replicas (High availability)

Use read replicas would be ideal in this case. It has primary node and multiple read replicas. Once the primary goes down, one of the replica start acting as new primary node (Redis Sentinel).

Redis use cases

Redis can use in 3 different main purposes,

Use as a Cache
Use as a Database
Use as a Message Broker

Redis core data types

Strings – Simple key-value pairs.
Lists – Doubly linked lists.
Hashes – Key-value maps.
Sets – Unordered unique elements.
Sorted Sets – Ordered sets with scores.

Spine Redis instance

Can use Docker to spine up a Redis server in a minute with different features.

# start redis server
$ docker run --name redis-server -d -p 6379:6379 redis
# -d: Detached mode
# -p: port mapping

# restart and stop redis server
$ docker restart redis-server
$ docker stop redis-server

Most needed command

# go inside docker container
$ docker exec -it <container_id> bash

# go inside redis
$ redis-cli -h <host> -p <port> -a <password>
# eg. redis-cli -h 192.168.1.8 -p 6379 -a xxxx

# OR without go inside,
$ docker exec redis-server redis-cli GET username

# set string
$ SET username "Apache"
$ GET username
$ DEL username
$ EXPIRE username 60 # expire item in 60 seconds
$ TTL username # check TTL of key. xx seconds left
$ FLUSHDB # delete all keys in current DB
$ FLUSHALL # delete all keys in all DB

# Hashes
$ HSET user:1000 name "Bob" age 23
$ HGET user:1000 name # Bob
$ HGET user:1000 age # 23
$ HGETALL user:1000

# Lists (ordered items)
$ LPUSH tasks "task1" "task2" # push item to left
$ LPOP tasks # remove item from left
$ RPUSH tasks "task3" # push item to right
$ LRANGE tasks 0 -1 # list all items

# Sets (unordered items)
$ SADD colors "red" # add item

# monitor redis activities
$ monitor

# docker create new network
$ docker network create redis-net

# inspect docker network
$ docker network inspect redis-net

Persistence of data (RDB/AOF). How to do?

# enable snapshots (RDB)
$ docker run --name redis-rdb -d -p 6379:6379 -v $(pwd)/redis-data:/data redis redis-server --save 60 1

# -v:  mount redis volume to host /redis-data folder.
# redis-server: this runs the redis-server executable inside the container. we use this to pass additional options
# -save 60 1: saves to disk if 1+ key changes in 60 seconds.

# enable append only (AOF)
$ docker run --name redis-rdb -d -p 6379:6379 -v $(pwd)/redis-data:/data redis redis-server --appendonly yes

Redis replicas. How to do?

# create docker network
$ docker network create redis-net

# make sure network is there
$ docker network list

# create master node
$ docker run --name redis-master --network redis-net -d -p 6379:6379 redis redis-server --appendonly yes

# create replica 01
$ docker run --name redis-replica1 --network redis-net -d -p 6380:6379 redis redis-server --replicaof redis-master 6379 --appendonly yes

# Note: both redis nodes must be in the same docker network, in order to communicate each other

# test everything works:
$ docker exec redis-master redis-cli set username "Bob"

$ docker exec redis-replica1 redis-cli get username

# check information about the node
$ docker exec redis-master redis-cli info replication

Can be used docker compose file to spine all in one command (docker-compose.yml)

services:
  redis-master:
    image: redis
    container_name: redis-master
    restart: always
    volumes:
      - redis_master:/data
    ports:
      - 6379:6379

  redis-replica1:
    image: redis
    container_name: redis-replica1
    restart: always
    volumes:
      - redis_slave:/data
    ports:
      - 6479:6379
    command: redis-server --slaveof redis-master 6379
volumes:
  redis_master:
  redis_replica1:

Run from command line

$ docker compose -f docker-compose up

Redis automatic failover (Sentinel). How to do?

Redis does not handle failover by default. We need to config for it. Sentinel is the Redis concept we can use to handle failover along with replicas created above.

Create sentinel config file (sentinel.conf) in the current working directory:

port 26379
sentinel monitor mymaster redis-master 6379 2
sentinel down-after-milliseconds mymaster 5000
sentinel failover-timeout mymaster 10000
sentinel parallel-syncs mymaster 1

mymaster → Name of the monitored master.
redis-master 6379 → IP and port of the master.
2 → The number of Sentinels that must agree before a failover occurs.
down-after-milliseconds 5000 → Time (5 sec) before Sentinel marks the master as down.
failover-timeout 10000 → Time (10 sec) before failing over.
parallel-syncs 1 → Number of replicas syncing simultaneously.

# create sentinel conatiner
$ docker run --name redis-sentinel --network redis-net -d -p 26379:26379 -v $(pwd):/etc/redis redis redis-server /etc/redis/sentinel.conf --sentinel

# verify sentinel uses the correct master node
$ docker exec -it redis-sentinel redis-cli -p 26379 SENTINEL get-master-addr-by-name mymaster
# this should return either redis-master or ip of the master container

# check the actual role of the node
$ docker exec redis-master redis-cli info replication

How to test the failover

# stop the master node
$ docker stop redis-master

# check the role of replica
$ docker exec redis-replica1 redis-cli info replication

Redis use cases

As a rate limiter
Leaky bucket algorithm
As a distribution lock
Rank/Leaderbord
Using sorted list data type

Conclusion

Now a days, we have plenty of managed services available out there, rather manually setting up everything. Example, AWS ElastiCache. But, I think it is better to know what is going on behind the scenes.

Add anything I missed here....

Cheers... Happy coding!!!

Connecting Database with NestJS Using Prisma ORM

Dilum Darshana — Sun, 06 Apr 2025 07:18:48 +0000

Hello Backend devs...

Time to connect NestJS application with a database. There are many databases can be connected with NestJS, including Sql or NoSql types. Choosing a right database is another crucial decision in the application's architecture. Today, let's focus on connect with the PostgreSQL database - a powerful popular relational database.

Obviously, we can use native drivers to connect with any databases from NestJS app. But, most of time, it is better to use an ORM, since, it is more time efficient and maintainable.

Today, let's focus on Prisma ORM, one of the most modern and developer-friendly ORMs, to connect PostgreSQL with a NestJS application.

📌 Install dependencies

# adding prisma cli
$ pnpm add -D prisma

# prisma client for development
$ pnpm add @prisma/client

📌 Initialise Prisma

This will create prisma folder and .env file in the root

$ pnpx prisma init

📌 Configurations

Need to update .env file for the database connection.

DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"

📌 Migrations

Schema file located at prisma/schema.prisma file. There are two ways to run migrations here,

Migrations
Mostly use this approach. We create a schema on code, then push the changes to the database.
Introspection
In here, When already have the database, we can update the schema by pulling it. Command in bellow,

$ pnpx prisma db pull

Let's go through the most common approach Migrations. In the first stage, we don't have anything in the database. We need to create it from the sketch. Assume that we need to create a user table. What we have to do is update the schema.prisma file as needed,

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

enum UserType {
  ADMIN
  USER
}

model Role {
  id         Int      @id @default(autoincrement())
  name       String   @unique
  created_at DateTime @default(now())
  User       User[]
}

model User {
  id         Int      @id @default(autoincrement())
  name       String
  email      String   @unique
  password   String
  role_id    Int
  type       UserType // custom type with enum
  created_at DateTime @default(now())
  Role       Role     @relation(fields: [role_id], references: [id])
}

Now, need to create the first migration file,

# pnpx prisma migrate dev --name <description_of_change>
$ pnpx prisma migrate dev --name init

This will do two actions.

Create new migration file inside prisma/migrations folder
Create tables in the connected database provided in the schema file

Anyway, we have a option to only create the migration file without execute it,

$ pnpx prisma migrate dev --name <description_of_change> --create-only

We can execute this any time by,

$ pnpx prisma migrate dev

📌 Update table

What if we want to modify existing table or add a new table to the database?

Modify the prisma.schema file for the new change.

Best practices:

Single logical change/s per migration
Always, create a migration file for change using prisma migrate dev. This will re generate the prisma client and create a migration file.
Review migration without execute it using npx prisma migrate dev --create-only
Descriptive naming on migration file
Never edit executed migration files. Create a new one for change

Let's assume that we want to add optional age filed to the user table. Modify the user model.

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Role {
  id         Int      @id @default(autoincrement())
  name       String   @unique
  created_at DateTime @default(now())
  User       User[]
}

model User {
  id         Int      @id @default(autoincrement())
  name       String
  email      String   @unique
  password   String
  age        Int? // ? mark indicate that optional
  role_id    Int
  created_at DateTime @default(now())
  Role       Role     @relation(fields: [role_id], references: [id])
}

Generate migration,

$ pnpx prisma migrate dev --name add-age-field-to-user --create-only
$ pnpx prisma migrate dev

📌 Deploy in production

When we want to apply migrations on production by manually or using CI/CD, then much safe to use,

$ pnpx prisma migrate deploy

Why it safe for production? This does not generate any migrations. Only apply the changes (diff) to the database and does not re generate the prisma client

📌 General tips

When delete node_modules folder, prisma client also will be deleted. Prisma client usually located at node_modules/@prisma folder. Need to re generate it before use in the code. Better option would be add the following to the package.json

"scripts": {
    "postinstall": "prisma generate",
}

OR run the command manually,

$ pnpx prisma generate

📌 Connect from NestJS

Now, we have done the setup for database infrastructure. Let's focus on how do we connect NestJS with the created database.

First step is create a prisma module. (It is work just with a prisma service without having a prisma module. But, with the NestJS module philosophy, it is recommended to have a prisma module)

Then, prisma service,

$ nest generate module prisma
$ nest generate service prisma

Once module generated, module import automatically add to the imports list in the app.module. (this is not necessary. without import prisma module from here, it works as usual)

Update src/prisma/prisma.service.ts file as bellow,

import { Injectable, OnModuleInit } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit {
  async onModuleInit() {
    await this.$connect();
  }
}

Now, Prisma will be globally available for dependency injection from any services. Let's try that as well,

Let's say we have a user module. Then when we want to access prisma inside a user module, first, need to import prisma service in the user module:

import { Module } from '@nestjs/common';
import { UserService } from './user.service';
import { UserController } from './user.controller';
import { PrismaService } from 'src/prisma/prisma.service';

@Module({
  controllers: [UserController],
  providers: [UserService, PrismaService],
})
export class UserModule {}

Then, can inject prisma service to the user service and use it within the user service,

import { Injectable } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';

@Injectable()
export class UserService {
  // injecting prisma service to user service
  constructor(private prisma: PrismaService) {}

  async findAll(): Promise<User[]> {
    return this.prisma.user.findMany();
  }

  async findOne(id: number): Promise<User | null> {
    return this.prisma.user.findUnique({
      where: { id },
    });
  }

  async create(data: CreateUserDto): Promise<User> {
    return this.prisma.user.create({
      data,
    });
  }

  async update(id: number, data: UpdateUserDto): Promise<User> {
    return this.prisma.user.update({
      where: { id },
      data,
    });
  }

  async remove(id: number): Promise<User> {
    return this.prisma.user.delete({
      where: { id },
    });
  }
}

That's it 🏆

📌 GUI for Prisma

Prisma has awesome tool to visualise the data.

$ pnpx prisma studio

This will open the GUI on http://localhost:5555

📌 Conclusion

There are many ORM supports with NestJS. Drizzle and TypeORM are the other most popular candidates. I hear that Drizzle is much performant than others. All candidates have tradeoffs each other and I use Prisma for small and medium scale projects. It is easy to use when compare with TypeORM.

May be you can share your thoughts on this?

🤝 Let's meet again with another important topic

Cheers... Happy coding!!!

My Mostly Used Docker Commands

Dilum Darshana — Thu, 03 Apr 2025 12:17:41 +0000

Mostly used Docker commands collection by me.

generic

# remove all stopped containers
$ docker prune

# docker full cleanup
$ docker system prune -a --volumes

# check disk usage by docker
$ docker system df

# check the service version
# --rm: this will remove the container after stop
$ docker run --rm redis redis-server --version
$ docker run --rm node node -v

images

# pull docker image
$ docker pull redis

# list pulled images
$ docker images

# remove image
$ docker rmi redis

container

# create and run docker container
$ docker run --name redis-master -d -p 6379:6379 redis

# run docker in specific network
$ docker run --name redis-master --network redis-net -d -p 6379:6379 redis

# stop container
$ docker stop redis-master

# start container
$ docker start redis-master

# check running containers
$ docker ps

# check all containers
$ docker ps -a

# restart container
$ docker restart redis-master

# check logs
$ docker logs redis-master

# go inside container
# docker exec -it <container_name|container_id> bash
$ docker exec -it redis-master bash

# execute command without go inside container
# docker exec <container_name> <command_to_run_inside_container>
$ docker exec redis-master redis-cli GET username

# remove container
$ docker rm redis-master

volums


# list all volumes
$ docker volume list

# create a new volume
$ docker volume create redis-volume

# remove volume
$ docker volume rm redis-volume

# inspect volume in a container
$ docker volume inspect redis_master

# mount volume to container
$ docker run -v redis-volume:/data redis-master

network


# create new network
# docker network create <options> <network_name> 
$ docker network create redis-net
$ docker network create --subnet=192.168.1.0/24 redis-net

# list all networks
$ docker network list

# check who is in the network
$ docker network inspect redis-net

# check what is inside network
$ docker network inspect redis-net

# connect to specific container
# docker network connect <network> <container>
$ docker network connect redis-net redis-master

# disconnect from network
$ docker network disconnect redis-net redis-master

# remove network
$ docker network rm redis-net

docker-compose


# compose start
$ docker-compose -f <docker-compose.yml> up

# compose stop. This will remove all containers as well
$ docker-compose -f <docker-compose.yml> down

# compose stop + delete volumes
$ docker-compose -f <docker-compose.yml> down -v

debug


# inspect container
# docker inspect <container_name>
$ docker inspect redis-master

# inspect image
$ docker inspect redis

# inspect docker network
$ docker network inspect redis-net

Cheers... Happy coding!!!

Note: This is a living document.

Next.js Deployment to AWS Amplify: Environment Variable Issue & Fix

Dilum Darshana — Sat, 29 Mar 2025 09:00:38 +0000

Recently, I had to spent hours to figure it out environment variable issue on NextJS deployment to AWS Amplify.

Context

Application has text search from MongoDB where user do the search from UI. API provided by the NextJS itself located at,

api/search/route.ts

Route handler connect to the Mongodb using mongoose.connect function. Function has an environment variable call MONGDOB_URI. This is coming from an environment variable. Application has some public environment variables as well (obviously start with NEXT_PUBLIC_XXXX). All variables set via Amplify Environment Variable section,

Problem

When application deployed to the Amplify, MONGDOB_URI read as 'undefined' while other public environment variables are reading without any issue.

Inspections

When I check the build log, all environment variables are reading well,

But, when I run the application, CloudWatch logs says it is not found MONGDOB_URI

Public variables are working fine,

Solutions tried out

Some articles says that add the missing variable implicitly add to the next.config.ts file.

const nextConfig: NextConfig = {
  /* config options here */
  env: {
    MONGODB_URI: process.env.MONGODB_URI,
  },
};

export default nextConfig;

Then, it worked!!!. But, it has a huge security issue, which is secured database connection will be exposed to the public.

Then, removed the next cache from the amplify.yml file.

Still did not work :(

Solution

At the last, created the .env.production file on the fly and appended the MONGODB_URI into the file using amplify.yml file,

Then, it worked!!!

Conclusion

For some reason, only public environment (starts with NEXT_PUBLIC) can be fetch from the Amplify when it is building without needing .env.production file. For secured variables, we need to append them into the .env.production file.

Anyone encountered this issue? Hope this help to someone for solution or debate !!!

Cheers... Happy coding!!!

Setting up NestJS Project

Dilum Darshana — Thu, 27 Mar 2025 07:53:41 +0000

Hello Backend devs...

Here let's go through the setting up new NestJS project with basic features.

🟢 Create a new project

Now is time to create a new NestJS app. The NestJS provide awesome command line tool to generate app and the main building blocks. Install NestCLI as a global package using your favourite package manager, then generate the app,

# add nest cli
$ pnpm add -g @nestjs/cli

# generate app
$ nest new project-name

Now, everything ready to customise the app as you needed. The whole boilerplate with minimal features is there. Run the following command to make sure that everything is working,

# start the app server
$ pnpm start:dev

# check everything works
$ curl http://localhost:3000

# you should see
Hello World!

🟢 Create a first module

Now, let's say, you want to add a new feature to your app. Example, user management, auth, etc...

There are few CLI commands to understand based on the requirement. There is a patter in the command,

$ nest generate <module|controller|service|resource> <name>

# eg. generate new module for user management, and the controller
$ nest generate module user

# generate controller
$ nest generate controller user

Please pay attention on name of the module (user) and the name of the controller (user). Those has to be same in order to NestJS understand both should generate to the same feature. Let's create the service also,

$ nest generate service user

Now, you should see the new folder and bunch of files created by NestCLI,

What is the resource command does? If you want to create whole crud feature at the same time, you can use it. Make sure that you use either options,

$ nest generate resource user

🟢 How to use main building blocks

Now, you have user module boilerplate to start coding. Mostly, use module, controller and the service. When you go deeper, you need guards, pipes, filters, etc..

Module: Connect everything needed for feature. You have nothing to do here, unless you have Injectable classes to be used or another module need to be used in this module. Basically, whatever connected to the DI (Dependency Injection) container, we can connect from here. If you do not have anything from outside, then leave it as it is. See bellow some usage of another module (auth),

Controller: The request handler in NestJS level. Basically, routes are defined here. Guard, Interceptors like other decorators can be applied to this level, before request goes to the service level. Let's say I have following API requirements,

Get all users: GET -> http://localhost:3000/user
Get a specific user: GET -> http://localhost:3000/user/1
Create a new user: POST -> http://localhost:3000/user

Look at the bellow code carefully. Main controller decorator define the 'user' part of the route. Rest of the path defined in function decorator. @Get, @Post, @Param and @Body are the main decorators used to make our life easier.

@Get: Define as GET http verb
@Post: Define as POST http verb
@Params: Read query params and return to id variable
@Body: Extract body contents and assign to user object

import { Body, Controller, Get, Param, Post } from '@nestjs/common';
import { UserService } from './user.service';
import { CreateUserDto } from './dto/create-user.dto';

@Controller('user') // main route path
export class UserController {
  // inject user service into the controller
  constructor(private readonly userService: UserService) {}

  @Get('/') // get all users
  allUsers() {
    return this.userService.findAll();
  }

  @Get(':id') // get a specific user. eg. user/1
  findOne(@Param('id') id: string) {
    return this.userService.findById(+id);
  }

  @Post('/') // create a new user
  createUser(@Body() user: CreateUserDto) {
    return this.userService.createUser(user);
  }
}

Service: The business logic layer. This is going to be Injectable to the DI container. Which means can be use from anywhere who can connect with the DI container. Can talk to database from here as well. And other processing and manipulations. Finally, return the response to the controller. Look at our user service bellow,

import { Injectable } from '@nestjs/common';
import { CreateUserDto } from '../modules/user/dto/create-user.dto';

@Injectable() // inject to the DI container
export class UserService {
  findAll() {
    // find all users from database

    // return list of users
    return [];
  }

  findById(id: number) {
    // find user from database

    // return user
    return id;
  }

  createUser(user: CreateUserDto) {
    // user creation logic

    // return created user
    return user;
  }
}

That's it for a basics to play around with the NestJS REST API creation.

🎯 Give it a try yourself and let me know how it goes!

🤝 Let's connect with the database click here

Cheers... Happy coding!!!

What You Need to Know Before Starting a NestJS Project

Dilum Darshana — Wed, 26 Mar 2025 10:12:03 +0000

Hello Backend devs...

NestJS has quickly become one of the most popular Node.js progressive frameworks for building scalable and maintainable server-side applications. The patterns are followed by Angular's architecture and fully support with TypeScripts. NestJS brings structure and strong typing to the fast-paced world of REST API developments.

If you're coming from Express or a similar minimal framework, starting a NestJS project can feel like a big shift—in a good way. Its modular design, built-in dependency injection, and clear separation of concerns promote clean code and make it easier to scale your application as it grows.

In this guide, I will walk you through the most important concepts you need to know before starting your NestJS project (I am talking about V11.X)

🟢 Main building blocks

Modules - Group together everything
Controller - Handle incoming request
Services - Handle business logic
Pipes - Validate incoming data
Exception Filters - Handle errors throws by controller or service
Guards - Handle authentication and authorisation. Can decide request proceed to not (return true / false)
Interceptors - Adding extra data to request or to response
Middleware - Can modify request object
Repositories - Handle data stored in DB

🟢 The main architecture

NestJS does not handle HTTP request itself. We need to provide either Express OR Fastify for handling HTTP requests. By default, NestJS uses Express.

NestJS main building blocks has an order of execution. See bellow,

🟢 DI Container

NestJS uses dependency injection (DI) as its main design pattern for the easy management of dependencies between application components. NestJS DI system is based on the Inversion of Control (IoC) technique, meaning that the framework controls the creation and life cycle of an objects (such as services and controllers) rather than the objects themselves controlling these aspects.

Basically, NestJS helps with automatically creating and injecting services and other dependencies into classes; hence, one can decouple components and keep the application modular.

🟢 Interceptors

This can be used to modify request and response. Let's say want to modify the request object before it goes to the controller,

Create a new interceptor in the correct module. Eg. modules -> auth -> interceptors -> auth.interceptor.ts

import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class OAuthInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();

    // transform user profile
    if (request.user) {
      request.user = this.normalizeUserProfile(); // modify user object
    }

   return next.handle(); // just return the request object without modifying response object
  }
}

Note that the return next.handle();. It just pass the request to the controller, no change on response.

Next, call the interceptor from controller,

@UseGuards(AuthGuard('github'))
@UseInterceptors(OAuthInterceptor)
async githubAuthCallback(@Req() req: AuthenticatedRequest, @Res() res: Response) {
  if (!req.user) {
      throw new UnauthorizedException('User not authorized');
  }
}

If it's need to modify the response,

import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
import { Observable, map } from 'rxjs';

@Injectable()
export class OAuthInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();

    // transform user profile
    if (request.user) {
      request.user = this.normalizeUserProfile(); // modify user object
    }

    // modify the response also,
    return next.handle().pipe(
      map((data) => {
        return {
          success: true, // add anything additional
          data,
        }
      })
    );
  }
}

🟢 Final Thoughts

It is vital to understand the basic concepts before start any new technologies. It is may be take some time, but, hold on, it would be a good investment for the future. I will update the post with the new finding continuously.

🤝 Let's meet again with setting up NestJS app. Click Here

Cheers... Happy coding!!!

Why NestJS Became My favourite Node.js Framework (After Years of Express.js)

Dilum Darshana — Tue, 25 Mar 2025 09:49:49 +0000

After spending nearly a decade building backend applications with Express.js, I thought I had everything I needed. Express is fast, easy to understand, and can build just about anything.

But as my projects grew larger, so did the complexity. I started facing challenges like maintaining a clean folder structure, managing dependency injection manually, code complexity and struggling with testability.

That is when I gave NestJS a serious try — and honestly, it felt like switching from manual to automatic. Today, it’s my go-to framework for scalable Node.js applications. Here’s why.

🟢 What is NestJS ?

A progressive (start with minimal) Node.js framework built with awesome TypeScript support based on Express or Fastify. It uses decorators heavily for reusability. OOP (Object Oriented Programming) or FP (Functional Programming) as needed. Would be ideal for medium and large scale projects

🟢 My Journey with Express.js

Express was the most convenient framework at the time I started my development career. It was easy to understand and flexible enough to develop almost every features what I needed.

After sometimes, when the projects are become larger and larger, it was hard to keep the consistency of the codebase. And, testing them as a module was a bit tricky. I had to create my own boilerplate with the specific folder structure.

Here is the one I created some times back: My Express based Boilerplate

🟢 Why I Switched to NestJS

There is few reasons I prefer NestJS over Express.

Well architected boilerplate with minimum features
It is already tested well
Can scale easily
Native Typescript support
Required extensions mostly provided by NestJS team itself (eg. JWT, Passport, Graphql, Cors, etc...)

🟢 Key Features That Sold Me on NestJS

Dependency injection
Modular pattern
Built-in features, like, Guards, Interceptors, Middlewares, Pipes
Typescript native support (Heavy with Decorators)
Easy expanding with external modules (Eg. Cors, JWT, Config, etc...)
Well structured folder structure
Easy routes with simple controllers
Support for microservices (I still not tried out this)
API documentation with few lines of codes (Swagger integration)

🟢 Drawbacks of NestJS (Yes, It might Has Some)

I still did not encountered significant drawbacks. It might be quite overhead for use NestJS for very small projects. And, obviously, there is a learning curve when switch from Express.js

🟢 Should You Switch?

Im my opinion, there are several factors need to consider behind it. If you have significant scalable app to be implemented, you have a good knowledge of TypeScript and if your app going to be type of microservices, then better option would be use NestJS

🟢 Final Thoughts

Switching from Express.js to NestJS was one of the best decisions I’ve made for building scalable backend apps. Still Express.js would be a good choice specially for small projects and MVPs.

🎯 If you haven’t tried it yet, I highly recommend giving it a shot!

NestJS Docs

🤝 I will write an another post on NestJS internals sooner Check Here

Cheers... Happy coding!!!