JavaScript AsyncGenerator return() Method

Beginner
6 min read
Updated: Nov 2026
3 examples
AsyncGenerator

Definition

asyncGenerator.return(value) finishes an async generator from the outside. At a paused yield it acts like a return value; statement: surrounding finally blocks run first (your cleanup), then the Promise resolves to { value, done: true }.

If value is a promise, it is awaited first. for await...of calls return() automatically when you break, return or throw out of the loop; call it yourself when you drive the generator with next() and want to stop early.

Remember
await gen.return("bye")  → { value: "bye", done: true }

paused inside try    → finally runs first (cleanup)
not started yet      → body never runs, done at once
already finished     → still { value, done: true }
next() afterwards    → { value: undefined, done: true }

for await...of + break → calls return() for you

Syntax

Call return() on the generator object when you want it to stop. Await the result to know that cleanup has finished.

JavaScript
const gen = myAsyncGenerator();

await gen.next();
const result = await gen.return(value);
CallWhat it does
asyncGenerator.return()Finish now; resolves to { value: undefined, done: true }.
asyncGenerator.return(value)Finish now and report value (a promise is awaited).
for await (const x of gen) { break; }The loop calls gen.return() for you.

Built into JavaScript (ES2018); no import required. Siblings: next() and throw().

Library declarations
JavaScript
// AsyncGenerator.prototype.return (ES2018)
asyncGenerator.return()
asyncGenerator.return(value)

// returns Promise<{ value: any, done: boolean }>
// usually { value, done: true }

Parameters

ParameterDescription
valueOptional. The final result to report; a promise is awaited first. Defaults to undefined.

Return Value

Return ValueDescription
Promise of { value, done: true }The usual case: finished, and value is your (awaited) argument.
Promise of { value, done: false }Rare: a finally block yields, so the generator stays alive until it completes.
Rejected promiseA finally block threw, or you passed a rejected promise the generator did not catch.

JavaScript Examples

Example 1 — Stop Early and Close the Connection

Read one message, then call return(). The finally block runs before the promise resolves.

JavaScript
async function* readMessages() {
  console.log("open connection");
  try {
    yield "hello";
    yield "how are you?";
    yield "bye";
  } finally {
    console.log("close connection");
  }
}

async function run() {
  const chat = readMessages();
  const first = await chat.next();
  console.log("got: " + first.value);

  const stopped = await chat.return("stopped early");
  console.log("return(): " + stopped.value + ", done: " + stopped.done);

  const after = await chat.next();
  console.log("next(): " + after.value + ", done: " + after.done);
}

run();
Try It Yourself

How It Works

  1. Paused inside try. After the first next(), the generator waits at yield "hello", which sits inside the try block.
  2. Cleanup before the answer. return("stopped early") leaves the try block, so "close connection" is printed before the promise resolves.
  3. Finished for good. The two remaining messages are never produced; a later next() only reports undefined and done: true.

Example 2 — break in for await...of Calls return()

An endless sensor feed stops cleanly when the loop body uses break; you never call return() yourself.

JavaScript
async function* sensor() {
  let reading = 20;
  try {
    while (true) {
      await new Promise((resolve) => setTimeout(resolve, 2));
      yield reading++;
    }
  } finally {
    console.log("sensor stopped");
  }
}

async function run() {
  for await (const temp of sensor()) {
    console.log("temperature: " + temp);
    if (temp >= 22) break;
  }
  console.log("loop finished");
}

run();
Try It Yourself

How It Works

  1. An endless feed. while (true) would yield readings forever; the loop body decides when enough is enough.
  2. break triggers return(). At 22 the break makes for await...of call return() on the generator behind the scenes.
  3. Cleanup is awaited. "sensor stopped" appears before "loop finished", because the loop waits for return() to settle before moving on.

Example 3 — return() Before the First next()

Cancel a generator that never started. Its body, including the finally block, does not run at all.

JavaScript
async function* loadSettings() {
  console.log("loading settings...");
  try {
    yield "theme: dark";
  } finally {
    console.log("finally ran");
  }
}

async function run() {
  const settings = loadSettings();
  const result = await settings.return(Promise.resolve("cancelled"));
  console.log("value: " + result.value + ", done: " + result.done);

  const later = await settings.next();
  console.log("next(): " + later.value + ", done: " + later.done);
}

run();
Try It Yourself

How It Works

  1. Never started. loadSettings() only created the object; not a single line of its body has run yet.
  2. Promise argument. return(Promise.resolve("cancelled")) awaits that promise, so the result holds the plain string "cancelled".
  3. Nothing to clean up. Neither "loading settings..." nor "finally ran" is printed: the try block was never entered, so its finally has nothing to do.

Browser & Runtime Support

AsyncGenerator.prototype.return() is part of async iteration in ES2018. The automatic call on break comes from for await...of, added in the same edition.

✓ Baseline · ES2018

AsyncGenerator.prototype.return()

Supported in Chrome 63+, Firefox 57+ (with for await...of), Safari 12+, Edge 79+, and Node.js 10+. Not available in Internet Explorer.

96% Modern browser support
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
AsyncGenerator return() Excellent

Bottom line: Safe in every current browser and Node.js LTS release. Early engines differed in small details, such as when a promise passed to return() is awaited; current engines agree, and the outputs above come from Node.js 24.

Frequently Asked Questions

It finishes the generator from the outside. At a paused yield it acts like a return statement: finally blocks run, then the promise resolves to { value, done: true }. Later next() calls resolve to { value: undefined, done: true }.
Yes, when the generator is paused inside a try block that has a finally, which is the main reason to use it: closing files, connections or timers. If the generator has not started yet, nothing in its body runs.
Yes. Leaving the loop early with break, return, or an error makes for await...of call return() and wait for it. When the loop ends normally the generator is already finished, so no call is needed.
The argument you pass, wrapped in { value, done: true }. A promise argument is awaited first. With no argument, value is undefined.
Not immediately. The request is queued until the current await finishes and the generator reaches its next yield; the return happens there. To cancel the slow operation itself, the awaited code must support cancellation, for example with an AbortController signal.

Next: throw()

Learn how to send an error into a paused async generator and let it recover or stop.

throw() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

12 people found this page helpful