ES6 async function

1. Meaning

ES2017 standard introduces async making asynchronous operation easier.

What is the async function? In a word, it's the Generator sugar of the Generator 语法糖

The previous version has a Generator function that reads two files in turn.

const fs = require('fs');
const readFile = function (fileName) {
  return new Promise(function (resolve, reject) {
    fs.readFile(fileName, function(error, data) {
      if (error) return reject(error);
      resolve(data);
    });
  });
};
const gen = function* () {
  const f1 = yield readFile('/etc/fstab');
  const f2 = yield readFile('/etc/shells');
  console.log(f1.toString());
  console.log(f2.toString());
};

The function gen of the gen can be written as async function, and that's it.

const asyncReadFile = async function () {
  const f1 = await readFile('/etc/fstab');
  const f2 = await readFile('/etc/shells');
  console.log(f1.toString());
  console.log(f2.toString());
};

A comparison reveals that the async function replaces the generator function's asterisk with async and yield with await, that's all.

The improvement of the Generator function by the async function is reflected in the following four points.

(1) Built-in executor.

Generator functions must be executed by the executor, so there is a co module, and the async function brings its own executor. That is, the execution of the async function is exactly the same as the normal function, as long as one line.

asyncReadFile();

The code above calls the asyncReadFile function, and then it executes automatically, outputing the final result. This is not like the Generator function at all, you need to call the next method, or use the co module, to actually execute and get the final result.

(2) Better semantics.

Async and await, the semantics are clearer than the asterisks and yields. Async indicates that there are asynchronous operations in the function, and await indicates that the expression that follows needs to wait for the result.

(3) Wider applicability.

The co module convention states that the yield command can only be followed by the Thunk function or the Promise object, while the await command of the async function can be followed by the Value of the Promise object and the value of the original type (values, strings, and Boolean values, but this is automatically converted to the Promise object of the immediate resolved).

(4) The return value is Promise.

The return value of the async function is the Promise object, which is much more convenient than the Generator function's return value is the Iterator object. You can specify the next step in the then method.

Further, the async function can be thought of as multiple asynchronous operations, wrapped as a Promise object, and the await command is the syntax sugar of the internal then command.

Basic usage

async function returns a Promise and you can use then method to add a callback function. When a function executes, it returns once it encounters await, waits until the asynchronous operation is complete, and then executes the statement that follows the function body.

Here's an example.

async function getStockPriceByName(name) {
  const symbol = await getStockSymbol(name);
  const stockPrice = await getStockPrice(symbol);
  return stockPrice;
}
getStockPriceByName('goog').then(function (result) {
  console.log(result);
});

The above code is a function for getting stock quotes, and the async keyword preceding the function indicates that there are asynchronous operations inside the function. When the function is called, a Promise object is returned immediately.

Here's another example, specifying how many milliseconds to output a value.

function timeout(ms) {
  return new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}
async function asyncPrint(value, ms) {
  await timeout(ms);
  console.log(value);
}
asyncPrint('hello world', 50);

The above code specifies that after 50 milliseconds, the hello world is output.

Because the async function returns a Promise object, it can be used as an argument to the await command. Therefore, the above example can also be written in the following form.

async function timeout(ms) {
  await new Promise((resolve) => {
    setTimeout(resolve, ms);
  });
}
async function asyncPrint(value, ms) {
  await timeout(ms);
  console.log(value);
}
asyncPrint('hello world', 50);

Async functions come in many forms of use.

// 函数声明
async function foo() {}
// 函数表达式
const foo = async function () {};
// 对象的方法
let obj = { async foo() {} };
obj.foo().then(...)
// Class 的方法
class Storage {
  constructor() {
    this.cachePromise = caches.open('avatars');
  }
  async getAvatar(name) {
    const cache = await this.cachePromise;
    return cache.match(`/avatars/${name}.jpg`);
  }
}
const storage = new Storage();
storage.getAvatar('jake').then(…);
// 箭头函数
const foo = async () => {};

3. Grammar

The syntax rules of the async function are generally simple, and the difficulty is the error handling mechanism.

Returns the Promise object

async function returns a Promise object.

The value returned by the return the async function becomes then to the then method callback function.

async function f() {
  return 'hello world';
}
f().then(v => console.log(v))
// "hello world"

In the above code, the value returned by the function f internal return command is received by the then method callback function.

async inside the async function causes the Promise object to become reject The wrong object thrown is received by the catch method callback function.

async function f() {
  throw new Error('出错了');
}
f().then(
  v => console.log(v),
  e => console.log(e)
)
// Error: 出错了

The state of the Promise object changes

async by the async function must wait until the Promise object behind all internal await commands has been executed before a state change occurs unless a return statement is encountered or an error is thrown. That is, the callback function specified by the then method is executed only after the asynchronous operation inside the async function has been performed.

Here's an example.

async function getTitle(url) {
  let response = await fetch(url);
  let html = await response.text();
  return html.match(/<title>([\s\S]+)<\/title>/i)[1];
}
getTitle('https://tc39.github.io/ecma262/').then(console.log)
// "ECMAScript 2017 Language Specification"

In the code above, the getTitle has three actions inside: 抓取网页 the 取出文本 match the page 匹配页面标题 Only when all three operations are complete will the console in the then method be .log.

await command

Normally, await command is followed by a Promise Promise that returns the result of that object. If it is not a Promise object, the corresponding value is returned directly.

async function f() {
  // 等同于
  // return 123;
  return await 123;
}
f().then(v => console.log(v))
// 123

In the code above, the parameter of the await command is the value 123, which is equivalent to return 123.

In another case, the await command is followed by a thenable object (that is, an object that defines the then method), and await equates it with a Promise object.

class Sleep {
  constructor(timeout) {
    this.timeout = timeout;
  }
  then(resolve, reject) {
    const startTime = Date.now();
    setTimeout(
      () => resolve(Date.now() - startTime),
      this.timeout
    );
  }
}
(async () => {
  const sleepTime = await new Sleep(1000);
  console.log(sleepTime);
})();
// 1000

In the code above, the await command is followed by an instance of a Sleep object. This instance is not a Promise object, but because the then method is defined, await treats it as Promise processing.

This example also shows how to achieve hibernation. J avaScript has never had a sleeping syntax, but with the await command you can pause the program for a specified amount of time. A simplified sleep implementation is given below.

function sleep(interval) {
  return new Promise(resolve => {
    setTimeout(resolve, interval);
  })
}
// 用法
async function one2FiveInAsync() {
  for(let i = 1; i <= 5; i++) {
    console.log(i);
    await sleep(1000);
  }
}
one2FiveInAsync();

If the Promise object after the await command changes to a reject state, the parameters of the reject are received by the callback function of the catch method.

async function f() {
  await Promise.reject('出错了');
}
f()
.then(v => console.log(v))
.catch(e => console.log(e))
// 出错了

Note that in the code above, there is no return before the await statement, but the parameters of the reject method are still passed in to the callback function of the catch method. Here, if you add return before await, the effect is the same.

If the Promise object after any await statement becomes reject, the entire async function interrupts execution.

async function f() {
  await Promise.reject('出错了');
  await Promise.resolve('hello world'); // 不会执行
}

In the above code, the second await statement is not executed because the first await statement state becomes reject.

Sometimes, we want to not interrupt the asynchronous operation even if the previous asynchronous operation fails. T he first await can then be placed in try... inside the catch structure, so that the second await is executed regardless of whether the asynchronous operation succeeds or not.

async function f() {
  try {
    await Promise.reject('出错了');
  } catch(e) {
  }
  return await Promise.resolve('hello world');
}
f()
.then(v => console.log(v))
// hello world

Another approach is for the Promise object after await to follow a catch method to handle previous errors.

async function f() {
  await Promise.reject('出错了')
    .catch(e => console.log(e));
  return await Promise.resolve('hello world');
}
f()
.then(v => console.log(v))
// 出错了
// hello world

Error handling

If an asynchronous operation after await goes wrong, the Promise object returned by the async function is rejected.

async function f() {
  await new Promise(function (resolve, reject) {
    throw new Error('出错了');
  });
}
f()
.then(v => console.log(v))
.catch(e => console.log(e))
// Error：出错了

In the above code, after the async function f is executed, the Promise object behind await throws an error object, causing the callback function of the catch method to be called, and its argument is the wrong object thrown. Specific execution mechanism, you can refer to the following "async function implementation principle."

The way to prevent errors is also to put them in try... catch code block.

async function f() {
  try {
    await new Promise(function (resolve, reject) {
      throw new Error('出错了');
    });
  } catch(e) {
  }
  return await('hello world');
}

If you have more than one await command, you can place it uniformly in try... catch structure.

async function main() {
  try {
    const val1 = await firstStep();
    const val2 = await secondStep(val1);
    const val3 = await thirdStep(val1, val2);
    console.log('Final: ', val3);
  }
  catch (err) {
    console.error(err);
  }
}

The following example uses try... catch structure, implementing multiple repeated attempts.

const superagent = require('superagent');
const NUM_RETRIES = 3;
async function test() {
  let i;
  for (i = 0; i < NUM_RETRIES; ++i) {
    try {
      await superagent.get('http://google.com/this-throws-an-error');
      break;
    } catch(err) {}
  }
  console.log(i); // 3
}
test();

In the above code, if the await operation succeeds, the loop is exited with a break statement, and if it fails, it is captured by the catch statement and then goes to the next loop.

Use attention points

First, as already said earlier, the Promise object behind the await command may run as a rejected result, so it's best to put the await command in try... catch code block.

async function myFunction() {
  try {
    await somethingThatReturnsAPromise();
  } catch (err) {
    console.log(err);
  }
}
// 另一种写法
async function myFunction() {
  await somethingThatReturnsAPromise()
  .catch(function (err) {
    console.log(err);
  });
}

Second, asynchronous operations following multiple await commands are best triggered at the same time if there is no secondary relationship.

let foo = await getFoo();
let bar = await getBar();

In the code above, getFoo and getBar are two separate asynchronous operations (i.e., not dependent on each other) that are written as secondary relationships. This is time-consuming because getBar is not executed until getFoo is complete, and they can be triggered at the same time.

// 写法一
let [foo, bar] = await Promise.all([getFoo(), getBar()]);
// 写法二
let fooPromise = getFoo();
let barPromise = getBar();
let foo = await fooPromise;
let bar = await barPromise;

Both of these writings, getFoo and getBar, are triggered at the same time, which shortens the execution time of the program.

Third, the await command can only be used in async functions, and if used in normal functions, errors are reported.

async function dbFuc(db) {
  let docs = [{}, {}, {}];
  // 报错
  docs.forEach(function (doc) {
    await db.post(doc);
  });
}

The above code will report an error because await is used in normal functions. However, there is a problem if you change the parameters of the forEach method to the async function.

function dbFuc(db) { //这里不需要 async
  let docs = [{}, {}, {}];
  // 可能得到错误结果
  docs.forEach(async function (doc) {
    await db.post(doc);
  });
}

The above code may not work because the three db.post operations will be performed in a synth, that is, at the same time, rather than as a secondary execution. The correct way to write is to use the for loop.

async function dbFuc(db) {
  let docs = [{}, {}, {}];
  for (let doc of docs) {
    await db.post(doc);
  }
}

Another approach is to use the array's reduce method.

async function dbFuc(db) {
  let docs = [{}, {}, {}];
  await docs.reduce(async (_, doc) => {
    await _;
    await db.post(doc);
  }, undefined);
}

In the example above, the first argument of the reduce method is the async function, so the first argument of the function is the Promise object returned by the previous operation, so you must wait for the operation to end with await. In addition, the reduce method returns the result of the execution of the async function of the last member of the docs array, and is also a Promise object, resulting in the addition of await before it.

If you do want multiple requests to execute in a synth, you can use the Promise.all method. When all three requests are resolved, the following two are written in the same way.

async function dbFuc(db) {
  let docs = [{}, {}, {}];
  let promises = docs.map((doc) => db.post(doc));
  let results = await Promise.all(promises);
  console.log(results);
}
// 或者使用下面的写法
async function dbFuc(db) {
  let docs = [{}, {}, {}];
  let promises = docs.map((doc) => db.post(doc));
  let results = [];
  for (let promise of promises) {
    results.push(await promise);
  }
  console.log(results);
}

Fourth, the async function preserves the run stack.

const a = () => {
  b().then(() => c());
};

In the above code, function a runs an asynchronous task b() inside. W hen b() runs, function a() does not break, but continues. B y the end of the b() run, it is possible that a() the run is over and the context in which b() is located has disappeared. If b() or c () is reported as incorrect, the error stack will not include a().

Now change this example to the async function.

const a = async () => {
  await b();
  c();
};

In the code above, when b() is running, a() is suspended and the context is saved. Once b() or c () is reported, the error stack will include a().

4. How the async function is implemented

The implementation principle of the async function is to Generator function and the 自动执行器 in a function.

async function fn(args) {
  // ...
}
// 等同于
function fn(args) {
  return spawn(function* () {
    // ...
  });
}

All async functions can be written in the second form above, where the spawn function is an auto-executor.

Here is the implementation of the spawn function, which is basically a remake of the previous auto-executor.

function spawn(genF) {
  return new Promise(function(resolve, reject) {
    const gen = genF();
    function step(nextF) {
      let next;
      try {
        next = nextF();
      } catch(e) {
        return reject(e);
      }
      if(next.done) {
        return resolve(next.value);
      }
      Promise.resolve(next.value).then(function(v) {
        step(function() { return gen.next(v); });
      }, function(e) {
        step(function() { return gen.throw(e); });
      });
    }
    step(function() { return gen.next(undefined); });
  });
}

5. Comparison with other asynchronous processing methods

Let's look at an example of async function Promise to Generator and Generator functions.

Assuming that a DOM element is above, a series of animations are deployed, and the previous animation ends before the latest one can begin. If one of the animations goes wrong, it no longer executes down, returning the return value of the previous successfully executed animation.

The first is how Promise is written.

function chainAnimationsPromise(elem, animations) {
  // 变量ret用来保存上一个动画的返回值
  let ret = null;
  // 新建一个空的Promise
  let p = Promise.resolve();
  // 使用then方法，添加所有动画
  for(let anim of animations) {
    p = p.then(function(val) {
      ret = val;
      return anim(elem);
    });
  }
  // 返回一个部署了错误捕捉机制的Promise
  return p.catch(function(e) {
    /* 忽略错误，继续执行 */
  }).then(function() {
    return ret;
  });
}

Although Promise's writing is much better than that of callback functions, at first glance, the code looks entirely like Promise's API (then, catch, and so on), and the semantics of the operation itself are not easy to see.

This is followed by the writing of the Generator function.

function chainAnimationsGenerator(elem, animations) {
  return spawn(function*() {
    let ret = null;
    try {
      for(let anim of animations) {
        ret = yield anim(elem);
      }
    } catch(e) {
      /* 忽略错误，继续执行 */
    }
    return ret;
  });
}

The above code traverses each animation using the Generator function, the semantics are clearer than the Promise write, and all user-defined actions appear inside the spawn function. The problem with this writing is that there must be a task operator that automates the Generator function, and the spawn function in the code above is the auto-executor, which returns a Promise object, and must guarantee that the expression after the yield statement must return a Promise.

Finally, the async function is written.

async function chainAnimationsAsync(elem, animations) {
  let ret = null;
  try {
    for(let anim of animations) {
      ret = await anim(elem);
    }
  } catch(e) {
    /* 忽略错误，继续执行 */
  }
  return ret;
}

You can see that the Implementation of the Async function is the most concise, semantic, and has almost no semantic irrelevant code. I t changes the auto actuator in generator writing to be available at the language level and is not exposed to the user, so the amount of code is minimal. If you use generator writing, the auto-acter needs to be provided by the user.

6. Example: Asynchronous operations are completed in order

In real-world development, you often encounter a set of asynchronous operations that need to be done sequentially. For example, read a set of URLs remotely in turn, and then output the results in the order in which they were read.

Promise is written as follows.

function logInOrder(urls) {
  // 远程读取所有URL
  const textPromises = urls.map(url => {
    return fetch(url).then(response => response.text());
  });
  // 按次序输出
  textPromises.reduce((chain, textPromise) => {
    return chain.then(() => textPromise)
      .then(text => console.log(text));
  }, Promise.resolve());
}

The code above uses the fetch method while remotely reading a set of URLs. E ach fetch operation returns a Promise object and puts it into a textPromises array. The reduce method then processes each Promise object in turn, and then uses then to connect all Promise objects so that you can output the results in turn.

This kind of writing is not very intuitive and the readability is poor. Here's the async function implementation.

async function logInOrder(urls) {
  for (const url of urls) {
    const response = await fetch(url);
    console.log(await response.text());
  }
}

The code above is really simplified, and the problem is that all remote operations are secondary. O nly if the previous URL returns the result will the next URL be read, which is inefficient and a waste of time. What we need is to make remote requests in a synth.

async function logInOrder(urls) {
  // 并发读取远程URL
  const textPromises = urls.map(async url => {
    const response = await fetch(url);
    return response.text();
  });
  // 按次序输出
  for (const textPromise of textPromises) {
    console.log(await textPromise);
  }
}

In the above code, although the parameter of the map method is the async function, it is executed in a synth because only the inside of the async function is a secondary execution and the externality is not affected. B ack for: Await is used inside the of the loop, so sequential output is implemented.

7. Top-level await

Depending on the syntax specification, the await command can only appear inside the async function, otherwise errors will be reported.

// 报错
const data = await fetch('https://api.example.com');

In the above code, the await command is used independently and is not placed in the async function, which will report an error.

Currently, there is a syntax proposal that allows the await command to be used independently at the top of the module so that the above line of code is not misalmented. The purpose of this proposal is to borrow await to solve the problem of asynchronous loading of modules.

// awaiting.js
let output;
async function main() {
  const dynamic = await import(someMission);
  const data = await fetch(url);
  output = someProcess(dynamic.default, data);
}
main();
export { output };

In the code above, the output value .js of the module awaiting is output, depending on the asynchronous operation. We wrap the asynchronous operation in an async function, and then call the function, and only if all the asynchronous operations inside are performed, the variable output will have a value, otherwise we will return undefined.

The above code can also be written in the form of an immediate execution function.

// awaiting.js
let output;
(async function1 main() {
  const dynamic = await import(someMission);
  const data = await fetch(url);
  output = someProcess(dynamic.default, data);
})();
export { output };

Here's how to load this module.

// usage.js
import { output } from "./awaiting.js";
function outputPlusValue(value) { return output + value }
console.log(outputPlusValue(100));
setTimeout(() => console.log(outputPlusValue(100), 1000);

In the code above, the result of the execution of outputPlusValue() depends entirely on the time of execution. If the .js the asynchronous operation inside the content is not completed, the value of the output loaded in is undefined.

The current solution is to let the original module output a Promise object from which to determine if the asynchronous operation is over.

// awaiting.js
let output;
export default (async function main() {
  const dynamic = await import(someMission);
  const data = await fetch(url);
  output = someProcess(dynamic.default, data);
})();
export { output };

In the above code, the awaiting.js in addition to output output, also outputs a Promise object by default (after the async function executes immediately, returns a Promise object) from which to determine whether the asynchronous operation ends.

Here's a new way to load this module.

// usage.js
import promise, { output } from "./awaiting.js";
function outputPlusValue(value) { return output + value }
promise.then(() => {
  console.log(outputPlusValue(100));
  setTimeout(() => console.log(outputPlusValue(100), 1000);
});

In the code above, the output of the .js is placed inside promise.then(), which ensures that the output is read only after the asynchronous operation is complete.

This writing is cumbersome and requires the user of the module to comply with an additional usage protocol and use the module in a special way. O nce you forget to load with Promise, using only the normal loading method, the code that depends on the module can go wrong. Also, if the .js above has external output, all modules of this dependency chain are loaded with Promise.

The await command at the top is to solve this problem. It guarantees that the module will output values only if the asynchronous operation is complete.

// awaiting.js
const dynamic = import(someMission);
const data = fetch(url);
export const output = someProcess((await dynamic).default, await data);

In the code above, both asynchronous operations are added to the await command at the output. The module will not output values until the asynchronous operation is complete.

Loading this module is written as follows.

// usage.js
import { output } from "./awaiting.js";
function outputPlusValue(value) { return output + value }
console.log(outputPlusValue(100));
setTimeout(() => console.log(outputPlusValue(100), 1000);

The above code is written exactly the same as a normal module load. That is to say, the user of the module does not care at all, depending on the internal of the module there is no asynchronous operation, normal loading can be.

At this point, the module loads and waits for the asynchronous operation of the dependent module (in the case of awaiting.js above) to complete before executing the subsequent code, a bit like pausing there. Therefore, it always gets the correct output and does not get different values because of the different loading times.

Here are some usage scenarios for top-level await.

// import() 方法加载
const strings = await import( /i18n/${navigator.language} );
// 数据库操作
const connection = await dbConnector();
// 依赖回滚
let jQuery;
try {
  jQuery = await import('https://cdn-a.com/jQuery');
} catch {
  jQuery = await import('https://cdn-b.com/jQuery');
}

Note that if you load more than one module that contains the top-level await command, the load command is executed synchronously.

// x.js
console.log("X1");
await new Promise(r => setTimeout(r, 1000));
console.log("X2");
// y.js
console.log("Y");
// z.js
import "./x.js";
import "./y.js";
console.log("Z");

The code above has three modules, the last z.js loads x.js and y .js, and the print results are X1, Y, X2, Z. This means that the z.js t wait for the x.js load to complete before loading the y.js.

The await command at the top level is a bit like handing over the execution power of the code to the other modules to load, and when the asynchronous operation is complete, take back the execution power and continue down.

Table of contents