From 499e303ea35c1ef03f762ad2bb654cf5cdd763a0 Mon Sep 17 00:00:00 2001 From: Igor Minar Date: Thu, 8 Nov 2018 18:25:33 +0100 Subject: [PATCH] test(ivy): add global utils to the public_api_guard test (#27008) This API is part of our public api surface and needs to be monitored by the public_api_guard. I also had to go back and mark all of the exported functions with @publicApi jsdoc tag. PR Close #27008 --- packages/core/src/render3/discovery_utils.ts | 18 ++++++++++++++++++ packages/core/src/render3/global_utils.ts | 3 +-- packages/core/src/render3/global_utils_api.ts | 19 +++++++++++++++++++ packages/core/src/render3/players.ts | 2 ++ .../core/test/render3/global_utils_spec.ts | 2 +- tools/public_api_guard/BUILD.bazel | 13 ++++++++++++- tools/public_api_guard/global_utils.d.ts | 11 +++++++++++ 7 files changed, 64 insertions(+), 4 deletions(-) create mode 100644 packages/core/src/render3/global_utils_api.ts create mode 100644 tools/public_api_guard/global_utils.d.ts diff --git a/packages/core/src/render3/discovery_utils.ts b/packages/core/src/render3/discovery_utils.ts index 52d3e168e1..10d1fcdfed 100644 --- a/packages/core/src/render3/discovery_utils.ts +++ b/packages/core/src/render3/discovery_utils.ts @@ -33,6 +33,8 @@ import {NodeInjector} from './view_engine_compatibility'; * the component instance is exists in a template. * If a directive instance is used then it will return the * component that contains that directive in it's template. + * + * @publicApi */ export function getComponent(target: {}): T|null { const context = loadContext(target) !; @@ -60,6 +62,8 @@ export function getComponent(target: {}): T|null { * * This will only return a component instance of the DOM node * contains an instance of a component on it. + * + * @publicApi */ export function getHostComponent(target: {}): T|null { const context = loadContext(target); @@ -74,6 +78,8 @@ export function getHostComponent(target: {}): T|null { /** * Returns the `RootContext` instance that is associated with * the application where the target is situated. + * + * @publicApi */ export function getRootContext(target: LViewData | {}): RootContext { const lViewData = Array.isArray(target) ? target : loadContext(target) !.lViewData; @@ -84,6 +90,8 @@ export function getRootContext(target: LViewData | {}): RootContext { /** * Returns a list of all the components in the application * that are have been bootstrapped. + * + * @publicApi */ export function getRootComponents(target: {}): any[] { return [...getRootContext(target).components]; @@ -92,6 +100,8 @@ export function getRootComponents(target: {}): any[] { /** * Returns the injector instance that is associated with * the element, component or directive. + * + * @publicApi */ export function getInjector(target: {}): Injector { const context = loadContext(target); @@ -103,6 +113,8 @@ export function getInjector(target: {}): Injector { /** * Returns a list of all the directives that are associated * with the underlying target element. + * + * @publicApi */ export function getDirectives(target: {}): Array<{}> { const context = loadContext(target) !; @@ -117,6 +129,8 @@ export function getDirectives(target: {}): Array<{}> { /** * Returns LContext associated with a target passed as an argument. * Throws if a given target doesn't have associated LContext. + * + * @publicApi */ export function loadContext(target: {}): LContext { const context = getContext(target); @@ -133,6 +147,8 @@ export function loadContext(target: {}): LContext { * reaching the root `LViewData`. * * @param componentOrView any component or view + * + * @publicApi */ export function getRootView(componentOrView: LViewData | {}): LViewData { let lViewData: LViewData; @@ -151,6 +167,8 @@ export function getRootView(componentOrView: LViewData | {}): LViewData { /** * Retrieve map of local references (local reference name => element or directive instance). + * + * @publicApi */ export function getLocalRefs(target: {}): {[key: string]: any} { const context = loadContext(target) !; diff --git a/packages/core/src/render3/global_utils.ts b/packages/core/src/render3/global_utils.ts index 25c14c2116..50d3ab726a 100644 --- a/packages/core/src/render3/global_utils.ts +++ b/packages/core/src/render3/global_utils.ts @@ -6,8 +6,7 @@ * found in the LICENSE file at https://angular.io/license */ import {global} from '../util'; -import {getComponent, getDirectives, getHostComponent, getInjector, getRootComponents} from './discovery_utils'; -import {getPlayers} from './players'; +import {getComponent, getDirectives, getHostComponent, getInjector, getPlayers, getRootComponents} from './global_utils_api'; /** * This file introduces series of globally accessible debug tools diff --git a/packages/core/src/render3/global_utils_api.ts b/packages/core/src/render3/global_utils_api.ts new file mode 100644 index 0000000000..dadef7a664 --- /dev/null +++ b/packages/core/src/render3/global_utils_api.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 + */ + +/** + * @fileoverview + * This file is the index file collecting all of the symbols published on the global.ng namespace. + * + * The reason why this file/module is separate global_utils.ts file is that we use this file + * to generate a d.ts file containing all the published symbols that is then compared to the golden + * file in the public_api_guard test. + */ + +export {getComponent, getDirectives, getHostComponent, getInjector, getRootComponents} from './discovery_utils'; +export {getPlayers} from './players'; diff --git a/packages/core/src/render3/players.ts b/packages/core/src/render3/players.ts index 5cf2762cae..74bee39ad1 100644 --- a/packages/core/src/render3/players.ts +++ b/packages/core/src/render3/players.ts @@ -50,6 +50,8 @@ export function addPlayer( * This function will only return players that have been added to the ref instance using * `addPlayer` or any players that are active through any template styling bindings * (`[style]`, `[style.prop]`, `[class]` and `[class.name]`). + * + * @publicApi */ export function getPlayers(ref: ComponentInstance | DirectiveInstance | HTMLElement): Player[] { const context = getContext(ref); diff --git a/packages/core/test/render3/global_utils_spec.ts b/packages/core/test/render3/global_utils_spec.ts index 06ef793a22..6a158e912a 100644 --- a/packages/core/test/render3/global_utils_spec.ts +++ b/packages/core/test/render3/global_utils_spec.ts @@ -7,8 +7,8 @@ */ import {getComponent, getDirectives, getHostComponent, getInjector, getRootComponents} from '../../src/render3/discovery_utils'; import {GLOBAL_PUBLISH_EXPANDO_KEY, GlobalDevModeContainer, publishDefaultGlobalUtils, publishGlobalUtil} from '../../src/render3/global_utils'; -import {global} from '../../src/util'; import {getPlayers} from '../../src/render3/players'; +import {global} from '../../src/util'; describe('global utils', () => { describe('publishGlobalUtil', () => { diff --git a/tools/public_api_guard/BUILD.bazel b/tools/public_api_guard/BUILD.bazel index bee1b28835..517993efa5 100644 --- a/tools/public_api_guard/BUILD.bazel +++ b/tools/public_api_guard/BUILD.bazel @@ -1,3 +1,14 @@ +load("//tools/ts-api-guardian:index.bzl", "ts_api_guardian_test") load(":public_api_guard.bzl", "generate_targets") -generate_targets(glob(["**/*.d.ts"])) +generate_targets(glob(["*/**/*.d.ts"])) + +ts_api_guardian_test( + name = "ng_global_utils_api", + actual = "angular/packages/core/src/render3/global_utils_api.d.ts", + data = [ + ":global_utils.d.ts", + "//packages/core", + ], + golden = "angular/tools/public_api_guard/global_utils.d.ts", +) diff --git a/tools/public_api_guard/global_utils.d.ts b/tools/public_api_guard/global_utils.d.ts new file mode 100644 index 0000000000..62fba3a094 --- /dev/null +++ b/tools/public_api_guard/global_utils.d.ts @@ -0,0 +1,11 @@ +export declare function getComponent(target: {}): T | null; + +export declare function getDirectives(target: {}): Array<{}>; + +export declare function getHostComponent(target: {}): T | null; + +export declare function getInjector(target: {}): Injector; + +export declare function getPlayers(ref: ComponentInstance | DirectiveInstance | HTMLElement): Player[]; + +export declare function getRootComponents(target: {}): any[];