feat(ngUpgrade): add support for AoT compiled upgrade applications

This commit introduces a new API to the ngUpgrade module, which is compatible
with AoT compilation. Primarily, it removes the dependency on reflection
over the Angular 2 metadata by introducing an API where this information
is explicitly defined, in the source code, in a way that is not lost through
AoT compilation.

This commit is a collaboration between @mhevery (who provided the original
design of the API); @gkalpak & @petebacondarwin (who implemented the
API and migrated the specs from the original ngUpgrade tests) and @alexeagle
(who provided input and review).

This commit is an starting point, there is still work to be done:

* add more documentation
* validate the API via internal projects
* align the ngUpgrade compilation of A1 directives closer to the real A1
  compiler
* add more unit tests
* consider support for async `templateUrl` A1 upgraded components

Closes #12239

karma-js.conf.js

@@ -23,7 +23,7 @@ module.exports = function(config) {
 
       'node_modules/core-js/client/core.js',
       // include Angular v1 for upgrade module testing
-      'node_modules/angular/angular.min.js',
+      'node_modules/angular/angular.js',
 
       'node_modules/zone.js/dist/zone.js', 'node_modules/zone.js/dist/long-stack-trace-zone.js',
       'node_modules/zone.js/dist/proxy.js', 'node_modules/zone.js/dist/sync-test.js',

modules/@angular/upgrade/index.ts

@@ -12,5 +12,5 @@
  * Entry point for all public APIs of the upgrade package.
  */
 export * from './src/upgrade';
-
+export * from './src/aot';
 // This file only reexports content of the `src` folder. Keep it that way.

modules/@angular/upgrade/src/angular_js.ts

@@ -6,20 +6,28 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+export type Ng1Token = string;
+
+export interface IAnnotatedFunction extends Function { $inject?: Ng1Token[]; }
+
+export type IInjectable = (Ng1Token | Function)[] | IAnnotatedFunction;
+
 export interface IModule {
-  config(fn: any): IModule;
-  directive(selector: string, factory: any): IModule;
+  name: string;
+  requires: (string|IInjectable)[];
+  config(fn: IInjectable): IModule;
+  directive(selector: string, factory: IInjectable): IModule;
   component(selector: string, component: IComponent): IModule;
-  controller(name: string, type: any): IModule;
-  factory(key: string, factoryFn: any): IModule;
-  value(key: string, value: any): IModule;
-  run(a: any): void;
+  controller(name: string, type: IInjectable): IModule;
+  factory(key: Ng1Token, factoryFn: IInjectable): IModule;
+  value(key: Ng1Token, value: any): IModule;
+  run(a: IInjectable): IModule;
 }
 export interface ICompileService {
   (element: Element|NodeList|string, transclude?: Function): ILinkFn;
 }
 export interface ILinkFn {
-  (scope: IScope, cloneAttachFn?: Function, options?: ILinkFnOptions): void;
+  (scope: IScope, cloneAttachFn?: ICloneAttachFunction, options?: ILinkFnOptions): IAugmentedJQuery;
 }
 export interface ILinkFnOptions {
   parentBoundTranscludeFn?: Function;
@@ -29,35 +37,42 @@ export interface ILinkFnOptions {
 export interface IRootScopeService {
   $new(isolate?: boolean): IScope;
   $id: string;
+  $parent: IScope;
+  $root: IScope;
   $watch(expr: any, fn?: (a1?: any, a2?: any) => void): Function;
   $destroy(): any;
   $apply(): any;
   $apply(exp: string): any;
   $apply(exp: Function): any;
   $evalAsync(): any;
+  $on(event: string, fn?: (event?: any, ...args: any[]) => void): Function;
   $$childTail: IScope;
   $$childHead: IScope;
   $$nextSibling: IScope;
+  [key: string]: any;
 }
 export interface IScope extends IRootScopeService {}
-export interface IAngularBootstrapConfig {}
+;
+export interface IAngularBootstrapConfig { strictDi?: boolean; }
 export interface IDirective {
   compile?: IDirectiveCompileFn;
-  controller?: any;
+  controller?: IController;
   controllerAs?: string;
-  bindToController?: boolean|Object;
+  bindToController?: boolean|{[key: string]: string};
   link?: IDirectiveLinkFn|IDirectivePrePost;
   name?: string;
   priority?: number;
   replace?: boolean;
-  require?: any;
+  require?: DirectiveRequireProperty;
   restrict?: string;
-  scope?: any;
-  template?: any;
-  templateUrl?: any;
+  scope?: boolean|{[key: string]: string};
+  template?: string|Function;
+  templateUrl?: string|Function;
+  templateNamespace?: string;
   terminal?: boolean;
-  transclude?: any;
+  transclude?: boolean|'element'|{[key: string]: string};
 }
+export type DirectiveRequireProperty = Ng1Token[] | Ng1Token | {[key: string]: Ng1Token};
 export interface IDirectiveCompileFn {
   (templateElement: IAugmentedJQuery, templateAttributes: IAttributes,
    transclude: ITranscludeFunction): IDirectivePrePost;
@@ -71,13 +86,13 @@ export interface IDirectiveLinkFn {
    controller: any, transclude: ITranscludeFunction): void;
 }
 export interface IComponent {
-  bindings?: Object;
-  controller?: any;
+  bindings?: {[key: string]: string};
+  controller?: string|IInjectable;
   controllerAs?: string;
-  require?: any;
-  template?: any;
-  templateUrl?: any;
-  transclude?: any;
+  require?: DirectiveRequireProperty;
+  template?: string|Function;
+  templateUrl?: string|Function;
+  transclude?: boolean;
 }
 export interface IAttributes { $observe(attr: string, fn: (v: string) => void): void; }
 export interface ITranscludeFunction {
@@ -90,14 +105,25 @@ export interface ICloneAttachFunction {
   // Let's hint but not force cloneAttachFn's signature
   (clonedElement?: IAugmentedJQuery, scope?: IScope): any;
 }
-export interface IAugmentedJQuery {
-  bind(name: string, fn: () => void): void;
-  data(name: string, value?: any): any;
-  inheritedData(name: string, value?: any): any;
-  contents(): IAugmentedJQuery;
-  parent(): IAugmentedJQuery;
-  length: number;
-  [index: number]: Node;
+export type IAugmentedJQuery = Node[] & {
+  bind?: (name: string, fn: () => void) => void;
+  data?: (name: string, value?: any) => any;
+  inheritedData?: (name: string, value?: any) => any;
+  contents?: () => IAugmentedJQuery;
+  parent?: () => IAugmentedJQuery;
+  empty?: () => void;
+  append?: (content: IAugmentedJQuery | string) => IAugmentedJQuery;
+  controller?: (name: string) => any;
+  isolateScope?: () => IScope;
+};
+export interface IProvider { $get: IInjectable; }
+export interface IProvideService {
+  provider(token: Ng1Token, provider: IProvider): IProvider;
+  factory(token: Ng1Token, factory: IInjectable): IProvider;
+  service(token: Ng1Token, type: IInjectable): IProvider;
+  value(token: Ng1Token, value: any): IProvider;
+  constant(token: Ng1Token, value: any): void;
+  decorator(token: Ng1Token, factory: IInjectable): void;
 }
 export interface IParseService { (expression: string): ICompiledExpression; }
 export interface ICompiledExpression { assign(context: any, value: any): any; }
@@ -110,8 +136,9 @@ export interface ICacheObject {
   get(key: string): any;
 }
 export interface ITemplateCacheService extends ICacheObject {}
+export type IController = string | IInjectable;
 export interface IControllerService {
-  (controllerConstructor: Function, locals?: any, later?: any, ident?: any): any;
+  (controllerConstructor: IController, locals?: any, later?: any, ident?: any): any;
   (controllerName: string, locals?: any): any;
 }
 
@@ -133,7 +160,8 @@ function noNg() {
 }
 
 var angular: {
-  bootstrap: (e: Element, modules: string[], config: IAngularBootstrapConfig) => void,
+  bootstrap: (e: Element, modules: (string | IInjectable)[], config: IAngularBootstrapConfig) =>
+                 void,
   module: (prefix: string, dependencies?: string[]) => IModule,
   element: (e: Element) => IAugmentedJQuery,
   version: {major: number}, resumeBootstrap?: () => void,

modules/@angular/upgrade/src/aot.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+export {downgradeComponent} from './aot/downgrade_component';
+export {downgradeInjectable} from './aot/downgrade_injectable';
+export {UpgradeComponent} from './aot/upgrade_component';
+export {UpgradeModule} from './aot/upgrade_module';

modules/@angular/upgrade/src/aot/angular1_providers.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import * as angular from '../angular_js';
+
+// We have to do a little dance to get the ng1 injector into the module injector.
+// We store the ng1 injector so that the provider in the module injector can access it
+// Then we "get" the ng1 injector from the module injector, which triggers the provider to read
+// the stored injector and release the reference to it.
+let tempInjectorRef: angular.IInjectorService;
+export function setTempInjectorRef(injector: angular.IInjectorService) {
+  tempInjectorRef = injector;
+}
+export function injectorFactory() {
+  const injector: angular.IInjectorService = tempInjectorRef;
+  tempInjectorRef = null;  // clear the value to prevent memory leaks
+  return injector;
+}
+
+export function rootScopeFactory(i: angular.IInjectorService) {
+  return i.get('$rootScope');
+}
+
+export function compileFactory(i: angular.IInjectorService) {
+  return i.get('$compile');
+}
+
+export function parseFactory(i: angular.IInjectorService) {
+  return i.get('$parse');
+}
+
+export const angular1Providers = [
+  // We must use exported named functions for the ng2 factories to keep the compiler happy:
+  // > Metadata collected contains an error that will be reported at runtime:
+  // >   Function calls are not supported.
+  // >   Consider replacing the function or lambda with a reference to an exported function
+  {provide: '$injector', useFactory: injectorFactory},
+  {provide: '$rootScope', useFactory: rootScopeFactory, deps: ['$injector']},
+  {provide: '$compile', useFactory: compileFactory, deps: ['$injector']},
+  {provide: '$parse', useFactory: parseFactory, deps: ['$injector']}
+];

modules/@angular/upgrade/src/aot/component_info.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {Type} from '@angular/core';
+
+export interface ComponentInfo {
+  component: Type<any>;
+  inputs?: string[];
+  outputs?: string[];
+}
+
+export class PropertyBinding {
+  prop: string;
+  attr: string;
+  bracketAttr: string;
+  bracketParenAttr: string;
+  parenAttr: string;
+  onAttr: string;
+  bindAttr: string;
+  bindonAttr: string;
+
+  constructor(public binding: string) { this.parseBinding(); }
+
+  private parseBinding() {
+    const parts = this.binding.split(':');
+    this.prop = parts[0].trim();
+    this.attr = (parts[1] || this.prop).trim();
+    this.bracketAttr = `[${this.attr}]`;
+    this.parenAttr = `(${this.attr})`;
+    this.bracketParenAttr = `[(${this.attr})]`;
+    const capitalAttr = this.attr.charAt(0).toUpperCase() + this.attr.substr(1);
+    this.onAttr = `on${capitalAttr}`;
+    this.bindAttr = `bind${capitalAttr}`;
+    this.bindonAttr = `bindon${capitalAttr}`;
+  }
+}

modules/@angular/upgrade/src/aot/constants.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+export const UPGRADE_MODULE_NAME = '$$UpgradeModule';
+export const INJECTOR_KEY = '$$angularInjector';
+
+export const $INJECTOR = '$injector';
+export const $PARSE = '$parse';
+export const $SCOPE = '$scope';
+
+export const $COMPILE = '$compile';
+export const $TEMPLATE_CACHE = '$templateCache';
+export const $HTTP_BACKEND = '$httpBackend';
+export const $CONTROLLER = '$controller';

modules/@angular/upgrade/src/aot/downgrade_component.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+
+import {ComponentFactory, ComponentFactoryResolver, Injector} from '@angular/core';
+
+import * as angular from '../angular_js';
+
+import {ComponentInfo} from './component_info';
+import {$INJECTOR, $PARSE, INJECTOR_KEY} from './constants';
+import {DowngradeComponentAdapter} from './downgrade_component_adapter';
+
+let downgradeCount = 0;
+
+/**
+ * @experimental
+ */
+export function downgradeComponent(info: ComponentInfo): angular.IInjectable {
+  const idPrefix = `NG2_UPGRADE_${downgradeCount++}_`;
+  let idCount = 0;
+
+  const directiveFactory:
+      angular.IAnnotatedFunction = function(
+                                       $injector: angular.IInjectorService,
+                                       $parse: angular.IParseService): angular.IDirective {
+
+    return {
+      restrict: 'E',
+      require: '?^' + INJECTOR_KEY,
+      link: (scope: angular.IScope, element: angular.IAugmentedJQuery, attrs: angular.IAttributes,
+             parentInjector: Injector, transclude: angular.ITranscludeFunction) => {
+
+        if (parentInjector === null) {
+          parentInjector = $injector.get(INJECTOR_KEY);
+        }
+
+        const componentFactoryResolver: ComponentFactoryResolver =
+            parentInjector.get(ComponentFactoryResolver);
+        const componentFactory: ComponentFactory<any> =
+            componentFactoryResolver.resolveComponentFactory(info.component);
+
+        if (!componentFactory) {
+          throw new Error('Expecting ComponentFactory for: ' + info.component);
+        }
+
+        const facade = new DowngradeComponentAdapter(
+            idPrefix + (idCount++), info, element, attrs, scope, parentInjector, $parse,
+            componentFactory);
+        facade.setupInputs();
+        facade.createComponent();
+        facade.projectContent();
+        facade.setupOutputs();
+        facade.registerCleanup();
+      }
+    };
+  };
+
+  directiveFactory.$inject = [$INJECTOR, $PARSE];
+  return directiveFactory;
+}