Parâmetros opcionais em TypeScript: padrão e rest

Coloque ? depois do nome de um parâmetro para torná-lo opcional. Quem chama pode omiti-lo, e dentro da função o tipo dele inclui 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

O TypeScript verifica o número de argumentos, então sem o ? a primeira chamada seria erro de compilação: Expected 2 arguments, but got 1. (TS2554).

Parâmetros opcionais podem ser undefined

Como quem chama pode omiti-lo, o tipo de um parâmetro opcional dentro da função é T | undefined. Com strictNullChecks você precisa tratar o caso undefined antes de usá-lo como 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

Optional chaining (?.) e nullish coalescing (??) são as ferramentas usuais aqui. Quando o valor alternativo é fixo, um parâmetro com valor padrão é mais curto.

Valores padrão de parâmetros

Um valor padrão torna o parâmetro opcional para quem chama e dá a ele um tipo sem undefined dentro da função. O tipo é inferido a partir do padrão, então a anotação muitas vezes é desnecessária.

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

Quem chama vê a assinatura repeat(text: string, times?: number, separator?: string). Os padrões seguem a regra do JavaScript: valem quando o argumento é undefined, seja omitido ou passado explicitamente, e não quando é null. Uma expressão de padrão pode usar parâmetros anteriores: function range(start: number, end = start + 10).

Regras de ordem dos parâmetros

Um parâmetro com padrão antes de um obrigatório é válido, mas desajeitado. O tipo dele para quem chama vira number | undefined, e ninguém gosta de escrever undefined como marcador. Se você precisa de um parâmetro inicial flexível, use um objeto de opções ou function overloading.

Omitido vs undefined

x?: number e x: number | undefined se parecem e têm o mesmo tipo dentro da função. A diferença é para quem chama: o primeiro pode ser omitido, o segundo precisa ser passado.

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

Use | undefined para um argumento obrigatório que pode não ter valor, para que todo mundo que chama precise pensar nele. Use ? quando omiti-lo é uma chamada normal. (A mensagem diz mesmo "1 arguments": é o texto do TypeScript.)

Rest parameters

Um rest parameter, ...name: T[], junta qualquer número de argumentos em um array. Ele precisa ser o último parâmetro.

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

Espalhar um array em parâmetros fixos é mais restrito. Um rest parameter aceita o spread de qualquer number[], mas uma função declarada (a: number, b: number) só aceita o spread de uma tupla, porque o TypeScript precisa saber o tamanho:

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

Um rest parameter também pode ter um tipo de tupla, que tipa cada posição: ...args: [name: string, age?: number].

Objetos de opções

Quando uma função tem mais de dois ou três parâmetros opcionais, quem chama perde a noção das posições. Um objeto de opções com padrões dá argumentos nomeados e sem ordem.

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

O = {} no final torna o objeto inteiro opcional. Sem ele, fetchData("/a") é erro de compilação (Expected 2 arguments, but got 1., TS2554), e em JavaScript puro a mesma chamada lançaria um TypeError em tempo de execução, porque a desestruturação precisa de um objeto de onde ler.

Parâmetros opcionais em tipos de callback

Em um tipo de função, ? significa "quem chama este callback pode não passar isto". Não significa "o callback pode ignorar isto": um callback sempre pode ignorar os parâmetros finais. Então não marque parâmetros de callback como opcionais só para deixar os handlers receberem menos argumentos.

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