خدمة الترجمة

يمثّل كائن 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

كل وعد قابل للربط بـ then. وهذا يعني وجود دالة then متاحة تُنفَّذ بمجرد إنجاز الوعد الأصلي. عند استخدام promise.then(onResolved)، تستقبل دالة رد النداء onResolved القيمة التي أُنجز بها الوعد الأصلي. وسيعيد هذا دائمًا وعدًا جديدًا "مترابطًا".

إرجاع value من then يُنجز الوعد "المترابط". ورميّ reason في then يرفض الوعد "المترابط".

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

• في نحو 1/2 من الحالات، سيسجّل هذا "Success!" بعد نحو 1000 مللي ثانية.
  • وستكون حالة promise1 وقيمته resolved و"Success!".
  • وستكون حالة promise2 وقيمته resolved وtrue.
• وفي نحو 1/2 من الحالات، سيسجّل هذا "NOPE!" فورًا.
  • وستكون حالة promise1 وقيمته rejected وNope!.
  • وستكون حالة promise2 وقيمته resolved وfalse.

من المهم أن تفهم أنه بسبب قواعد دورة الحياة، عندما rejects، فإن resolve الذي يأتي بعد نحو 1000 مللي ثانية يُتجاهَل بصمت، لأن الحالة الداخلية لا يمكن أن تتغيّر بمجرد أن يُرفَض الوعد أو يُنجَز. ومن المهم أن تفهم أن إرجاع قيمة من وعد يُنجزه، ورميّ قيمة يرفضه. عندما يُنجَز promise1 ويكون هناك onResolved مترابط: then(onResolved)، فإن ذلك التابع وعد جديد يمكن أن يُنجَز أو يُرفَض. وعندما يُرفَض promise1 لكن يكون هناك onRejected مترابط: then(, onRejected)، فإن ذلك التابع وعد جديد يمكن أن يُنجَز أو يُرفَض.

catch

أحيانًا تريد التقاط الأخطاء والمتابعة فقط عندما rejects الوعد الأصلي. عند استخدام promise.catch(onCatch)، تستقبل دالة رد النداء onCatch سبب رفض الوعد الأصلي. وسيعيد هذا دائمًا وعدًا جديدًا "مترابطًا".

إرجاع value من catch يُنجز الوعد "المترابط". ورميّ reason في catch يرفض الوعد "المترابط".

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

في نحو 1/2 من الحالات، سيسجّل هذا "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. ورميّ reason في finally يرفض الوعد "المترابط"، ويلغي أي حالة وقيمة أو سبب من الوعد الأصلي.

مثال

عدة طرق معًا:

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 مع سلسلة نصية، ويمكن للوعد أيضًا أن يُرفَض بكائن Error.