Node.js Backend Patterns
Purpose
Core patterns for building scalable Node.js backend applications with TypeScript, emphasizing clean architecture, error handling, and testability.
When to Use This Skill
- Building Node.js backend services
- Implementing async/await patterns
- Error handling and logging
- Configuration management
- Testing backend code
- Layered architecture (routes → controllers → services → repositories)
Quick Start
Layered Architecture
src/
├── api/
│ ├── routes/ # HTTP route definitions
│ ├── controllers/ # Request/response handling
│ ├── services/ # Business logic
│ └── repositories/ # Data access
├── middleware/ # Express middleware
├── types/ # TypeScript types
├── config/ # Configuration
└── utils/ # UtilitiesFlow: Route → Controller → Service → Repository → Database
Async/Await Error Handling
Basic Pattern
async function fetchUser(id: string): Promise<User> {
try {
const user = await db.user.findUnique({ where: { id } });
if (!user) {
throw new Error('User not found');
}
return user;
} catch (error) {
console.error('Error fetching user:', error);
throw error;
}
}Async Controller Pattern
class UserController {
async getUser(req: Request, res: Response): Promise<void> {
try {
const { id } = req.params;
const user = await this.userService.getById(id);
res.json({
success: true,
data: user,
});
} catch (error) {
console.error('Error in getUser:', error);
res.status(500).json({
success: false,
error: 'Failed to fetch user',
});
}
}
}Promise.all for Parallel Operations
async function getUserDashboard(userId: string) {
try {
const [user, posts, followers] = await Promise.all([
userService.getById(userId),
postService.getByUser(userId),
followerService.getByUser(userId),
]);
return { user, posts, followers };
} catch (error) {
console.error('Error loading dashboard:', error);
throw error;
}
}TypeScript Patterns
Request/Response Types
// Request body
interface CreateUserRequest {
email: string;
name: string;
password: string;
}
// Response
interface ApiResponse<T> {
success: boolean;
data?: T;
error?: string;
message?: string;
}
// Usage
async function createUser(
req: Request<{}, {}, CreateUserRequest>,
res: Response<ApiResponse<User>>
): Promise<void> {
const { email, name, password } = req.body;
const user = await userService.create({ email, name, password });
res.json({
success: true,
data: user,
});
}Service Layer Types
interface IUserService {
getById(id: string): Promise<User>;
create(data: CreateUserDto): Promise<User>;
update(id: string, data: UpdateUserDto): Promise<User>;
delete(id: string): Promise<void>;
}
class UserService implements IUserService {
async getById(id: string): Promise<User> {
// Implementation
}
async create(data: CreateUserDto): Promise<User> {
// Implementation
}
async update(id: string, data: UpdateUserDto): Promise<User> {
// Implementation
}
async delete(id: string): Promise<void> {
// Implementation
}
}Configuration Management
Environment Variables
// config/env.ts
import { z } from 'zod';
const envSchema = z.object({
NODE_ENV: z.enum(['development', 'production', 'test']),
PORT: z.string().transform(Number),
DATABASE_URL: z.string().url(),
JWT_SECRET: z.string().min(32),
LOG_LEVEL: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
});
export const env = envSchema.parse(process.env);Unified Config
// config/index.ts
interface Config {
server: {
port: number;
host: string;
};
database: {
url: string;
};
auth: {
jwtSecret: string;
jwtExpiry: string;
};
}
export const config: Config = {
server: {
port: parseInt(process.env.PORT || '3000'),
host: process.env.HOST || 'localhost',
},
database: {
url: process.env.DATABASE_URL || '',
},
auth: {
jwtSecret: process.env.JWT_SECRET || '',
jwtExpiry: process.env.JWT_EXPIRY || '7d',
},
};Layered Architecture
Controller Layer
// controllers/UserController.ts
export class UserController {
constructor(private userService: UserService) {}
async getById(req: Request, res: Response): Promise<void> {
const { id } = req.params;
const user = await this.userService.getById(id);
res.json({
success: true,
data: user,
});
}
async create(req: Request, res: Response): Promise<void> {
const userData = req.body;
const user = await this.userService.create(userData);
res.status(201).json({
success: true,
data: user,
});
}
}Service Layer
// services/UserService.ts
export class UserService {
constructor(private userRepository: UserRepository) {}
async getById(id: string): Promise<User> {
const user = await this.userRepository.findById(id);
if (!user) {
throw new Error('User not found');
}
return user;
}
async create(data: CreateUserDto): Promise<User> {
// Business logic
const hashedPassword = await this.hashPassword(data.password);
return this.userRepository.create({
...data,
password: hashedPassword,
});
}
private async hashPassword(password: string): Promise<string> {
// Hash implementation
return password; // Placeholder
}
}Repository Layer
// repositories/UserRepository.ts
export class UserRepository {
async findById(id: string): Promise<User | null> {
// Database query
return db.user.findUnique({ where: { id } });
}
async create(data: CreateUserData): Promise<User> {
return db.user.create({ data });
}
async update(id: string, data: UpdateUserData): Promise<User> {
return db.user.update({
where: { id },
data,
});
}
async delete(id: string): Promise<void> {
await db.user.delete({ where: { id } });
}
}Dependency Injection
Basic DI Pattern
// Composition root
const userRepository = new UserRepository();
const userService = new UserService(userRepository);
const userController = new UserController(userService);
export { userController };Service Container
// container.ts
class Container {
private services: Map<string, any> = new Map();
register<T>(name: string, factory: () => T): void {
this.services.set(name, factory());
}
get<T>(name: string): T {
const service = this.services.get(name);
if (!service) {
throw new Error(`Service ${name} not found`);
}
return service;
}
}
export const container = new Container();
// Register services
container.register('userRepository', () => new UserRepository());
container.register('userService', () => new UserService(
container.get('userRepository')
));
container.register('userController', () => new UserController(
container.get('userService')
));Error Handling
Custom Error Classes
export class AppError extends Error {
constructor(
public message: string,
public statusCode: number = 500,
public isOperational: boolean = true
) {
super(message);
Object.setPrototypeOf(this, AppError.prototype);
}
}
export class NotFoundError extends AppError {
constructor(resource: string) {
super(`${resource} not found`, 404);
}
}
export class ValidationError extends AppError {
constructor(message: string) {
super(message, 400);
}
}
// Usage
async function getUser(id: string): Promise<User> {
const user = await userRepository.findById(id);
if (!user) {
throw new NotFoundError('User');
}
return user;
}Async Error Wrapper
type AsyncHandler = (
req: Request,
res: Response,
next: NextFunction
) => Promise<void>;
export const asyncHandler = (fn: AsyncHandler) => {
return (req: Request, res: Response, next: NextFunction) => {
Promise.resolve(fn(req, res, next)).catch(next);
};
};
// Usage
router.get('/users/:id', asyncHandler(async (req, res) => {
const user = await userService.getById(req.params.id);
res.json({ data: user });
}));Best Practices
1. Always Use Async/Await
// ✅ Good: async/await
async function getUser(id: string): Promise<User> {
const user = await userRepository.findById(id);
return user;
}
// ❌ Avoid: Promise chains
function getUser(id: string): Promise<User> {
return userRepository.findById(id)
.then(user => user)
.catch(error => throw error);
}2. Layer Separation
// ✅ Good: Separated layers
// Controller handles HTTP
// Service handles business logic
// Repository handles data access
// ❌ Avoid: Business logic in controllers
class UserController {
async create(req: Request, res: Response) {
// ❌ Don't put business logic here
const hashedPassword = await hash(req.body.password);
const user = await db.user.create({...});
res.json(user);
}
}3. Type Everything
// ✅ Good: Full type coverage
async function updateUser(
id: string,
data: UpdateUserDto
): Promise<User> {
return userService.update(id, data);
}
// ❌ Avoid: any types
async function updateUser(id: any, data: any): Promise<any> {
return userService.update(id, data);
}Additional Resources
For more patterns, see:
- async-and-errors.md - Advanced error handling
- testing-guide.md - Comprehensive testing
- architecture-patterns.md - Architecture details