TypeScript Function: Parameter and Return Types, void

A TypeScript function is a JavaScript function with types on its parameters and, optionally, on its return value. Every parameter gets an annotation, the return type goes after the parameter list, and the compiler checks every call against both.

function area(width: number, height: number): number {
  return width * height;
}

console.log(area(3, 4)); // 12

// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
area("3", 4);

// @ts-expect-error: Expected 2 arguments, but got 1.
area(3);

Both bad calls are compile-time errors (TS2345 and TS2554). The // @ts-expect-error comments tell the compiler that an error is expected on the next line, so the rest of the file still runs. Remove one of them and run again to see the real message.

Parameter Types

Each parameter is written name: Type. Under strict, which is on by default in TypeScript 7, a parameter with no annotation and no context to infer from is an error: Parameter 'x' implicitly has an 'any' type. (TS7006). So in practice every parameter of a standalone function is annotated.

Any type works as a parameter type: primitives, arrays, object types, unions, other functions.

type User = { name: string; tags: string[] };

function describe(user: User, maxTags: number): string {
  const shown = user.tags.slice(0, maxTags).join(", ");
  return `${user.name} (${shown})`;
}

function formatId(id: string | number): string {
  return typeof id === "number" ? id.toFixed(0).padStart(5, "0") : id.toUpperCase();
}

console.log(describe({ name: "Ada", tags: ["math", "code", "tea"] }, 2)); // Ada (math, code)
console.log(formatId(42));      // 00042
console.log(formatId("ab-7"));  // AB-7

TypeScript checks the number of arguments too. Passing more or fewer than the function declares is an error, unlike plain JavaScript, which fills missing ones with undefined and ignores extras. To make a parameter optional or give it a default, see optional parameters.

Return Types: Annotate or Infer

The return type follows the closing parenthesis: function f(): Type. It is optional. Without it, TypeScript infers the type from every return in the body.

// Inferred: (n: number) => "even" | "odd"
function parity(n: number) {
  return n % 2 === 0 ? "even" : "odd";
}

// Annotated: the contract is written down
function average(values: number[]): number {
  if (values.length === 0) return 0;
  const sum = values.reduce((acc, v) => acc + v, 0);
  return sum / values.length;
}

const p = parity(7);
console.log(p, average([2, 4, 9])); // odd 5

An annotation earns its place when the function is exported, when it has several return paths, or when it is recursive. The error then shows up inside the function, at the wrong return, instead of at a caller. A classic case is a branch that forgets to return:

// This does not compile: one path falls off the end of the function.
function grade(score: number): string {
  if (score >= 90) return "A";
  if (score >= 80) return "B";
}

console.log(grade(85));

The compiler reports index.ts(2,32): error TS2366: Function lacks ending return statement and return type does not include 'undefined'. Add a final return "C"; and it runs. Without the : string annotation the function would compile with the inferred type "A" | "B" | undefined, and the problem would move to whoever uses the result.

void: Functions That Return Nothing

A function that only does something (logs, writes, mutates) has the return type void. It is what TypeScript infers when there is no return with a value, and you can write it explicitly.

function logLine(label: string, value: number): void {
  console.log(`${label.padEnd(8)}${value}`);
}

logLine("apples", 3);
logLine("pears", 12);

// A callback typed as returning void may return a value; it is ignored.
const lengths: number[] = [];
const push: (s: string) => void = (s) => lengths.push(s.length);
["a", "bcd"].forEach(push);
console.log(lengths); // [ 1, 3 ]

These rules about void surprise people:

The second row is deliberate. It is why arr.forEach(x => list.push(x)) compiles even though push returns a number. void in a function type means "whatever this returns, nobody reads it". For a function that never returns at all (it always throws or loops forever), the return type is never.

Arrow Functions and Function Expressions

Arrow functions and function expressions take the same annotations. The return type goes after the parameter list, before =>.

const double = (n: number): number => n * 2;

const toUpper = function (s: string): string {
  return s.toUpperCase();
};

// Returning an object literal from an arrow needs parentheses.
const point = (x: number, y: number) => ({ x, y });

console.log(double(21), toUpper("ok")); // 42 OK
console.log(point(1, 2));               // { x: 1, y: 2 }

Without the parentheses, (x, y) => { x, y } is a block with no return, and the function returns undefined. The runtime rules for arrow functions (no own this, no arguments) are the same as in JavaScript; see arrow functions in JavaScript.

When a function is written inline as an argument, you usually do not annotate its parameters at all. TypeScript knows what the callback receives from the function it is passed to (contextual typing): in [1, 2].map(n => n * 2), n is already number. Writing the type of a function as a value, (n: number) => string, is covered in function types.

Returning Several Values

A function returns one value, so return an object or a tuple and destructure it.

function minMax(values: number[]): { min: number; max: number } {
  return { min: Math.min(...values), max: Math.max(...values) };
}

function splitName(full: string): [first: string, last: string] {
  const i = full.indexOf(" ");
  return [full.slice(0, i), full.slice(i + 1)];
}

const { min, max } = minMax([7, 2, 9]);
const [first, last] = splitName("Grace Hopper");
console.log(min, max, first, last); // 2 9 Grace Hopper

The tuple return type needs the annotation. Without it, [a, b] is inferred as string[]: destructuring still works, but the type no longer says there are exactly two elements.

Async Functions

An async function always returns a Promise. Annotate the return type as Promise<T>, where T is what the function returns inside.

async function loadScore(id: number): Promise<number> {
  await new Promise((resolve) => setTimeout(resolve, 10));
  return id * 10;
}

async function main(): Promise<void> {
  const score = await loadScore(4); // score: number
  console.log("score", score);
}

main();

Writing async function f(): number is an error: The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'? (TS1064).

The this Parameter

JavaScript decides this at call time. TypeScript lets you declare what this must be with a fake first parameter named this. It is removed from the compiled JavaScript and callers do not pass it.

interface Counter {
  count: number;
}

function increment(this: Counter, by: number): void {
  this.count += by;
}

const c = { count: 0, increment };
c.increment(2); // fine: this is c

increment(2);
// error TS2684: The 'this' context of type 'void' is not assignable to method's 'this' of type 'Counter'.

Without the this parameter, this inside a standalone function is an implicit any and strict mode reports 'this' implicitly has type 'any' because it does not have a type annotation. (TS2683). In class methods this is already typed as the class instance, so the parameter is mostly useful for standalone functions attached to objects and for callbacks that libraries call with a specific this.