Parametri opzionali in TypeScript: valori predefiniti e rest

Aggiungi ? dopo il nome di un parametro per renderlo opzionale. Chi chiama può ometterlo, e dentro la funzione il suo tipo include 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 controlla il numero di argomenti, quindi senza il ? la prima chiamata sarebbe un errore di compilazione: Expected 2 arguments, but got 1. (TS2554).

I parametri opzionali possono essere undefined

Dato che chi chiama può ometterlo, il tipo di un parametro opzionale dentro la funzione è T | undefined. Con strictNullChecks devi gestire il caso undefined prima di usarlo come 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

L'optional chaining (?.) e il nullish coalescing (??) sono gli strumenti abituali in questi casi. Quando il valore di ripiego è fisso, un parametro predefinito è più breve.

Valori predefiniti dei parametri

Un valore predefinito rende il parametro opzionale per chi chiama e gli dà un tipo senza undefined dentro la funzione. Il tipo viene inferito dal valore predefinito, quindi spesso l'annotazione non serve.

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

Chi chiama vede la firma repeat(text: string, times?: number, separator?: string). I valori predefiniti seguono la regola di JavaScript: si applicano quando l'argomento è undefined, sia omesso sia passato in modo esplicito, e non quando è null. Un'espressione predefinita può usare i parametri precedenti: function range(start: number, end = start + 10).

Regole sull'ordine dei parametri

Un parametro con valore predefinito prima di uno obbligatorio è lecito ma scomodo. Per chi chiama il suo tipo diventa number | undefined, e a nessuno piace scrivere undefined come segnaposto. Se ti serve un primo parametro flessibile, usa invece un oggetto di opzioni o l'overloading delle funzioni.

Omesso vs undefined

x?: number e x: number | undefined si somigliano e hanno lo stesso tipo dentro la funzione. Cambiano per chi chiama: il primo si può omettere, il secondo va passato.

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

Usa | undefined per un argomento obbligatorio che può non avere un valore, così ogni chiamante deve pensarci. Usa ? quando ometterlo è una chiamata normale. (Il messaggio dice davvero "1 arguments": è la formulazione di TypeScript.)

Parametri rest

Un parametro rest, ...name: T[], raccoglie un numero qualsiasi di argomenti in un array. Deve essere l'ultimo parametro.

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

Espandere un array in parametri fissi è più rigido. Un parametro rest accetta lo spread di qualsiasi number[], ma una funzione dichiarata (a: number, b: number) accetta solo lo spread di una tupla, perché TypeScript deve conoscerne la lunghezza:

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

Anche un parametro rest può avere un tipo tupla, che tipizza ogni posizione: ...args: [name: string, age?: number].

Oggetti di opzioni

Quando una funzione ha più di due o tre parametri opzionali, chi chiama perde il conto delle posizioni. Un oggetto di opzioni con valori predefiniti dà argomenti con nome e senza ordine.

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

Il = {} finale rende opzionale l'intero oggetto. Senza, fetchData("/a") è un errore di compilazione (Expected 2 arguments, but got 1., TS2554), e in JavaScript puro la stessa chiamata lancerebbe un TypeError in fase di esecuzione, perché la destrutturazione ha bisogno di un oggetto da cui leggere.

Parametri opzionali nei tipi di callback

In un tipo di funzione, ? significa "chi chiama questa callback potrebbe non passarlo". Non significa "la callback può ignorarlo": una callback può sempre ignorare i parametri finali. Quindi non segnare come opzionali i parametri di una callback solo per permettere agli handler di ricevere meno argomenti.

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