المعامل await في JavaScript

المعامل await يُستخدَم لانتظار وعد (الكائن Promise)، ويمكن أن يُستخدَم داخل دالة غير متزامنة فقط (async function).

البنية العامة

[rv] = await expression;

expression

كائن Promise أو أيّة قيمة يجب انتظارها.

rv

إعادة قيمة المُحققة للوعد (الكائن Promise)، أو القيمة نفسها إذا لم تكن وعدًا.

الوصف

التعبير await يؤدي إلى إيقاف تنفيذ دالة غير متزامنة (async function) ريثما يتحقق (fulfill) أو يُرفَض (reject) الوعد (الكائن Promise)، ويؤدي إلى استئناف تنفيذ الدالة غير المتزامنة بعد أن يتحقق الوعد، وعند استنئاف الدالة ستكون قيمة تعبير await هي القيمة المُحقَّقة للوعد (الكائن Promise).

إذا رُفِضَ الوعد، فسيرمي (throw) التعبير await القيمة المرفوضة.

إذا كانت قيمة التعبير الذي يلي المعامل await ليست وعدًا Promise، فستحوَّل إلى وعد باستخدام الدالة resolve()‎.

أمثلة

إذا مُرِّر كائن Promise إلى التعبير await، فسينتظر إلى أن يتحقق الوعد ويُعيد تلك القيمة:

function resolveAfter2Seconds(x) { 
  return new Promise(resolve => {
    setTimeout(() => {
      resolve(x);
    }, 2000);
  });
}

async function f1() {
  var x = await resolveAfter2Seconds(10);
  console.log(x); // 10
}
f1();

أما إذا لم تكن القيمة كائنًا من النوع Promise، فستحوّل عبر الدالة resolve()‎. وسينتظر التعبير await الوعد حتى يتحقق:

async function f2() {
  var y = await 20;
  console.log(y); // 20
}
f2();

إذا رُفِضَ الوعد، فسترمى القيمة المرفوضة:

async function f3() {
  try {
    var z = await Promise.reject(30);
  } catch(e) {
    console.log(e); // 30
  }
}
f3();

دعم المتصفحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	55	52	غير مدعومة	42	10.1

على النقيض من متصفح IE، يدعم متصفح Edge هذه الميزة.

مصادر ومواصفات

• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2017.