TypeScript Interface vs Type Cheat Sheet

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

const user: User = { id: 1, name: 'Alice', email: 'alice@example.com' };

type User = {
  id: number;
  name: string;
  email: string;
};

const user: User = { id: 1, name: 'Alice', email: 'alice@example.com' };

interface Animal {
  name: string;
  age: number;
}

interface Dog extends Animal {
  breed: string;
}

// Dog has: name, age, breed
const dog: Dog = { name: 'Rex', age: 3, breed: 'Labrador' };

interface HasId { id: string }
interface HasTimestamps { createdAt: Date; updatedAt: Date }

interface Article extends HasId, HasTimestamps {
  title: string;
  body: string;
}

// Article has: id, createdAt, updatedAt, title, body

// First declaration
interface Window {
  title: string;
}

// Second declaration -- merges with the first
interface Window {
  appVersion: string;
}

// Window now has both: title and appVersion
const w: Window = { title: 'My App', appVersion: '1.0.0' };

type Status = 'pending' | 'active' | 'archived';

type Result<T> =
  | { ok: true; data: T }
  | { ok: false; error: string };

type ID = string | number;
type Coordinate = [x: number, y: number];
type Callback = (event: Event) => void;

// None of these can be expressed with interface

type Flags<T> = {
  [K in keyof T]: boolean;
};

interface Features {
  darkMode: string;
  notifications: string;
  analytics: string;
}

type FeatureFlags = Flags<Features>;
// => { darkMode: boolean; notifications: boolean; analytics: boolean }

// Interface version
interface ConfigI {
  readonly apiUrl: string;
  timeout?: number;
  debug?: boolean;
}

// Type version -- identical behavior
type ConfigT = {
  readonly apiUrl: string;
  timeout?: number;
  debug?: boolean;
};

// Interface
interface StringMap {
  [key: string]: string;
}

// Type
type StringMapT = {
  [key: string]: string;
};

// Both accept the same values
const headers: StringMap = { 'Content-Type': 'application/json' };

// Interface
interface Formatter {
  format(value: string): string;
}

// Type
type FormatterT = {
  format(value: string): string;
};

// Both accept the same implementation
const upper: Formatter = { format: (v) => v.toUpperCase() };

interface Base { id: number }
interface WithName extends Base { name: string }

const item: WithName = { id: 1, name: 'Alice' };

type Base = { id: number };
type WithName = Base & { name: string };

const item: WithName = { id: 1, name: 'Alice' };

// Type extending an interface
interface Animal { name: string }
type Pet = Animal & { owner: string };

// Interface extending a type
type HasId = { id: number };
interface User extends HasId { name: string }

// Interface extends -- conflicts are caught:
interface A { x: number }
// interface B extends A { x: string }
// => Error: 'x' in B is incompatible with 'x' in A

// Type intersection -- conflicts produce never:
type C = { x: number } & { x: string };
// C.x is type: never (number & string = nothing)

// In your app code, extend Express Request:
declare module 'express' {
  interface Request {
    userId?: string;
    sessionId?: string;
  }
}

// Now req.userId is available in handlers
// This is the primary real-world use of declaration merging

// Add a custom property to the global Window
declare global {
  interface Window {
    analytics: {
      track(event: string, data?: Record<string, unknown>): void;
    };
  }
}

// Now window.analytics.track('pageview') type-checks

type Config = { host: string };
// type Config = { port: number };
// => Error: Duplicate identifier 'Config'

// If you need merging, use interface instead:
interface Config { host: string }
interface Config { port: number }
// Config now has both host and port

// TS 5.0 improved performance for intersection types.
// Large intersections that caused slowdowns in TS 4.x are now faster.

// Before (TS 4.x): complex intersections could cause slow type-checking
type BigIntersection = A & B & C & D & E & F;  // could stall

// After (TS 5.0+): same type checks faster due to
// internal deferred type evaluation

// TS 5.x produces clearer error messages for both:

interface UserI { name: string; age: number }
type UserT = { name: string; age: number };

// Both now show structured diffs on mismatch:
// const user: UserI = { name: 'Alice', age: 'thirty' };
//                                       ~~~~~~~~~~~
// Type 'string' is not assignable to type 'number'.

// Use INTERFACE when:
//   - Defining an object shape you might extend later
//   - You need declaration merging (augmenting libraries)
//   - You want clearer error messages on property conflicts
//   - Your team convention says "interface for objects"

// Use TYPE when:
//   - Defining a union type (A | B)
//   - Defining a tuple type ([string, number])
//   - Defining a primitive alias (type ID = string)
//   - Using mapped types or conditional types
//   - Composing types with intersection (&)
//   - Your team convention says "type for everything"

// Use EITHER when:
//   - Defining a plain object shape (both work identically)
//   - The decision doesn't matter (be consistent, pick one)

// Convention A: "interface for objects, type for everything else"
interface User { name: string }          // object shape
type Status = 'active' | 'inactive';     // union
type Pair = [string, number];            // tuple

// Convention B: "type for everything"
type User = { name: string };
type Status = 'active' | 'inactive';
type Pair = [string, number];

// Both are valid. The TypeScript team uses Convention A internally.