عرض مصدر JavaScript/async function

<noinclude>{{DISPLAYTITLE:التصريح عن الدوال غير المتزامنة في JavaScript}}</noinclude>
التصريح عن دالة غير متزامنة ('''asynchronous function''' '''declaration''') يُعيد كائنًا من النوع <code>[[JavaScript/AsyncFunction|AsyncFunction]]</code>، يمكن أيضًا إنشاء الدوال غير المتزامنة عبر تعابير تعريف الدوال غير المتزامنة (<code>[[JavaScript/Async Function Expression|async function expression]]</code>).
==البنية العامة==
<syntaxhighlight lang="javascript">
async function name([param[, param[, ... param]]]) {
   statements
}
</syntaxhighlight>
=== <code>name</code> ===
اسم الدالة

=== <code>param</code> ===
اسم الوسيط المُرَّر إلى الدالة.

=== <code>statements</code> ===
التعابير البرمجية التي تُشكِّل جسم الدالة.

=== القيمة المعادة ===
كائن <code>[[JavaScript/AsyncFunction|AsyncFunction]]</code> الذي يُمثِّل الدالة غير المتزامنة ويُنفِّذ الشيفرة الموجودة ضمنها.

== الوصف ==
عندما تُستدعى دالة غير متزامنة، فستعيد كائن <code>[[JavaScript/Promise|Promise]]</code>، وعندما تُعيد دالةٌ غير متزامنةٍ قيمةً فستُستبين (resolve) قيمة «الوعد» (أي الكائن <code>[[JavaScript/Promise|Promise]]</code>)، وعندما ترمي دالةٌ غيرُ متزامنةٍ استثناءً فسيُرفَض الوعد (أي الكائن <code>[[JavaScript/Promise|Promise]]</code>).

يمكن أن تحتوي الدوال غير المتزامنة على التعبير <code>[[JavaScript/await|await]]</code>، الذي يوقف تنفيذ الدالة غير المتزامنة وينتظر استبيان قيمة الوعد (الكائن <code>[[JavaScript/Promise|Promise]]</code>) ثم يُكمِل تنفيذ الدالة غير المتزامنة ويُعيد القيمة المُستبينة (resolved value).

الغرض من دوال <code>async</code>/<code>await</code> هو تبسيط استخدام الوعود (promises) بشكل متزامن (synchronously) ولتنفيذ سلوك معيّن على مجموعة من الوعود (كائنات <code>[[JavaScript/Promise|Promises]]</code>).

== أمثلة ==

=== مثال بسيط ===
<syntaxhighlight lang="javascript">
function resolveAfter2Seconds(x) {
  return new Promise(resolve => {
    setTimeout(() => {
      resolve(x);
    }, 2000);
  });
}


async function add1(x) {
  const a = await resolveAfter2Seconds(20);
  const b = await resolveAfter2Seconds(30);
  return x + a + b;
}

add1(10).then(v => {
  console.log(v);  // إظهار 60 بعد 4 ثواني
});


async function add2(x) {
  const p_a = resolveAfter2Seconds(20);
  const p_b = resolveAfter2Seconds(30);
  return x + await p_a + await p_b;
}

add2(10).then(v => {
  console.log(v);  // إظهار 60 بعد 2 ثواني
});
</syntaxhighlight>لاحظ أنَّ التنفيذ قد توقف لمدة ثانيتن في الدالة <code>add1</code> لأوّل <code>await</code> وثم توقف لثانيتن أخرتين لثاني <code>await</code>؛ ذلك لأنَّ المؤقت الثاني لم يُنشَأ حتى انتهى تنفيذ الأول. لكن في الدالة <code>add2</code> فقد أُنشِئ كلا المؤقتين معًا وثم انتظرناهما (<code>await</code>) معًا؛ وهذا أدى إلى تنفيذ الدالة في ثانيتين بدلًا من 4 ثواني، وذلك لأنَّ المؤقتين يعملان في وقتٍ واحد؛ لكن لاحظ أنَّ استدعائَيّ <code>await</code> سيعملان بالتسلسل وليس بالتوازي: أي أنَّ هذا ليس تطبيقًا تلقائيًا لاستخدام <code>Promise.all</code>، فإذا أردتَ انتظار <code>await</code> وعدَين (promises) أو أكثر على التوازي، فيجب أن تستخدم <code>Promise.all</code>.

=== إعادة كتابة سلسلة وعود باستخدام دالة غير متزامنة ===
أيّة واجهة برمجية (API) تُعيد كائن <code>[[JavaScript/Promise|Promise]]</code> ستؤدي إلى إنشاء سلسلة وعود، وهي تُقسِّم الدالة إلى أقسام عديدة. انظر إلى الشيفرة الآتية:<syntaxhighlight lang="javascript">
function getProcessedData(url) {
  return downloadData(url) // إعادة وعد
    .catch(e => {
      return downloadFallbackData(url)  // إعادة وعد
    })
    .then(v => {
      return processDataInWorker(v); // إعادة وعد
    });
}
</syntaxhighlight>يمكن كتابة ما سبق كما يلي باستخدام دالة غير متزامنة:<syntaxhighlight lang="javascript">
async function getProcessedData(url) {
  let v;
  try {
    v = await downloadData(url); 
  } catch(e) {
    v = await downloadFallbackData(url);
  }
  return processDataInWorker(v);
}
</syntaxhighlight>لاحظ عدم وجود التعبير <code>[[JavaScript/await|await]]</code> في المثال السابق على التعبير البرمجي <code>[[JavaScript/return|return]]</code>، وذلك لأنَّ القيمة المُعادة من الدالة غير المتزامنة (async function) ستحتوى ضمنيًا في <code>Promise.resolve</code>.

==دعم المتصفحات==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|55
|52
|غير مدعومة
|42
|10.1
|}
على النقيض من متصفح IE، يدعم متصفح Edge هذه الميزة.

== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-async-function-definitions ECMAScript Latest Draft].
* معيار [https://tc39.github.io/ecma262/2017/#sec-async-function-definitions ECMAScript 2017]. 
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Statement|{{SUBPAGENAME}}]]