الدالة Promise.all()‎ في JavaScript

الدالة Promise.all(iterable)‎ تُعيد وعدًا Promise وحيدًا الذي سيُقبَل (resolves) عندما تكون جميع الوعود في الوسيط iterable مقبولة، أو عندما يكون المعامل iterable لا تحتوي على أيّ وعود. وسيُرفَض مع سبب أول وعد مرفوض.

var promise1 = Promise.resolve(3);
var promise2 = 42;
var promise3 = new Promise(function(resolve, reject) {
  setTimeout(resolve, 100, 'foo');
});

Promise.all([promise1, promise2, promise3]).then(function(values) {
  console.log(values);
});
// Array [3, 42, "foo"]

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

Promise.all(iterable);

المعاملات

iterable

كائن قابل للتكرار (iterable) مثل Array أو String.

القيمة المعادة

• وعد Promise مقبول (already resolved) إذا كان iterable المُمرَّر فارغًا.

• وعد Promise مقبول غير تزامنيًا (asynchronously resolved) إذا كان iterable لا تحتوي على أي وعود. لاحظ أنَّ متصفح Chrome 58 يعيد وعدًا مقبولًا (already resolved) في هذه الحالة.

• وعد Promise في الانتظار (pending). هذا الوعد المعادي سيقبل أو يرفض بشكل غير متزامن (فور فراغ المكدس) عند قبول جميع الوعود في iterable أو في حال رفض أحدها.

الوصف

هذه الدالة مفيدة في معرفة نتائج عدّة وعود.

حالة القبول

إذا مرر iterable فارغ، فستعيد هذه الدالة وعدًا مقبولًا (already resolved promise). وإذا قبلت جميع الوعود، أو لم تكن هنالك مكونات iterable هي وعود، فإن الوعد المعاد من الدالة Promise.all هو وعدٌ مقبول بشكل غير متزامن (fulfilled asynchronously).

في جميع الحالات، الوعد المعاد يقبل مع مصفوفة تحتوي على جميع قيم iterable المُمرَّر كمعامل (حتى القيم التي ليست وعودًا.

حالة الرفض

إذا رفض أي من الوعود المُمرَّرة، فإن الدالة Promise.all ستُرفَض بشكل غير متزامن مع قيمة الوعود التي رفضت، سواءً كانت بقية الوعود مقبولة أم لا.

أمثلة

تنتظر الدالة ()Promise.all لقبول جميع الوعود (أو لأول رفض):

var p1 = Promise.resolve(3);
var p2 = 1337;
var p3 = new Promise((resolve, reject) => {
  setTimeout(resolve, 100, 'foo');
}); 

Promise.all([p1, p2, p3]).then(values => { 
  console.log(values); // [3, 1337, "foo"] 
});

إذا لم يحتو iterable على قيم تُمثِّل وعودًا، فسيتم تجاهلها، لكنها ستبقى موجودةً في المصفوفة المعادة عند قبول الوعد:

// الممرر فارغًا، لذا سيتحقق الوعد iterable هذا سيعد أن
var p = Promise.all([1,2,3]);
// الُممرر يحوي وعدًا مقبولًا مع القيمة "444"، لذا سيتحقق الوعد iterable هذا سيعد أن
var p2 = Promise.all([1,2,3, Promise.resolve(444)]);
// الممرر يحوي وعدًا مرفوضًا مع القيمة "555"، لذا سيرفض الوعد iterable هذا سيعد أن
var p3 = Promise.all([1,2,3, Promise.reject(555)]);

// بعد أن يفرغ المكدس setTimeout يمكننا تنفيذ شيفرة باستعمال
setTimeout(function() {
    console.log(p);
    console.log(p2);
    console.log(p3);
});

// :يسجل
// Promise { <state>: "fulfilled", <value>: Array[3] }
// Promise { <state>: "fulfilled", <value>: Array[4] }
// Promise { <state>: "rejected", <reason>: 555 }

المصادر

• صفحة Promise​.all()‎ في توثيق MDN الرسمي.