Skip to main content

TypeScript Interface vs Type

TypeScript offers two primary ways to define object structures: interfaces and types. While they share many similarities, each has unique features that make them suitable for different scenarios. In this article, we'll explore how to choose between them, define detailed object shapes, expand existing definitions, handle intersection and union types, document your code clearly, enhance readability, and ensure compatibility. Understanding these concepts will help you write better TypeScript code that's easier to maintain and scale.

1. Choosing Between Interfaces and Types​

The choice between interfaces and types in TypeScript can be tricky because of their overlapping abilities. Here are the key differences to help you decide:

  • Interfaces excel at defining contracts for object shapes, especially when they'll be implemented by classes. They support declaration merging, allowing you to add properties to existing interfaces.
  • Types offer more flexibility with unions, primitives, and intersections, making them ideal for complex type compositions when working with TypeScript in your projects.
// Interface - great for object shapes and class contracts
interface User {
  name: string;
  age: number;
  getFullName(): string;
}

// Type - excellent for unions, primitives, and type operations
type UserId = string | number;
type UserRecord = `Record<UserId, User>`;

// Using the interface in a class
class Employee implements User {
  name: string;
  age: number;
  
  constructor(name: string, age: number) {
    this.name = name;
    this.age = age;
  }
  
  getFullName(): string {
    return this.name;
  }
}

When defining data models with generics<T>, choosing between interfaces and types often depends on your specific requirements and how you plan to use them throughout your codebase.

2. Defining Detailed Object Shapes​

Creating complex object shapes requires a clear and maintainable code structure. Developers must decide how best to represent nested objects, optional properties, or mixed data types. This can become challenging when modeling something like a deeply nested configuration object with both optional and required properties.

// Nested interface for a complex configuration object
interface Config {
  database: {
    host: string;
    port: number;
    username: string;
    password: string;
  };
  api: {
    endpoint: string;
    headers: {
      'Content-Type': string;
      Authorization?: string; // Optional property
    };
  };
  features?: {
    enableLogging: boolean;
    maxRetries: number;
  }; // Optional section
}

// Type for handling mixed data types
type DataValue = string | number | boolean | null;
type DataRecord = `Record<string, DataValue>`;

// Using the interface and type together
const appConfig: Config = {
  database: {
    host: 'localhost',
    port: 5432,
    username: 'admin',
    password: 'securepassword',
  },
  api: {
    endpoint: 'https://api.example.com',
    headers: {
      'Content-Type': 'application/json',
    },
  },
};

const userData: DataRecord = {
  id: 1234,
  name: 'John Doe',
  active: true,
  lastLogin: null,
};

Here are the key differences to help you decide: When working with complex data structures in Convex, you can use validation helpers to ensure your objects match their expected shapes. This approach makes your code more reliable and easier to maintain as your project grows.

For large projects, consider using utility types to manipulate object shapes and create variations without duplicating code.

3. Extending Interfaces and Types​

In TypeScript, you can extend interfaces and types in several ways. Interfaces can be extended using the extends keyword, while types can be combined using the & symbol. You can also use declaration merging to expand an interface or type.

// Interface extension using 'extends'
interface User {
  name: string;
  age: number;
}

interface Admin extends User {
  role: string;
  permissions: string[];
}

// Type intersection using '&'
type BasicUser = {
  id: number;
  email: string;
};

type EnhancedUser = BasicUser & {
  verified: boolean;
  lastLogin: Date;
};

// Declaration merging for interfaces
interface User {
  phone?: string; // Adding optional property to existing interface
}

// Using the extended types
const admin: Admin = {
  name: 'Jane Doe',
  age: 32,
  role: 'system admin',
  permissions: ['read', 'write', 'delete'],
  phone: '555-1234' // From merged interface
};

const verifiedUser: EnhancedUser = {
  id: 123,
  email: 'user@example.com',
  verified: true,
  lastLogin: new Date()
};

When building schema validation in Convex, you can leverage these extension techniques to create reusable field validators. This approach helps eliminate repetition and enforce consistent data structures across your application.

For complex type hierarchies, extends provides a clean way to build relationships between different data types.

4. Managing Intersection and Union Types​

Understanding how to use intersection and union types with TypeScript interfaces and types is critical. Intersection types, represented by &, combine two types, while union types, represented by |, allow a value to be one of several types.

// Intersection type - combines multiple types
type Employee = {
  id: number;
  name: string;
};

type Manager = {
  department: string;
  reports: Employee[];
};

type ManagerWithDetails = Employee & Manager;

// Union type - can be one of several types
type ID = string | number;
type Status = 'pending' | 'active' | 'deleted';

// Type guards to narrow union types
function processID(id: ID): string {
  if (typeof id === 'string') {
    return id.toUpperCase();
  } else {
    return id.toString().padStart(5, '0');
  }
}

// Using the composed types
const seniorManager: ManagerWithDetails = {
  id: 101,
  name: 'Alice Smith',
  department: 'Engineering',
  reports: [
    { id: 201, name: 'Bob Johnson' },
    { id: 202, name: 'Carol Williams' }
  ]
};

const userStatus: Status = 'active';
const userID: ID = 'U12345';

When working with complex filters in Convex, union types help you create flexible query parameters that can handle different filtering criteria. This pattern makes your backend API more adaptable to various client requirements.

For state management patterns, consider using discriminated union to model different states with associated data.

5. Documenting Code Clearly​

Using TypeScript interfaces and types effectively involves clear documentation with JSDoc comments. Well-written comments help other developers understand the purpose and behavior of your code.

/**
 * Represents a user in the system
 * @interface
 */
interface User {
  /**
   * Unique identifier for the user
   */
  id: number;
  
  /**
   * User's full name
   */
  name: string;
  
  /**
   * User's email address
   * @example "user@example.com"
   */
  email: string;
  
  /**
   * Get the user's display name
   * @returns A formatted string with the user's name
   */
  getDisplayName(): string;
}

/**
 * Represents possible authentication methods
 * @typedef {string} AuthMethod
 */
type AuthMethod = 'password' | 'oauth' | 'sso' | 'mfa';

/**
 * Configuration for user authentication
 * @typedef {Object} AuthConfig
 */
type AuthConfig = {
  /**
   * Primary authentication method
   */
  primary: AuthMethod;
  
  /**
   * Optional backup methods
   */
  fallbacks?: AuthMethod[];
};

When building type-safe backends with Convex, thorough documentation ensures your team can understand the data structures and API contracts. This becomes especially important as your project grows and more developers join.

For complex type hierarchies, using utility types with clear documentation provides both flexibility and clarity to your codebase.

6. Boosting Code Readability​

Readable TypeScript code is easier to maintain and less prone to errors. Following consistent naming conventions and using type aliases wisely can significantly improve your code's clarity.

// Poor readability
interface i {
  n: string;
  a: number;
  e: string;
  act: boolean;
}

// Better readability with clear naming
interface UserProfile {
  name: string;
  age: number;
  email: string;
  active: boolean;
}

// Using type aliases for complex types
type UserID = string;
type Timestamp = number;

// Simplifying deeply nested types
type ApiResponse<T> = {
  data: T;
  metadata: {
    timestamp: Timestamp;
    requestId: string;
  };
  status: 'success' | 'error';
};

// Instead of repeating complex types
type UserResponse = ApiResponse<UserProfile>;
type ProductResponse = ApiResponse<Product>;

When creating custom functions in Convex, following consistent naming patterns makes your API more intuitive. This approach helps developers quickly understand how different parts of the system relate to each other.

The Record<K, V> offers a clean way to represent key-value collections, improving code readability compared to index signatures.

7. Ensuring Compatibility​

To ensure compatibility when using interfaces and types together in TypeScript, it's important to understand how to extend or merge them without causing errors. Techniques like declaration merging, type intersection, and type guards help maintain a solid codebase.

// Interface declaration
interface User {
  id: number;
  name: string;
}

// Compatible type - can be assigned to User
type Employee = {
  id: number;
  name: string;
  department?: string; // Optional additional property
};

// Type guard for runtime type checking
function isUser(obj: any): obj is User {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'id' in obj &&
    'name' in obj &&
    typeof obj.id === 'number' &&
    typeof obj.name === 'string'
  );
}

// Using interfaces and types together
function processUser(user: User) {
  console.log(`Processing user: ${user.name}`);
}

const employee: Employee = {
  id: 1,
  name: 'Alice Smith',
  department: 'Engineering'
};

// This works due to structural typing
processUser(employee);

// Runtime type checking
function processUserData(data: unknown) {
  if (isUser(data)) {
    processUser(data);
  } else {
    console.error('Invalid user data');
  }
}

When traversing data relationships in Convex, understanding structural typing helps you build flexible yet type-safe queries. The helpers in convex-helpers leverage TypeScript's structural typing to provide both safety and flexibility.

For complex type checking, typeof can help narrow down types in your conditional logic, ensuring type compatibility at runtime.

Final Thoughts on TypeScript Interface vs Type​

Choosing between interfaces and types in TypeScript depends on your specific requirements. Here's a quick reference to help you decide:

  • Use interfaces when:
    • Defining class contracts
    • You need declaration merging
    • Working with object shapes that might be extended later
  • Use types when:
    • Working with unions or intersections
    • Creating mapped or conditional types
    • Needing to manipulate types with utility functions

Both approaches help make your code more robust by catching errors at compile time rather than runtime. As you build more complex applications with TypeScript in Convex, you'll develop an intuition for which tool fits each situation better.