Опциональные параметры TypeScript: default и rest

Добавьте ? после имени параметра, чтобы сделать его опциональным. Вызывающий код может его не передавать, а внутри функции его тип включает undefined.

function greet(name: string, title?: string): string {
  // title is string | undefined here
  return title ? `Hello, ${title} ${name}` : `Hello, ${name}`;
}

console.log(greet("Lovelace"));          // Hello, Lovelace
console.log(greet("Lovelace", "Lady"));  // Hello, Lady Lovelace

TypeScript проверяет количество аргументов, поэтому без ? первый вызов дал бы ошибку компиляции: Expected 2 arguments, but got 1. (TS2554).

Опциональный параметр может быть undefined

Раз вызывающий код может его пропустить, тип опционального параметра внутри функции это T | undefined. При strictNullChecks нужно обработать случай undefined, прежде чем использовать значение как T.

function formatPrice(amount: number, currency?: string): string {
  // currency.toUpperCase() here would fail: 'currency' is possibly 'undefined'. (TS18048)
  const code = currency?.toUpperCase() ?? "USD";
  return `${amount.toFixed(2)} ${code}`;
}

console.log(formatPrice(9.5));        // 9.50 USD
console.log(formatPrice(12, "eur"));  // 12.00 EUR

Обычные инструменты здесь это опциональная цепочка (?.) и оператор нулевого слияния (??). Когда запасное значение фиксированное, короче параметр со значением по умолчанию.

Значения параметров по умолчанию

Значение по умолчанию делает параметр опциональным для вызывающего кода и даёт ему внутри функции тип без undefined. Тип выводится из значения по умолчанию, поэтому аннотация часто не нужна.

function repeat(text: string, times = 2, separator: string = " "): string {
  // times: number, separator: string (never undefined here)
  return Array.from({ length: times }, () => text).join(separator);
}

console.log(repeat("ha"));              // ha ha
console.log(repeat("ha", 3, "-"));      // ha-ha-ha
console.log(repeat("ha", undefined, "")); // haha

Вызывающий код видит сигнатуру repeat(text: string, times?: number, separator?: string). Значения по умолчанию подчиняются правилу JavaScript: они применяются, когда аргумент равен undefined, пропущен он или передан явно, и не применяются, когда он равен null. Выражение по умолчанию может использовать предыдущие параметры: function range(start: number, end = start + 10).

Правила порядка параметров

Параметр со значением по умолчанию перед обязательным допустим, но неудобен. Для вызывающего кода его тип становится number | undefined, а писать undefined как заглушку никому не нравится. Если нужен гибкий первый параметр, используйте объект опций или перегрузку функций.

Пропуск аргумента и undefined

x?: number и x: number | undefined выглядят похоже и внутри функции имеют одинаковый тип. Для вызывающего кода они различаются: первый можно пропустить, второй нужно передать.

function a(x?: number) { return x; }
function b(x: number | undefined) { return x; }

console.log(a());          // undefined
console.log(b(undefined)); // undefined
// @ts-expect-error: Expected 1 arguments, but got 0.
b();

Используйте | undefined для обязательного аргумента, у которого может не быть значения, чтобы каждый вызывающий код задумался об этом. Используйте ?, когда пропуск это обычный вызов. (В сообщении действительно написано «1 arguments»: такова формулировка TypeScript.)

Rest-параметры

Rest-параметр, ...name: T[], собирает любое количество аргументов в массив. Он должен быть последним параметром.

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

function tag(name: string, ...classes: string[]): string {
  return `<${name} class="${classes.join(" ")}">`;
}

console.log(sum());             // 0
console.log(sum(1, 2, 3));      // 6
const scores = [4, 8, 15];
console.log(sum(...scores));    // 27
console.log(tag("div", "card", "wide")); // <div class="card wide">

Разворачивание массива в фиксированные параметры проверяется строже. Rest-параметр принимает развёрнутый любой number[], но функция, объявленная как (a: number, b: number), принимает только развёрнутый кортеж, потому что TypeScript должен знать длину:

function point(x: number, y: number) { return { x, y }; }

const list = [3, 4];            // number[]
point(...list);
// error TS2556: A spread argument must either have a tuple type or be passed to a rest parameter.

const pair = [3, 4] as const;   // readonly [3, 4]
point(...pair);                 // fine

Rest-параметр может иметь и тип кортежа, который типизирует каждую позицию: ...args: [name: string, age?: number].

Объекты опций

Когда у функции больше двух-трёх опциональных параметров, вызывающий код начинает путаться в позициях. Объект опций со значениями по умолчанию даёт именованные аргументы без привязки к порядку.

interface FetchOptions {
  retries?: number;
  timeoutMs?: number;
  verbose?: boolean;
}

function fetchData(url: string, { retries = 3, timeoutMs = 5000, verbose = false }: FetchOptions = {}): string {
  return `${url} retries=${retries} timeout=${timeoutMs} verbose=${verbose}`;
}

console.log(fetchData("/a"));
// /a retries=3 timeout=5000 verbose=false
console.log(fetchData("/b", { verbose: true }));
// /b retries=3 timeout=5000 verbose=true

= {} в конце делает опциональным весь объект. Без него fetchData("/a") даёт ошибку компиляции (Expected 2 arguments, but got 1., TS2554), а в обычном JavaScript тот же вызов бросил бы TypeError во время выполнения, потому что деструктуризации нужен объект, из которого можно читать.

Опциональные параметры в типах колбэков

В типе функции ? означает «вызывающий этот колбэк код может его не передать». Он не означает «колбэк может его пропустить»: колбэк всегда может игнорировать последние параметры. Поэтому не делайте параметры колбэка опциональными только для того, чтобы обработчики могли принимать меньше аргументов.

// Too loose: every handler must now cope with index being undefined
type Visit = (item: string, index?: number) => void;

// Right: the caller always passes both; handlers may use only item
type VisitStrict = (item: string, index: number) => void;
const log: VisitStrict = (item) => console.log(item);