TypeScript Types vs Interfaces: When to Use Each and Why It Matters

// ── 1. Aliasing a union type ──────────────────────────────────────────────
// This says: a Status can ONLY be one of these three strings.
// TypeScript will error if you try to assign anything else.
type Status = 'idle' | 'loading' | 'success' | 'error';

// ── 2. Describing a function signature ────────────────────────────────────
// Anyone reading this immediately knows what this callback must look like.
// No more guessing what arguments an event handler receives.
type PriceFormatter = (amount: number, currencyCode: string) => string;

const formatUSD: PriceFormatter = (amount, currencyCode) => {
  // Intl.NumberFormat gives us locale-aware currency formatting
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: currencyCode,
  }).format(amount);
};

console.log(formatUSD(1999.5, 'USD')); // $1,999.50

// ── 3. Describing a complex object shape ──────────────────────────────────
type ApiResponse<T> = {
  data: T | null;       // the actual payload, or null if there's an error
  status: Status;       // reusing our union type from above
  errorMessage?: string; // the ? makes this property optional
  requestedAt: Date;
};

// A concrete usage — an API response that carries a list of product names
const productResponse: ApiResponse<string[]> = {
  data: ['Wireless Keyboard', 'USB Hub', 'Monitor Stand'],
  status: 'success',
  requestedAt: new Date('2024-06-01T10:00:00Z'),
};

console.log(productResponse.status);       // success
console.log(productResponse.data?.length); // 3

// ── 4. Tuple type — positional, fixed-length array ────────────────────────
// Use this when the ORDER and TYPES of positions are meaningful.
// Here: [latitude, longitude] — never the other way around.
type Coordinates = [latitude: number, longitude: number];

const sydneyHarbour: Coordinates = [-33.8568, 151.2153];
console.log(`Lat: ${sydneyHarbour[0]}, Lng: ${sydneyHarbour[1]}`);
// Lat: -33.8568, Lng: 151.2153

// ── 1. Base interface for any entity stored in the database ───────────────
interface BaseEntity {
  id: string;           // UUID from the database
  createdAt: Date;
  updatedAt: Date;
}

// ── 2. Extending an interface — User inherits all of BaseEntity ───────────
// The extends keyword says: a User must satisfy BaseEntity PLUS these fields.
interface User extends BaseEntity {
  email: string;
  displayName: string;
  isEmailVerified: boolean;
}

// ── 3. Multi-level extension ───────────────────────────────────────────────
// AdminUser must satisfy User (which itself satisfies BaseEntity) plus this.
interface AdminUser extends User {
  permissions: string[];  // e.g. ['users:delete', 'billing:read']
  lastLoginAt: Date;
}

// ── 4. Declaration merging — extending an interface from a separate location
// Imagine this second block is in a different file, e.g. analytics.d.ts
// TypeScript merges BOTH declarations into one complete interface.
interface User {
  analyticsId?: string; // added by your analytics module — optional
}

// Now a User object can legally include analyticsId
const currentUser: User = {
  id: 'usr_8f3kd92',
  createdAt: new Date('2023-01-15'),
  updatedAt: new Date('2024-05-20'),
  email: 'priya@example.com',
  displayName: 'Priya Sharma',
  isEmailVerified: true,
  analyticsId: 'ga_4829xz', // merged from second declaration
};

console.log(currentUser.displayName);  // Priya Sharma
console.log(currentUser.analyticsId);  // ga_4829xz

// ── 5. Interface for a class contract ────────────────────────────────────
// This is where interface is strictly more appropriate than type.
// The implements keyword enforces the contract at the class level.
interface NotificationService {
  send(recipient: string, message: string): Promise<void>;
  getDeliveryStatus(messageId: string): Promise<'delivered' | 'failed' | 'pending'>;
}

class EmailNotificationService implements NotificationService {
  async send(recipient: string, message: string): Promise<void> {
    // Real implementation would call an email API here
    console.log(`Sending email to ${recipient}: "${message}"`);
  }

  async getDeliveryStatus(messageId: string): Promise<'delivered' | 'failed' | 'pending'> {
    // Real implementation would query an email delivery API
    console.log(`Checking status for message: ${messageId}`);
    return 'delivered';
  }
}

const emailService = new EmailNotificationService();
emailService.send('alex@example.com', 'Your order has shipped!');
// Sending email to alex@example.com: "Your order has shipped!"

// ── 1. Intersection type — combining two shapes into one ──────────────────
type Timestamped = {
  createdAt: Date;
  updatedAt: Date;
};

type Identifiable = {
  id: string;
};

// A Product must satisfy BOTH Timestamped AND Identifiable, plus its own fields
type Product = Timestamped & Identifiable & {
  name: string;
  priceInCents: number; // storing money as integers avoids floating-point bugs
  stockCount: number;
};

const wirelessMouse: Product = {
  id: 'prod_wm_001',
  name: 'Wireless Ergonomic Mouse',
  priceInCents: 4999, // represents $49.99
  stockCount: 142,
  createdAt: new Date('2024-01-10'),
  updatedAt: new Date('2024-06-01'),
};

console.log(`${wirelessMouse.name}: $${wirelessMouse.priceInCents / 100}`);
// Wireless Ergonomic Mouse: $49.99

// ── 2. Generic type — a reusable wrapper for paginated API responses ───────
// The <T> is a placeholder. When you USE this type, you fill in what T is.
type PaginatedResult<T> = {
  items: T[];           // an array of whatever type T turns out to be
  totalCount: number;
  currentPage: number;
  totalPages: number;
  hasNextPage: boolean;
};

// Now reuse it for any entity — no duplication
type PaginatedProducts = PaginatedResult<Product>;
type PaginatedUsers = PaginatedResult<{ id: string; email: string }>;

const productPage: PaginatedProducts = {
  items: [wirelessMouse],
  totalCount: 87,
  currentPage: 1,
  totalPages: 9,
  hasNextPage: true,
};

console.log(`Page ${productPage.currentPage} of ${productPage.totalPages}`);
// Page 1 of 9

// ── 3. Generic function — works with any entity that has an id ─────────────
// The constraint 'extends Identifiable' means: T must have at least an id.
// This prevents calling findById with a plain number or a string.
function findById<T extends Identifiable>(items: T[], targetId: string): T | undefined {
  // TypeScript knows items[i].id is safe because of the extends constraint
  return items.find(item => item.id === targetId);
}

const foundProduct = findById([wirelessMouse], 'prod_wm_001');
console.log(foundProduct?.name); // Wireless Ergonomic Mouse

// ── 4. Using built-in utility types ───────────────────────────────────────
// Partial<T> makes every property optional — perfect for update/patch payloads
type ProductUpdatePayload = Partial<Pick<Product, 'name' | 'priceInCents' | 'stockCount'>>;

// A PATCH request only needs to send the fields being changed
const priceUpdate: ProductUpdatePayload = {
  priceInCents: 3999, // just updating the price — all other fields are optional
};

console.log(priceUpdate); // { priceInCents: 3999 }

// ── Our domain types ──────────────────────────────────────────────────────
type SuccessResponse = {
  kind: 'success'; // discriminant field — a literal type, not just string
  data: { orderId: string; total: number };
};

type ErrorResponse = {
  kind: 'error'; // different literal — same field name, different value
  message: string;
  code: number;
};

// A discriminated union — both members share 'kind' but with different values
type CheckoutResponse = SuccessResponse | ErrorResponse;

// ── 1. Discriminated union narrowing — the cleanest pattern ───────────────
// TypeScript uses the 'kind' field to automatically narrow the type in each branch.
function handleCheckoutResponse(response: CheckoutResponse): void {
  if (response.kind === 'success') {
    // Inside this block, TypeScript KNOWS response is SuccessResponse
    // So response.data is available and type-safe
    console.log(`Order confirmed! ID: ${response.data.orderId}`);
    console.log(`Total charged: $${response.data.total / 100}`);
  } else {
    // In the else block, TypeScript KNOWS response is ErrorResponse
    console.log(`Checkout failed [${response.code}]: ${response.message}`);
  }
}

handleCheckoutResponse({
  kind: 'success',
  data: { orderId: 'ord_7f4kx', total: 8997 },
});
// Order confirmed! ID: ord_7f4kx
// Total charged: $89.97

handleCheckoutResponse({
  kind: 'error',
  message: 'Card declined',
  code: 4001,
});
// Checkout failed [4001]: Card declined

// ── 2. User-defined type guard — for validating unknown external data ──────
// The return type 'value is SuccessResponse' is the magic.
// When this function returns true, TypeScript narrows the type in the calling scope.
function isSuccessResponse(value: unknown): value is SuccessResponse {
  // We manually check every field we care about
  return (
    typeof value === 'object' &&
    value !== null &&
    'kind' in value &&
    (value as SuccessResponse).kind === 'success' &&
    'data' in value
  );
}

// Simulating data coming back from fetch() — typed as unknown
const rawApiData: unknown = {
  kind: 'success',
  data: { orderId: 'ord_9g5kp', total: 4500 },
};

if (isSuccessResponse(rawApiData)) {
  // TypeScript now trusts that rawApiData is SuccessResponse
  console.log(`Validated order: ${rawApiData.data.orderId}`);
} else {
  console.log('Received unexpected response shape from API');
}
// Validated order: ord_9g5kp