Learning Objectives

By the end of this lesson, you should understand:

Basic TypeScript types and type annotations
Interfaces and Type aliases
Generics basics
TypeScript with React/Next.js

Philosophy

This is a brief introduction to TypeScript. You'll learn more as we build the project together. The best way to learn TypeScript is by using it in real applications.

1. Why TypeScript?

TypeScript adds static typing to JavaScript, which helps:

Catch errors early - Find bugs at compile time, not runtime
Better IDE support - Autocomplete, refactoring, go-to-definition
Self-documenting code - Types serve as documentation
Safer refactoring - Change with confidence

The following example demonstrates how TypeScript catches potential errors before your code runs, unlike plain JavaScript where such issues would only surface at runtime.

// JavaScript - No error until runtime
function getUser(id) {
  return fetch(`/api/users/${id}`); // What if id is undefined?
}

// TypeScript - Error at compile time
function getUser(id: number): Promise<User> {
  return fetch(`/api/users/${id}`).then(res => res.json());
}

2. Basic Types

TypeScript provides type annotations to define what kind of values variables can hold. These annotations help catch type-related errors early and improve code documentation.

Primitive Types

The most fundamental types in TypeScript mirror JavaScript's primitive values. You specify a type by adding a colon and the type name after the variable name.

// String
const name: string = 'John';

// Number
const age: number = 25;
const price: number = 99.99;

// Boolean
const isActive: boolean = true;

// Null and Undefined
const empty: null = null;
const notDefined: undefined = undefined;

Arrays

Arrays can be typed to contain only specific types of elements. You can use the square bracket syntax or the generic Array syntax to define array types.

// Array of strings
const names: string[] = ['John', 'Jane', 'Bob'];

// Array of numbers
const prices: number[] = [10, 20, 30];

// Alternative syntax
const ids: Array<number> = [1, 2, 3];

// Mixed types (avoid if possible)
const mixed: (string | number)[] = ['hello', 42];

Objects

Object types define the structure of an object, specifying what properties it should have and their types. You can mark properties as optional using the question mark syntax.

// Inline object type
const user: { name: string; age: number } = {
  name: 'John',
  age: 25
};

// Optional properties
const config: { debug?: boolean; timeout: number } = {
  timeout: 5000
  // debug is optional
};

3. Type Inference

TypeScript is smart enough to automatically determine types based on the values you assign. This feature, called type inference, lets you write less code while still getting type safety.

// TypeScript infers: string
const message = 'Hello';

// TypeScript infers: number
const count = 42;

// TypeScript infers: boolean
const isValid = true;

// TypeScript infers: string[]
const fruits = ['apple', 'banana', 'orange'];

// TypeScript infers the return type
function add(a: number, b: number) {
  return a + b; // Inferred return type: number
}

Rule of thumb: Let TypeScript infer when it can, annotate when it can't or for clarity.

4. Interfaces

Interfaces are a powerful way to define the shape of objects. They provide a contract that objects must follow, making your code more predictable and easier to understand.

Interfaces define the shape of objects:

// Define an interface
interface User {
  id: number;
  name: string;
  email: string;
  phone?: string;        // Optional property
  readonly createdAt: Date;  // Can't be modified
}

// Use the interface
const user: User = {
  id: 1,
  name: 'John Doe',
  email: 'john@example.com',
  createdAt: new Date()
};

// Function with interface parameter
function displayUser(user: User) {
  console.log(`${user.name} (${user.email})`);
}

Extending Interfaces

Interfaces can extend other interfaces to inherit their properties. This promotes code reuse and helps create hierarchical type structures for related entities.

interface BaseEntity {
  id: number;
  createdAt: Date;
  updatedAt: Date;
}

interface User extends BaseEntity {
  name: string;
  email: string;
}

interface Transaction extends BaseEntity {
  amount: number;
  type: 'credit' | 'debit';
  userId: number;
}

5. Type Aliases

Type aliases create custom type names that can represent primitives, unions, objects, or functions. They provide flexibility for types that interfaces cannot express, such as union types.

// Simple alias
type ID = number | string;

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

// Union type
type Status = 'pending' | 'completed' | 'failed';

// Function type
type Formatter = (value: number) => string;

// Using type aliases
const userId: ID = 123;
const status: Status = 'pending';

const formatCurrency: Formatter = (value) => `₦${value.toLocaleString()}`;

Interface vs Type

Both interfaces and types can define object shapes, but they have different capabilities. Understanding when to use each helps you write more maintainable code.

// Both can define object shapes
interface UserInterface {
  name: string;
}

type UserType = {
  name: string;
};

// Interfaces can be extended/merged
interface UserInterface {
  email: string; // This merges with above
}

// Types are more flexible
type StringOrNumber = string | number;
type Callback = () => void;

When to use which:

Use interface for object shapes (especially public APIs)
Use type for unions, primitives, tuples, and complex types

6. Union and Intersection Types

Union and intersection types let you combine types in different ways. Unions represent values that can be one of several types, while intersections combine multiple types into one.

Union Types (OR)

Union types use the pipe symbol to indicate a value can be one of several types. They are particularly useful for representing different states or variations of data.

// Can be either type
type ID = string | number;

// Common pattern: different states
type LoadingState =
  | { status: 'loading' }
  | { status: 'success'; data: User[] }
  | { status: 'error'; error: string };

function handleState(state: LoadingState) {
  switch (state.status) {
    case 'loading':
      return 'Loading...';
    case 'success':
      return state.data.map(u => u.name);
    case 'error':
      return `Error: ${state.error}`;
  }
}

Intersection Types (AND)

Intersection types combine multiple types into one, requiring the resulting type to have all properties from each constituent type.

type HasId = { id: number };
type HasName = { name: string };

// Must have both id AND name
type Entity = HasId & HasName;

const entity: Entity = {
  id: 1,
  name: 'Test'
};

7. Functions

TypeScript allows you to specify types for function parameters and return values. This ensures functions are called correctly and return the expected types.

// Parameter and return types
function add(a: number, b: number): number {
  return a + b;
}

// Arrow function
const multiply = (a: number, b: number): number => a * b;

// Optional parameters
function greet(name: string, greeting?: string): string {
  return `${greeting || 'Hello'}, ${name}!`;
}

// Default parameters
function createUser(name: string, role: string = 'user'): User {
  return { name, role };
}

// Rest parameters
function sum(...numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

// Function type
type MathOperation = (a: number, b: number) => number;

const divide: MathOperation = (a, b) => a / b;

Async Functions

Async functions return Promises, which TypeScript handles with the Promise generic type. This ensures you properly handle the asynchronous nature of these functions.

// Async function returns Promise
async function fetchUser(id: number): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

// Or with explicit Promise type
function fetchUsers(): Promise<User[]> {
  return fetch('/api/users').then(res => res.json());
}

8. Generics

Generics allow you to write reusable code that works with multiple types while maintaining type safety. They act as type variables that get filled in when the function or type is used.

// Generic function
function identity<T>(value: T): T {
  return value;
}

const num = identity(42);        // type: number
const str = identity('hello');   // type: string

// Generic array wrapper
function first<T>(array: T[]): T | undefined {
  return array[0];
}

const firstNum = first([1, 2, 3]);        // type: number | undefined
const firstStr = first(['a', 'b', 'c']);  // type: string | undefined

Generic Interfaces

Generic interfaces let you create reusable type structures that can work with different data types. They are commonly used for API responses, collections, and wrapper types.

// Generic response wrapper
interface ApiResponse<T> {
  data: T;
  success: boolean;
  message?: string;
}

// Usage
type UserResponse = ApiResponse<User>;
type UsersResponse = ApiResponse<User[]>;

// Function using generic interface
async function fetchData<T>(url: string): Promise<ApiResponse<T>> {
  const response = await fetch(url);
  const data = await response.json();
  return { data, success: true };
}

const userResponse = await fetchData<User>('/api/user/1');

9. TypeScript with React

TypeScript integrates seamlessly with React, providing type safety for props, state, and event handlers. This section covers the most common patterns you will use in Next.js applications.

Component Props

Defining props interfaces ensures components receive the correct data types. Optional props, default values, and union types for variants make your components self-documenting.

// Define props interface
interface ButtonProps {
  children: React.ReactNode;
  variant?: 'primary' | 'secondary' | 'danger';
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
  onClick?: () => void;
}

// Function component with typed props
const Button = ({
  children,
  variant = 'primary',
  size = 'medium',
  disabled = false,
  onClick
}: ButtonProps) => {
  return (
    <button
      className={`btn btn-${variant} btn-${size}`}
      disabled={disabled}
      onClick={onClick}
    >
      {children}
    </button>
  );
};

useState with Types

The useState hook can infer types from initial values, but you can also provide explicit types using generics. This is especially useful for nullable values or complex state shapes.

import { useState } from 'react';

// Type is inferred
const [count, setCount] = useState(0);

// Explicit type for complex state
const [user, setUser] = useState<User | null>(null);

// Array of specific type
const [items, setItems] = useState<string[]>([]);

// Object state
interface FormData {
  name: string;
  email: string;
}

const [form, setForm] = useState<FormData>({
  name: '',
  email: ''
});

Event Handlers

React provides specific event types for different DOM events. Using these types ensures you have access to the correct properties and methods on the event object.

import { useState, ChangeEvent, FormEvent } from 'react';

const Form = () => {
  const [email, setEmail] = useState('');

  // Input change event
  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
    setEmail(e.target.value);
  };

  // Form submit event
  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    console.log('Submitted:', email);
  };

  // Button click event
  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    console.log('Clicked');
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" value={email} onChange={handleChange} />
      <button type="submit" onClick={handleClick}>Submit</button>
    </form>
  );
};

10. Common Patterns for Next.js

These patterns are frequently used throughout Next.js applications. Familiarizing yourself with them will make building the bill payment platform much smoother.

API Response Types

Creating consistent response types ensures your API endpoints return predictable data structures. Generic types make it easy to wrap different data types in the same response format.

// types/api.ts
export interface ApiError {
  message: string;
  code?: string;
}

export interface PaginatedResponse<T> {
  data: T[];
  total: number;
  page: number;
  pageSize: number;
  hasMore: boolean;
}

export interface Transaction {
  id: string;
  type: 'airtime' | 'data' | 'electricity' | 'cable';
  amount: number;
  status: 'pending' | 'completed' | 'failed';
  createdAt: string;
}

// Usage in component
const [transactions, setTransactions] = useState<Transaction[]>([]);

Server Action Types

Server actions use a specific pattern with form state and FormData. Defining these types ensures proper handling of form submissions and validation errors.

// Form state type
interface FormState {
  success: boolean;
  message: string;
  errors?: Record<string, string[]>;
}

// Server action
async function createTransaction(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  // Implementation
  return { success: true, message: 'Transaction created' };
}

Props with Children

The children prop is typed as React.ReactNode, which accepts any valid React content. This pattern is essential for layout and wrapper components.

interface LayoutProps {
  children: React.ReactNode;
  title?: string;
}

const Layout = ({ children, title }: LayoutProps) => (
  <div>
    {title && <h1>{title}</h1>}
    <main>{children}</main>
  </div>
);

Quick Reference

This quick reference summarizes the most common TypeScript syntax you will use throughout this course. Keep it handy as you build your Next.js applications.

// Primitives
const str: string = 'hello';
const num: number = 42;
const bool: boolean = true;

// Arrays
const arr: number[] = [1, 2, 3];

// Objects
interface User { name: string; age: number; }

// Functions
const fn = (x: number): number => x * 2;

// Union
type Status = 'active' | 'inactive';

// Optional
interface Config { debug?: boolean; }

// Generic
function wrap<T>(value: T): { value: T } {
  return { value };
}

// React component
interface Props { title: string; }
const Component = ({ title }: Props) => <h1>{title}</h1>;

Assignment

Task: Type a Transaction System

Create a file types/transactions.ts with the following types:

This exercise will help you practice creating types that model real-world data. Consider what properties each type needs and how they relate to each other.

// 1. Define TransactionType
type TransactionType = // 'airtime' | 'data' | 'electricity' | 'cable'

// 2. Define TransactionStatus
type TransactionStatus = // 'pending' | 'processing' | 'completed' | 'failed'

// 3. Define Transaction interface
interface Transaction {
  // id, type, amount, status, phoneNumber (optional),
  // meterNumber (optional), createdAt, updatedAt
}

// 4. Define CreateTransactionInput (for creating new transactions)
interface CreateTransactionInput {
  // type, amount, phoneNumber?, meterNumber?
}

// 5. Define ApiResponse generic
interface ApiResponse<T> {
  // success, data, message?, errors?
}

// 6. Define a function type for transaction processing
type ProcessTransaction = (input: CreateTransactionInput) => Promise<ApiResponse<Transaction>>;

Then create a component that uses these types:

// components/TransactionForm.tsx
// Create a typed form component that:
// 1. Has typed props
// 2. Uses typed state
// 3. Has typed event handlers
// 4. Returns typed data

Additional Resources

Next Lesson: Development Environment Setup