Служба перекладу

Обʼєкт Promise представляє майбутнє завершення (або невдачу) асинхронної операції та її результуюче значення.

Життєвий цикл проміса

Promise має три стани:

1. очікування
2. виконано
3. відхилено

Коли проміс створюють, він перебуває в стані очікування. У якийсь момент у майбутньому він може виконатися або відхилитися. Щойно проміс виконався або відхилився, він уже ніколи не зможе виконатися чи відхилитися знову, і його стан теж не може змінитися.

Іншими словами:

1. У стані очікування проміс:
   • може перейти або в стан «виконано», або в стан «відхилено».
2. У стані «виконано» проміс:
   • не повинен переходити в жоден інший стан.
   • повинен мати значення, яке не повинно змінюватися.
3. У стані «відхилено» проміс:
   • не повинен переходити в жоден інший стан.
   • повинен мати причину, яка не повинна змінюватися.

Виконання проміса

Проміс можна виконати в різні способи:

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

У наведених прикладах value може бути чим завгодно, зокрема помилкою, undefined, null або іншим промісом. Зазвичай ми хочемо виконати проміс зі значенням, яке не є помилкою.

Відхилення проміса

Проміс можна відхилити в різні способи:

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

У наведених прикладах reason може бути чим завгодно, зокрема помилкою, undefined або null. Зазвичай ми хочемо відхилити проміс із помилкою.

Ланцюжки промісів

Проміс можна продовжити майбутньою дією, щойно він виконається або відхилиться.

• promise.then() викликається, коли promise виконується
• promise.catch() викликається, коли promise відхиляється
• promise.finally() викликається, коли promise або виконується, або відхиляється

then

Кожен проміс є «thenable». Це означає, що в нього є доступна функція then, яка виконається, щойно початковий проміс виконається. Якщо маємо promise.then(onResolved), то функція зворотного виклику onResolved отримує значення, яким було виконано початковий проміс. Це завжди повертає новий проміс у ланцюжку.

Повернення value з then виконує проміс у ланцюжку. Якщо в then кинути reason, проміс у ланцюжку відхиляється.

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

Це виведе "Success!" приблизно через 1000 мс. Стан і значення promise1 будуть resolved і "Success!". Стан і значення promise2 будуть resolved і true.

Є й другий аргумент, який запускається, коли початковий проміс відхиляється. Якщо маємо promise.then(onResolved, onRejected), то функція зворотного виклику onResolved отримує значення, яким було виконано початковий проміс, або функція зворотного виклику onRejected отримує причину, з якої проміс було відхилено.

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

• Приблизно в половині випадків це виведе "Success!" приблизно через 1000 мс.
  • Стан і значення promise1 будуть resolved і "Success!".
  • Стан і значення promise2 будуть resolved і true.
• Приблизно в половині випадків це одразу виведе "NOPE!".
  • Стан і значення promise1 будуть rejected і Nope!.
  • Стан і значення promise2 будуть resolved і false.

Важливо розуміти, що через правила життєвого циклу, коли відбувається reject, той resolve, який надходить приблизно через 1000 мс, мовчки ігнорується, бо внутрішній стан не може змінитися після відхилення чи виконання. Важливо розуміти, що повернення значення з проміса виконує його, а викидання значення відхиляє його. Коли promise1 виконується і є приєднаний onResolved: then(onResolved), то цей наступний крок стає новим промісом, який може виконатися або відхилитися. Коли promise1 відхиляється, але є приєднаний onRejected: then(, onRejected), то цей наступний крок стає новим промісом, який може виконатися або відхилитися.

catch

Іноді ми хочемо перехопити помилки й продовжити лише тоді, коли початковий проміс зазнає reject. Якщо маємо promise.catch(onCatch), то функція зворотного виклику onCatch отримує причину, з якої початковий проміс було відхилено. Це завжди повертає новий проміс у ланцюжку.

Повернення value з catch виконує проміс у ланцюжку. Якщо в catch кинути reason, проміс у ланцюжку відхиляється.

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

Приблизно в половині випадків це виведе "Success!" приблизно через 1000 мс. В іншій половині випадків це одразу виведе 42.

• Якщо promise1 виконується, catch пропускається, керування доходить до then і значення виводиться в консоль.
  • Стан і значення promise1 будуть resolved і "Success!".
  • Стан і значення promise2 будуть resolved і "done";
• Якщо promise1 відхиляється, виконується catch, який повертає значення, і таким чином ланцюжок тепер перебуває в стані resolved, керування доходить до then і значення виводиться в консоль.
  • Стан і значення promise1 будуть rejected і "Nope!".
  • Стан і значення promise2 будуть resolved і "done";

finally

Іноді ми хочемо виконати код після того, як проміс завершиться, незалежно від того, виконався він чи відхилився. Якщо маємо promise.finally(onSettled), то функція зворотного виклику onSettled не отримує нічого. Це завжди повертає новий проміс у ланцюжку.

Повернення value з finally копіює стан і значення початкового проміса, ігноруючи value. Якщо в finally кинути reason, проміс у ланцюжку відхиляється, перезаписуючи будь-який стан і значення чи причину початкового проміса.

Приклад

Кілька методів разом:

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');
  });

• У випадках, коли randomNumber дорівнює 0-3:
  • myPromise буде виконано зі значенням 2, 4, 6, or 8
  • finalPromise буде виконано зі значенням 'yay'
  • Буде два виводи:
    • Sampled data: ...
    • Promise completed
• У випадках, коли randomNumber дорівнює 4-5:
  • myPromise буде відхилено з причиною 'Sampling did not result in a sample'
  • finalPromise буде відхилено з причиною Error('Sampling did not result in a sample')
  • Буде один вивід:
    • Promise completed
    • у деяких середовищах це дасть вивід "uncaught rejected promise: Error('Sampling did not result in a sample')"

Як показано вище, reject працює з рядком тексту (англ. string), і проміс також може відхилитися з Error.