Interfaces and Type Aliases

The API Contract That Saved Our Integration

It was Thursday afternoon when our mobile team pinged me on Slack: "The user endpoint is returning different fields randomly. Sometimes we get firstName, sometimes first_name. The app is crashing."

I pulled up our Node.js API code:

// user-service.js
function getUser(id) {
  return db.query('SELECT * FROM users WHERE id = ?', [id])
    .then(user => {
      // Sometimes we do this
      return { firstName: user.first_name, lastName: user.last_name };
      // Other times we forget and return raw DB fields
      return user;
    });
}

No contract. No consistency. Just JavaScript objects that could be anything.

The mobile team had built their models based on the first response they saw. When I refactored the backend, I changed field names without realizing it. Result: 3,000 users stuck on a broken app screen.

I spent that weekend migrating to TypeScript and defining explicit interfaces:

interface User {
  id: string;
  firstName: string;
  lastName: string;
  email: string;
  createdAt: Date;
}

interface UserResponse {
  user: User;
  metadata: {
    lastLogin: Date;
    status: 'active' | 'suspended' | 'deleted';
  };
}

function getUser(id: string): Promise<UserResponse> {
  // TypeScript won't let me return the wrong shape
  return db.query('SELECT * FROM users WHERE id = ?', [id])
    .then(row => ({
      user: {
        id: row.id,
        firstName: row.first_name,  // Explicit mapping
        lastName: row.last_name,
        email: row.email,
        createdAt: new Date(row.created_at)
      },
      metadata: {
        lastLogin: new Date(row.last_login),
        status: row.status
      }
    }));
}

The migration took 2 days. We caught 43 different inconsistencies during compilation. No more runtime surprises. The mobile team could finally trust our API contract.

This article covers everything about interfaces and type aliases that I wish I'd learned before that incident.

---

Object Types

TypeScript's core strength: describing object shapes.

Inline Object Types

function printUser(user: { name: string; age: number }) {
  console.log(`${user.name} is ${user.age} years old`);
}

printUser({ name: 'Alice', age: 30 });  // ✓
printUser({ name: 'Bob' });              // ✗ Missing 'age'
printUser({ name: 'Eve', age: 25, extra: true });  // ✗ Excess property

Object Type Inference

const product = {
  name: 'Laptop',
  price: 999,
  inStock: true
};

// TypeScript infers:
// {
//   name: string;
//   price: number;
//   inStock: boolean;
// }

---

Interfaces: Defining Contracts

Interfaces describe object shapes that can be implemented and extended.

Basic Interface

interface Product {
  id: string;
  name: string;
  price: number;
  description: string;
}

const laptop: Product = {
  id: 'prod-001',
  name: 'MacBook Pro',
  price: 2499,
  description: '16-inch laptop'
};

// Missing properties
const invalid: Product = {
  id: 'prod-002',
  name: 'iPad'
  // ✗ Error: Missing 'price' and 'description'
};

Optional Properties

interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  phoneNumber?: string;      // Optional
  middleName?: string;       // Optional
}

const user1: User = {
  id: '1',
  email: '[email protected]',
  firstName: 'Alice',
  lastName: 'Smith'
  // phoneNumber is optional - valid
};

const user2: User = {
  id: '2',
  email: '[email protected]',
  firstName: 'Bob',
  lastName: 'Jones',
  phoneNumber: '[phone]'  // Also valid
};

// Using optional properties
function displayPhone(user: User) {
  // Must check if exists
  if (user.phoneNumber) {
    console.log(`Phone: ${user.phoneNumber}`);
  } else {
    console.log('No phone number provided');
  }
}

Readonly Properties

interface Config {
  readonly apiKey: string;
  readonly endpoint: string;
  timeout: number;  // Mutable
}

const config: Config = {
  apiKey: 'secret-key-123',
  endpoint: 'https://api.example.com',
  timeout: 5000
};

config.timeout = 10000;  // ✓ Allowed
config.apiKey = 'new-key';  // ✗ Error: Cannot assign to 'apiKey' because it is read-only

Real-world use case from my API project:

interface DatabaseConfig {
  readonly host: string;
  readonly port: number;
  readonly database: string;
  readonly user: string;
  readonly password: string;
  poolSize: number;  // Can be changed at runtime
  connectionTimeout: number;  // Can be changed at runtime
}

// Prevents accidental modification of connection details
function connectToDatabase(config: DatabaseConfig) {
  // config.host = 'localhost';  // ✗ Compiler error
  config.poolSize = 20;  // ✓ Allowed
}

---

Interface Extension

Interfaces can extend other interfaces, building complex types from simpler ones.

Single Extension

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

interface Dog extends Animal {
  breed: string;
  bark(): void;
}

const myDog: Dog = {
  name: 'Rex',
  age: 5,
  breed: 'Golden Retriever',
  bark() {
    console.log('Woof!');
  }
};

Multiple Extension

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

interface Identifiable {
  id: string;
}

interface User extends Identifiable, Timestamped {
  email: string;
  name: string;
}

const user: User = {
  id: 'user-123',
  email: '[email protected]',
  name: 'John Doe',
  createdAt: new Date('2024-01-01'),
  updatedAt: new Date('2024-12-01')
};

Production pattern I use everywhere:

interface BaseEntity {
  id: string;
  createdAt: Date;
  updatedAt: Date;
  deletedAt?: Date;
}

interface User extends BaseEntity {
  email: string;
  firstName: string;
  lastName: string;
  role: 'admin' | 'user' | 'guest';
}

interface Product extends BaseEntity {
  name: string;
  price: number;
  sku: string;
  inventory: number;
}

interface Order extends BaseEntity {
  userId: string;
  items: OrderItem[];
  total: number;
  status: 'pending' | 'paid' | 'shipped' | 'delivered';
}

---

Type Aliases

Type aliases create new names for types, including primitives, unions, tuples, and complex types.

Basic Type Alias

type UserID = string;
type ProductID = string;

function getUser(id: UserID): User { /* ... */ }
function getProduct(id: ProductID): Product { /* ... */ }

// More readable than:
// function getUser(id: string): User { /* ... */ }

Object Type Aliases

type Point = {
  x: number;
  y: number;
};

type Circle = {
  center: Point;
  radius: number;
};

const myCircle: Circle = {
  center: { x: 0, y: 0 },
  radius: 10
};

Union Type Aliases

type Status = 'loading' | 'success' | 'error';
type ID = string | number;

function handleStatus(status: Status) {
  if (status === 'loading') {
    console.log('Loading...');
  }
  // 'pending' is not assignable
  // status = 'pending';  // ✗ Error
}

---

Interfaces vs Type Aliases

When I started with TypeScript, this confused me the most. Here's what I learned:

Key Differences

// 1. Declaration Merging - Interfaces only
interface Window {
  title: string;
}

interface Window {
  version: number;
}

// Merged into:
// interface Window {
//   title: string;
//   version: number;
// }

// Type aliases DON'T merge
type User = { name: string; };
type User = { age: number; };  // ✗ Error: Duplicate identifier

// 2. Extending vs Intersection
interface Animal {
  name: string;
}

// Interface extension
interface Dog extends Animal {
  breed: string;
}

// Type alias intersection
type Cat = Animal & {
  indoor: boolean;
};

// Both work, but interfaces give better error messages

// 3. Type aliases can represent primitives, unions, tuples
type ID = string | number;  // ✓ Valid
type Coordinate = [number, number];  // ✓ Valid

interface ID = string | number;  // ✗ Can't do this

My Decision Framework

Use Interfaces When:

• Defining object shapes

• Building public APIs (better error messages)

• Working with classes

• Might need declaration merging (libraries)

Use Type Aliases When:

• Defining union types

• Defining tuple types

• Creating utility types

• Aliasing primitives

• Complex type manipulations

Real example from my codebase:

// Interface for object contract
interface User {
  id: string;
  email: string;
  role: UserRole;  // Type alias
}

// Type alias for union
type UserRole = 'admin' | 'moderator' | 'user';

// Type alias for utility
type PartialUser = Partial<User>;

// Interface for extension
interface AdminUser extends User {
  permissions: string[];
  departmentId: string;
}

---

Index Signatures

When object property names aren't known ahead of time.

String Index Signature

interface StringDictionary {
  [key: string]: string;
}

const translations: StringDictionary = {
  hello: 'Hola',
  goodbye: 'Adiós',
  thanks: 'Gracias'
};

translations.welcome = 'Bienvenido';  // ✓
translations.count = 123;  // ✗ Must be string

Number Index Signature

interface NumberArray {
  [index: number]: string;
}

const fruits: NumberArray = ['apple', 'banana', 'orange'];
console.log(fruits[0]);  // 'apple'

Mixed Index Signatures

interface Config {
  // Known properties
  apiUrl: string;
  timeout: number;
  
  // Dynamic properties
  [key: string]: string | number;
}

const config: Config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
  retryCount: 3,
  maxConnections: 10
};

Real-world use from my feature flag system:

interface FeatureFlags {
  [featureName: string]: boolean | { enabled: boolean; rolloutPercentage: number };
}

const flags: FeatureFlags = {
  newDashboard: true,
  betaFeature: { enabled: true, rolloutPercentage: 25 },
  experimentalAPI: false
};

function isFeatureEnabled(feature: string): boolean {
  const flag = flags[feature];
  if (typeof flag === 'boolean') {
    return flag;
  }
  return flag?.enabled ?? false;
}

---

Nested Interfaces

Complex data structures often need nested types.

Simple Nesting

interface Address {
  street: string;
  city: string;
  state: string;
  zipCode: string;
  country: string;
}

interface Company {
  name: string;
  address: Address;
  employees: number;
}

const acme: Company = {
  name: 'ACME Corp',
  address: {
    street: '123 Main St',
    city: 'Springfield',
    state: 'IL',
    zipCode: '62701',
    country: 'USA'
  },
  employees: 500
};

Deep Nesting

interface OrderItem {
  productId: string;
  quantity: number;
  price: number;
}

interface Order {
  id: string;
  customer: {
    id: string;
    name: string;
    email: string;
    shippingAddress: Address;
    billingAddress: Address;
  };
  items: OrderItem[];
  payment: {
    method: 'credit_card' | 'paypal' | 'bank_transfer';
    status: 'pending' | 'completed' | 'failed';
    transactionId?: string;
  };
  totals: {
    subtotal: number;
    tax: number;
    shipping: number;
    total: number;
  };
  createdAt: Date;
}

Pattern I use to keep types manageable:

// Break into smaller, reusable interfaces
interface Customer {
  id: string;
  name: string;
  email: string;
  shippingAddress: Address;
  billingAddress: Address;
}

interface Payment {
  method: 'credit_card' | 'paypal' | 'bank_transfer';
  status: 'pending' | 'completed' | 'failed';
  transactionId?: string;
}

interface OrderTotals {
  subtotal: number;
  tax: number;
  shipping: number;
  total: number;
}

// Compose them
interface Order {
  id: string;
  customer: Customer;
  items: OrderItem[];
  payment: Payment;
  totals: OrderTotals;
  createdAt: Date;
}

---

Function Properties in Interfaces

Interfaces can describe object methods.

Method Syntax

interface Calculator {
  add(a: number, b: number): number;
  subtract(a: number, b: number): number;
}

const calc: Calculator = {
  add(a, b) {
    return a + b;
  },
  subtract(a, b) {
    return a - b;
  }
};

Property Syntax

interface Calculator {
  add: (a: number, b: number) => number;
  subtract: (a: number, b: number) => number;
}

// Same implementation
const calc: Calculator = {
  add: (a, b) => a + b,
  subtract: (a, b) => a - b
};

Both are valid, but I prefer method syntax for consistency:

interface Logger {
  log(message: string): void;
  error(message: string, error?: Error): void;
  warn(message: string): void;
  debug(message: string): void;
}

class ConsoleLogger implements Logger {
  log(message: string): void {
    console.log(`[INFO] ${message}`);
  }
  
  error(message: string, error?: Error): void {
    console.error(`[ERROR] ${message}`, error);
  }
  
  warn(message: string): void {
    console.warn(`[WARN] ${message}`);
  }
  
  debug(message: string): void {
    console.debug(`[DEBUG] ${message}`);
  }
}

---

Hybrid Types

Objects that act as both a function and an object.

interface Counter {
  (start: number): string;
  interval: number;
  reset(): void;
}

function getCounter(): Counter {
  const counter = function(start: number) {
    return `Count: ${start}`;
  } as Counter;
  
  counter.interval = 1000;
  counter.reset = function() {
    console.log('Counter reset');
  };
  
  return counter;
}

const c = getCounter();
c(10);          // "Count: 10"
c.interval;     // 1000
c.reset();      // "Counter reset"

Honestly? I rarely use this pattern. It's more common in library code.

---

Real-World Example: API Response Types

Here's how I structure a real REST API with TypeScript:

// Base response wrapper
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: unknown;
  };
  metadata: {
    timestamp: Date;
    requestId: string;
  };
}

// User domain
interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  role: UserRole;
  createdAt: Date;
  lastLogin?: Date;
}

type UserRole = 'admin' | 'user' | 'guest';

interface UserListResponse {
  users: User[];
  pagination: {
    page: number;
    pageSize: number;
    total: number;
    hasMore: boolean;
  };
}

// API functions with proper types
async function getUser(id: string): Promise<ApiResponse<User>> {
  try {
    const response = await fetch(`/api/users/${id}`);
    const data = await response.json();
    
    return {
      success: true,
      data: data as User,
      metadata: {
        timestamp: new Date(),
        requestId: generateRequestId()
      }
    };
  } catch (error) {
    return {
      success: false,
      error: {
        code: 'USER_FETCH_ERROR',
        message: 'Failed to fetch user',
        details: error
      },
      metadata: {
        timestamp: new Date(),
        requestId: generateRequestId()
      }
    };
  }
}

async function listUsers(
  page: number,
  pageSize: number
): Promise<ApiResponse<UserListResponse>> {
  // Implementation with proper typing
  // ...
}

// Type-safe usage
async function displayUser(userId: string) {
  const response = await getUser(userId);
  
  if (response.success && response.data) {
    const user = response.data;  // TypeScript knows this is User
    console.log(`${user.firstName} ${user.lastName}`);
    console.log(`Email: ${user.email}`);
    console.log(`Role: ${user.role}`);
  } else if (response.error) {
    console.error(`Error: ${response.error.message}`);
  }
}

---

Practical Patterns from Production

1. Discriminated Unions with Interfaces

interface LoadingState {
  status: 'loading';
}

interface SuccessState<T> {
  status: 'success';
  data: T;
}

interface ErrorState {
  status: 'error';
  error: string;
}

type AsyncState<T> = LoadingState | SuccessState<T> | ErrorState;

function renderUser(state: AsyncState<User>) {
  switch (state.status) {
    case 'loading':
      return 'Loading...';
    case 'success':
      return `User: ${state.data.firstName}`;  // TypeScript knows data exists
    case 'error':
      return `Error: ${state.error}`;
  }
}

2. Builder Pattern

interface UserBuilder {
  setEmail(email: string): UserBuilder;
  setName(firstName: string, lastName: string): UserBuilder;
  setRole(role: UserRole): UserBuilder;
  build(): User;
}

class UserBuilderImpl implements UserBuilder {
  private user: Partial<User> = {
    id: generateId()
  };
  
  setEmail(email: string): UserBuilder {
    this.user.email = email;
    return this;
  }
  
  setName(firstName: string, lastName: string): UserBuilder {
    this.user.firstName = firstName;
    this.user.lastName = lastName;
    return this;
  }
  
  setRole(role: UserRole): UserBuilder {
    this.user.role = role;
    return this;
  }
  
  build(): User {
    if (!this.user.email || !this.user.firstName || !this.user.lastName) {
      throw new Error('Missing required fields');
    }
    
    return {
      id: this.user.id!,
      email: this.user.email,
      firstName: this.user.firstName,
      lastName: this.user.lastName,
      role: this.user.role || 'user',
      createdAt: new Date()
    };
  }
}

// Usage
const user = new UserBuilderImpl()
  .setEmail('[email protected]')
  .setName('John', 'Doe')
  .setRole('admin')
  .build();

3. Configuration Pattern

interface DatabaseConfig {
  readonly host: string;
  readonly port: number;
  readonly database: string;
  readonly user: string;
  readonly password: string;
}

interface CacheConfig {
  readonly host: string;
  readonly port: number;
  readonly ttl: number;
}

interface AppConfig {
  readonly env: 'development' | 'staging' | 'production';
  readonly port: number;
  readonly database: DatabaseConfig;
  readonly cache: CacheConfig;
  readonly features: {
    [key: string]: boolean;
  };
}

// Type-safe config loading
function loadConfig(): AppConfig {
  return {
    env: (process.env.NODE_ENV as AppConfig['env']) || 'development',
    port: parseInt(process.env.PORT || '3000'),
    database: {
      host: process.env.DB_HOST || 'localhost',
      port: parseInt(process.env.DB_PORT || '5432'),
      database: process.env.DB_NAME || 'myapp',
      user: process.env.DB_USER || 'postgres',
      password: process.env.DB_PASSWORD || ''
    },
    cache: {
      host: process.env.REDIS_HOST || 'localhost',
      port: parseInt(process.env.REDIS_PORT || '6379'),
      ttl: parseInt(process.env.CACHE_TTL || '3600')
    },
    features: {
      newDashboard: process.env.FEATURE_NEW_DASHBOARD === 'true',
      betaApi: process.env.FEATURE_BETA_API === 'true'
    }
  };
}

---

Common Mistakes I Made

1. Over-Nesting

Bad:

interface User {
  profile: {
    personal: {
      name: {
        first: string;
        last: string;
      };
    };
  };
}

// Annoying to use
user.profile.personal.name.first;

Good:

interface User {
  firstName: string;
  lastName: string;
  email: string;
}

// Much cleaner
user.firstName;

2. Using any in Interfaces

Bad:

interface ApiResponse {
  data: any;  // Lost all type safety!
}

Good:

interface ApiResponse<T> {
  data: T;  // Preserve type information
}

type UserResponse = ApiResponse<User>;
type ProductResponse = ApiResponse<Product>;

3. Not Using Optional Properties

Bad:

interface User {
  id: string;
  email: string;
  phoneNumber: string;  // Required, but not all users have phones
}

// Have to provide fake data
const user: User = {
  id: '1',
  email: '[email protected]',
  phoneNumber: ''  // Hack!
};

Good:

interface User {
  id: string;
  email: string;
  phoneNumber?: string;  // Optional
}

const user: User = {
  id: '1',
  email: '[email protected]'
  // No phoneNumber needed
};

---

Your Challenge

Build a type-safe task management system:

// TODO: Define these interfaces

interface Task {
  // id, title, description, status, priority, assignee, createdAt, dueDate
}

interface User {
  // id, name, email, role
}

interface Project {
  // id, name, tasks, members
}

// TODO: Implement these functions with proper types

function createTask(data: /* ... */): Task {
  // Validate and create task
}

function assignTask(taskId: string, userId: string): Task {
  // Assign task to user
}

function getTasksByStatus(status: /* ... */): Task[] {
  // Filter tasks by status
}

function getProjectProgress(projectId: string): {
  total: number;
  completed: number;
  inProgress: number;
  percentage: number;
} {
  // Calculate project progress
}

// Requirements:
// 1. Use interfaces for all domain objects
// 2. Use type aliases for unions (status, priority)
// 3. Use optional properties where appropriate
// 4. Use readonly for immutable fields
// 5. Provide type-safe function signatures

---

Key Takeaways

1. Interfaces define contracts - explicit shape of objects

2. Optional properties with ? - not all fields required

3. Readonly properties - prevent modification after creation

4. Interfaces extend - build complex types from simple ones

5. Type aliases - unions, tuples, complex types

6. Index signatures - dynamic property names

7. Interfaces vs Types - use interfaces for objects, types for everything else

8. Generic interfaces - reusable type-safe structures

---

What I Learned

Before TypeScript, my API contracts were implicit. Documentation (when it existed) was always out of sync. The mobile team would discover field changes in production.

After adopting interfaces:

• 43 bugs caught during compilation

• Zero field mismatch incidents in 6 months

• API documentation generated from types

• Confidence in refactoring - compiler validates everything

The Thursday afternoon incident taught me: types are communication. Interfaces aren't just for the compiler - they're documentation, contracts, and team agreements rolled into one.

When I write:

interface UserResponse {
  user: User;
  metadata: ResponseMetadata;
}

I'm not just helping TypeScript. I'm telling my team, the mobile developers, future maintainers, and my future self: this is exactly what you'll get.

No surprises. No runtime detective work. Just clear, explicit contracts.

Interfaces made my code boring. And boring code doesn't break at 3 AM.

---

Next: Functions in TypeScript

In the next article, we'll explore TypeScript's powerful function typing system. You'll learn how function signatures prevented a critical authentication bug in my production app.