Adopting Async/Await for Simplified Asynchronous JavaScript

# Title: Adopting Async/Await for Simplified Asynchronous JavaScript
# Description: Guidelines on using async/await syntax to write cleaner and more readable asynchronous JavaScript code.
# Category: JavaScript Cursor Rules

rules:
  - id: prefer-async-await
    description: "Use async/await syntax over traditional Promise chains for better readability and maintainability."
    severity: warning
    pattern: |
      function $FUNC_NAME($PARAMS$) {
        return $PROMISE.then($CALLBACK$);
      }
    replacement: |
      async function $FUNC_NAME($PARAMS$) {
        try {
          const result = await $PROMISE;
          $CALLBACK$(result);
        } catch (error) {
          // Handle error
        }
      }
    examples:
      - before: |
          function fetchData() {
            return fetch('https://api.example.com/data')
              .then(response => response.json())
              .then(data => console.log(data))
              .catch(error => console.error('Error:', error));
          }
        after: |
          async function fetchData() {
            try {
              const response = await fetch('https://api.example.com/data');
              const data = await response.json();
              console.log(data);
            } catch (error) {
              console.error('Error:', error);
            }
          }

  - id: no-async-in-promise-constructor
    description: "Avoid using async functions as Promise executors to prevent unhandled rejections."
    severity: error
    pattern: |
      new Promise(async ($RESOLVE$, $REJECT$) => {
        $BODY$
      });
    replacement: |
      new Promise(($RESOLVE$, $REJECT$) => {
        $BODY$
      });
    examples:
      - before: |
          new Promise(async (resolve, reject) => {
            const data = await fetchData();
            resolve(data);
          });
        after: |
          new Promise((resolve, reject) => {
            fetchData()
              .then(data => resolve(data))
              .catch(error => reject(error));
          });

  - id: no-await-in-loop
    description: "Avoid using await inside loops; instead, run asynchronous operations concurrently to improve performance."
    severity: warning
    pattern: |
      for ($VAR$ of $ITERABLE$) {
        const $RESULT$ = await $ASYNC_FUNC$($VAR$);
        $BODY$
      }
    replacement: |
      const promises = $ITERABLE$.map($VAR$ => $ASYNC_FUNC$($VAR$));
      const results = await Promise.all(promises);
      for (const $RESULT$ of results) {
        $BODY$
      }
    examples:
      - before: |
          for (const url of urls) {
            const response = await fetch(url);
            const data = await response.json();
            console.log(data);
          }
        after: |
          const promises = urls.map(url => fetch(url).then(response => response.json()));
          const data = await Promise.all(promises);
          data.forEach(item => console.log(item));

  - id: handle-errors-with-try-catch
    description: "Use try/catch blocks to handle errors in async functions to ensure proper error management."
    severity: error
    pattern: |
      async function $FUNC_NAME($PARAMS$) {
        const $RESULT$ = await $ASYNC_OPERATION$;
        $BODY$
      }
    replacement: |
      async function $FUNC_NAME($PARAMS$) {
        try {
          const $RESULT$ = await $ASYNC_OPERATION$;
          $BODY$
        } catch (error) {
          // Handle error
        }
      }
    examples:
      - before: |
          async function fetchData() {
            const response = await fetch('https://api.example.com/data');
            const data = await response.json();
            console.log(data);
          }
        after: |
          async function fetchData() {
            try {
              const response = await fetch('https://api.example.com/data');
              const data = await response.json();
              console.log(data);
            } catch (error) {
              console.error('Error fetching data:', error);
            }
          }

  - id: no-unnecessary-await
    description: "Avoid unnecessary use of await when the value is immediately returned; return the promise directly."
    severity: warning
    pattern: |
      async function $FUNC_NAME($PARAMS$) {
        return await $ASYNC_OPERATION$;
      }
    replacement: |
      async function $FUNC_NAME($PARAMS$) {
        return $ASYNC_OPERATION$;
      }
    examples:
      - before: |
          async function getUserData() {
            return await fetchUserData();
          }
        after: |
          async function getUserData() {
            return fetchUserData();
          }