feat(common): rename underlying NgFor class and add a type parameter (#14104)

Note, this affects the underlying class and should not affect usage.

DEPRECATION:
- the `NgFor` class is now deprecated. Use `NgForOf<T>` instead.
  IMPORTANT: Only the `NgFor` class is deprecated, not the `ngFor`
  directive. The `*ngFor` and related directives are unaffected by
  this change  as references to the `NgFor` class generated from
  templates will be automatically converted to references to
  `NgForOf<T>` without requiring any template modifications.
- `TrackByFn` is now deprecated. Use `TrackByFunction<T>` instead.

Migration:
- Replace direct references to the `NgFor` class to `NgForOf<any>`.
- Replace references to `TrackByFn` to `TrackByFunction<any>`.

BREAKING CHANGE:
A definition of `Iterable<T>` is now required to correctly compile
Angular applications. Support for `Iterable<T>` is not required at
runtime but a type definition `Iterable<T>` must be available.

`NgFor`, and now `NgForOf<T>`, already supports `Iterable<T>` at
runtime. With this change the type definition is updated to reflect
this support.

Migration:
- add "es2015.iterable.ts" to your tsconfig.json "libs" fields.

Part of #12398

PR Close #14104

modules/@angular/core/src/change_detection.ts

@@ -12,4 +12,4 @@
  * Change detection enables data binding in Angular.
  */
 
-export {ChangeDetectionStrategy, ChangeDetectorRef, CollectionChangeRecord, DefaultIterableDiffer, IterableChangeRecord, IterableChanges, IterableDiffer, IterableDifferFactory, IterableDiffers, KeyValueChangeRecord, KeyValueChanges, KeyValueDiffer, KeyValueDifferFactory, KeyValueDiffers, PipeTransform, SimpleChange, SimpleChanges, TrackByFn, WrappedValue} from './change_detection/change_detection';
+export {ChangeDetectionStrategy, ChangeDetectorRef, CollectionChangeRecord, DefaultIterableDiffer, IterableChangeRecord, IterableChanges, IterableDiffer, IterableDifferFactory, IterableDiffers, KeyValueChangeRecord, KeyValueChanges, KeyValueDiffer, KeyValueDifferFactory, KeyValueDiffers, NgIterable, PipeTransform, SimpleChange, SimpleChanges, TrackByFn, TrackByFunction, WrappedValue} from './change_detection/change_detection';

modules/@angular/core/src/change_detection/change_detection.ts

@@ -18,7 +18,7 @@ export {ChangeDetectionStrategy, ChangeDetectorStatus, isDefaultChangeDetectionS
 export {DefaultIterableDifferFactory} from './differs/default_iterable_differ';
 export {DefaultIterableDiffer} from './differs/default_iterable_differ';
 export {DefaultKeyValueDifferFactory} from './differs/default_keyvalue_differ';
-export {CollectionChangeRecord, IterableChangeRecord, IterableChanges, IterableDiffer, IterableDifferFactory, IterableDiffers, TrackByFn} from './differs/iterable_differs';
+export {CollectionChangeRecord, IterableChangeRecord, IterableChanges, IterableDiffer, IterableDifferFactory, IterableDiffers, NgIterable, TrackByFn, TrackByFunction} from './differs/iterable_differs';
 export {KeyValueChangeRecord, KeyValueChanges, KeyValueDiffer, KeyValueDifferFactory, KeyValueDiffers} from './differs/keyvalue_differs';
 export {PipeTransform} from './pipe_transform';
 

modules/@angular/core/src/change_detection/differs/default_iterable_differ.ts

@@ -10,13 +10,13 @@ import {isListLikeIterable, iterateListLike} from '../../facade/collection';
 import {isBlank, looseIdentical, stringify} from '../../facade/lang';
 import {ChangeDetectorRef} from '../change_detector_ref';
 
-import {IterableChangeRecord, IterableChanges, IterableDiffer, IterableDifferFactory, TrackByFn} from './iterable_differs';
+import {IterableChangeRecord, IterableChanges, IterableDiffer, IterableDifferFactory, NgIterable, TrackByFunction} from './iterable_differs';
 
 
 export class DefaultIterableDifferFactory implements IterableDifferFactory {
   constructor() {}
   supports(obj: Object): boolean { return isListLikeIterable(obj); }
-  create<V>(cdRef: ChangeDetectorRef, trackByFn?: TrackByFn): DefaultIterableDiffer<V> {
+  create<V>(cdRef: ChangeDetectorRef, trackByFn?: TrackByFunction<any>): DefaultIterableDiffer<V> {
     return new DefaultIterableDiffer<V>(trackByFn);
   }
 }
@@ -28,7 +28,7 @@ const trackByIdentity = (index: number, item: any) => item;
  */
 export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChanges<V> {
   private _length: number = null;
-  private _collection: V[]|Set<V>[]|any /* |Iterable<V> */ = null;
+  private _collection: NgIterable<V> = null;
   // Keeps track of the used records at any point in time (during & across `_check()` calls)
   private _linkedRecords: _DuplicateMap<V> = null;
   // Keeps track of the removed records at any point in time during `_check()` calls.
@@ -46,7 +46,7 @@ export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChan
   private _identityChangesHead: IterableChangeRecord_<V> = null;
   private _identityChangesTail: IterableChangeRecord_<V> = null;
 
-  constructor(private _trackByFn?: TrackByFn) {
+  constructor(private _trackByFn?: TrackByFunction<V>) {
     this._trackByFn = this._trackByFn || trackByIdentity;
   }
 
@@ -146,7 +146,7 @@ export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChan
     }
   }
 
-  diff(collection: V[]|Set<V>[]|any /* |Iterable<V> */): DefaultIterableDiffer<V> {
+  diff(collection: NgIterable<V>): DefaultIterableDiffer<V> {
     if (isBlank(collection)) collection = [];
     if (!isListLikeIterable(collection)) {
       throw new Error(`Error trying to diff '${collection}'`);
@@ -162,7 +162,7 @@ export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChan
   onDestroy() {}
 
   // todo(vicb): optim for UnmodifiableListView (frozen arrays)
-  check(collection: V[]|Set<V>[]|any /* |Iterable<V> */): boolean {
+  check(collection: NgIterable<V>): boolean {
     this._reset();
 
     let record: IterableChangeRecord_<V> = this._itHead;
@@ -171,11 +171,10 @@ export class DefaultIterableDiffer<V> implements IterableDiffer<V>, IterableChan
     let item: V;
     let itemTrackBy: any;
     if (Array.isArray(collection)) {
-      const list = collection as V[];
-      this._length = list.length;
+      this._length = collection.length;
 
       for (let index = 0; index < this._length; index++) {
-        item = list[index];
+        item = collection[index];
         itemTrackBy = this._trackByFn(index, item);
         if (record === null || !looseIdentical(record.trackById, itemTrackBy)) {
           record = this._mismatch(record, item, itemTrackBy, index);

modules/@angular/core/src/change_detection/differs/iterable_differs.ts

@@ -10,6 +10,12 @@ import {Optional, Provider, SkipSelf} from '../../di';
 import {getTypeNameForDebugging, isPresent} from '../../facade/lang';
 import {ChangeDetectorRef} from '../change_detector_ref';
 
+/**
+ * A type describing supported interable types.
+ *
+ * @stable
+ */
+export type NgIterable<T> = Array<T>| Iterable<T>;
 
 /**
  * A strategy for tracking changes over time to an iterable. Used by {@link NgFor} to
@@ -25,9 +31,7 @@ export interface IterableDiffer<V> {
    * @returns an object describing the difference. The return value is only valid until the next
    * `diff()` invocation.
    */
-  diff(object: V[]|Set<V>|any /* |Iterable<V> */): IterableChanges<V>;
-  // TODO(misko): We can't use Iterable as it would break the .d.ts file for ES5 users.
-  // Iterable is not apart of @types/es6-collections since it requires Symbol.
+  diff(object: NgIterable<V>): IterableChanges<V>;
 }
 
 /**
@@ -112,13 +116,19 @@ export interface CollectionChangeRecord<V> extends IterableChangeRecord<V> {}
 
 
 /**
- * An optional function passed into {@link NgFor} that defines how to track
- * items in an iterable (e.g. by index or id)
+ * Nolonger used.
  *
- * @stable
+ * @deprecated v4.0.0 - Use TrackByFunction instead
  */
 export interface TrackByFn { (index: number, item: any): any; }
 
+/**
+ * An optional function passed into {@link NgForOf} that defines how to track
+ * items in an iterable (e.g. fby index or id)
+ *
+ * @stable
+ */
+export interface TrackByFunction<T> { (index: number, item: T): any; }
 
 /**
  * Provides a factory for {@link IterableDiffer}.
@@ -127,7 +137,7 @@ export interface TrackByFn { (index: number, item: any): any; }
  */
 export interface IterableDifferFactory {
   supports(objects: any): boolean;
-  create<V>(cdRef: ChangeDetectorRef, trackByFn?: TrackByFn): IterableDiffer<V>;
+  create<V>(cdRef: ChangeDetectorRef, trackByFn?: TrackByFunction<V>): IterableDiffer<V>;
 }
 
 /**