TypeScript Best Practices and Advanced Patterns: Write Type-Safe Code

TypeScript has become the standard for building large-scale JavaScript applications. Its type system helps catch errors early, improves code maintainability, and enhances developer experience. However, writing effective TypeScript requires understanding best practices and advanced patterns.

This guide covers TypeScript best practices, advanced patterns, and techniques to write type-safe, maintainable code.

Type Safety Fundamentals

Avoid

any

Type

The

any

type defeats the purpose of TypeScript. Always use specific types or

unknown

when the type is truly unknown.

// ❌ Bad: Using any
function processData(data: any) {
  return data.value;
}

// ✅ Good: Using specific types
function processData(data: { value: string }) {
  return data.value;
}

// ✅ Good: Using unknown for truly unknown types
function processData(data: unknown) {
  if (typeof data === 'object' && data !== null && 'value' in data) {
    return (data as { value: string }).value;
  }
  throw new Error('Invalid data');
}

Use Type Inference

Let TypeScript infer types when possible, but be explicit for function parameters and return types.

// ✅ Good: Type inference for variables
const name = 'John'; // Type: string
const age = 30; // Type: number

// ✅ Good: Explicit types for functions
function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}

Leverage Type Guards

Use type guards to narrow types safely.

// Type guard function
function isString(value: unknown): value is string {
  return typeof value === 'string';
}

function processValue(value: unknown) {
  if (isString(value)) {
    // TypeScript knows value is string here
    console.log(value.toUpperCase());
  }
}

Advanced Type Patterns

Generics for Reusability

Generics allow you to create reusable, type-safe components.

// Generic function
function identity<T>(value: T): T {
  return value;
}

const stringValue = identity<string>('hello');
const numberValue = identity<number>(42);

// Generic interface
interface Repository<T> {
  findById(id: string): Promise<T | null>;
  save(entity: T): Promise<T>;
  delete(id: string): Promise<void>;
}

// Generic class
class UserRepository implements Repository<User> {
  async findById(id: string): Promise<User | null> {
    // Implementation
  }
  
  async save(user: User): Promise<User> {
    // Implementation
  }
  
  async delete(id: string): Promise<void> {
    // Implementation
  }
}

Utility Types

TypeScript provides powerful utility types for common transformations.

interface User {
  id: string;
  name: string;
  email: string;
  age: number;
}

// Partial: Make all properties optional
type PartialUser = Partial<User>;
// { id?: string; name?: string; email?: string; age?: number; }

// Pick: Select specific properties
type UserPreview = Pick<User, 'id' | 'name'>;
// { id: string; name: string; }

// Omit: Remove specific properties
type UserWithoutId = Omit<User, 'id'>;
// { name: string; email: string; age: number; }

// Required: Make all properties required
type RequiredUser = Required<Partial<User>>;

// Readonly: Make all properties readonly
type ReadonlyUser = Readonly<User>;

Conditional Types

Conditional types enable type-level logic and transformations.

// Basic conditional type
type IsArray<T> = T extends any[] ? true : false;

type Test1 = IsArray<string[]>; // true
type Test2 = IsArray<string>; // false

// Extract array element type
type ArrayElement<T> = T extends (infer U)[] ? U : never;

type Element = ArrayElement<string[]>; // string

// Non-nullable type
type NonNullable<T> = T extends null | undefined ? never : T;

Mapped Types

Mapped types create new types by transforming properties of existing types.

// Make all properties optional and nullable
type OptionalNullable<T> = {
  [K in keyof T]?: T[K] | null;
};

// Create readonly version
type Readonly<T> = {
  readonly [K in keyof T]: T[K];
};

// Transform property types
type Stringify<T> = {
  [K in keyof T]: string;
};

Best Practices

1. Use Strict Mode

Enable strict mode in

tsconfig.json

for better type checking.

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true
  }
}

2. Prefer Interfaces for Object Shapes

Use interfaces for object shapes, types for unions, intersections, and primitives.

// ✅ Good: Interface for object shape
interface User {
  id: string;
  name: string;
}

// ✅ Good: Type for union
type Status = 'pending' | 'approved' | 'rejected';

// ✅ Good: Type for intersection
type AdminUser = User & { role: 'admin' };

3. Use Enums Sparingly

Prefer union types over enums for better type safety and tree-shaking.

// ❌ Avoid: Numeric enums
enum Status {
  Pending,
  Approved,
  Rejected
}

// ✅ Prefer: Union types
type Status = 'pending' | 'approved' | 'rejected';

// ✅ Or: Const assertions
const Status = {
  Pending: 'pending',
  Approved: 'approved',
  Rejected: 'rejected'
} as const;

type Status = typeof Status[keyof typeof Status];

4. Handle Null and Undefined Explicitly

Use strict null checks and handle null/undefined explicitly.

// ✅ Good: Explicit null handling
function getUser(id: string): User | null {
  const user = database.find(id);
  return user ?? null;
}

// ✅ Good: Using optional chaining
const userName = user?.name ?? 'Unknown';

// ✅ Good: Non-null assertion when certain
const userName = user!.name; // Only if you're 100% sure user exists

5. Use Const Assertions

Use const assertions for literal types and readonly arrays.

// ✅ Good: Const assertion
const colors = ['red', 'green', 'blue'] as const;
type Color = typeof colors[number]; // 'red' | 'green' | 'blue'

// ✅ Good: Readonly array
const numbers: readonly number[] = [1, 2, 3];

Advanced Patterns

Discriminated Unions

Use discriminated unions for type-safe state management.

type LoadingState = {
  status: 'loading';
};

type SuccessState = {
  status: 'success';
  data: string;
};

type ErrorState = {
  status: 'error';
  error: Error;
};

type AsyncState = LoadingState | SuccessState | ErrorState;

function handleState(state: AsyncState) {
  switch (state.status) {
    case 'loading':
      return 'Loading...';
    case 'success':
      return state.data; // TypeScript knows data exists
    case 'error':
      return state.error.message; // TypeScript knows error exists
  }
}

Branded Types

Create branded types for additional type safety.

type UserId = string & { readonly brand: unique symbol };
type ProductId = string & { readonly brand: unique symbol };

function createUserId(id: string): UserId {
  return id as UserId;
}

function getUser(id: UserId) {
  // Implementation
}

// Type error: ProductId is not assignable to UserId
const userId = createUserId('123');
const productId = '456' as ProductId;
getUser(productId); // Error!

Template Literal Types

Use template literal types for string manipulation.

type EventName<T extends string> = `on${Capitalize<T>}`;

type ClickEvent = EventName<'click'>; // 'onClick'
type ChangeEvent = EventName<'change'>; // 'onChange'

// API route types
type ApiRoute<T extends string> = `/api/${T}`;

type UserRoute = ApiRoute<'users'>; // '/api/users'
type PostRoute = ApiRoute<'posts'>; // '/api/posts'

Function Overloads

Use function overloads for better type inference.

function format(value: string): string;
function format(value: number): string;
function format(value: boolean): string;
function format(value: string | number | boolean): string {
  return String(value);
}

const str = format('hello'); // Type: string
const num = format(42); // Type: string

React-Specific Patterns

Component Props Types

Define clear prop types for React components.

interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
  disabled?: boolean;
}

function Button({ label, onClick, variant = 'primary', disabled = false }: ButtonProps) {
  return (
    <button onClick={onClick} disabled={disabled} className={variant}>
      {label}
    </button>
  );
}

Generic Components

Create reusable generic components.

interface ListProps<T> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
}

function List<T>({ items, renderItem }: ListProps<T>) {
  return (
    <ul>
      {items.map((item, index) => (
        <li key={index}>{renderItem(item)}</li>
      ))}
    </ul>
  );
}

// Usage
<List
  items={users}
  renderItem={(user) => <div>{user.name}</div>}
/>

Error Handling Patterns

Result Type Pattern

Use Result type for explicit error handling.

type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

function divide(a: number, b: number): Result<number> {
  if (b === 0) {
    return { success: false, error: new Error('Division by zero') };
  }
  return { success: true, data: a / b };
}

const result = divide(10, 2);
if (result.success) {
  console.log(result.data); // TypeScript knows data exists
} else {
  console.error(result.error); // TypeScript knows error exists
}

Conclusion

TypeScript's type system is powerful and expressive. By following best practices and leveraging advanced patterns, you can write more maintainable, type-safe code.

Key Takeaways:

1. Avoid

   any

   - Use specific types or

   unknown

2. Leverage type inference - Let TypeScript infer when possible
3. Use utility types - They solve common type transformation needs
4. Prefer union types - Over enums for better type safety
5. Handle null explicitly - Use strict null checks
6. Use generics - For reusable, type-safe code
7. Leverage advanced patterns - Discriminated unions, branded types, template literals

Master these patterns and practices to write robust, type-safe TypeScript code that scales with your application!