What is the difference between the return types `void`, `undefined`, and `never`?

`void` means the function's return value is irrelevant (can be ignored). `undefined` requires an explicit return of `undefined`. `never` guarantees that the function will never complete normally (it will throw an exception or enter an infinite loop).

How do you type an asynchronous function that returns nothing?

With the type `Promise `. Any async function always wraps its result in a promise, so returning a simple `void` without `Promise` is a syntax error.

How does Contextual Typing infer the types of callback parameters?

The compiler examines the location where the function is passed. If a function is passed to a parameter with the type `(item: string) => void`, then the callback argument `arr.forEach(x => ...)` automatically receives the type `string` without explicitly specifying `x: string`.

Can you type the `this` parameter within a function?

Yes. In TypeScript, you can declare a fictitious first parameter `this`: `function handleClick(this: HTMLButtonElement, event: Event) { this.disabled = true; }`. This parameter is completely removed during compilation and is only used for verifying the call context.

Why are function parameters checked contravariantly?

Because the caller passes arguments to the function. If a function expects a base type (e.g., `Entity`), it is safe to pass a function that can handle any supertype. However, you cannot pass a function that requires a specific subtype (`User`), as accessing `User` properties would lead to a runtime error.

How do Function Overloads differ from Conditional Types in functions?

Overloads are useful for discrete, well-defined usage scenarios and provide clearer IDE hints. Conditional types based on generics (`T extends string ? A : B`) are preferred when the return type inference logic continuously depends on the argument type.

Function Typing, Promises, Callbacks, and Signatures — TypeScript 5.8+ Mastery

Architectural Foundation#

Functions in TypeScript are First-Class Citizens. They can be passed as arguments, returned from other functions, and assigned to variables.

Function typing represents a formal mathematical contract: f: (A1, A2, ...An) -> R The contract defines a set of input parameters and a guarantee of the return value's type.

Unlike many statically typed languages, functions in TypeScript have unique properties:

Parameter Contravariance: Function parameters are matched strictly contravariantly when the strictFunctionTypes flag is enabled.
Return Covariance: The return value is checked covariantly (a function returning a subtype is compatible with code expecting a supertype).
No-Value Semantics (void vs undefined vs never): The distinction between functions with no useful result, returning undefined, and functions that never return control (infinite loops, throwing exceptions).
Function Overloads: Declaring multiple public signatures for a single internal implementation function.

Mental Model#

Let's look at the differences between void, undefined, and never:

text

+-------------------------------------------------------------------------+
|                  RETURN SEMANTICS: VOID vs UNDEFINED vs NEVER         |
+-------------------------------------------------------------------------+
| void:                                                                   |
|   "I don't care about the result." The function performs a side effect. |
|   In JS, it returns undefined, but TypeScript allows callbacks to return |
|   any value, ignoring it on the caller's side.                         |
+-------------------------------------------------------------------------+
| undefined:                                                              |
|   "The function explicitly returns the value undefined."                |
|   Requires `return undefined` or an empty `return`.                     |
+-------------------------------------------------------------------------+
| never:                                                                  |
|   "The function will NEVER complete normally."                          |
|   Either throws an error (`throw new Error()`) or gets stuck in a `while` loop.|
+-------------------------------------------------------------------------+

Call Signature
Function Overload
Rest Parameters
Contextual Typing

Function Signature Matching Pipeline#

How the TypeScript Compiler Matches Function Signatures

1. Argument Count Check

The calling function can pass fewer arguments than declared, but not more than required (arity check).

2. Contravariant Parameter Check

Each parameter of the target function must safely accept the type of the corresponding argument from the source function.

3. Covariant Return Check

The return type of the source function must be a subtype of the declared return type of the target signature.

4. Overload Resolution

The compiler checks call arguments against overloads from top to bottom until the first complete match is found.

CHECKPOINT #1

Understanding Check: void Semantics in Callbacks

+15 XP

Why does the compiler allow the code `const fn: () => void = () => 42;` to pass type checking successfully, even though the arrow function returns a number?

In Practice#

UI Event Handlers (React / DOM): Strict typing of event parameters (event: React.MouseEvent<HTMLButtonElement>) => void.
Asynchronous Contracts and Promises: Explicitly specifying the promise type async function fetchEntity(): Promise<Entity> to protect against implicit Promise<unknown>.
Overload Pattern in SDKs and Utilities: Creating ergonomic APIs that return different types depending on the argument format (readFile(path, 'utf-8'): string vs readFile(path): Buffer).
Higher-Order Function Pipelines (Currying / Middleware): Typing function composers that pass the result of a previous call as input to the next.

How It Works#

1. Declaring Signatures: Arrow Types vs. Call Signatures in Objects#

A function signature can be declared as an arrow type or within an interface body:

typescriptFunctional Type Declaration

// 1. Arrow type alias:
type FormValidator = (value: string, minLength?: number) => boolean;

// 2. Object type with a Call Signature:
interface Logger {
  // Call Signature
  (message: string, level?: 'info' | 'warn' | 'error'): void;
  // Static property attached to the function
  defaultLevel: 'info' | 'warn' | 'error';
}

const consoleLogger: Logger = Object.assign(
  (msg: string, level: 'info' | 'warn' | 'error' = 'info') => {
    console.log(`[${level.toUpperCase()}] ${msg}`);
  },
  { defaultLevel: 'info' as const }
);

2. Function Overloads#

An overload consists of one or more overload signatures (without a body) and a single implementation signature (with a body):

typescriptCorrect Function Overload Implementation

// Public overloads (visible to API consumers)
function formatTimestamp(timestamp: number): string;
function formatTimestamp(date: Date, locale: string): string;

// Implementation signature (NOT directly visible to consumers!)
function formatTimestamp(arg1: number | Date, arg2?: string): string {
  if (typeof arg1 === 'number') {
    return new Date(arg1).toISOString();
  }
  return arg1.toLocaleDateString(arg2 ?? 'en-US');
}

// Correct calls:
formatTimestamp(1728000000000); // OK
formatTimestamp(new Date(), 'ru-RU'); // OK

// ERROR: The compiler only checks against public overloads, not the implementation!
// formatTimestamp(new Date()); // TS2554: Expected 2 arguments, but got 1.

3. Optional Parameters and Default Values#

Optional parameters (param?: Type) must strictly follow required parameters:

typescriptFunction Parameters and Rest Tuples

// Default parameters automatically make the parameter optional
function createRequest(
  url: string,
  timeoutMs: number = 5000,
  headers?: Record<string, string>
) {
  return { url, timeoutMs, headers: headers ?? {} };
}

// Typed Rest parameters using tuples:
type LogArgs = [code: number, message: string, ...details: unknown[]];

function emitAuditLog(...args: LogArgs): void {
  const [code, message, ...details] = args;
  console.log(`Audit #${code}: ${message}`, details);
}

emitAuditLog(403, 'Forbidden', { ip: '127.0.0.1' }); // Correct

CHECKPOINT #2

Understanding Check: Implementation Signature in Overloads

+15 XP

Why can't calling code invoke a function with arguments that match the implementation signature if that combination is not present in the public overloads?

Common Mistakes#

Ошибка: Overload Order: From General to Specific

TypeScript matches overloads from top to bottom. If a broader signature is placed first, it will intercept all calls:

typescript

// ERROR: The first overload will block the second!
function get(url: string): unknown;
function get(url: 'https://api.wpskills.dev'): SpecificResponse;

// CORRECT: Place specific signatures FIRST, and broader ones last!
function get(url: 'https://api.wpskills.dev'): SpecificResponse;
function get(url: string): unknown;

Ошибка: Confusion Between void and never in Functions

Declaring a function with never if it completes normally:

typescript

// ERROR: TS2534: A function returning 'never' cannot have a reachable end point.
function logError(msg: string): never {
  console.error(msg);
  // No throw or while(true)!
}

Use void for functions that perform a side effect.

Interview: Questions and Answers#

Interview Questions6 questions