This guide provides a comprehensive overview of NestJS concepts with practical examples tailored for Warehouse Management System (WMS) development. It's designed to help new developers quickly understand and start working with NestJS in a WMS context.
NestJS is a progressive Node.js framework for building efficient, reliable, and scalable server-side applications. It uses TypeScript and combines elements of OOP (Object Oriented Programming), FP (Functional Programming), and FRP (Functional Reactive Programming).
# Install NestJS CLI
npm i -g @nestjs/cli
# Create a new project
nest new wms-system
# Navigate to project directory
cd wms-system
# Start the development server
npm run start:dev
wms-system/
├── src/
│ ├── main.ts # Application entry point
│ ├── app.module.ts # Root module
│ ├── inventory/ # Inventory module
│ │ ├── inventory.module.ts
│ │ ├── inventory.controller.ts
│ │ ├── inventory.service.ts
│ │ ├── dto/
│ │ └── entities/
│ ├── orders/ # Orders module
│ │ ├── orders.module.ts
│ │ ├── orders.controller.ts
│ │ ├── orders.service.ts
│ │ ├── dto/
│ │ └── entities/
│ └── shared/ # Shared resources
│ ├── interfaces/
│ ├── constants/
│ └── utils/
├── test/ # Tests
├── node_modules/
├── package.json
└── tsconfig.json
Modules are the building blocks of NestJS applications. They help organize related components and provide boundaries between different functional areas.
// inventory.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { InventoryController } from './inventory.controller';
import { InventoryService } from './inventory.service';
import { Product } from './entities/product.entity';
import { Location } from './entities/location.entity';
import { StockMovement } from './entities/stock-movement.entity';
@Module({
imports: [
TypeOrmModule.forFeature([Product, Location, StockMovement]),
],
controllers: [InventoryController],
providers: [InventoryService],
exports: [InventoryService], // Export to use in other modules
})
export class InventoryModule {}
// app.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { InventoryModule } from './inventory/inventory.module';
import { OrdersModule } from './orders/orders.module';
import { ShippingModule } from './shipping/shipping.module';
import { UsersModule } from './users/users.module';
import { AuthModule } from './auth/auth.module';
@Module({
imports: [
ConfigModule.forRoot({ isGlobal: true }),
TypeOrmModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService) => ({
type: 'postgres',
host: configService.get('DB_HOST'),
port: configService.get('DB_PORT'),
username: configService.get('DB_USERNAME'),
password: configService.get('DB_PASSWORD'),
database: configService.get('DB_DATABASE'),
entities: [__dirname + '/**/*.entity{.ts,.js}'],
synchronize: configService.get('NODE_ENV') !== 'production',
}),
}),
InventoryModule,
OrdersModule,
ShippingModule,
UsersModule,
AuthModule,
],
})
export class AppModule {}
Controllers handle incoming requests and return responses to the client. They define routes and HTTP methods (GET, POST, PUT, DELETE) for your API endpoints.
// inventory.controller.ts
import { Controller, Get, Post, Body, Param, Put, Delete, Query, UseGuards } from '@nestjs/common';
import { InventoryService } from './inventory.service';
import { CreateProductDto } from './dto/create-product.dto';
import { UpdateProductDto } from './dto/update-product.dto';
import { StockMovementDto } from './dto/stock-movement.dto';
import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
import { RolesGuard } from '../auth/guards/roles.guard';
import { Roles } from '../auth/decorators/roles.decorator';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
@ApiTags('inventory')
@Controller('inventory')
@UseGuards(JwtAuthGuard, RolesGuard)
export class InventoryController {
constructor(private readonly inventoryService: InventoryService) {}
@Post('products')
@Roles('admin', 'inventory-manager')
@ApiOperation({ summary: 'Create a new product' })
@ApiResponse({ status: 201, description: 'Product created successfully' })
async createProduct(@Body() createProductDto: CreateProductDto) {
return this.inventoryService.createProduct(createProductDto);
}
@Get('products')
@ApiOperation({ summary: 'Get all products with optional filtering' })
async findAllProducts(
@Query('category') category?: string,
@Query('location') location?: string,
) {
return this.inventoryService.findAllProducts(category, location);
}
@Get('products/:id')
@ApiOperation({ summary: 'Get product by ID' })
async findProductById(@Param('id') id: string) {
return this.inventoryService.findProductById(id);
}
@Put('products/:id')
@Roles('admin', 'inventory-manager')
@ApiOperation({ summary: 'Update product information' })
async updateProduct(
@Param('id') id: string,
@Body() updateProductDto: UpdateProductDto,
) {
return this.inventoryService.updateProduct(id, updateProductDto);
}
@Post('stock-movement')
@Roles('warehouse-operator', 'inventory-manager')
@ApiOperation({ summary: 'Record stock movement (receiving, picking, etc.)' })
async recordStockMovement(@Body() stockMovementDto: StockMovementDto) {
return this.inventoryService.recordStockMovement(stockMovementDto);
}
@Get('stock-levels')
@ApiOperation({ summary: 'Get current stock levels' })
async getStockLevels(@Query('productId') productId?: string) {
return this.inventoryService.getStockLevels(productId);
}
@Get('low-stock')
@ApiOperation({ summary: 'Get products with low stock levels' })
async getLowStockProducts(@Query('threshold') threshold: number = 10) {
return this.inventoryService.getLowStockProducts(threshold);
}
}
Providers are classes that can be injected into each other as dependencies. Services contain the business logic of your application and are typically injected into controllers.
// inventory.service.ts
import { Injectable, NotFoundException, ConflictException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository, In } from 'typeorm';
import { Product } from './entities/product.entity';
import { Location } from './entities/location.entity';
import { StockMovement } from './entities/stock-movement.entity';
import { CreateProductDto } from './dto/create-product.dto';
import { UpdateProductDto } from './dto/update-product.dto';
import { StockMovementDto } from './dto/stock-movement.dto';
import { MovementType } from './enums/movement-type.enum';
@Injectable()
export class InventoryService {
constructor(
@InjectRepository(Product)
private productRepository: Repository,
@InjectRepository(Location)
private locationRepository: Repository,
@InjectRepository(StockMovement)
private stockMovementRepository: Repository,
) {}
async createProduct(createProductDto: CreateProductDto): Promise {
const existingProduct = await this.productRepository.findOne({
where: { sku: createProductDto.sku },
});
if (existingProduct) {
throw new ConflictException(`Product with SKU ${createProductDto.sku} already exists`);
}
const product = this.productRepository.create(createProductDto);
return this.productRepository.save(product);
}
async findAllProducts(category?: string, locationId?: string): Promise {
const queryBuilder = this.productRepository.createQueryBuilder('product');
if (category) {
queryBuilder.andWhere('product.category = :category', { category });
}
if (locationId) {
queryBuilder
.innerJoin('product.stockMovements', 'movement')
.innerJoin('movement.location', 'location')
.andWhere('location.id = :locationId', { locationId })
.andWhere('movement.quantity > 0');
}
return queryBuilder.getMany();
}
async findProductById(id: string): Promise {
const product = await this.productRepository.findOne({ where: { id } });
if (!product) {
throw new NotFoundException(`Product with ID ${id} not found`);
}
return product;
}
async updateProduct(id: string, updateProductDto: UpdateProductDto): Promise {
const product = await this.findProductById(id);
Object.assign(product, updateProductDto);
return this.productRepository.save(product);
}
async recordStockMovement(stockMovementDto: StockMovementDto): Promise {
const { productId, locationId, quantity, type } = stockMovementDto;
const product = await this.findProductById(productId);
const location = await this.locationRepository.findOne({ where: { id: locationId } });
if (!location) {
throw new NotFoundException(`Location with ID ${locationId} not found`);
}
// Check if there's enough stock for outbound movements
if (type === MovementType.PICK || type === MovementType.SHIP) {
const availableStock = await this.getProductStockAtLocation(productId, locationId);
if (availableStock < quantity) {
throw new ConflictException(
`Not enough stock for product ${product.name} at location ${location.name}. Available: ${availableStock}, Requested: ${quantity}`,
);
}
}
const movement = this.stockMovementRepository.create({
product,
location,
quantity,
type,
timestamp: new Date(),
});
return this.stockMovementRepository.save(movement);
}
async getStockLevels(productId?: string): Promise {
const queryBuilder = this.stockMovementRepository.createQueryBuilder('movement')
.select('product.id', 'productId')
.addSelect('product.name', 'productName')
.addSelect('product.sku', 'sku')
.addSelect('location.id', 'locationId')
.addSelect('location.name', 'locationName')
.addSelect('SUM(CASE WHEN movement.type IN (:...inboundTypes) THEN movement.quantity ELSE 0 END)', 'inbound')
.addSelect('SUM(CASE WHEN movement.type IN (:...outboundTypes) THEN movement.quantity ELSE 0 END)', 'outbound')
.addSelect('SUM(CASE WHEN movement.type IN (:...inboundTypes) THEN movement.quantity ELSE -movement.quantity END)', 'available')
.leftJoin('movement.product', 'product')
.leftJoin('movement.location', 'location')
.groupBy('product.id')
.addGroupBy('location.id')
.setParameters({
inboundTypes: [MovementType.RECEIVE, MovementType.RETURN, MovementType.ADJUST_IN],
outboundTypes: [MovementType.PICK, MovementType.SHIP, MovementType.ADJUST_OUT],
});
if (productId) {
queryBuilder.andWhere('product.id = :productId', { productId });
}
return queryBuilder.getRawMany();
}
async getLowStockProducts(threshold: number): Promise {
const stockLevels = await this.getStockLevels();
return stockLevels.filter(item => item.available <= threshold);
}
private async getProductStockAtLocation(productId: string, locationId: string): Promise {
const result = await this.stockMovementRepository.createQueryBuilder('movement')
.select('SUM(CASE WHEN movement.type IN (:...inboundTypes) THEN movement.quantity ELSE -movement.quantity END)', 'available')
.where('movement.product.id = :productId', { productId })
.andWhere('movement.location.id = :locationId', { locationId })
.setParameters({
inboundTypes: [MovementType.RECEIVE, MovementType.RETURN, MovementType.ADJUST_IN],
})
.getRawOne();
return result.available || 0;
}
}
NestJS provides built-in support for testing using Jest. You can write unit tests, integration tests, and end-to-end tests for your application.
// inventory.service.spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { getRepositoryToken } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { InventoryService } from './inventory.service';
import { Product } from './entities/product.entity';
import { Location } from './entities/location.entity';
import { StockMovement } from './entities/stock-movement.entity';
import { MovementType } from './enums/movement-type.enum';
import { ConflictException, NotFoundException } from '@nestjs/common';
describe('InventoryService', () => {
let service: InventoryService;
let productRepository: Repository;
let locationRepository: Repository;
let stockMovementRepository: Repository;
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
providers: [
InventoryService,
{
provide: getRepositoryToken(Product),
useClass: Repository,
},
{
provide: getRepositoryToken(Location),
useClass: Repository,
},
{
provide: getRepositoryToken(StockMovement),
useClass: Repository,
},
],
}).compile();
service = module.get(InventoryService);
productRepository = module.get>(getRepositoryToken(Product));
locationRepository = module.get>(getRepositoryToken(Location));
stockMovementRepository = module.get>(getRepositoryToken(StockMovement));
});
it('should be defined', () => {
expect(service).toBeDefined();
});
describe('createProduct', () => {
it('should create a product successfully', async () => {
const createProductDto = {
sku: 'TEST-12345',
name: 'Test Product',
description: 'Test Description',
category: 'Test Category',
weight: 1.5,
dimensions: '10x10x10',
barcode: '123456789012',
reorderPoint: 10,
};
jest.spyOn(productRepository, 'findOne').mockResolvedValue(null);
jest.spyOn(productRepository, 'create').mockReturnValue(createProductDto as any);
jest.spyOn(productRepository, 'save').mockResolvedValue({
id: 'test-id',
...createProductDto,
} as any);
const result = await service.createProduct(createProductDto);
expect(result).toHaveProperty('id', 'test-id');
expect(result).toHaveProperty('sku', 'TEST-12345');
expect(productRepository.findOne).toHaveBeenCalledWith({
where: { sku: 'TEST-12345' },
});
expect(productRepository.create).toHaveBeenCalledWith(createProductDto);
expect(productRepository.save).toHaveBeenCalled();
});
it('should throw ConflictException if product with same SKU exists', async () => {
const createProductDto = {
sku: 'TEST-12345',
name: 'Test Product',
};
jest.spyOn(productRepository, 'findOne').mockResolvedValue({ id: 'existing-id' } as any);
await expect(service.createProduct(createProductDto)).rejects.toThrow(ConflictException);
expect(productRepository.findOne).toHaveBeenCalledWith({
where: { sku: 'TEST-12345' },
});
});
});
describe('recordStockMovement', () => {
it('should record a stock movement successfully', async () => {
const stockMovementDto = {
productId: 'product-id',
locationId: 'location-id',
quantity: 10,
type: MovementType.RECEIVE,
reference: 'PO-12345',
};
const product = { id: 'product-id', name: 'Test Product' };
const location = { id: 'location-id', name: 'Test Location' };
jest.spyOn(service, 'findProductById').mockResolvedValue(product as any);
jest.spyOn(locationRepository, 'findOne').mockResolvedValue(location as any);
jest.spyOn(stockMovementRepository, 'create').mockReturnValue({
product,
location,
quantity: stockMovementDto.quantity,
type: stockMovementDto.type,
reference: stockMovementDto.reference,
timestamp: expect.any(Date),
} as any);
jest.spyOn(stockMovementRepository, 'save').mockResolvedValue({
id: 'movement-id',
product,
location,
quantity: stockMovementDto.quantity,
type: stockMovementDto.type,
reference: stockMovementDto.reference,
timestamp: new Date(),
} as any);
const result = await service.recordStockMovement(stockMovementDto);
expect(result).toHaveProperty('id', 'movement-id');
expect(result.product).toEqual(product);
expect(result.location).toEqual(location);
expect(result.quantity).toEqual(stockMovementDto.quantity);
expect(result.type).toEqual(stockMovementDto.type);
});
it('should throw NotFoundException if location does not exist', async () => {
const stockMovementDto = {
productId: 'product-id',
locationId: 'non-existent-location',
quantity: 10,
type: MovementType.RECEIVE,
};
jest.spyOn(service, 'findProductById').mockResolvedValue({ id: 'product-id' } as any);
jest.spyOn(locationRepository, 'findOne').mockResolvedValue(null);
await expect(service.recordStockMovement(stockMovementDto)).rejects.toThrow(NotFoundException);
});
});
});
// inventory.e2e-spec.ts
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication, ValidationPipe } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from '../src/app.module';
import { getRepositoryToken } from '@nestjs/typeorm';
import { Product } from '../src/inventory/entities/product.entity';
import { Location } from '../src/inventory/entities/location.entity';
import { AuthService } from '../src/auth/auth.service';
describe('Inventory Controller (e2e)', () => {
let app: INestApplication;
let authToken: string;
let productRepository: any;
let locationRepository: any;
let authService: AuthService;
beforeAll(async () => {
const moduleFixture: TestingModule = await Test.createTestingModule({
imports: [AppModule],
}).compile();
app = moduleFixture.createNestApplication();
app.useGlobalPipes(
new ValidationPipe({
whitelist: true,
transform: true,
}),
);
await app.init();
// Get repositories and services
productRepository = app.get(getRepositoryToken(Product));
locationRepository = app.get(getRepositoryToken(Location));
authService = app.get(AuthService);
// Get auth token for testing
const { accessToken } = await authService.login({
id: 'test-user',
email: 'test@example.com',
roles: ['admin'],
});
authToken = accessToken;
// Seed test data
await seedTestData();
});
async function seedTestData() {
// Create test location
const location = await locationRepository.save({
code: 'TEST-LOC',
name: 'Test Location',
zone: 'Test Zone',
isActive: true,
});
// Create test product
await productRepository.save({
sku: 'TEST-SKU',
name: 'Test Product',
description: 'Test Description',
category: 'Test Category',
reorderPoint: 10,
});
}
afterAll(async () => {
// Clean up test data
await productRepository.delete({ sku: 'TEST-SKU' });
await locationRepository.delete({ code: 'TEST-LOC' });
await app.close();
});
describe('/inventory/products (GET)', () => {
it('should return all products', () => {
return request(app.getHttpServer())
.get('/inventory/products')
.set('Authorization', `Bearer ${authToken}`)
.expect(200)
.expect(res => {
expect(Array.isArray(res.body)).toBe(true);
expect(res.body.some(product => product.sku === 'TEST-SKU')).toBe(true);
});
});
});
describe('/inventory/products (POST)', () => {
it('should create a new product', () => {
return request(app.getHttpServer())
.post('/inventory/products')
.set('Authorization', `Bearer ${authToken}`)
.send({
sku: 'NEW-SKU',
name: 'New Product',
description: 'New Description',
category: 'New Category',
reorderPoint: 5,
})
.expect(201)
.expect(res => {
expect(res.body).toHaveProperty('id');
expect(res.body).toHaveProperty('sku', 'NEW-SKU');
// Clean up the created product
productRepository.delete({ sku: 'NEW-SKU' });
});
});
it('should validate input data', () => {
return request(app.getHttpServer())
.post('/inventory/products')
.set('Authorization', `Bearer ${authToken}`)
.send({
// Missing required 'sku' field
name: 'Invalid Product',
})
.expect(400);
});
});
});
NestJS applications can be deployed in various ways, including traditional hosting, containerization with Docker, or serverless architectures.
# Dockerfile
FROM node:16-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Production stage
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
# Health check
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
CMD wget -qO- http://localhost:3000/health || exit 1
# Environment variables
ENV NODE_ENV=production
ENV PORT=3000
EXPOSE ${PORT}
CMD ["node", "dist/main"]
# docker-compose.yml
version: '3.8'
services:
api:
build:
context: .
dockerfile: Dockerfile.dev
ports:
- "3000:3000"
volumes:
- .:/app
- /app/node_modules
environment:
- NODE_ENV=development
- DB_HOST=postgres
- DB_PORT=5432
- DB_USERNAME=postgres
- DB_PASSWORD=postgres
- DB_DATABASE=wms_db
- JWT_SECRET=dev_secret
depends_on:
- postgres
- redis
postgres:
image: postgres:13-alpine
ports:
- "5432:5432"
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=postgres
- POSTGRES_DB=wms_db
volumes:
- postgres_data:/var/lib/postgresql/data
redis:
image: redis:6-alpine
ports:
- "6379:6379"
volumes:
- redis_data:/data
volumes:
postgres_data:
redis_data:
# kubernetes/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: wms-api
labels:
app: wms-api
spec:
replicas: 3
selector:
matchLabels:
app: wms-api
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
template:
metadata:
labels:
app: wms-api
spec:
containers:
- name: wms-api
image: ${DOCKER_REGISTRY}/wms-api:${VERSION}
ports:
- containerPort: 3000
env:
- name: NODE_ENV
value: "production"
- name: PORT
value: "3000"
- name: DB_HOST
valueFrom:
secretKeyRef:
name: wms-db-credentials
key: host
- name: DB_PORT
valueFrom:
secretKeyRef:
name: wms-db-credentials
key: port
- name: DB_USERNAME
valueFrom:
secretKeyRef:
name: wms-db-credentials
key: username
- name: DB_PASSWORD
valueFrom:
secretKeyRef:
name: wms-db-credentials
key: password
- name: DB_DATABASE
valueFrom:
secretKeyRef:
name: wms-db-credentials
key: database
- name: JWT_SECRET
valueFrom:
secretKeyRef:
name: wms-jwt-secret
key: secret
resources:
limits:
cpu: "1"
memory: "1Gi"
requests:
cpu: "500m"
memory: "512Mi"
livenessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /health/ready
port: 3000
initialDelaySeconds: 5
periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
name: wms-api
spec:
selector:
app: wms-api
ports:
- port: 80
targetPort: 3000
type: ClusterIP
When developing a WMS with NestJS, following these best practices will help ensure a robust, maintainable system.