TypeScriptの関数: 引数と戻り値の型、void

TypeScriptの関数は、引数と（必要なら）戻り値に型を付けたJavaScriptの関数です。すべての引数に型注釈を付け、戻り値の型は引数リストのあとに書きます。コンパイラーはすべての呼び出しをその両方と照らし合わせてチェックします。

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

間違った2つの呼び出しはどちらもコンパイルエラー（TS2345 と TS2554）です。// @ts-expect-error コメントは次の行でエラーが起きることをコンパイラーに伝えるので、ファイルの残りは実行されます。どちらかを消してもう一度実行すると、実際のメッセージが見られます。

引数の型

各引数は name: Type の形で書きます。TypeScript 7 でデフォルトで有効な strict のもとでは、型注釈がなく推論の手がかりもない引数はエラーになります: Parameter 'x' implicitly has an 'any' type.（TS7006）。そのため実際には、独立した関数の引数にはすべて型注釈を付けることになります。

引数の型にはどんな型でも使えます。プリミティブ、配列、オブジェクト型、ユニオン型、ほかの関数などです。

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は引数の数もチェックします。宣言より多く渡しても少なく渡してもエラーです。足りない引数を undefined で埋め、余分な引数を無視する素のJavaScriptとは違います。引数を省略可能にしたりデフォルト値を付けたりする方法は 省略可能な引数 を参照してください。

戻り値の型: 書くか推論に任せるか

戻り値の型は閉じかっこのあとに書きます: function f(): Type。書くかどうかは任意で、省略すると本体のすべての return から型が推論されます。

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

関数を export する場合、戻り値の経路が複数ある場合、再帰している場合には注釈を書く価値があります。エラーが呼び出し側ではなく、関数の中の間違った return で報告されるからです。典型的なのは、あるブランチで 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));

コンパイラーは index.ts(2,32): error TS2366: Function lacks ending return statement and return type does not include 'undefined'. を報告します。最後に return "C"; を追加すれば実行できます。: string の注釈がなければ、この関数は推論された型 "A" | "B" | undefined でコンパイルされ、問題は結果を使う側に移ってしまいます。

void: 何も返さない関数

処理をするだけの関数（ログを出す、書き込む、値を変更する）の戻り値の型は void です。値を伴う return がないときにTypeScriptが推論する型で、明示的に書くこともできます。

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 ]

void には意外なルールがあります:

2行目は意図的な仕様です。push は数値を返すのに arr.forEach(x => list.push(x)) がコンパイルできるのはこのためです。関数型の中の void は「何を返しても、誰もそれを読まない」という意味です。決して戻らない関数（必ず例外を投げる、または無限ループする）の戻り値の型は never です。

アロー関数と関数式

アロー関数と関数式にも同じように型注釈を書きます。戻り値の型は引数リストのあと、=> の前に書きます。

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 }

かっこがないと、(x, y) => { x, y } は return のないブロックになり、関数は undefined を返します。アロー関数の実行時のルール（自分の this を持たない、arguments がない）はJavaScriptと同じです。JavaScriptのアロー関数 を参照してください。

関数を引数としてその場で書く場合、ふつうは引数に型注釈を付けません。コールバックが何を受け取るかは、渡す先の関数からTypeScriptがわかるからです（文脈による型付け）。[1, 2].map(n => n * 2) では n はすでに number です。関数の型を値として書く方法（(n: number) => string）は 関数型 で説明しています。

複数の値を返す

関数が返せる値は1つなので、オブジェクトかタプルを返して分割代入します。

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

タプルの戻り値には型注釈が必要です。注釈がないと [a, b] は string[] と推論されます。分割代入は動きますが、要素がちょうど2つであることが型に表れなくなります。

async 関数

async 関数は常に Promise を返します。戻り値の型は Promise<T> と書き、T には関数の中で返す値の型を入れます。

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 と書くとエラーです: The return type of an async function or method must be the global Promise<T> type. Did you mean to write 'Promise<number>'?（TS1064）。

this パラメーター

JavaScriptでは this は呼び出し時に決まります。TypeScriptでは、this という名前の見せかけの第1引数で、this が何であるべきかを宣言できます。この引数はコンパイル後のJavaScriptからは取り除かれ、呼び出し側は渡しません。

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

this パラメーターがないと、独立した関数の中の this は暗黙の any になり、strict モードでは 'this' implicitly has type 'any' because it does not have a type annotation.（TS2683）が報告されます。クラスのメソッドでは this はすでにクラスのインスタンスとして型付けされているので、このパラメーターが役立つのは主に、オブジェクトに取り付ける独立した関数や、ライブラリが特定の this で呼び出すコールバックです。