TypeScript Best Practices

Project Configuration

Enable Strict Mode

{
"compilerOptions": {

/* Enable all strict type - checking options */

}
}

Enable Strict Checks

{
"compilerOptions": {

}
}

Type System Best Practices

Use Type Inference Where Possible

return a + b;
}
// Good: Let TypeScript infer return type function add(a: number, b: number) {
return a + b;
}

Precise Type Annotations

return user.name.toUpperCase();
}

id: number;
name: string;
email?: string;  // Optional property
}
function processUser(user: User): string {
return user.name.toUpperCase();
}

Know when to use interface vs type

// Use interface for object shapes that can be extended/implemented interface User {
id: number;
name: string;
}
// Extending an interface interface AdminUser extends User {
permissions: string[];
}
// Use type for unions, tuples, or mapped types type UserRole = 'admin' | 'editor' | 'viewer';
// Union types type UserId = number | string;
// Mapped types type ReadonlyUser = Readonly<User>;
// Tuple types type Point = [number, number];

Avoid any

Type

Prefer more specific types over any

console.log(value.toUpperCase()); // No error until runtime
}

// Better: Use generic type parameter function logValue < T > (value: T) {

console.log(String(value)); // Safer, but still not ideal
}
// Best: Be specific about expected types function logString(value: string) {
console.log(value.toUpperCase()); // Type-safe
}

// When you need to accept any value but still be type - safe function logUnknown(value: unknown) {

if (typeof value === 'string') {
console.log(value.toUpperCase());
} else {
console.log(String(value));
}
}

Code Organization

Module Organization

// user/user.model.ts export interface User {
id: string;
name: string;
email: string;
}
// user/user.service.ts import { User } from './user.model';
export class UserService {
private users: User[] = [];
addUser(user: User) {
this.users.push(user);
}
getUser(id: string): User | undefined {
return this.users.find(user => user.id === id);
}
}

// user/index.ts (barrel file)

export * from './user.model';
export * from './user.service';

File Naming Conventions

Follow consistent file naming patterns:

Best Practices

Keep tsconfig.json strict and up - to - date.

Functions and Methods

Function Parameters and Return Types

Write clear and type - safe functions with proper parameter and return types:

notify(user.name);
}
// Good: Explicit parameter and return types function processUser(
user: User, notify: (message: string) => void
): void {
notify(`Processing user: ${user.name}`);
}
// Use default parameters instead of conditionals function createUser(

name: string, role: UserRole = 'viewer', isActive: boolean = true

): User {
return { name, role, isActive };
}
// Use rest parameters for variable arguments function sum(...numbers: number[]): number {
return numbers.reduce((total, num) => total + num, 0);
}

Avoid Function Overuse

// Validation if (!userData || !userData.name) throw new Error('Invalid user data');
// Data transformation const processedData = {...userData, name: userData.name.trim(), createdAt: new Date()
};
// Side effect saveToDatabase(processedData);
// Notification sendNotification(processedData.email, 'Profile updated');
return processedData;
}
// Better: Split into smaller, focused functions function validateUserData(data: unknown): UserData {
if (!data || typeof data !== 'object') {
throw new Error('Invalid user data');
}
return data as UserData;
}
function processUserData(userData: UserData): ProcessedUserData {
return {...userData, name: userData.name.trim(), createdAt: new Date()
};
}

Async/Await Patterns

Proper Async/Await Usage

const response = await fetch('/api/data');
return response.json();
}

// Good: Proper error handling async function fetchData < T > (url: string): Promise < T > {

try {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return await response.json() as T;
} catch (error) {
console.error('Failed to fetch data:', error);
throw error; // Re-throw to allow caller to handle
}
}

// Better: Use Promise.all for parallel operations async function fetchMultipleData < T > (urls: string[]): Promise < T[]> {

try {
const promises = urls.map(url => fetchData<T>(url));
return await Promise.all(promises);
} catch (error) {
console.error('One or more requests failed:', error);
throw error;
}
}
// Example usage interface User {
id: string;
name: string;
email: string;
}

// Fetch user data with proper typing async function getUserData(userId: string): Promise < User > {

return fetchData<User>(`/api/users/${userId}`);
}

Avoid Nested Async/Await

Flatten your async/await code to avoid callback hell:
// Bad: Nested async/await (callback hell)

async function processUser(userId: string) {
const user = await getUser(userId);
if (user) {
const orders = await getOrders(user.id);
if (orders.length > 0) {
const latestOrder = orders[0];
const items = await getOrderItems(latestOrder.id);
return { user, latestOrder, items };
}
}
return null;
}

// Better: Flatten the async/await chain async function processUser(userId: string) {

const user = await getUser(userId);
if (!user) return null;
const orders = await getOrders(user.id);
if (orders.length === 0) return { user, latestOrder: null, items: [] };
const latestOrder = orders[0];
const items = await getOrderItems(latestOrder.id);
return { user, latestOrder, items };
}
// Best: Use Promise.all for independent async operations async function processUser(userId: string) {
const [user, orders] = await Promise.all([
getUser(userId), getOrders(userId)
]);
if (!user) return null;
if (orders.length === 0) return { user, latestOrder: null, items: [] };
const latestOrder = orders[0];
const items = await getOrderItems(latestOrder.id);
return { user, latestOrder, items };
}

Testing and Quality

Writing Testable Code

async processPayment(amount: number) {
const paymentGateway = new PaymentGateway();
return paymentGateway.charge(amount);
}
}

charge(amount: number): Promise<boolean>;
}
class PaymentProcessor {
constructor(private paymentGateway: PaymentGateway) {}
async processPayment(amount: number): Promise<boolean> {
if (amount <= 0) {
throw new Error('Amount must be greater than zero');
}
return this.paymentGateway.charge(amount);
}
}
// Test example with Jest describe('PaymentProcessor', () => {
let processor: PaymentProcessor;
let mockGateway: jest.Mocked<PaymentGateway>;
beforeEach(() => {
mockGateway = {
charge: jest.fn()
};
processor = new PaymentProcessor(mockGateway);
});
it('should process a valid payment', async () => {
mockGateway.charge.mockResolvedValue(true);
const result = await processor.processPayment(100);
expect(result).toBe(true);
expect(mockGateway.charge).toHaveBeenCalledWith(100);
});
it('should throw for invalid amount', async () => {
await expect(processor.processPayment(-50)).rejects toThrow('Amount must be greater than zero');
});
});