feat(core): support usage of non-experimental decorators with TypeScript 5.0 (#49492)

clydin · dylhunn · commit aad05ebeb44a · 2023-04-05T09:59:07.000-07:00
Previously, attempting to turn off the `experimentalDecorators` TypeScript configuration option within an Angular project would result in build time errors. These errors were due to an exposed Decorator signature from `@angular/core` that TypeScript thought was incompatible with standard decorators. However, Angular's class decorators (`Component`, `Directive`, `Pipe`, `Injectable`, `NgModule`) are actually already compatible with standard decorators. The export types for the decorators only needed to be updated to reflect that compatibility. With the updated exported types, applications will now successfully compile and execute in AOT mode with one important dependency injection caveat explained in the note below. For JIT mode applications that are built with the Angular CLI, `@ngtools/webpack`, or use `tsickle`, there were also no additional changes required. These tools automatically convert property decorators (now called field decorators) at build time to store Angular property metadata directly on the relevant class. Building with these tools is the overwhelmingly common method of building an application. Any applications that do not use one of these tools will not function at runtime in JIT mode if using standard decorators. The behavior and code for when experimental decorators is enabled has been left intact. NOTE: Angular constructor dependency injection that requires parameter decorators is not supported. The standard decorator specification does not support parameter decorators. The `inject` function must be used for all cases that previously required a parameter decorator. This includes such decorators as `Inject`, `Optional`, `Self`, `SkipSelf`, `Host`, and `Attribute`. Constructor dependency injection that relies only on the supplied parameter type will continue to function as expected if using AOT; as well as in JIT mode if using the Angular CLI, `@ngtools/webpack` directly, or `tsickle`. Documentation for the `inject` function can be found at: https://angular.io/api/core/inject The decorator specification proposal can be found at: https://github.com/tc39/proposal-decorators PR Close #49492
diff --git a/goldens/public-api/core/index.md b/goldens/public-api/core/index.md
@@ -1466,6 +1466,8 @@ export interface TypeDecorator {
     <T extends Type<any>>(type: T): T;
     // (undocumented)
     (target: Object, propertyKey?: string | symbol, parameterIndex?: number): void;
+    // (undocumented)
+    (target: unknown, context: unknown): void;
 }
 
 // @public
diff --git a/packages/core/src/util/decorators.ts b/packages/core/src/util/decorators.ts
@@ -34,6 +34,9 @@ export interface TypeDecorator {
   // so we cannot declare this interface as a subtype.
   // see https://github.com/angular/angular/issues/3379#issuecomment-126169417
   (target: Object, propertyKey?: string|symbol, parameterIndex?: number): void;
+  // Standard (non-experimental) Decorator signature that avoids direct usage of
+  // any TS 5.0+ specific types.
+  (target: unknown, context: unknown): void;
 }
 
 export const ANNOTATIONS = '__annotations__';
@@ -152,6 +155,12 @@ export function makePropDecorator(
       const decoratorInstance = new (<any>PropDecoratorFactory)(...args);
 
       function PropDecorator(target: any, name: string) {
+        // target is undefined with standard decorators. This case is not supported and will throw
+        // if this decorator is used in JIT mode with standard decorators.
+        if (target === undefined) {
+          throw new Error('Standard Angular field decorators are not supported in JIT mode.');
+        }
+
         const constructor = target.constructor;
         // Use of Object.defineProperty is important because it creates a non-enumerable property
         // which prevents the property from being copied during subclassing.

Original file line number	Diff line number	Diff line change
`@@ -1466,6 +1466,8 @@ export interface TypeDecorator {`
`1466`	`1466`	`<T extends Type<any>>(type: T): T;`
`1467`	`1467`	`// (undocumented)`
`1468`	`1468`	`(target: Object, propertyKey?: string \| symbol, parameterIndex?: number): void;`
	`1469`	`+ // (undocumented)`
	`1470`	`+ (target: unknown, context: unknown): void;`
`1469`	`1471`	`}`
`1470`	`1472`
`1471`	`1473`	`// @public`