feat(core): add unsafeListenToOutput & listenToOuput to ComponentRef

JeanMeche · JeanMeche · commit fe1d474e5263 · 2025-01-14T20:41:05.000+01:00
This commit adds 2 methods to the `ComponentRef` class that allows to listen to outputs. It abstracts the underlying `EventEmitter` or `OutputEmitterRef` and returns a anonymous function to unsubscribe.
diff --git a/goldens/public-api/core/index.api.md b/goldens/public-api/core/index.api.md
@@ -335,9 +335,11 @@ export abstract class ComponentRef<C> {
     abstract get hostView(): ViewRef;
     abstract get injector(): Injector;
     abstract get instance(): C;
+    abstract listenToOutput<OutputType extends keyof C>(propertyName: OutputType, listenerFn: (eventArg: ExtractOutputType<C[OutputType]>) => unknown): () => void;
     abstract get location(): ElementRef;
     abstract onDestroy(callback: Function): void;
     abstract setInput(name: string, value: unknown): void;
+    abstract unsafeListenToOutput(outputName: string, listenerFn: (eventArg: unknown) => unknown): () => void;
 }
 
 // @public
diff --git a/packages/core/src/linker/component_factory.ts b/packages/core/src/linker/component_factory.ts
@@ -9,12 +9,17 @@
 import type {ChangeDetectorRef} from '../change_detection/change_detection';
 import type {Injector} from '../di/injector';
 import type {EnvironmentInjector} from '../di/r3_injector';
+import type {OutputEmitterRef} from '../authoring';
+import type {EventEmitter} from '../event_emitter';
 import {Type} from '../interface/type';
 
 import type {ElementRef} from './element_ref';
 import type {NgModuleRef} from './ng_module_factory';
 import type {ViewRef} from './view_ref';
 
+export type ExtractOutputType<T> =
+  T extends OutputEmitterRef<infer U> ? U : T extends EventEmitter<infer U> ? U : never;
+
 /**
  * Represents a component created by a `ComponentFactory`.
  * Provides access to the component instance and related objects,
@@ -33,6 +38,34 @@ export abstract class ComponentRef<C> {
    */
   abstract setInput(name: string, value: unknown): void;
 
+  /**
+   * Listen to a given output on the component.
+   *
+   * @param propertyName the output property to listen to
+   * @param listenerFn the callback invoked everytime the output fires the event
+   *
+   * @returns a function to manually clean up the output listening
+   */
+
+  abstract listenToOutput<OutputType extends keyof C>(
+    propertyName: OutputType,
+    listenerFn: (eventArg: ExtractOutputType<C[OutputType]>) => unknown,
+  ): () => void;
+
+  /**
+   * Listen to a given output on the component.
+   * This method does not ensure type safety of the output name nor of the event type.
+   *
+   * @param outputName the output to listen to
+   * @param listenerFn the callback invoked everytime the output fires the event
+   *
+   * @returns a function to manually clean up the output listening
+   */
+  abstract unsafeListenToOutput(
+    outputName: string,
+    listenerFn: (eventArg: unknown) => unknown,
+  ): () => void;
+
   /**
    * The host or anchor element for this component instance.
    */
diff --git a/packages/core/src/render3/component_ref.ts b/packages/core/src/render3/component_ref.ts
@@ -22,6 +22,7 @@ import {Type} from '../interface/type';
 import {
   ComponentFactory as AbstractComponentFactory,
   ComponentRef as AbstractComponentRef,
+  ExtractOutputType,
 } from '../linker/component_factory';
 import {ComponentFactoryResolver as AbstractComponentFactoryResolver} from '../linker/component_factory_resolver';
 import {createElementRef, ElementRef} from '../linker/element_ref';
@@ -53,7 +54,12 @@ import {
   markAsComponentHost,
   setInputsForProperty,
 } from './instructions/shared';
-import {ComponentDef, DirectiveDef, HostDirectiveDefs} from './interfaces/definition';
+import {
+  ComponentDef,
+  ComponentType,
+  DirectiveDef,
+  HostDirectiveDefs,
+} from './interfaces/definition';
 import {InputFlags} from './interfaces/input_flags';
 import {
   NodeInputBindings,
@@ -91,6 +97,7 @@ import {ChainedInjector} from './chained_injector';
 import {unregisterLView} from './interfaces/lview_tracking';
 import {profiler} from './profiler';
 import {ProfilerEvent} from './profiler_types';
+import {listenToOutput} from './instructions/listener';
 
 export class ComponentFactoryResolver extends AbstractComponentFactoryResolver {
   /**
@@ -479,6 +486,30 @@ export class ComponentRef<T> extends AbstractComponentRef<T> {
     }
   }
 
+  override listenToOutput<OutputType extends keyof T>(
+    propertyName: OutputType,
+    listenerFn: (eventArg: any) => unknown,
+  ): () => void {
+    return this.unsafeListenToOutput(propertyName as string, listenerFn);
+  }
+
+  override unsafeListenToOutput(
+    outputName: string,
+    listenerFn: (eventArg: unknown) => unknown,
+  ): () => void {
+    const subscription = listenToOutput(this._tNode, this._rootLView, outputName, listenerFn);
+    if (!subscription) {
+      // TODO: create a runtime error
+      throw new Error(
+        ngDevMode
+          ? `${outputName} is not an output of the component ${this.componentType.name}`
+          : '',
+      );
+    }
+
+    return subscription!;
+  }
+
   override get injector(): Injector {
     return new NodeInjector(this._tNode, this._rootLView);
   }
diff --git a/packages/core/src/render3/instructions/listener.ts b/packages/core/src/render3/instructions/listener.ts
@@ -230,11 +230,25 @@ export function listenerInternal(
   }
 
   // subscribe to directive outputs
+  if (processOutputs) {
+    listenToOutput(tNode, lView, eventName, listenerFn, lCleanup, tCleanup);
+  }
+}
+
+export function listenToOutput(
+  tNode: TNode,
+  lView: LView,
+  eventName: string,
+  listenerFn: (e: unknown) => unknown,
+  lCleanup?: any[],
+  tCleanup?: false | any[],
+): VoidFunction | undefined {
   const outputs = tNode.outputs;
   let props: NodeOutputBindings[keyof NodeOutputBindings] | undefined;
-  if (processOutputs && outputs !== null && (props = outputs[eventName])) {
+  if (outputs !== null && (props = outputs[eventName])) {
     const propsLength = props.length;
     if (propsLength) {
+      const subscriptions: {unsubscribe: () => void}[] = [];
       for (let i = 0; i < propsLength; i += 2) {
         const index = props[i] as number;
         ngDevMode && assertIndexInRange(lView, index);
@@ -249,12 +263,19 @@ export function listenerInternal(
         }
 
         const subscription = (output as SubscribableOutput<unknown>).subscribe(listenerFn);
-        const idx = lCleanup.length;
-        lCleanup.push(listenerFn, subscription);
-        tCleanup && tCleanup.push(eventName, tNode.index, idx, -(idx + 1));
+        if (lCleanup) {
+          const idx = lCleanup.length;
+          lCleanup.push(listenerFn, subscription);
+          tCleanup && tCleanup.push(eventName, tNode.index, idx, -(idx + 1));
+        }
+        subscriptions.push(subscription);
       }
+      return () => {
+        subscriptions.forEach((s) => s.unsubscribe());
+      };
     }
   }
+  return undefined;
 }
 
 function executeListenerWithErrorHandling(
diff --git a/packages/core/test/acceptance/authoring/output_function_spec.ts b/packages/core/test/acceptance/authoring/output_function_spec.ts
@@ -208,6 +208,46 @@ describe('output() function', () => {
     expect(dir.effectCount).toEqual(1);
   });
 
+  it('should ensure type safety for listenToOutput', () => {
+    @Component({template: ``, standalone: true})
+    class MyComponent {
+      outputRefString = output<{foo: string}>();
+    }
+
+    const fixture = TestBed.createComponent(MyComponent);
+
+    let foo: {foo: string};
+    fixture.componentRef.listenToOutput('outputRefString', (event) => {
+      foo = event;
+    });
+
+    // Testing an non matching type throws
+    let bar: {bar: string};
+    fixture.componentRef.listenToOutput('outputRefString', (event) => {
+      /* @ts-expect-error */
+      bar = event;
+    });
+  });
+
+  it('should emit on listenToOutput', () => {
+    @Component({template: ``, standalone: true})
+    class MyComponent {
+      outputRefString = output<string>();
+    }
+
+    const fixture = TestBed.createComponent(MyComponent);
+    const logs: string[] = [];
+
+    fixture.componentRef.listenToOutput('outputRefString', (event) => {
+      logs.push(event);
+    });
+
+    fixture.componentInstance.outputRefString.emit('emitted');
+
+    expect(logs.length).toBe(1);
+    expect(logs[0]).toEqual('emitted');
+  });
+
   describe('outputFromObservable()', () => {
     it('should support using a `Subject` as source', () => {
       @Directive({
diff --git a/packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json b/packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json
@@ -495,6 +495,7 @@
   "leaveDI",
   "leaveView",
   "leaveViewLight",
+  "listenToOutput",
   "lookupTokenUsingModuleInjector",
   "lookupTokenUsingNodeInjector",
   "makeParamDecorator",
diff --git a/packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json b/packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json
@@ -481,6 +481,7 @@
   "leaveDI",
   "leaveView",
   "leaveViewLight",
+  "listenToOutput",
   "listenerInternal",
   "lookupTokenUsingModuleInjector",
   "lookupTokenUsingNodeInjector",
diff --git a/packages/core/test/bundling/router/bundle.golden_symbols.json b/packages/core/test/bundling/router/bundle.golden_symbols.json
@@ -570,6 +570,7 @@
   "leaveDI",
   "leaveView",
   "leaveViewLight",
+  "listenToOutput",
   "locateDirectiveOrProvider",
   "lookupTokenUsingModuleInjector",
   "lookupTokenUsingNodeInjector",
diff --git a/packages/core/test/bundling/todo/bundle.golden_symbols.json b/packages/core/test/bundling/todo/bundle.golden_symbols.json
@@ -402,6 +402,7 @@
   "leaveDI",
   "leaveView",
   "leaveViewLight",
+  "listenToOutput",
   "lookupTokenUsingModuleInjector",
   "lookupTokenUsingNodeInjector",
   "makeParamDecorator",
diff --git a/packages/core/test/render3/component_ref_spec.ts b/packages/core/test/render3/component_ref_spec.ts
@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {ComponentRef} from '@angular/core';
+import {ComponentRef, inject} from '@angular/core';
 import {ComponentFactoryResolver} from '@angular/core/src/render3/component_ref';
 import {Renderer} from '@angular/core/src/render3/interfaces/renderer';
 import {RElement} from '@angular/core/src/render3/interfaces/renderer_dom';
@@ -15,10 +15,13 @@ import {TestBed} from '@angular/core/testing';
 import {
   ChangeDetectionStrategy,
   Component,
+  Directive,
+  EventEmitter,
   Injector,
   Input,
   NgModuleRef,
   OnChanges,
+  output,
   Output,
   RendererType2,
   SimpleChanges,
@@ -467,4 +470,105 @@ describe('ComponentFactory', () => {
       expect(fixture.nativeElement.innerText).toBe('2');
     });
   });
+
+  describe('listen', () => {
+    it('should allow listening to on the ComponentRef', () => {
+      const logs: string[] = [];
+
+      @Directive({standalone: true})
+      class MyDirective {
+        @Output() onDirChange = new EventEmitter<void>();
+        @Output() onChange = new EventEmitter<void>();
+
+        emit() {
+          this.onChange.emit();
+          this.onDirChange.emit();
+        }
+      }
+
+      @Component({
+        template: `{{in}}`,
+        hostDirectives: [{directive: MyDirective, outputs: ['onDirChange', 'onChange']}],
+        standalone: true,
+      })
+      class MyComponent {
+        @Output() onChange = new EventEmitter<void>();
+        @Output('onSomeOtherChange') onOtherChange = new EventEmitter<void>();
+
+        private readonly directive: MyDirective = inject(MyDirective, {self: true});
+
+        emit() {
+          this.onChange.emit();
+          this.onOtherChange.emit();
+          this.directive.emit();
+        }
+      }
+
+      const fixture = TestBed.createComponent(MyComponent);
+      fixture.detectChanges();
+
+      const cleanUp1 = fixture.componentRef.unsafeListenToOutput('onChange', () => {
+        logs.push('onChange');
+      });
+      const cleanUp2 = fixture.componentRef.unsafeListenToOutput('onSomeOtherChange', () => {
+        logs.push('onSomeOtherChange');
+      });
+      const cleanUp3 = fixture.componentRef.unsafeListenToOutput('onDirChange', () => {
+        logs.push('onDirChange');
+      });
+
+      expect(logs.length).toBe(0);
+
+      fixture.componentInstance.emit();
+      expect(logs.length).toBe(4);
+      // Emited by the component
+      expect(logs.at(-4)).toBe('onChange');
+      expect(logs.at(-3)).toBe('onSomeOtherChange');
+
+      // Emited by the HostDirective
+      expect(logs.at(-2)).toBe('onChange');
+      expect(logs.at(-1)).toBe('onDirChange');
+
+      cleanUp1();
+      cleanUp2();
+      cleanUp3();
+      fixture.componentInstance.emit();
+      expect(logs.length).toBe(4);
+    });
+
+    it('should ensure type safety for listenToOutput', () => {
+      @Component({template: ``, standalone: true})
+      class MyComponent {
+        @Output() eventEmitterString = new EventEmitter<{foo: string}>();
+      }
+
+      const fixture = TestBed.createComponent(MyComponent);
+
+      let foo: {foo: string};
+      fixture.componentRef.listenToOutput('eventEmitterString', (event) => {
+        foo = event;
+      });
+
+      // Testing an non matching type throws
+      let bar: {bar: string};
+      fixture.componentRef.listenToOutput('eventEmitterString', (event) => {
+        /* @ts-expect-error */
+        bar = event;
+      });
+    });
+
+    it('should throw when listening a non-existing output', () => {
+      const logs: string[] = [];
+
+      @Component({template: `{{in}}`})
+      class DynamicCmp {
+        notAnInput: any;
+      }
+
+      const fixture = TestBed.createComponent(DynamicCmp);
+      fixture.detectChanges();
+
+      expect(() => fixture.componentRef.unsafeListenToOutput('notAnOutput', () => {})).toThrow();
+    });
+  });
 });
