Functions & Overloads

📞 Functions & Overloads

🔧 Function Typing Basics (Review)

Parameter Types and Return Types

Copyfunction greet(name: string): string {
  return `Hello, ${name}!`;
}

function add(a: number, b: number): number {
  return a + b;
}

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

// Optional parameters
function greetOptional(name: string, title?: string): string {
  return title ? `${title} ${name}` : name;
}

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

🎯 Function Overloads

The Pattern

Copy// Overload signatures (just the type, no body)
function describe(value: string): string;
function describe(value: number): string;

// Implementation (with union type to match all overloads)
function describe(value: string | number): string {
  if (typeof value === "string") {
    return `String: ${value}`;
  } else {
    return `Number: ${value.toFixed(2)}`;
  }
}

// Callers see the specific signatures
describe("hello");  // ✅ Matches first signature
describe(42);       // ✅ Matches second signature
describe(true);   // ❌ Error! No overload for boolean

Overloads with Different Return Types

Copy// Each overload can have a different return type
function process(input: string): string;
function process(input: number): number;
function process(input: boolean): boolean;

function process(input: string | number | boolean) {
  if (typeof input === "string") {
    return input.toUpperCase();
  } else if (typeof input === "number") {
    return input * 2;
  } else {
    return !input;
  }
}

const str: string = process("hello");  // TypeScript knows return is string
const num: number = process(5);      // TypeScript knows return is number
const bool: boolean = process(true);  // TypeScript knows return is boolean

Overloads with Optional Parameters

Copy// Different number of parameters
function createElement(tag: string): HTMLElement;
function createElement(tag: string, content: string): HTMLElement;
function createElement(tag: string, content: string, className: string): HTMLElement;

function createElement(
  tag: string,
  content?: string,
  className?: string
): HTMLElement {
  const el = document.createElement(tag);
  if (content) el.textContent = content;
  if (className) el.className = className;
  return el;
}

createElement("div");  // ✅ Just tag
createElement("div", "Hello");  // ✅ Tag + content
createElement("div", "Hello", "container");  // ✅ All three

🤔 Overloads vs Union Types

When should you use overloads instead of union types? Let's compare:

Copyfunction padString(
  value: string | number
): string {
  return String(value).padStart(10);
}

const result = padString(42);
// TypeScript doesn't know result is a string
// The caller loses type information!

Copyfunction padString(value: string): string;
function padString(value: number): string;

function padString(value: string | number) {
  return String(value).padStart(10);
}

const result = padString(42);
// TypeScript knows result is a string!
// Overloads preserve type information

When to Use Overloads

• Different return types — Based on input type, return type differs
• Different parameters — Accept different number of parameters
• Complex relationships — Type of parameter 2 depends on parameter 1
• API clarity — Make intent clear to callers

When NOT to Use Overloads

• Same behavior — If logic is identical, just use union types
• Simple cases — Optional parameters are often enough
• Too many overloads — More than 3-4 usually signals design problem

🚀 Advanced Overload Patterns

Overloads with Generics

Copy// Generic function with overloads
function getProperty<T>(obj: T, key: string): unknown;
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K];

function getProperty<T>(obj: T, key: string) {
  return obj[key as keyof T];
}

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

const user: User = { name: "Alice", age: 30 };

// ✅ TypeScript knows this returns a string
const name: string = getProperty(user, "name");

// ✅ TypeScript knows this returns a number
const age: number = getProperty(user, "age");

Overloads with Conditional Return Types

Copy// Using conditional types with overloads
function flatten<T>(arr: T[]): T[];
function flatten<T>(arr: T[][]): T[];

function flatten<T>(arr: T[] | T[][]): T[] {
  return arr.flat() as T[];
}

const single: string[] = flatten(["a", "b"]);
const double: number[] = flatten([[1, 2], [3, 4]]);

📋 Best Practices

Copyfunction parse(input: string): Record<string, unknown>;
function parse(input: Buffer): Uint8Array;

function parse(input: string | Buffer) {
  // implementation
}

Copy// ❌ Too many overloads - refactor instead
function process(input: string): string;
function process(input: number): number;
function process(input: boolean): boolean;
function process(input: Date): string;
function process(input: object): object;

💻 Coding Challenges

🌍 Real-World Example: Event Listener

Copy// Realistic addEventListener with proper typing
function addEventListener(
  element: HTMLElement,
  event: "click",
  handler: (e: MouseEvent) => void
): void;

function addEventListener(
  element: HTMLElement,
  event: "input",
  handler: (e: InputEvent) => void
): void;

function addEventListener(
  element: HTMLElement,
  event: "click" | "input",
  handler: (e: Event) => void
) {
  element.addEventListener(event, handler);
}

// Callers get proper type checking for each event
const button = document.querySelector("button")!;
const input = document.querySelector("input")!;

addEventListener(button, "click", (e: MouseEvent) => {
  // ✅ e is typed as MouseEvent
  console.log(e.clientX);
});

addEventListener(input, "input", (e: InputEvent) => {
  // ✅ e is typed as InputEvent
  console.log(e.data);
});

🎯 What's Next

We've mastered function overloads and learned when to use them. Chapter 9 covers Enums & Literal Types — how to create strongly-typed constants and restrict values to specific options.