AsyncGenerator.prototype.return()

Метод return() экземпляров AsyncGenerator действует так, как если бы в теле генератора в текущей приостановленной позиции была вставлена инструкция return, которая завершает работу генератора и позволяет ему выполнять любые задачи очистки при совместном использовании с блоком try...finally.

Синтаксис

asyncGeneratorInstance.return()
asyncGeneratorInstance.return(value)

Параметры

value Необязательный

Значение для возврата.

Возвращаемое значение

Объект Promise, который разрешается с объектом Object с двумя свойствами:

done

Булево значение:

• true, если поток управления функции-генератора достиг конца.
• false, если поток управления функции-генератора не достиг конца и может создавать больше значений. Это может произойти только в том случае, если return перехвачено в блоке try...finally и в блоке yield есть больше выражений finally.

value

Значение, переданное в качестве аргумента, или, если выражение yield обернуто в блок try...finally, значение, возвращенное из блока finally.

Описание

Метод return() при вызове можно рассматривать так, как будто в теле генератора в текущей приостановленной позиции вставлена инструкция return value;, где value — это значение, переданное методу return(). Поэтому, при обычном потоке выполнения, вызов return(value) вернет { done: true, value: value }. Однако, если выражение yield обернуто в блок try...finally, поток управления не выходит из тела функции, а вместо этого переходит к блоку finally. В этом случае возвращаемое значение может отличаться, а done может быть даже false, если в блоке yield есть другие выражения finally.

Примеры

Использование return()

Следующий пример демонстрирует асинхронный генератор и метод return.

// An async task. Pretend it's doing something more useful
// in practice.
function delayedValue(time, value) {
  return new Promise((resolve, reject) => {
    setTimeout(() => resolve(value), time);
  });
}

async function* createAsyncGenerator() {
  yield delayedValue(500, 1);
  yield delayedValue(500, 2);
  yield delayedValue(500, 3);
}

const asyncGen = createAsyncGenerator();
asyncGen.next().then((res) => console.log(res)); // { value: 1, done: false }
asyncGen.return("foo").then((res) => console.log(res)); // { value: "foo", done: true }
asyncGen.next().then((res) => console.log(res)); // { value: undefined, done: true }

Использование return() после завершения генератора

Если в метод value не передан аргумент return(), промис будет разрешен так, как если бы был вызван метод next(). В этом примере генератор завершил работу, поэтому возвращаемое значение равно undefined.

return() все еще можно вызвать после того, как генератор находится в состоянии "завершен", однако генератор останется в этом состоянии.

async function* createAsyncGenerator() {
  yield Promise.resolve(1);
  yield await Promise.resolve(2);
  yield 3;
}
const asyncGen = createAsyncGenerator();
asyncGen.next().then((res) => console.log(res)); // { value: 1, done: false }
asyncGen.next().then((res) => console.log(res)); // { value: 2, done: false }
asyncGen.next().then((res) => console.log(res)); // { value: 3, done: false }
// value is returned undefined, as no value is passed and generator is 'done'
asyncGen.return().then((res) => console.log(res)); // { value: undefined, done: true }
// we can still return a value once the generator is complete
asyncGen.return(1).then((res) => console.log(res)); // { value: 1, done: true }

Спецификации

Совместимость с браузерами

См. также

• async function*
• Руководство по итераторам и генераторам