[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

@@ -61,8 +61,9 @@ declare class Object {
 
 // Well known Symbols.
 declare class $SymbolHasInstance mixins Symbol {}
-declare class $SymboIsConcatSpreadable mixins Symbol {}
+declare class $SymbolIsConcatSpreadable mixins Symbol {}
 declare class $SymbolIterator mixins Symbol {}
+declare class $SymbolAsyncIterator mixins Symbol {}
 declare class $SymbolMatch mixins Symbol {}
 declare class $SymbolReplace mixins Symbol {}
 declare class $SymbolSearch mixins Symbol {}
@@ -76,8 +77,9 @@ declare class Symbol {
   static (value?:any): Symbol;
   static for(key: string): Symbol;
   static hasInstance: $SymbolHasInstance;
-  static isConcatSpreadable: $SymboIsConcatSpreadable;
+  static isConcatSpreadable: $SymbolIsConcatSpreadable;
   static iterator: string; // polyfill '@@iterator'
+  static asyncIterator: $SymbolAsyncIterator;
   static keyFor(sym: Symbol): ?string;
   static length: 0;
   static match: $SymbolMatch;
@@ -547,20 +549,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 +573,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<Yield,Return,Next> {
+    @@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 */
 

newtests/array_literal_tuple_spread/test.js

@@ -261,8 +261,8 @@ export default suite(({addFile, addFiles, addCode}) => [
           test.js:3
             3: const arr: Array<number> = [..."hello"];
                                 ^^^^^^ number. This type is incompatible with
-          276:     @@iterator(): Iterator<string>;
-                                          ^^^^^^ string. See lib: [LIB] core.js:276
+          278:     @@iterator(): Iterator<string>;
+                                          ^^^^^^ string. See lib: [LIB] core.js:278
         `,
       )
       .because('String is an Iterable<string>'),