refactor(ivy): make return value of define(Component|Directive|Pipe|Injector|Injectable) private (#23371) (#23383)

Ivy definition looks something like this:

```
class MyService {
  static ngInjectableDef = defineInjectable({
    …
  });
}
```

Here the argument to `defineInjectable` is well known public contract which needs
to be honored in backward compatible way between versions. The type of the
return value of `defineInjectable` on the other hand is private and can change
shape drastically between versions without effecting backwards compatibility of
libraries publish to NPM. To our users it is effectively an opaque token.
For this reson why declare the return value of `defineInjectable` as `never`.

PR Close #23383

Author: mhevery

packages/core/src/change_detection/differs/iterable_differs.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {InjectableDef, defineInjectable} from '../../di/defs';
+import {defineInjectable} from '../../di/defs';
 import {Optional, SkipSelf} from '../../di/metadata';
 import {StaticProvider} from '../../di/provider';
 import {DefaultIterableDifferFactory} from '../differs/default_iterable_differ';
@@ -137,7 +137,7 @@ export interface IterableDifferFactory {
  *
  */
 export class IterableDiffers {
-  static ngInjectableDef: InjectableDef<IterableDiffers> = defineInjectable({
+  static ngInjectableDef = defineInjectable({
     providedIn: 'root',
     factory: () => new IterableDiffers([new DefaultIterableDifferFactory()])
   });

packages/core/src/di.ts

@@ -13,7 +13,7 @@
  */
 
 export * from './di/metadata';
-export * from './di/defs';
+export {InjectableType, InjectorType, defineInjectable, defineInjector} from './di/defs';
 export {forwardRef, resolveForwardRef, ForwardRefFn} from './di/forward_ref';
 export {Injectable, InjectableDecorator, InjectableProvider} from './di/injectable';
 export {inject, InjectFlags, INJECTOR, Injector} from './di/injector';

packages/core/src/di/defs.ts

@@ -20,9 +20,7 @@ import {ClassProvider, ClassSansProvider, ConstructorProvider, ConstructorSansPr
  * `InjectorDef`, `NgModule`, or a special scope (e.g. `'root'`). A value of `null` indicates
  * that the injectable does not belong to any scope.
  *
- * This type is typically generated by the Angular compiler, but can be hand-written if needed.
- *
- * @experimental
+ * NOTE: This is a private type and should not be exported
  */
 export interface InjectableDef<T> {
   /**
@@ -54,7 +52,7 @@ export interface InjectableDef<T> {
  * structure of providers with a defined priority (identically to how `NgModule`s also have
  * an import/dependency structure).
  *
- * @experimental
+ * NOTE: This is a private type and should not be exported
  */
 export interface InjectorDef<T> {
   factory: () => T;
@@ -75,7 +73,12 @@ export interface InjectorDef<T> {
  *
  * @experimental
  */
-export interface InjectableType<T> extends Type<T> { ngInjectableDef: InjectableDef<T>; }
+export interface InjectableType<T> extends Type<T> {
+  /**
+   * Opaque type whose structure is highly version dependent. Do not rely on any properties.
+   */
+  ngInjectableDef: never;
+}
 
 /**
  * A type which has an `InjectorDef` static field.
@@ -84,15 +87,20 @@ export interface InjectableType<T> extends Type<T> { ngInjectableDef: Injectable
  *
  * @experimental
  */
-export interface InjectorType<T> extends Type<T> { ngInjectorDef: InjectorDef<T>; }
+export interface InjectorType<T> extends Type<T> {
+  /**
+   * Opaque type whose structure is highly version dependent. Do not rely on any properties.
+   */
+  ngInjectorDef: never;
+}
 
 /**
  * Describes the `InjectorDef` equivalent of a `ModuleWithProviders`, an `InjectorDefType` with an
  * associated array of providers.
  *
  * Objects of this type can be listed in the imports section of an `InjectorDef`.
  *
- * @experimental
+ * NOTE: This is a private type and should not be exported
  */
 export interface InjectorTypeWithProviders<T> {
   ngModule: InjectorType<T>;
@@ -120,12 +128,10 @@ export interface InjectorTypeWithProviders<T> {
 export function defineInjectable<T>(opts: {
   providedIn?: Type<any>| 'root' | 'any' | null,
   factory: () => T,
-}): InjectableDef<T> {
-  return {
-    providedIn: opts.providedIn as any || null,
-    factory: opts.factory,
-    value: undefined,
-  };
+}): never {
+  return ({
+    providedIn: opts.providedIn as any || null, factory: opts.factory, value: undefined,
+  } as InjectableDef<T>) as never;
 }
 
 /**
@@ -149,10 +155,8 @@ export function defineInjectable<T>(opts: {
  * @experimental
  */
 export function defineInjector(options: {factory: () => any, providers?: any[], imports?: any[]}):
-    InjectorDef<any> {
-  return {
-    factory: options.factory,
-    providers: options.providers || [],
-    imports: options.imports || [],
-  };
+    never {
+  return ({
+    factory: options.factory, providers: options.providers || [], imports: options.imports || [],
+  } as InjectorDef<any>) as never;
 }

packages/core/src/di/injection_token.ts

@@ -52,7 +52,7 @@ export class InjectionToken<T> {
   /** @internal */
   readonly ngMetadataName = 'InjectionToken';
 
-  readonly ngInjectableDef: InjectableDef<T>|undefined;
+  readonly ngInjectableDef: never|undefined;
 
   constructor(protected _desc: string, options?: {
     providedIn?: Type<any>| 'root' | null,
@@ -71,6 +71,4 @@ export class InjectionToken<T> {
   toString(): string { return `InjectionToken ${this._desc}`; }
 }
 
-export interface InjectableDefToken<T> extends InjectionToken<T> {
-  ngInjectableDef: InjectableDef<T>;
-}
+export interface InjectableDefToken<T> extends InjectionToken<T> { ngInjectableDef: never; }

packages/core/src/di/r3_injector.ts

@@ -326,7 +326,7 @@ export class R3Injector {
 }
 
 function injectableDefRecord(token: Type<any>| InjectionToken<any>): Record<any> {
-  const def = (token as InjectableType<any>).ngInjectableDef;
+  const def = (token as InjectableType<any>).ngInjectableDef as InjectableDef<any>;
   if (def === undefined) {
     throw new Error(`Type ${stringify(token)} is missing an ngInjectableDef definition.`);
   }

packages/core/src/render3/definition.ts

@@ -162,7 +162,7 @@ export function defineComponent<T>(componentDefinition: {
    * `PipeDefs`s. The function is necessary to be able to support forward declarations.
    */
   pipes?: PipeTypesOrFactory | null;
-}): ComponentDef<T> {
+}): never {
   const type = componentDefinition.type;
   const pipeTypes = componentDefinition.pipes !;
   const directiveTypes = componentDefinition.directives !;
@@ -196,7 +196,7 @@ export function defineComponent<T>(componentDefinition: {
   };
   const feature = componentDefinition.features;
   feature && feature.forEach((fn) => fn(def));
-  return def;
+  return def as never;
 }
 
 export function extractDirectiveDef(type: DirectiveType<any>& ComponentType<any>):
@@ -400,7 +400,7 @@ export const defineDirective = defineComponent as any as<T>(directiveDefinition:
    * See: {@link Directive.exportAs}
    */
   exportAs?: string;
-}) => DirectiveDef<T>;
+}) => never;
 
 /**
  * Create a pipe definition object.
@@ -428,11 +428,11 @@ export function definePipe<T>(pipeDef: {
 
   /** Whether the pipe is pure. */
   pure?: boolean
-}): PipeDef<T> {
-  return <PipeDef<T>>{
+}): never {
+  return (<PipeDef<T>>{
     name: pipeDef.name,
     n: pipeDef.factory,
     pure: pipeDef.pure !== false,
     onDestroy: pipeDef.type.prototype.ngOnDestroy || null
-  };
+  }) as never;
 }

packages/core/src/render3/interfaces/definition.ts

@@ -38,21 +38,21 @@ export const enum RenderFlags {
  * A subclass of `Type` which has a static `ngComponentDef`:`ComponentDef` field making it
  * consumable for rendering.
  */
-export interface ComponentType<T> extends Type<T> { ngComponentDef: ComponentDef<T>; }
+export interface ComponentType<T> extends Type<T> { ngComponentDef: never; }
 
 /**
  * A subclass of `Type` which has a static `ngDirectiveDef`:`DirectiveDef` field making it
  * consumable for rendering.
  */
-export interface DirectiveType<T> extends Type<T> { ngDirectiveDef: DirectiveDef<T>; }
+export interface DirectiveType<T> extends Type<T> { ngDirectiveDef: never; }
 
 export const enum DirectiveDefFlags {ContentQuery = 0b10}
 
 /**
  * A subclass of `Type` which has a static `ngPipeDef`:`PipeDef` field making it
  * consumable for rendering.
  */
-export interface PipeType<T> extends Type<T> { ngPipeDef: PipeDef<T>; }
+export interface PipeType<T> extends Type<T> { ngPipeDef: never; }
 
 /**
  * Runtime link information for Directives.

packages/core/test/bundling/injection/usage.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {InjectableDef, Injector, InjectorDef, createInjector, defineInjectable, defineInjector} from '@angular/core';
+import {Injector, createInjector, defineInjectable, defineInjector} from '@angular/core';
 
 export class RootService {
   static ngInjectableDef = defineInjectable({

packages/core/test/render3/compiler_canonical/back_patch_types_specs.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {Component, ContentChild, Directive, Injectable, Injector, InjectorDef, Input, NgModule, NgModuleFactory, NgModuleRef, OnDestroy, Optional, Pipe, PipeTransform, QueryList, SimpleChanges, TemplateRef, Type, ViewChild, ViewContainerRef, defineInjector} from '../../../src/core';
+import {Component, ContentChild, Directive, Injectable, Injector, Input, NgModule, NgModuleFactory, NgModuleRef, OnDestroy, Optional, Pipe, PipeTransform, QueryList, SimpleChanges, TemplateRef, Type, ViewChild, ViewContainerRef, defineInjector} from '../../../src/core';
 import * as r3 from '../../../src/render3/index';
 
 const details_elided = {

packages/core/test/render3/compiler_canonical/component_directives_spec.ts

@@ -8,8 +8,11 @@
 
 import {ChangeDetectionStrategy, ChangeDetectorRef, Component, ContentChild, ContentChildren, Directive, HostBinding, HostListener, Injectable, Input, NgModule, OnDestroy, Optional, Pipe, PipeTransform, QueryList, SimpleChanges, TemplateRef, ViewChild, ViewChildren, ViewContainerRef} from '../../../src/core';
 import * as $r3$ from '../../../src/core_render3_private_export';
+import {ComponentDef} from '../../../src/render3/interfaces/definition';
 import {renderComponent, toHtml} from '../render_util';
 
+
+
 /// See: `normative.md`
 describe('components & directives', () => {
   type $RenderFlags$ = $r3$.ɵRenderFlags;
@@ -76,8 +79,8 @@ describe('components & directives', () => {
     }
 
     // NON-NORMATIVE (done by defineNgModule)
-    MyComponent.ngComponentDef.directiveDefs =
-        [ChildComponent.ngComponentDef, SomeDirective.ngDirectiveDef];
+    (MyComponent.ngComponentDef as ComponentDef<any>).directiveDefs =
+        [(ChildComponent.ngComponentDef as ComponentDef<any>), SomeDirective.ngDirectiveDef];
     // /NON-NORMATIVE
 
     expect(renderComp(MyComponent)).toEqual('<child some-directive="">child-view</child>!');
@@ -126,7 +129,7 @@ describe('components & directives', () => {
     }
 
     // NON-NORMATIVE (done by defineNgModule)
-    MyApp.ngComponentDef.directiveDefs = [HostBindingDir.ngDirectiveDef];
+    (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs = [HostBindingDir.ngDirectiveDef];
     // /NON-NORMATIVE
 
     expect(renderComp(MyApp)).toEqual(`<div hostbindingdir="" id="some id"></div>`);
@@ -177,7 +180,7 @@ describe('components & directives', () => {
     }
 
     // NON-NORMATIVE (done by defineNgModule)
-    MyApp.ngComponentDef.directiveDefs = [HostListenerDir.ngDirectiveDef];
+    (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs = [HostListenerDir.ngDirectiveDef];
     // /NON-NORMATIVE
 
     expect(renderComp(MyApp)).toEqual(`<button hostlistenerdir="">Click</button>`);
@@ -222,7 +225,7 @@ describe('components & directives', () => {
     }
 
     // NON-NORMATIVE (done by defineNgModule)
-    MyApp.ngComponentDef.directiveDefs = [HostAttributeDir.ngDirectiveDef];
+    (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs = [HostAttributeDir.ngDirectiveDef];
     // /NON-NORMATIVE
 
     expect(renderComp(MyApp)).toEqual(`<div hostattributedir="" role="listbox"></div>`);
@@ -270,7 +273,7 @@ describe('components & directives', () => {
     }
 
     // NON-NORMATIVE (done by defineNgModule)
-    MyApp.ngComponentDef.directiveDefs = [HostBindingDir.ngDirectiveDef];
+    (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs = [HostBindingDir.ngDirectiveDef];
     // /NON-NORMATIVE
 
     expect(renderComp(MyApp)).toEqual(`<div aria-label="some label" hostbindingdir=""></div>`);
@@ -333,7 +336,8 @@ describe('components & directives', () => {
     }
 
     // NON-NORMATIVE (done by defineNgModule)
-    MyApp.ngComponentDef.directiveDefs = [MyComp.ngComponentDef];
+    (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs =
+        [(MyComp.ngComponentDef as ComponentDef<any>)];
     // /NON-NORMATIVE
 
     expect(renderComp(MyApp)).toEqual(`<my-comp>some name</my-comp>`);
@@ -463,7 +467,8 @@ describe('components & directives', () => {
       }
 
       // NON-NORMATIVE (done by defineNgModule)
-      MyApp.ngComponentDef.directiveDefs = [MyArrayComp.ngComponentDef];
+      (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs =
+          [(MyArrayComp.ngComponentDef as ComponentDef<any>)];
       // /NON-NORMATIVE
 
       expect(renderComp(MyApp)).toEqual(`<my-array-comp>Nancy Bess</my-array-comp>`);
@@ -507,7 +512,8 @@ describe('components & directives', () => {
       }
 
       // NON-NORMATIVE (done by defineNgModule)
-      MyApp.ngComponentDef.directiveDefs = [MyArrayComp.ngComponentDef];
+      (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs =
+          [(MyArrayComp.ngComponentDef as ComponentDef<any>)];
       // /NON-NORMATIVE
 
       expect(renderComp(MyApp)).toEqual(`<my-array-comp>NANCY Bess</my-array-comp>`);
@@ -567,7 +573,8 @@ describe('components & directives', () => {
       }
 
       // NON-NORMATIVE (done by defineNgModule)
-      MyApp.ngComponentDef.directiveDefs = [MyComp.ngComponentDef];
+      (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs =
+          [(MyComp.ngComponentDef as ComponentDef<any>)];
       // /NON-NORMATIVE
 
       expect(renderComp(MyApp)).toEqual(`<my-comp>3</my-comp>`);
@@ -609,7 +616,8 @@ describe('components & directives', () => {
       }
 
       // NON-NORMATIVE (done by defineNgModule)
-      MyApp.ngComponentDef.directiveDefs = [MyArrayComp.ngComponentDef];
+      (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs =
+          [(MyArrayComp.ngComponentDef as ComponentDef<any>)];
       // /NON-NORMATIVE
 
       expect(renderComp(MyApp)).toEqual(`<my-array-comp>Nancy Bess</my-array-comp>`);
@@ -721,7 +729,8 @@ describe('components & directives', () => {
       }
 
       // NON-NORMATIVE (done by defineNgModule)
-      MyApp.ngComponentDef.directiveDefs = [MyComp.ngComponentDef];
+      (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs =
+          [(MyComp.ngComponentDef as ComponentDef<any>)];
       // /NON-NORMATIVE
 
       expect(renderComp(MyApp)).toEqual(`<my-comp>start-abcde-middle-fghi-end</my-comp>`);
@@ -795,7 +804,8 @@ describe('components & directives', () => {
       }
 
       // NON-NORMATIVE (done by defineNgModule)
-      MyApp.ngComponentDef.directiveDefs = [ObjectComp.ngComponentDef];
+      (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs =
+          [(ObjectComp.ngComponentDef as ComponentDef<any>)];
       // /NON-NORMATIVE
 
       expect(renderComp(MyApp)).toEqual(`<object-comp><p>500</p><p>slide</p></object-comp>`);
@@ -882,7 +892,8 @@ describe('components & directives', () => {
       }
 
       // NON-NORMATIVE (done by defineNgModule)
-      MyApp.ngComponentDef.directiveDefs = [NestedComp.ngComponentDef];
+      (MyApp.ngComponentDef as ComponentDef<any>).directiveDefs =
+          [(NestedComp.ngComponentDef as ComponentDef<any>)];
       // /NON-NORMATIVE
 
       expect(renderComp(MyApp))

packages/core/test/render3/compiler_canonical/elements_spec.ts

@@ -7,10 +7,13 @@
  */
 
 import {browserDetection} from '@angular/platform-browser/testing/src/browser_util';
+
 import {ChangeDetectionStrategy, ChangeDetectorRef, Component, ContentChild, ContentChildren, Directive, HostBinding, HostListener, Injectable, Input, NgModule, OnDestroy, Optional, Pipe, PipeTransform, QueryList, SimpleChanges, TemplateRef, ViewChild, ViewChildren, ViewContainerRef} from '../../../src/core';
 import * as $r3$ from '../../../src/core_render3_private_export';
+import {ComponentDef} from '../../../src/render3/interfaces/definition';
 import {ComponentFixture, renderComponent, toHtml} from '../render_util';
 
+
 /// See: `normative.md`
 describe('elements', () => {
   // Saving type as $any$, etc to simplify testing for compiler, as types aren't saved
@@ -103,7 +106,7 @@ describe('elements', () => {
     }
 
     // NON-NORMATIVE
-    LocalRefComp.ngComponentDef.directiveDefs = () => [Dir.ngDirectiveDef];
+    (LocalRefComp.ngComponentDef as ComponentDef<any>).directiveDefs = () => [Dir.ngDirectiveDef];
     // /NON-NORMATIVE
 
     const fixture = new ComponentFixture(LocalRefComp);

packages/core/test/render3/compiler_canonical/injection_spec.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {Attribute, ChangeDetectionStrategy, ChangeDetectorRef, Component, ContentChild, ContentChildren, Directive, HostBinding, HostListener, INJECTOR, Inject, InjectFlags, Injectable, InjectableDef, Injector, InjectorDef, Input, NgModule, OnDestroy, Optional, Pipe, PipeTransform, QueryList, SimpleChanges, SkipSelf, TemplateRef, ViewChild, ViewChildren, ViewContainerRef, defineInjectable, defineInjector, inject} from '../../../src/core';
+import {Attribute, ChangeDetectionStrategy, ChangeDetectorRef, Component, ContentChild, ContentChildren, Directive, HostBinding, HostListener, INJECTOR, Inject, InjectFlags, Injectable, Injector, Input, NgModule, OnDestroy, Optional, Pipe, PipeTransform, QueryList, SimpleChanges, SkipSelf, TemplateRef, ViewChild, ViewChildren, ViewContainerRef, defineInjectable, defineInjector, inject} from '../../../src/core';
 import * as $r3$ from '../../../src/core_render3_private_export';
 import {renderComponent, toHtml} from '../render_util';