Le richieste di rete, le letture di file e i timer terminano tutti più tardi, ma JavaScript non può semplicemente fermarsi e attendere, altrimenti la pagina si bloccherebbe. Le promesse di JavaScript ti danno un modo ordinato per dire “quando finisce, fai quello, e se fallisce, fai invece questo”.

Anche se scrivi principalmente async e await, stai usando le promesse sottostanti, quindi comprenderle rende il debug molto più semplice. Abbiamo eseguito questi esempi su Node.js 24 e l’output mostrato proviene da quell’esecuzione. Si comportano allo stesso modo nei browser moderni.

Cos’è una promessa?

Una promessa è un segnaposto per un valore futuro. Pensa al cicalino che ti passa un ristorante quando ordini. Non hai ancora il tuo cibo, ma tieni in mano qualcosa che ti dirà quando sarà pronto, o che c’è un problema, e nel frattempo sei libero di fare altre cose.

Nel codice, una funzione asincrona restituisce immediatamente una promessa e alleghi cosa dovrebbe accadere dopo:

fetch("/api/user")
  .then((response) => response.json())
  .then((user) => console.log(user.name))
  .catch((error) => console.log("Failed:", error.message));

I tre stati promessi

Una promessa mantenuta o respinta si chiama saldata. Una promessa può essere saldata una sola volta. Successivamente, il suo stato e il suo valore vengono fissi e le chiamate successive a resolve o reject vengono ignorate.

Crea una promessa

Di solito consumi le promesse di API come fetch, ma crearne una mostra come funzionano. Il costruttore riceve due funzioni, resolve e reject:

function fetchUser(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id > 0) {
        resolve({ id, name: "Asha" });
      } else {
        reject(new Error("Invalid id"));
      }
    }, 100);
  });
}

console.log(fetchUser(1));

// Promise { <pending> }

La registrazione immediata della promessa mostra che è ancora in sospeso, poiché il timer non è stato attivato. Il valore può essere raggiunto solo tramite un gestore o await. Rifiuta sempre con un oggetto Error anziché con una stringa, poiché un Error trasporta una traccia dello stack che aiuta con il debug.

poi, cattura e infine

Questi tre metodi collegano i gestori a una promessa:

fetchUser(1).then((user) => console.log(user.name));
// Asha

fetchUser(-1)
  .then((user) => console.log("never runs", user))
  .catch((error) => console.log("caught:", error.message))
  .finally(() => console.log("finally"));

// caught: Invalid id
// finally

then funziona in caso di successo, catch funziona in caso di fallimento e finally funziona in entrambi i casi. Ciò rende finally il posto giusto per la pulizia, ad esempio nascondere uno spinner di caricamento. Non riceve argomenti, perché non dovrebbe preoccuparsi del risultato.

Concatenare le promesse

L’idea chiave è che then restituisce sempre una nuova promessa. Qualunque cosa restituisca il tuo gestore diventa il valore di quella nuova promessa:

Promise.resolve(2)
  .then((n) => n * 10)
  .then((n) => n + 1)
  .then((n) => console.log("chain:", n));

// chain: 21

Se un gestore restituisce un’altra promessa, la catena attende che la situazione si stabilizzi prima di proseguire. Questo è ciò che trasforma i callback nidificati in una sequenza piatta di passaggi:

getUser(id)
  .then((user) => getOrders(user.id))
  .then((orders) => getInvoice(orders[0].id))
  .then((invoice) => console.log(invoice.total))
  .catch(handleError);

Come gli errori viaggiano attraverso una catena

Una promessa rifiutata salta ogni then finché non raggiunge un catch. Anche gettare dentro un conduttore conta come un rifiuto. E un catch che ritorna normalmente riporta la catena in carreggiata:

Promise.resolve("start")
  .then(() => {
    throw new Error("step 2 failed");
  })
  .then(() => console.log("skipped"))
  .catch((error) => {
    console.log("caught:", error.message);
    return "recovered";
  })
  .then((value) => console.log("continues:", value));

// caught: step 2 failed
// continues: recovered

Pensatela come la versione asincrona di try e catch. Uno catch alla fine solitamente copre l’intera catena. Se vuoi solo registrare un errore e fallire comunque, lancialo di nuovo dall’interno di catch.

Promise.all, allSettled, razza e altro

Questi metodi statici coordinano più promesse contemporaneamente. Tutti prendono un array e restituiscono una promessa.

Per testarli, abbiamo utilizzato due piccoli aiutanti, uno che funziona dopo un ritardo e uno che fallisce dopo un ritardo:

const wait = (ms, value) =>
  new Promise((resolve) => setTimeout(() => resolve(value), ms));
const fail = (ms, message) =>
  new Promise((_, reject) => setTimeout(() => reject(new Error(message)), ms));

Promise.all

await Promise.all([wait(300, "a"), wait(100, "b"), wait(200, "c")]);

// [ 'a', 'b', 'c' ]   took about 300 ms

Due dettagli da notare. I risultati mantengono l’ordine di input, anche se b è arrivato primo. E il tempo totale è stato di circa 300 ms, il tempo dell’attività più lenta e non la somma di 600 ms, perché tutti e tre erano già in esecuzione contemporaneamente. Se uno di loro rifiuta, tutti rifiutano immediatamente:

await Promise.all([wait(100, "a"), fail(50, "b failed")]);

// rejected: b failed

Promise.allSettled

Questo attende tutto e segnala ogni risultato, quindi un fallimento non perde il resto. Si adatta a una dashboard in cui ciascun widget viene caricato in modo indipendente:

const results = await Promise.allSettled([wait(50, "a"), fail(50, "b failed")]);
results.map((r) => r.status);

// [ 'fulfilled', 'rejected' ]

Promise.race e Promise.any

await Promise.race([wait(300, "slow"), wait(100, "fast")]);   // fast
await Promise.any([fail(50, "x"), wait(100, "ok")]);          // ok

La differenza è che race prende il primo per risolversi, anche se fallisce, mentre any ignora i fallimenti finché qualcosa riesce. Un uso classico di race è l’aggiunta di un timeout a una richiesta lenta, sebbene l’attività più lenta continui a essere eseguita in background a meno che non venga annullata.

Promesse e asincrono/attendono

async e await sono un modo più leggibile per lavorare con le stesse promesse. Una funzione async restituisce sempre una promessa e await mette in pausa quella funzione finché non viene stabilita una promessa:

async function showInvoice(id) {
  try {
    const user = await getUser(id);
    const orders = await getOrders(user.id);
    console.log(orders.length);
  } catch (error) {
    console.log("Failed:", error.message);
  }
}

I rifiuti diventano errori generati, quindi i normali try e catch funzionano. Hai ancora bisogno di Promise.all per il lavoro parallelo, perché aspettando una chiamata dopo l’altra le esegui in sequenza. La nostra guida JavaScript async/await approfondisce questo aspetto.

Le promesse e il ciclo degli eventi

I gestori delle promesse non vengono mai chiamati immediatamente, anche quando la promessa è già stata saldata. Vengono eseguiti al termine del codice corrente e prima di qualsiasi timer. Ecco la prova:

setTimeout(() => console.log("timeout"), 0);
Promise.resolve().then(() => console.log("microtask"));
console.log("sync");

// sync
// microtask
// timeout

Il codice sincrono viene eseguito per primo. Poi arriva la coda di microtask, che contiene i gestori delle promesse. Solo allora il ciclo degli eventi riprende la attività successiva, ad esempio un timer. Questa è una domanda popolare nelle interviste e spiega perché un setTimeout pari a zero non è proprio immediato.

Promesse vs richiamate

Errori comuni

• Dimenticando di tornare dentro then. Senza un return, il passo successivo riceve undefined e non attende la tua promessa interiore.
• No catch affatto. Ciò provoca un rifiuto non gestito e in Node.js interrompe il processo per impostazione predefinita.
• Annidamento invece di concatenamento. L’inserimento di then all’interno di then ricrea l’inferno delle richiamate. Restituisci la promessa e continua la catena.
• Racchiudere una promessa in new Promise. Se una funzione restituisce già una promessa, usala.
• Utilizzando forEach con callback asincroni. Non aspetta. Utilizza for...of o Promise.all con map, come mostrato nella nostra guida ai metodi di array JavaScript.
• Pensare che una promessa possa essere annullata.Non può da sola. Per le richieste, utilizzare AbortController.

Considerazioni finali

Le promesse si riducono a poche regole: una promessa viene mantenuta una volta, then restituisce una nuova promessa e gli errori viaggiano lungo la catena finché qualcosa non li cattura. Una volta che queste regole sembrano naturali, async e await smettono di essere magiche. Per esercitarti, riscrivi una funzione basata su callback utilizzando le promesse, quindi recupera due endpoint con Promise.all e gestisci correttamente un errore.

Domande frequenti

Continua a imparare