TypeScript Funktionen: Parameter, Rückgabetyp und void

Eine TypeScript-Funktion ist eine JavaScript-Funktion mit Typen an ihren Parametern und optional an ihrem Rückgabewert. Jeder Parameter bekommt eine Annotation, der Rückgabetyp steht hinter der Parameterliste, und der Compiler prüft jeden Aufruf gegen beides.

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);

Beide fehlerhaften Aufrufe sind Fehler beim Kompilieren (TS2345 und TS2554). Die Kommentare // @ts-expect-error sagen dem Compiler, dass in der nächsten Zeile ein Fehler erwartet wird, damit der Rest der Datei trotzdem läuft. Entferne einen davon und führe erneut aus, um die echte Meldung zu sehen.

Parametertypen

Jeder Parameter wird als name: Type geschrieben. Unter strict, das in TypeScript 7 standardmäßig aktiv ist, ist ein Parameter ohne Annotation und ohne Kontext, aus dem sich ableiten ließe, ein Fehler: Parameter 'x' implicitly has an 'any' type. (TS7006). In der Praxis wird also jeder Parameter einer eigenständigen Funktion annotiert.

Jeder Typ kann Parametertyp sein: primitive Typen, Arrays, Objekttypen, Unions, andere Funktionen.

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 prüft auch die Anzahl der Argumente. Mehr oder weniger zu übergeben, als die Funktion deklariert, ist ein Fehler, anders als in reinem JavaScript, das fehlende mit undefined auffüllt und überzählige ignoriert. Wie du einen Parameter optional machst oder ihm einen Standardwert gibst, steht unter optionale Parameter.

Rückgabetypen: annotieren oder ableiten

Der Rückgabetyp folgt auf die schließende Klammer: function f(): Type. Er ist optional. Ohne ihn leitet TypeScript den Typ aus jedem return im Rumpf ab.

// 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

Eine Annotation lohnt sich, wenn die Funktion exportiert wird, mehrere Rückgabepfade hat oder rekursiv ist. Der Fehler erscheint dann in der Funktion, beim falschen return, statt bei einem Aufrufer. Ein klassischer Fall ist ein Zweig, der das Zurückgeben vergisst:

// 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));

Der Compiler meldet index.ts(2,32): error TS2366: Function lacks ending return statement and return type does not include 'undefined'. Ergänze am Ende return "C";, und es läuft. Ohne die Annotation : string würde die Funktion mit dem abgeleiteten Typ "A" | "B" | undefined kompilieren, und das Problem würde zu dem wandern, der das Ergebnis verwendet.

void: Funktionen ohne Rückgabewert

Eine Funktion, die nur etwas tut (loggt, schreibt, verändert), hat den Rückgabetyp void. Das leitet TypeScript ab, wenn es kein return mit Wert gibt, und du kannst es auch ausdrücklich schreiben.

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 ]

Diese Regeln zu void überraschen viele:

Die zweite Zeile ist Absicht. Deshalb kompiliert arr.forEach(x => list.push(x)), obwohl push eine Zahl zurückgibt. void in einem Funktionstyp bedeutet: Was auch immer das zurückgibt, niemand liest es. Für eine Funktion, die nie zurückkehrt (sie wirft immer oder läuft endlos), ist der Rückgabetyp never.

Arrow Functions und Funktionsausdrücke

Arrow Functions und Funktionsausdrücke nehmen dieselben Annotationen. Der Rückgabetyp steht hinter der Parameterliste, vor =>.

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 }

Ohne die Klammern ist (x, y) => { x, y } ein Block ohne return, und die Funktion gibt undefined zurück. Die Laufzeitregeln für Arrow Functions (kein eigenes this, kein arguments) sind dieselben wie in JavaScript; siehe Arrow Functions in JavaScript.

Wird eine Funktion inline als Argument geschrieben, annotierst du ihre Parameter meist gar nicht. TypeScript weiß aus der Funktion, an die sie übergeben wird, was der Callback bekommt (kontextuelle Typisierung): In [1, 2].map(n => n * 2) ist n bereits number. Wie man den Typ einer Funktion als Wert schreibt, (n: number) => string, steht unter Funktionstypen.

Mehrere Werte zurückgeben

Eine Funktion gibt einen Wert zurück, also gibst du ein Objekt oder ein Tupel zurück und zerlegst es per Destructuring.

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

Der Tupel-Rückgabetyp braucht die Annotation. Ohne sie wird [a, b] als string[] abgeleitet: Destructuring funktioniert trotzdem, aber der Typ sagt nicht mehr, dass es genau zwei Elemente sind.

async-Funktionen

Eine async-Funktion gibt immer ein Promise zurück. Annotiere den Rückgabetyp als Promise<T>, wobei T das ist, was die Funktion innen zurückgibt.

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();

async function f(): number zu schreiben ist ein Fehler: The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'? (TS1064).

Der this-Parameter

JavaScript bestimmt this beim Aufruf. TypeScript lässt dich mit einem scheinbaren ersten Parameter namens this festlegen, was this sein muss. Er wird aus dem kompilierten JavaScript entfernt, und Aufrufer übergeben ihn nicht.

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'.

Ohne den this-Parameter ist this in einer eigenständigen Funktion ein implizites any, und der Strict Mode meldet 'this' implicitly has type 'any' because it does not have a type annotation. (TS2683). In Klassenmethoden ist this bereits als Instanz der Klasse typisiert, der Parameter ist also vor allem für eigenständige Funktionen nützlich, die an Objekte gehängt werden, und für Callbacks, die Bibliotheken mit einem bestimmten this aufrufen.