TypeScript Aliases & Interfaces

TypeScript Aliases & Interfaces: Defining Custom Contracts

Both type aliases and interface declarations allow you to define reusable type contracts in TypeScript. While similar, they have distinct capabilities and best-use cases.

Type Alias vs Interface Feature Matrix

flowchart TD
    A["Contract Definition"] --> B["interface"]
    A --> C["type Alias"]
    B --> D["Can be extended via extends"]
    B --> E["Supports Declaration Merging"]
    B --> F["Best for OOP & Library APIs"]
    C --> G["Can represent primitives & unions"]
    C --> H["Supports Mapped & Tuple Types"]
    C --> I["Best for Complex Functional Types"]

Practical Code Example

// Interface definition
interface Identifiable {
  readonly id: string;
}

interface Timestamped {
  createdAt: Date;
  updatedAt: Date;
}

// Interface extending multiple interfaces
interface UserProfile extends Identifiable, Timestamped {
  username: string;
  email: string;
}

// Type alias for primitive unions and object shapes
type AccountStatus = "active" | "suspended" | "pending";

type UserAccount = UserProfile & {
  status: AccountStatus;
  loginCount: number;
};

const activeUser: UserAccount = {
  id: "usr_1029",
  username: "johndoe",
  email: "[email protected]",
  status: "active",
  loginCount: 42,
  createdAt: new Date("2024-01-01"),
  updatedAt: new Date()
};

console.log(`User ${activeUser.username} (${activeUser.id}) status: ${activeUser.status}`);

Best Practices & Gotchas

• Use interface for Public APIs & Object Models: Interfaces support declaration merging and provide better error messages in IDEs.
• Use type for Unions, Primitives, & Tuples: Type aliases are required when defining union types (type ID = string | number).
• Be Mindful of Declaration Merging: Multiple interface declarations with the same name in the same scope will merge automatically, which can cause unexpected property inheritance if not intended.

Self-Check Challenge

Define an interface Person with name: string. Define another interface Employee that extends Person and adds jobTitle: string.