[RFC] Improve core types for (Async) Iterable/Iterator/Generator

* Changes `@@iterator` method to return more specific type in Generators.
* An `$Iterator` is an `$Iterable`
* Add optional `return` and `throw` methods to `$Iterator` (http://www.ecma-international.org/ecma-262/7.0/#table-54)
* A `$Generator` is an `$Iterator`
* Fix mistaken function name to `$asyncIterate` to match style of `$iterate`.

Author: leebyron

lib/core.js

@@ -547,20 +547,22 @@ type IteratorResult<Yield,Return> =
   | { done: true, value?: Return }
   | { done: false, value: Yield };
 
-interface $Iterator<+Yield,+Return,-Next> {
-    @@iterator(): $Iterator<Yield,Return,Next>;
-    next(value?: Next): IteratorResult<Yield,Return>;
-}
-type Iterator<+T> = $Iterator<T,void,void>;
-
 interface $Iterable<+Yield,+Return,-Next> {
     @@iterator(): $Iterator<Yield,Return,Next>;
 }
 type Iterable<+T> = $Iterable<T,void,void>;
 
-interface Generator<+Yield,+Return,-Next> {
+interface $Iterator<+Yield,+Return,-Next> extends $Iterable<Yield,Return,Next> {
     @@iterator(): $Iterator<Yield,Return,Next>;
     next(value?: Next): IteratorResult<Yield,Return>;
+    +return?: <R>(value: R) => IteratorResult<Yield,R|Return>;
+    +throw?: (error?: any) => IteratorResult<Yield,Return>;
+}
+type Iterator<+T> = $Iterator<T,void,void>;
+
+interface Generator<+Yield,+Return,-Next> extends $Iterator<Yield,Return,Next> {
+    @@iterator(): Generator<Yield,Return,Next>;
+    next(value?: Next): IteratorResult<Yield,Return>;
     return<R>(value: R): IteratorResult<Yield,R|Return>;
     throw(error?: any): IteratorResult<Yield,Return>;
 }
@@ -569,25 +571,27 @@ declare function $iterate<T>(p: Iterable<T>): T;
 
 /* Async Iterable/Iterator/Generator */
 
-interface $AsyncIterator<+Yield,+Return,-Next> {
-    @@asyncIterator(): $AsyncIterator<Yield,Return,Next>;
-    next(value?: Next): Promise<IteratorResult<Yield,Return>>;
-}
-type AsyncIterator<+T> = $AsyncIterator<T,void,void>;
-
 interface $AsyncIterable<+Yield,+Return,-Next> {
     @@asyncIterator(): $AsyncIterator<Yield,Return,Next>;
 }
 type AsyncIterable<+T> = $AsyncIterable<T,void,void>;
 
-interface AsyncGenerator<+Yield,+Return,-Next> {
+interface $AsyncIterator<+Yield,+Return,-Next> extends $AsyncIterable<Yield,Return,Next> {
     @@asyncIterator(): $AsyncIterator<Yield,Return,Next>;
     next(value?: Next): Promise<IteratorResult<Yield,Return>>;
+    +return?: <R>(value: R) => Promise<IteratorResult<Yield,R|Return>>;
+    +throw?: (error?: any) => Promise<IteratorResult<Yield,Return>>;
+}
+type AsyncIterator<+T> = $AsyncIterator<T,void,void>;
+
+interface AsyncGenerator<+Yield,+Return,-Next> extends $AsyncIterator {
+    @@asyncIterator(): AsyncGenerator<Yield,Return,Next>;
+    next(value?: Next): Promise<IteratorResult<Yield,Return>>;
     return<R>(value: R): Promise<IteratorResult<Yield,R|Return>>;
     throw(error?: any): Promise<IteratorResult<Yield,Return>>;
 }
 
-declare function $asyncIterator<T>(p: AsyncIterable<T>): T;
+declare function $asyncIterate<T>(p: AsyncIterable<T>): T;
 
 /* Maps and Sets */