feat(core): Add type information to injector.get() (#13785)

- Introduce `InjectionToken<T>` which is a parameterized and type-safe
  version of `OpaqueToken`.

DEPRECATION:
- `OpaqueToken` is now deprecated, use `InjectionToken<T>` instead.
- `Injector.get(token: any, notFoundValue?: any): any` is now deprecated
  use the same method which is now overloaded as
  `Injector.get<T>(token: Type<T>|InjectionToken<T>, notFoundValue?: T): T;`.

Migration
- Replace `OpaqueToken` with `InjectionToken<?>` and parameterize it.
- Migrate your code to only use `Type<?>` or `InjectionToken<?>` as
  injection tokens. Using other tokens will not be supported in the
  future.

BREAKING CHANGE:
- Because `injector.get()` is now parameterize it is possible that code
  which used to work no longer type checks. Example would be if one
  injects `Foo` but configures it as `{provide: Foo, useClass: MockFoo}`.
  The injection instance will be that of `MockFoo` but the type will be
  `Foo` instead of `any` as in the past. This means that it was possible
  to call a method on `MockFoo` in the past which now will fail type
  check. See this example:

```
class Foo {}
class MockFoo extends Foo {
  setupMock();
}

var PROVIDERS = [
  {provide: Foo, useClass: MockFoo}
];

...

function myTest(injector: Injector) {
  var foo = injector.get(Foo);
  // This line used to work since `foo` used to be `any` before this
  // change, it will now be `Foo`, and `Foo` does not have `setUpMock()`.
  // The fix is to downcast: `injector.get(Foo) as MockFoo`.
  foo.setUpMock();
}
```

PR Close #13785

modules/@angular/examples/core/di/ts/injector_spec.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {Injector, ReflectiveInjector} from '@angular/core';
+import {InjectionToken, Injector, ReflectiveInjector} from '@angular/core';
 
 export function main() {
   describe('injector metadata examples', () => {
@@ -25,7 +25,17 @@ export function main() {
       const injector = ReflectiveInjector.resolveAndCreate([]);
       expect(injector.get(Injector)).toBe(injector);
       // #enddocregion
+    });
 
+    it('should infer type', () => {
+      // #docregion InjectionToken
+      const BASE_URL = new InjectionToken<string>('BaseUrl');
+      const injector =
+          ReflectiveInjector.resolveAndCreate([{provide: BASE_URL, useValue: 'http://localhost'}]);
+      const url = injector.get(BASE_URL);
+      // here `url` is inferred to be `string` because `BASE_URL` is `InjectionToken<string>`.
+      expect(url).toBe('http://localhost');
+      // #enddocregion
     });
   });
 }

modules/@angular/examples/core/di/ts/provider_spec.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {Inject, Injectable, OpaqueToken, Optional, ReflectiveInjector} from '@angular/core';
+import {Inject, Injectable, InjectionToken, Optional, ReflectiveInjector} from '@angular/core';
 
 export function main() {
   describe('Provider examples', () => {
@@ -113,8 +113,8 @@ export function main() {
     describe('FactoryProvider', () => {
       it('works', () => {
         // #docregion FactoryProvider
-        const Location = new OpaqueToken('location');
-        const Hash = new OpaqueToken('hash');
+        const Location = new InjectionToken('location');
+        const Hash = new InjectionToken('hash');
 
         const injector = ReflectiveInjector.resolveAndCreate([
           {provide: Location, useValue: 'http://angular.io/#someLocation'}, {
@@ -130,8 +130,8 @@ export function main() {
 
       it('supports optional dependencies', () => {
         // #docregion FactoryProviderOptionalDeps
-        const Location = new OpaqueToken('location');
-        const Hash = new OpaqueToken('hash');
+        const Location = new InjectionToken('location');
+        const Hash = new InjectionToken('hash');
 
         const injector = ReflectiveInjector.resolveAndCreate([{
           provide: Hash,