Core Node.js backend patterns for TypeScript applications including async/await error handling, middleware concepts, configuration management, testing strategies, and layered architecture principles. Use when building Node.js backend services, APIs, or microservices.
Core patterns for building scalable Node.js backend applications with TypeScript, emphasizing clean architecture, error handling, and testability.
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/ # Utilities
Flow: Route → Controller → Service → Repository → Database
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;
}
}
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',
});
}
}
}
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;
}
}
// 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,
});
}
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
}
}
// 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);
// 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',
},
};
// 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,
});
}
}
// 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
}
}
// 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 } });
}
}
// Composition root
const userRepository = new UserRepository();
const userService = new UserService(userRepository);
const userController = new UserController(userService);
export { userController };
// 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')
));
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;
}
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 });
}));
// ✅ 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);
}
// ✅ 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);
}
}
// ✅ 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);
}
For more patterns, see: