SAE Logo

TypeScript Functions

Functions are fundamental building blocks in JavaScript and TypeScript. TypeScript enhances functions with optional static typing, helping you catch errors early and improve code quality. This guide will walk you through the essentials of TypeScript functions, from basic syntax to best practices.

Function Basics

©Net Ninja

Basic Function Syntax

Traditional function syntax using the function keyword, followed by the function name, parameter list with types, and return type annotation. The function body contains the implementation logic.

// Function with typed parameters and return type
function add(a: number, b: number): number {
  return a + b;
}

// Using the function
const sum = add(5, 3); // 8

The function add takes two parameters of type number and returns a value of type number. TypeScript ensures that you call this function with the correct parameter types.

Function Expressions

Functions assigned to variables using either the function keyword or arrow function syntax. These can be anonymous or named and require type annotations for parameters and optionally for return types.

// Function expression with type annotation
const multiply: (x: number, y: number) => number = function (x, y) {
  return x * y;
};

// Arrow function version (more concise)
const divide = (x: number, y: number): number => x / y;

Optional Parameters

Parameters marked with question marks ? can be omitted when calling the function. They must appear after required parameters and automatically include undefined in their type.

function greet(name: string, greeting?: string): string {
  if (greeting) {
    return `${greeting}, ${name}!`;
  }
  return `Hello, ${name}!`;
}

greet("Alice"); // "Hello, Alice!"
greet("Bob", "Welcome"); // "Welcome, Bob!"

Optional parameters must come after required parameters in the function signature.

Default Parameters

Parameters can have default values that are used when no argument is provided. The default value determines the parameter's type if no explicit annotation is given.

function createMessage(name: string, role: string = "user"): string {
  return `${name} is a ${role}`;
}

createMessage("Alice"); // "Alice is a user"
createMessage("Bob", "administrator"); // "Bob is a administrator"

Rest Parameters

Functions can accept variable numbers of arguments using rest parameter syntax with three dots. Rest parameters are typed as arrays and must be the last parameter.

function sum(...numbers: number[]): number {
  return numbers.reduce((total, n) => total + n, 0);
}

sum(1, 2); // 3
sum(1, 2, 3, 4, 5); // 15

Function Overloads

Multiple function signatures can be declared for the same function to support different parameter combinations, with the implementation signature handling all cases.

// Overload signatures
function formatValue(value: string): string;
function formatValue(value: number): string;
// Implementation signature
function formatValue(value: string | number): string {
  if (typeof value === "string") {
    return value.trim();
  }
  return value.toFixed(2);
}

formatValue("  hello  "); // "hello"
formatValue(3.14159); // "3.14"

Function overloads help you provide more specific type information to TypeScript when a function can handle different types of arguments.

Void Returns

Functions that don't return values explicitly return undefined, which is typically annotated as void to indicate no meaningful return value is expected.

function logMessage(message: string): void {
  console.log(message);
  // No return statement needed
}

Never Return Type

The never type indicates functions that never complete normally, either because they throw exceptions, run infinite loops, or terminate the program. This type helps TypeScript understand control flow and eliminates unreachable code warnings. Functions returning never signal to the type system that execution will not continue past that point.

function throwError(message: string): never {
  throw new Error(message);
}

function infiniteLoop(): never {
  while (true) {
    // Do something forever
  }
}

Function Types as Variables

Variables can hold function types, allowing functions to be assigned, passed as arguments, and returned from other functions. These variables require type annotations that specify the function signature including parameter types and return type. This enables functional programming patterns and callback-based APIs with full type safety.

// Define a function type
type MathOperation = (x: number, y: number) => number;

// Functions that match this type
const add: MathOperation = (a, b) => a + b;
const subtract: MathOperation = (a, b) => a - b;

// Function that takes a function as argument
function calculate(operation: MathOperation, a: number, b: number): number {
  return operation(a, b);
}

calculate(add, 5, 3); // 8
calculate(subtract, 10, 4); // 6

Object Method Syntax

Object types can define methods using either property syntax with function types or method syntax that looks like class methods. Method syntax provides cleaner notation for object-oriented designs while property syntax works better for functional approaches. Both approaches support overloads, optional methods, and generic parameters.

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

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

calculator.add(5, 3); // 8
calculator.subtract(10, 4); // 6

Contextual Typing

TypeScript infers function parameter and return types based on how the function is used, reducing the need for explicit annotations. This occurs when functions are assigned to typed variables, passed as arguments to typed parameters, or used in contexts where the expected signature is known. Contextual typing makes code cleaner while maintaining type safety.

// The array's forEach method provides type context
const numbers = [1, 2, 3, 4, 5];

// TypeScript knows 'num' is a number from context
numbers.forEach((num) => {
  console.log(num.toFixed(2));
});

Type Guards

Type guards are functions that perform runtime checks and inform TypeScript's type system about the narrowed type within conditional blocks. They return boolean values but use special return type syntax that tells TypeScript how to refine types.

Type guards enable safe type narrowing for union types, unknown values, and complex type checking scenarios where TypeScript cannot automatically determine the specific type.

function isString(value: any): value is string {
  return typeof value === "string";
}

function processValue(value: string | number) {
  if (isString(value)) {
    // TypeScript knows value is a string here
    console.log(value.toUpperCase());
  } else {
    // TypeScript knows value is a number here
    console.log(value.toFixed(2));
  }
}

Real-World Examples

Here are some examples of how to use TypeScript functions in common scenarios:

Event Handlers

// Event handler function typed with TypeScript
function handleClick(event: MouseEvent): void {
  console.log("Button clicked at:", event.clientX, event.clientY);
  event.preventDefault();
}

// Adding an event listener
document.querySelector("button")?.addEventListener("click", handleClick);

Async Functions

// Async function with TypeScript types
async function fetchUserData(userId: string): Promise<User> {
  const response = await fetch(`/api/users/${userId}`);

  if (!response.ok) {
    throw new Error(`Failed to fetch user: ${response.statusText}`);
  }

  return response.json();
}

// Using the async function
interface User {
  id: string;
  name: string;
  email: string;
}

async function displayUser(userId: string): Promise<void> {
  try {
    const user = await fetchUserData(userId);
    console.log(`User: ${user.name} (${user.email})`);
  } catch (error) {
    console.error("Error:", error);
  }
}

Callback Patterns

// Function with a callback parameter
function processData(data: string[], callback: (item: string, index: number) => void): void {
  data.forEach((item, index) => {
    callback(item, index);
  });
}

// Using the function with a callback
const items = ["apple", "banana", "cherry"];
processData(items, (item, index) => {
  console.log(`Item ${index + 1}: ${item}`);
});

Best Practices for TypeScript Functions

1. Always specify return types

Explicit return types serve as documentation and prevent accidental changes to function contracts. They catch errors when refactoring and make function signatures self-documenting. While TypeScript can infer return types, explicit annotations communicate intent and create a contract that the compiler enforces.

// Good: Explicit return type
function calculateArea(radius: number): number {
  return Math.PI * radius * radius;
}

// Avoid: Implicit return type
function calculateArea(radius: number) {
  return Math.PI * radius * radius;
}

2. Use function declarations for regular functions

Function declarations are hoisted, making them available throughout their scope regardless of declaration order. They're more readable for standard functions and clearly separate function definitions from variable assignments. This approach works well for main application logic and utility functions.

// Good: Function declaration
function createGreeting(name: string): string {
  return `Hello, ${name}!`;
}

// Less preferable for simple functions
const createGreeting = (name: string): string => {
  return `Hello, ${name}!`;
};

3. Use arrow functions for callbacks and short functions

Arrow functions provide lexical this binding, eliminating common context issues in callbacks. They're more concise for simple operations and functional programming patterns. Arrow functions work particularly well for array methods, event handlers, and any scenario where maintaining the surrounding context is important.

// Good: Arrow function for callback
[1, 2, 3].map((n: number): number => n * 2);

// Good: Arrow function for short operations
const double = (n: number): number => n * 2;

4. Prefer union types over overloads when possible

Union types are simpler to understand and maintain compared to function overloads. They create cleaner function signatures for straightforward cases where a function can accept multiple types but handles them similarly. Reserve overloads for complex scenarios where different parameter combinations require fundamentally different return types.

// Good: Union type
function formatValue(value: string | number): string {
  if (typeof value === "string") {
    return value.trim();
  }
  return value.toFixed(2);
}

// More complex but sometimes necessary: Overloads
function formatValue(value: string): string;
function formatValue(value: number): string;
function formatValue(value: string | number): string {
  // Implementation
}

5. Use default parameters instead of conditionals

Default parameters make function signatures more expressive and eliminate boilerplate code inside function bodies. They clearly communicate optional behavior and reduce cognitive load by handling common cases automatically. This approach creates cleaner APIs and reduces the chance of errors from manual conditional logic.

// Good: Default parameter
function createUser(name: string, role: string = "user"): User {
  return { name, role };
}

// Avoid: Conditional inside function
function createUser(name: string, role?: string): User {
  return { name, role: role || "user" };
}

6. Keep functions focused

Single-responsibility functions are easier to test, debug, and reuse. They promote modular design and make code more maintainable by isolating concerns. Focused functions also make type definitions simpler and reduce the complexity of both implementation and usage.

// Good: Two focused functions
function validateUser(user: User): boolean {
  // Only handle validation logic
}

function saveUser(user: User): void {
  // Only handle saving logic
}

// Avoid: One function doing multiple things
function validateAndSaveUser(user: User): boolean {
  // Handles both validation and saving
}

7. Document functions with JSDoc comments

JSDoc comments provide context that type annotations cannot express, including business rules, usage examples, and parameter constraints. They improve IDE experience through better tooltips and help other developers understand function purpose and proper usage patterns.

/**
 * Calculates the distance between two points
 * @param {Point} point1 - The first point
 * @param {Point} point2 - The second point
 * @returns {number} The distance between the points
 */
function calculateDistance(point1: Point, point2: Point): number {
  const dx = point2.x - point1.x;
  const dy = point2.y - point1.y;
  return Math.sqrt(dx * dx + dy * dy);
}

Exercises

Exercise 1: Basic Function Types

Create a function called calculateTax that takes an amount (number) and a tax rate (number) and returns the tax amount. Use proper TypeScript type annotations.

Exercise 2: Function with Optional Parameters

Create a function called buildProfile that takes a person's name (required), age (required), and occupation (optional). The function should return a formatted string with the person's information.

Exercise 3: Function Types and Callbacks

Create a function processNumbers that takes an array of numbers and a callback function. The callback should receive a number and return a number. The processNumbers function should apply the callback to each number in the array and return a new array with the results.

Summary

TypeScript functions enhance JavaScript functions with static typing, making your code more robust and maintainable. Key points covered in this guide include:

  1. Basic Syntax: TypeScript allows you to specify parameter types and return types for functions.

  2. Optional and Default Parameters: Make parameters optional with ? or provide default values with =.

  3. Rest Parameters: Handle variable numbers of arguments with rest parameters (...args).

  4. Function Types: Define and reuse function type signatures for consistent typing.

  5. Type Guards: Create functions that help TypeScript narrow down types in conditional blocks.

  6. Best Practices:

    • Always specify return types

    • Use function declarations for regular functions

    • Use arrow functions for callbacks

    • Keep functions focused on a single responsibility

    • Document functions with JSDoc comments

By applying these principles, you can write TypeScript functions that are more reliable, easier to understand, and simpler to maintain.

© 2025, SAE Academy