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/             # Utilities

Flow: 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