refactor(devtools): Make every ng function optional in the typings (angular#60208)

This will help in the future guarding against old apps what don't have the new APIs implemented

PR Close angular#60208

Author: JeanMeche

devtools/projects/ng-devtools-backend/src/lib/BUILD.bazel

@@ -41,6 +41,7 @@ ts_library(
     name = "highlighter",
     srcs = ["highlighter.ts"],
     deps = [
+        "//devtools/projects/ng-devtools-backend/src/lib/ng-debug-api",
         "//devtools/projects/protocol",
         "//packages/core",
     ],
@@ -98,6 +99,10 @@ ts_library(
 ts_library(
     name = "utils",
     srcs = ["utils.ts"],
+    deps = [
+        "//devtools/projects/ng-devtools-backend/src/lib/ng-debug-api",
+        "//packages/core",
+    ],
 )
 
 ts_library(

devtools/projects/ng-devtools-backend/src/lib/component-tree.ts

@@ -64,15 +64,16 @@ export function getInjectorId() {
 }
 
 export function getInjectorMetadata(injector: Injector) {
-  return ngDebugClient().ɵgetInjectorMetadata!(injector);
+  return ngDebugClient().ɵgetInjectorMetadata?.(injector) ?? null;
 }
 
 export function getInjectorResolutionPath(injector: Injector): Injector[] {
-  if (!ngDebugApiIsSupported('ɵgetInjectorResolutionPath')) {
+  const ng = ngDebugClient();
+  if (!ngDebugApiIsSupported(ng, 'ɵgetInjectorResolutionPath')) {
     return [];
   }
 
-  return ngDebugClient().ɵgetInjectorResolutionPath!(injector);
+  return ng.ɵgetInjectorResolutionPath(injector) ?? [];
 }
 
 export function getInjectorFromElementNode(element: Node): Injector | null {
@@ -83,9 +84,10 @@ function getDirectivesFromElement(element: HTMLElement): {
   component: unknown | null;
   directives: unknown[];
 } {
+  const ng = ngDebugClient();
   let component = null;
-  if (element instanceof Element) {
-    component = ngDebugClient().getComponent!(element);
+  if (element instanceof Element && ngDebugApiIsSupported(ng, 'getComponent')) {
+    component = ng.getComponent(element);
   }
 
   return {
@@ -108,7 +110,7 @@ export const getLatestComponentState = (
 
   const directiveProperties: DirectivesProperties = {};
 
-  const injector = getInjectorFromElementNode!(node.nativeElement!);
+  const injector = getInjectorFromElementNode(node.nativeElement!);
 
   const injectors = injector ? getInjectorResolutionPath(injector) : [];
   const resolutionPathWithProviders = !ngDebugDependencyInjectionApiIsSupported()
@@ -265,12 +267,12 @@ const getDependenciesForDirective = (
   resolutionPath: {injector: Injector; providers: ProviderRecord[]}[],
   directive: any,
 ): SerializedInjectedService[] => {
-  if (!ngDebugApiIsSupported('ɵgetDependenciesFromInjectable')) {
+  const ng = ngDebugClient();
+  if (!ngDebugApiIsSupported(ng, 'ɵgetDependenciesFromInjectable')) {
     return [];
   }
 
-  let dependencies =
-    ngDebugClient().ɵgetDependenciesFromInjectable!(injector, directive)?.dependencies ?? [];
+  let dependencies = ng.ɵgetDependenciesFromInjectable(injector, directive)?.dependencies ?? [];
   const uniqueServices = new Set<string>();
   const serializedInjectedServices: SerializedInjectedService[] = [];
 
@@ -580,7 +582,9 @@ export const updateState = (updatedStateData: UpdatedStateData): void => {
   if (updatedStateData.directiveId.directive !== undefined) {
     const directive = node.directives[updatedStateData.directiveId.directive].instance;
     mutateComponentOrDirective(updatedStateData, directive);
-    ng.applyChanges?.(ng.getOwningComponent!(directive)!);
+    if (ngDebugApiIsSupported(ng, 'getOwningComponent')) {
+      ng.applyChanges?.(ng.getOwningComponent(directive)!);
+    }
     return;
   }
   if (node.component) {

devtools/projects/ng-devtools-backend/src/lib/directive-forest/render-tree.ts

@@ -16,7 +16,7 @@ import {isCustomElement} from '../utils';
 const extractViewTree = (
   domNode: Node | Element,
   result: ComponentTreeNode[],
-  getComponent: (element: Element) => {} | null,
+  getComponent?: (element: Element) => {} | null,
   getDirectives?: (node: Node) => {}[],
 ): ComponentTreeNode[] => {
   // Ignore DOM Node if it came from a different frame. Use instanceof Node to check this.
@@ -45,7 +45,7 @@ const extractViewTree = (
     result.push(componentTreeNode);
     return result;
   }
-  const component = getComponent(domNode);
+  const component = getComponent?.(domNode);
   if (component) {
     componentTreeNode.component = {
       instance: component,
@@ -98,7 +98,7 @@ export class RTreeStrategy {
     while (element.parentElement) {
       element = element.parentElement;
     }
-    const getComponent = ngDebugClient().getComponent!;
+    const getComponent = ngDebugClient().getComponent;
     const getDirectives = ngDebugClient().getDirectives;
     return extractViewTree(element, [], getComponent, getDirectives);
   }

devtools/projects/ng-devtools-backend/src/lib/highlighter.ts

@@ -6,14 +6,13 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import type {ɵGlobalDevModeUtils as GlobalDevModeUtils, Type} from '@angular/core';
+import type {Type} from '@angular/core';
 import {HydrationStatus} from 'protocol';
+import {ngDebugClient} from './ng-debug-api/ng-debug-api';
 
 let hydrationOverlayItems: HTMLElement[] = [];
 let selectedElementOverlay: HTMLElement | null = null;
 
-declare const ng: GlobalDevModeUtils['ng'];
-
 const DEV_TOOLS_HIGHLIGHT_NODE_ID = '____ngDevToolsHighlight';
 
 const OVERLAY_CONTENT_MARGIN = 4;
@@ -61,11 +60,12 @@ export function findComponentAndHost(el: Node | undefined): {
   component: any;
   host: HTMLElement | null;
 } {
+  const ng = ngDebugClient();
   if (!el) {
     return {component: null, host: null};
   }
   while (el) {
-    const component = el instanceof HTMLElement && ng.getComponent(el);
+    const component = el instanceof HTMLElement && ng.getComponent!(el);
     if (component) {
       return {component, host: el as HTMLElement};
     }

devtools/projects/ng-devtools-backend/src/lib/ng-debug-api/ng-debug-api.ts

@@ -16,12 +16,14 @@ import type {ɵGlobalDevModeUtils as GlobalDevModeUtils} from '@angular/core';
 export const ngDebugClient = () => (window as any).ng as Partial<GlobalDevModeUtils['ng']>;
 
 /**
- * Checks whether a given debug API is supported within window.ng
+ * Type guard that checks whether a given debug API is supported within window.ng
  *
- * @returns boolean
+ * @returns whether the ng object includes the given debug API
  */
-export function ngDebugApiIsSupported(api: keyof GlobalDevModeUtils['ng']): boolean {
-  const ng = ngDebugClient();
+export function ngDebugApiIsSupported<
+  T extends Partial<GlobalDevModeUtils['ng']>,
+  K extends keyof T,
+>(ng: T, api: K): ng is T & Record<K, NonNullable<T[K]>> {
   return typeof ng[api] === 'function';
 }
 
@@ -31,19 +33,20 @@ export function ngDebugApiIsSupported(api: keyof GlobalDevModeUtils['ng']): bool
  * @returns boolean
  */
 export function ngDebugDependencyInjectionApiIsSupported(): boolean {
-  if (!ngDebugApiIsSupported('getInjector')) {
+  const ng = ngDebugClient();
+  if (!ngDebugApiIsSupported(ng, 'getInjector')) {
     return false;
   }
-  if (!ngDebugApiIsSupported('ɵgetInjectorResolutionPath')) {
+  if (!ngDebugApiIsSupported(ng, 'ɵgetInjectorResolutionPath')) {
     return false;
   }
-  if (!ngDebugApiIsSupported('ɵgetDependenciesFromInjectable')) {
+  if (!ngDebugApiIsSupported(ng, 'ɵgetDependenciesFromInjectable')) {
     return false;
   }
-  if (!ngDebugApiIsSupported('ɵgetInjectorProviders')) {
+  if (!ngDebugApiIsSupported(ng, 'ɵgetInjectorProviders')) {
     return false;
   }
-  if (!ngDebugApiIsSupported('ɵgetInjectorMetadata')) {
+  if (!ngDebugApiIsSupported(ng, 'ɵgetInjectorMetadata')) {
     return false;
   }
 

devtools/projects/ng-devtools-backend/src/lib/utils.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-export const ngDebug = () => (window as any).ng;
+import {ngDebugApiIsSupported, ngDebugClient} from './ng-debug-api/ng-debug-api';
 
 export const runOutsideAngular = (f: () => void): void => {
   const w = window as any;
@@ -37,30 +37,9 @@ export const isCustomElement = (node: Node) => {
   return !!customElements.get(tagName);
 };
 
-export function hasDiDebugAPIs(): boolean {
-  if (!ngDebugApiIsSupported('ɵgetInjectorResolutionPath')) {
-    return false;
-  }
-  if (!ngDebugApiIsSupported('ɵgetDependenciesFromInjectable')) {
-    return false;
-  }
-  if (!ngDebugApiIsSupported('ɵgetInjectorProviders')) {
-    return false;
-  }
-  if (!ngDebugApiIsSupported('ɵgetInjectorMetadata')) {
-    return false;
-  }
-
-  return true;
-}
-
-export function ngDebugApiIsSupported(api: string): boolean {
-  const ng = ngDebug();
-  return typeof ng[api] === 'function';
-}
-
 export function isSignal(prop: unknown): prop is (() => unknown) & {set: (value: unknown) => void} {
-  if (!ngDebugApiIsSupported('isSignal')) {
+  const ng = ngDebugClient();
+  if (!ngDebugApiIsSupported(ng, 'isSignal')) {
     return false;
   }
   return (window as any).ng.isSignal(prop);