Servizio di traduzione

L'oggetto Promise rappresenta il completamento (o il fallimento) futuro di un'operazione asincrona e il valore che ne risulta.

Ciclo di vita di una promise

Una Promise ha tre stati:

1. pending
2. fulfilled
3. rejected

Quando viene creata, una promise è nello stato pending. A un certo punto nel futuro potrà resolve o reject. Una volta che una promise raggiunge lo stato resolved o rejected, non potrà mai più diventare resolved o rejected, né il suo stato può cambiare.

In altre parole:

1. Nello stato pending, una promise:
   • può passare allo stato fulfilled o rejected.
2. Nello stato fulfilled, una promise:
   • non deve passare a nessun altro stato.
   • deve avere un valore, che non deve cambiare.
3. Nello stato rejected, una promise:
   • non deve passare a nessun altro stato.
   • deve avere un motivo, che non deve cambiare.

Risolvere una promise

Una promise può essere risolta in vari modi:

// Creates a promise that is immediately resolved
Promise.resolve(value);

// Creates a promise that is immediately resolved
new Promise((resolve) => {
  resolve(value);
});

// Chaining a promise leads to a resolved promise
somePromise.then(() => {
  // ...
  return value;
});

Negli esempi qui sopra value può essere qualsiasi cosa, incluso un errore, undefined, null o un'altra promise. Di solito vorrai risolvere con un valore che non sia un errore.

Rifiutare una promise

Una promise può essere rifiutata in vari modi:

// Creates a promise that is immediately rejected
Promise.reject(reason)

// Creates a promise that is immediately rejected
new Promise((_, reject) {
  reject(reason)
})

// Chaining a promise with an error leads to a rejected promise
somePromise.then(() => {
  // ...
  throw reason
})

Negli esempi qui sopra reason può essere qualsiasi cosa, incluso un errore, undefined o null. Di solito vorrai rifiutare con un errore.

Concatenare una promise

A una promise si può collegare un'azione futura, eseguita quando si risolve o si rifiuta.

• promise.then() viene chiamata quando promise si risolve
• promise.catch() viene chiamata quando promise si rifiuta
• promise.finally() viene chiamata quando promise si risolve o si rifiuta

then

Ogni promise è «thenable». Questo significa che è disponibile una funzione then che verrà eseguita una volta che la promise originale è risolta. Dato promise.then(onResolved), la callback onResolved riceve il valore con cui è stata risolta la promise originale. Questa restituirà sempre una nuova promise «concatenata».

Restituire un value da then risolve la promise «concatenata». Lanciare un reason in then rifiuta la promise «concatenata».

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);
});

const promise2 = promise1.then(function (value) {
  console.log(value);
  // expected output: "Success!"

  return true;
});

Questo registrerà "Success!" dopo circa 1000 ms. Lo stato e il valore di promise1 saranno resolved e "Success!". Lo stato e il valore di promise2 saranno resolved e true.

È disponibile un secondo argomento che viene eseguito quando la promise originale viene rifiutata. Dato promise.then(onResolved, onRejected), la callback onResolved riceve il valore con cui è stata risolta la promise originale, oppure la callback onRejected riceve il motivo per cui la promise è stata rifiutata.

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);

  if (Math.random() < 0.5) {
    reject('Nope!');
  }
});

function log(value) {
  console.log(value);
  return true;
}

function shout(reason) {
  console.error(reason.toUpperCase());
  return false;
}

const promise2 = promise1.then(log, shout);

• In circa 1/2 dei casi, registrerà "Success!" dopo circa 1000 ms.
  • Lo stato e il valore di promise1 saranno resolved e "Success!".
  • Lo stato e il valore di promise2 saranno resolved e true.
• In circa 1/2 dei casi, registrerà immediatamente "NOPE!".
  • Lo stato e il valore di promise1 saranno rejected e Nope!.
  • Lo stato e il valore di promise2 saranno resolved e false.

È importante capire che, a causa delle regole del ciclo di vita, quando la promise esegue reject, la resolve che arriva circa 1000 ms dopo viene ignorata silenziosamente: lo stato interno non può cambiare una volta che è diventato rejected o resolved. È importante capire che restituire un valore da una promise la risolve, e lanciare un valore la rifiuta. Quando promise1 si risolve e c'è un onResolved concatenato: then(onResolved), quella continuazione è una nuova promise che può risolversi o rifiutarsi. Quando promise1 viene rifiutata ma c'è un onRejected concatenato: then(, onRejected), quella continuazione è una nuova promise che può risolversi o rifiutarsi.

catch

A volte vuoi catturare gli errori e continuare solo quando la promise originale esegue reject. Dato promise.catch(onCatch), la callback onCatch riceve il motivo per cui la promise originale è stata rifiutata. Questa restituirà sempre una nuova promise «concatenata».

Restituire un value da catch risolve la promise «concatenata». Lanciare un reason in catch rifiuta la promise «concatenata».

const promise1 = new Promise(function (resolve, reject) {
  setTimeout(() => {
    resolve('Success!');
  }, 1000);

  if (Math.random() < 0.5) {
    reject('Nope!');
  }
});

function log(value) {
  console.log(value);
  return 'done';
}

function recover(reason) {
  console.error(reason.toUpperCase());
  return 42;
}

const promise2 = promise1.catch(recover).then(log);

In circa 1/2 dei casi, registrerà "Success!" dopo circa 1000 ms. Nell'altro 1/2 dei casi, registrerà immediatamente 42.

• Se promise1 si risolve, catch viene saltata, si arriva a then e viene registrato il valore.
  • Lo stato e il valore di promise1 saranno resolved e "Success!".
  • Lo stato e il valore di promise2 saranno resolved e "done";
• Se promise1 viene rifiutata, catch viene eseguita, il che restituisce un valore: la catena ora è resolved, si arriva a then e viene registrato il valore.
  • Lo stato e il valore di promise1 saranno rejected e "Nope!".
  • Lo stato e il valore di promise2 saranno resolved e "done";

finally

A volte vuoi eseguire del codice dopo che una promise si è conclusa, indipendentemente dal fatto che si risolva o venga rifiutata. Dato promise.finally(onSettled), la callback onSettled non riceve nulla. Questa restituirà sempre una nuova promise «concatenata».

Restituire un value da finally copia lo stato e il valore dalla promise originale, ignorando il value. Lanciare un reason in finally rifiuta la promise «concatenata», sovrascrivendo qualsiasi stato, valore o motivo della promise originale.

Esempio

Diversi metodi usati insieme:

const myPromise = new Promise(function (resolve, reject) {
  const sampleData = [2, 4, 6, 8];
  const randomNumber = Math.round(Math.random() * 5);

  if (sampleData[randomNumber]) {
    resolve(sampleData[randomNumber]);
  } else {
    reject('Sampling did not result in a sample');
  }
});

const finalPromise = myPromise
  .then(function (sampled) {
    // If the random number was 0, 1, 2, or 3, this will be
    // reached and the number 2, 4, 6, or 8 will be logged.
    console.log(`Sampled data: ${sampled}`);
    return 'yay';
  })
  .catch(function (reason) {
    // If the random number was 4 or 5, this will be reached and
    // reason will be "An error occurred". The entire chain will
    // then reject with an Error with the reason as message.
    throw new Error(reason);
  })
  .finally(function () {
    // This will always log after either the sampled data is
    // logged or the error is raised.
    console.log('Promise completed');
  });

• Nei casi in cui randomNumber è 0-3:
  • myPromise sarà risolta con il valore 2, 4, 6, or 8
  • finalPromise sarà risolta con il valore 'yay'
  • Ci saranno due registrazioni:
    • Sampled data: ...
    • Promise completed
• Nei casi in cui randomNumber è 4-5:
  • myPromise sarà rifiutata con il motivo 'Sampling did not result in a sample'
  • finalPromise sarà rifiutata con il motivo Error('Sampling did not result in a sample')
  • Ci sarà una registrazione:
    • Promise completed
    • in alcuni ambienti questo produrrà una registrazione "uncaught rejected promise: Error('Sampling did not result in a sample')"

Come mostrato sopra, reject funziona con una stringa, e una promise può anche essere rifiutata con un Error.