Generator.prototype.return()
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2016年9月.
return() は Generator インスタンスのメソッドで、ジェネレーターの本体内で、現在の停止位置に return 文が挿入されたかのように振る舞い、これによりジェネレーターが完了します。また、try...finally ブロックと組み合わせることで、ジェネレーターがクリーンアップ処理を実行することができるようにします。
構文
generatorInstance.return()
generatorInstance.return(value)
引数
value省略可-
返却する値です。
返値
以下の 2 つのプロパティを持った Object です。
done-
論理値です。
- このジェネレーター関数の制御フローが末尾に達している場合、
trueになります。 - このジェネレーター関数の制御フローが末尾に達しておらず、さらに値を生成できる場合、
falseになります。これは、returnがtry...finallyで捕捉され、かつfinallyブロック内にさらにyield式が存在する場合にのみ発生します。
- このジェネレーター関数の制御フローが末尾に達している場合、
value-
引数として指定された値、または
yield式がtry...finallyで囲まれている場合、finallyブロックから yield/return で返された値。
例外
TypeError-
ジェネレーターが既に実行中である場合に発生します。
解説
return() メソッドが呼び出されると、ジェネレーターの本体内で現在中断された位置に return value; 文が挿入されたかのように見なされます。ここで value は return() メソッドに渡された値です。したがって、通常のフローでは、return(value) を呼び出すと { done: true, value: value } が返されます。ただし、yield 式が try...finally ブロックで囲まれている場合、制御フローは関数本体から抜けず、代わりに finally ブロックに進みます。この場合、返される値は異なる可能性があり、finally ブロック内にさらに yield 式がある場合、done が false になることもあります。
例
return() の使用
次の例では簡単なジェネレーターと return メソッドを示します。
function* gen() {
yield 1;
yield 2;
yield 3;
}
const g = gen();
g.next(); // { value: 1, done: false }
g.return("foo"); // { value: "foo", done: true }
g.next(); // { value: undefined, done: true }
return(value) がすでに "完了" の状態のジェネレーターで呼び出されると、ジェネレーターは "完了" の状態のままになります。
引数が提供されなかった場合、返却されるオブジェクトの value プロパティは .next() の場合と同じになります。引数が提供された場合は、返却されるオブジェクトの value プロパティの値に設定されます。
function* gen() {
yield 1;
yield 2;
yield 3;
}
const g = gen();
g.next(); // { value: 1, done: false }
g.next(); // { value: 2, done: false }
g.next(); // { value: 3, done: false }
g.next(); // { value: undefined, done: true }
g.return(); // { value: undefined, done: true }
g.return(1); // { value: 1, done: true }
return() と try...finally
return メソッドが呼び出された事実は、yield 式が try...finally ブロックで囲まれている場合にのみ、ジェネレーター自身で認識できます。
return メソッドが try ブロック内で一時停止されたジェネレーターに対して呼び出されると、ジェネレーター内の実行は finally ブロックに進みます。これは、try...finally 文では finally ブロックが常に実行されるためです。
function* gen() {
yield 1;
try {
yield 2;
yield 3;
} finally {
yield "cleanup";
}
}
const g1 = gen();
g1.next(); // { value: 1, done: false }
// 実行が try...finally の前で一時停止
g1.return("early return"); // { value: 'early return', done: true }
const g2 = gen();
g2.next(); // { value: 1, done: false }
g2.next(); // { value: 2, done: false }
// 実行が try...finally の中で一時停止
g2.return("early return"); // { value: 'cleanup', done: false }
// 完了値は保持される
g2.next(); // { value: 'early return', done: true }
// ジェネレーターは完了状態
g2.return("not so early return"); // { value: 'not so early return', done: true }
finally ブロックの返値は、return 呼び出しから返される結果の value にもなります。
function* gen() {
try {
yield 1;
} finally {
return "cleanup";
}
}
const generator = gen();
generator.next(); // { value: 1, done: false }
generator.return("early return"); // { value: 'cleanup', done: true }
仕様書
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-generator.prototype.return |