deprecate EntityName, introduce CompoundEntityRef

deprecate getEntityName, introduce getCompoundEntityRef

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

packages/catalog-client/api-report.md

@@ -3,8 +3,8 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Entity } from '@backstage/catalog-model';
-import { EntityName } from '@backstage/catalog-model';
 
 // @public
 export type AddLocationRequest = {
@@ -39,7 +39,7 @@ export interface CatalogApi {
     options?: CatalogRequestOptions,
   ): Promise<GetEntityAncestorsResponse>;
   getEntityByName(
-    name: EntityName,
+    name: CompoundEntityRef,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined>;
   getEntityFacets(
@@ -91,7 +91,7 @@ export class CatalogClient implements CatalogApi {
     options?: CatalogRequestOptions,
   ): Promise<GetEntityAncestorsResponse>;
   getEntityByName(
-    compoundName: EntityName,
+    compoundName: CompoundEntityRef,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined>;
   getEntityFacets(

packages/catalog-client/src/CatalogClient.ts

@@ -18,7 +18,7 @@ import {
   ANNOTATION_LOCATION,
   ANNOTATION_ORIGIN_LOCATION,
   Entity,
-  EntityName,
+  CompoundEntityRef,
   parseEntityRef,
   stringifyEntityRef,
   stringifyLocationRef,
@@ -174,7 +174,7 @@ export class CatalogClient implements CatalogApi {
    * {@inheritdoc CatalogApi.getEntityByName}
    */
   async getEntityByName(
-    compoundName: EntityName,
+    compoundName: CompoundEntityRef,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined> {
     const { kind, namespace = 'default', name } = compoundName;

packages/catalog-client/src/types/api.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { Entity, EntityName } from '@backstage/catalog-model';
+import { CompoundEntityRef, Entity } from '@backstage/catalog-model';
 
 /**
  * This symbol can be used in place of a value when passed to filters in e.g.
@@ -310,7 +310,7 @@ export interface CatalogApi {
    * @param options - Additional options
    */
   getEntityByName(
-    name: EntityName,
+    name: CompoundEntityRef,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined>;
 

packages/catalog-model/api-report.md

@@ -88,6 +88,13 @@ export { ComponentEntityV1alpha1 };
 // @public
 export const componentEntityV1alpha1Validator: KindValidator;
 
+// @public
+export type CompoundEntityRef = {
+  kind: string;
+  namespace: string;
+  name: string;
+};
+
 // @public
 export const DEFAULT_NAMESPACE = 'default';
 
@@ -166,12 +173,8 @@ export type EntityMeta = JsonObject & {
   links?: EntityLink[];
 };
 
-// @public
-export type EntityName = {
-  kind: string;
-  namespace: string;
-  name: string;
-};
+// @public @deprecated
+export type EntityName = CompoundEntityRef;
 
 // @public
 export const EntityPolicies: {
@@ -196,7 +199,7 @@ export type EntityRef =
 // @public
 export type EntityRelation = {
   type: string;
-  target: EntityName;
+  target: CompoundEntityRef;
   targetRef: string;
 };
 
@@ -229,7 +232,10 @@ export class FieldFormatEntityPolicy implements EntityPolicy {
 }
 
 // @public
-export function getEntityName(entity: Entity): EntityName;
+export function getCompoundEntityRef(entity: Entity): CompoundEntityRef;
+
+// @public @deprecated
+export const getEntityName: typeof getCompoundEntityRef;
 
 // @public
 export function getEntitySourceLocation(entity: Entity): {
@@ -337,7 +343,7 @@ export function parseEntityName(
     defaultKind?: string;
     defaultNamespace?: string;
   },
-): EntityName;
+): CompoundEntityRef;
 
 // @public
 export function parseEntityRef(
@@ -352,7 +358,7 @@ export function parseEntityRef(
     defaultKind?: string;
     defaultNamespace?: string;
   },
-): EntityName;
+): CompoundEntityRef;
 
 // @public
 export function parseLocationRef(ref: string): {

packages/catalog-model/src/entity/Entity.ts

@@ -15,7 +15,7 @@
  */
 
 import { JsonObject } from '@backstage/types';
-import { EntityName } from '../types';
+import { CompoundEntityRef } from '../types';
 import { EntityStatus } from './EntityStatus';
 
 /**
@@ -201,7 +201,7 @@ export type EntityRelation = {
    *
    * @deprecated use targetRef instead
    */
-  target: EntityName;
+  target: CompoundEntityRef;
 
   /**
    * The entity ref of the target of this relation.

packages/catalog-model/src/entity/index.ts

@@ -34,6 +34,7 @@ export type {
 } from './EntityStatus';
 export * from './policies';
 export {
+  getCompoundEntityRef,
   getEntityName,
   parseEntityName,
   parseEntityRef,

packages/catalog-model/src/entity/ref.ts

@@ -15,7 +15,7 @@
  */
 
 import { DEFAULT_NAMESPACE } from './constants';
-import { EntityName } from '../types';
+import { CompoundEntityRef } from '../types';
 import { Entity } from './Entity';
 
 function parseRefString(ref: string): {
@@ -38,14 +38,25 @@ function parseRefString(ref: string): {
 }
 
 /**
- * Extracts the kind, namespace and name that form the name triplet of the
- * given entity.
+ * Extracts the kind, namespace and name that form the compound entity ref
+ * triplet of the given entity.
+ *
+ * @public
+ * @deprecated Use getCompoundEntityRef instead
+ * @param entity - An entity
+ * @returns The compound entity ref
+ */
+export const getEntityName = getCompoundEntityRef;
+
+/**
+ * Extracts the kind, namespace and name that form the compound entity ref
+ * triplet of the given entity.
  *
  * @public
  * @param entity - An entity
- * @returns The complete entity name
+ * @returns The compound entity ref
  */
-export function getEntityName(entity: Entity): EntityName {
+export function getCompoundEntityRef(entity: Entity): CompoundEntityRef {
   return {
     kind: entity.kind,
     namespace: entity.metadata.namespace || DEFAULT_NAMESPACE,
@@ -77,7 +88,7 @@ export function parseEntityName(
     /** The default namespace, if none is given in the reference */
     defaultNamespace?: string;
   } = {},
-): EntityName {
+): CompoundEntityRef {
   const { kind, namespace, name } = parseEntityRef(ref, {
     defaultNamespace: DEFAULT_NAMESPACE,
     ...context,
@@ -114,7 +125,7 @@ export function parseEntityRef(
     /** The default namespace, if none is given in the reference */
     defaultNamespace?: string;
   },
-): EntityName {
+): CompoundEntityRef {
   if (!ref) {
     throw new Error(`Entity reference must not be empty`);
   }

packages/catalog-model/src/index.ts

@@ -24,5 +24,5 @@ export * from './entity';
 export { EntityPolicies } from './EntityPolicies';
 export * from './kinds';
 export * from './location';
-export type { EntityName, EntityRef } from './types';
+export type { EntityName, EntityRef, CompoundEntityRef } from './types';
 export * from './validation';

packages/catalog-model/src/types.ts

@@ -15,16 +15,25 @@
  */
 
 /**
- * A complete entity name, with the full kind-namespace-name triplet.
+ * All parts of a complete entity ref, forming a full kind-namespace-name
+ * triplet.
  *
  * @public
  */
-export type EntityName = {
+export type CompoundEntityRef = {
   kind: string;
   namespace: string;
   name: string;
 };
 
+/**
+ * A complete entity name, with the full kind-namespace-name triplet.
+ *
+ * @deprecated Use CompoundEntityRef instead
+ * @public
+ */
+export type EntityName = CompoundEntityRef;
+
 /**
  * A reference by name to an entity, either as a compact string representation,
  * or as a compound reference structure.

packages/techdocs-cli-embedded-app/src/apis.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { EntityName } from '@backstage/catalog-model';
+import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import {
   scmIntegrationsApiRef,
@@ -81,7 +81,7 @@ class TechDocsDevStorageApi implements TechDocsStorageApi {
     return this.configApi.getString('techdocs.builder');
   }
 
-  async getEntityDocs(_entityId: EntityName, path: string) {
+  async getEntityDocs(_entityId: CompoundEntityRef, path: string) {
     const apiOrigin = await this.getApiOrigin();
     // Irrespective of the entity, use mkdocs server to find the file for the path.
     const url = `${apiOrigin}/${path}`;
@@ -97,7 +97,7 @@ class TechDocsDevStorageApi implements TechDocsStorageApi {
     return request.text();
   }
 
-  async syncEntityDocs(_: EntityName): Promise<SyncResult> {
+  async syncEntityDocs(_: CompoundEntityRef): Promise<SyncResult> {
     // this is just stub of this function as we don't need to check if docs are up to date,
     // we always want to retrigger a new build
     return 'cached';
@@ -106,7 +106,7 @@ class TechDocsDevStorageApi implements TechDocsStorageApi {
   // Used by transformer to modify the request to assets (CSS, Image) from inside the HTML.
   async getBaseUrl(
     oldBaseUrl: string,
-    _entityId: EntityName,
+    _entityId: CompoundEntityRef,
     path: string,
   ): Promise<string> {
     const apiOrigin = await this.getApiOrigin();
@@ -154,7 +154,7 @@ class TechDocsDevApi implements TechDocsApi {
     };
   }
 
-  async getTechDocsMetadata(_entityId: EntityName) {
+  async getTechDocsMetadata(_entityId: CompoundEntityRef) {
     return {
       site_name: 'Live preview environment',
       site_description: '',

packages/techdocs-cli-embedded-app/src/components/TechDocsPage/TechDocsPage.tsx

@@ -29,7 +29,7 @@ import LightIcon from '@material-ui/icons/Brightness7';
 import DarkIcon from '@material-ui/icons/Brightness4';
 
 import { lightTheme, darkTheme } from '@backstage/theme';
-import { EntityName } from '@backstage/catalog-model';
+import { CompoundEntityRef } from '@backstage/catalog-model';
 
 import { Content } from '@backstage/core-components';
 
@@ -127,7 +127,7 @@ const TechDocsPageContent = ({
   onReady,
   entityRef,
 }: {
-  entityRef: EntityName;
+  entityRef: CompoundEntityRef;
   onReady: () => void;
 }) => {
   const classes = useStyles();

packages/techdocs-common/api-report.md

@@ -5,10 +5,10 @@
 ```ts
 /// <reference types="node" />
 
+import { CompoundEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import { ContainerRunner } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
-import { EntityName } from '@backstage/catalog-model';
 import express from 'express';
 import { IndexableDocument } from '@backstage/search-common';
 import { Logger as Logger_2 } from 'winston';
@@ -157,7 +157,9 @@ export class Publisher {
 // @public
 export interface PublisherBase {
   docsRouter(): express.Handler;
-  fetchTechDocsMetadata(entityName: EntityName): Promise<TechDocsMetadata>;
+  fetchTechDocsMetadata(
+    entityName: CompoundEntityRef,
+  ): Promise<TechDocsMetadata>;
   getReadiness(): Promise<ReadinessResponse>;
   hasDocsBeenGenerated(entityName: Entity): Promise<boolean>;
   migrateDocsCase?(migrateRequest: MigrateRequest): Promise<void>;

packages/techdocs-common/src/stages/publish/awsS3.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Entity, EntityName } from '@backstage/catalog-model';
+import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import { assertError, ForwardedError } from '@backstage/errors';
 import aws, { Credentials } from 'aws-sdk';
@@ -321,7 +321,7 @@ export class AwsS3Publish implements PublisherBase {
   }
 
   async fetchTechDocsMetadata(
-    entityName: EntityName,
+    entityName: CompoundEntityRef,
   ): Promise<TechDocsMetadata> {
     try {
       return await new Promise<TechDocsMetadata>(async (resolve, reject) => {

packages/techdocs-common/src/stages/publish/azureBlobStorage.ts

@@ -19,7 +19,7 @@ import {
   ContainerClient,
   StorageSharedKeyCredential,
 } from '@azure/storage-blob';
-import { Entity, EntityName } from '@backstage/catalog-model';
+import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import { assertError, ForwardedError } from '@backstage/errors';
 import express from 'express';
@@ -300,7 +300,7 @@ export class AzureBlobStoragePublish implements PublisherBase {
   }
 
   async fetchTechDocsMetadata(
-    entityName: EntityName,
+    entityName: CompoundEntityRef,
   ): Promise<TechDocsMetadata> {
     const entityTriplet = `${entityName.namespace}/${entityName.kind}/${entityName.name}`;
     const entityRootDir = this.legacyPathCasing

packages/techdocs-common/src/stages/publish/googleStorage.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Entity, EntityName } from '@backstage/catalog-model';
+import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import { assertError } from '@backstage/errors';
 import { File, FileExistsResponse, Storage } from '@google-cloud/storage';
@@ -238,7 +238,9 @@ export class GoogleGCSPublish implements PublisherBase {
     return { objects };
   }
 
-  fetchTechDocsMetadata(entityName: EntityName): Promise<TechDocsMetadata> {
+  fetchTechDocsMetadata(
+    entityName: CompoundEntityRef,
+  ): Promise<TechDocsMetadata> {
     return new Promise((resolve, reject) => {
       const entityTriplet = `${entityName.namespace}/${entityName.kind}/${entityName.name}`;
       const entityDir = this.legacyPathCasing

packages/techdocs-common/src/stages/publish/local.ts

@@ -17,7 +17,7 @@ import {
   PluginEndpointDiscovery,
   resolvePackagePath,
 } from '@backstage/backend-common';
-import { Entity, EntityName } from '@backstage/catalog-model';
+import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import express from 'express';
 import fs from 'fs-extra';
@@ -142,7 +142,7 @@ export class LocalPublish implements PublisherBase {
   }
 
   async fetchTechDocsMetadata(
-    entityName: EntityName,
+    entityName: CompoundEntityRef,
   ): Promise<TechDocsMetadata> {
     const metadataPath = this.staticEntityPathJoin(
       entityName.namespace,

packages/techdocs-common/src/stages/publish/openStackSwift.test.ts

@@ -17,7 +17,7 @@
 import { getVoidLogger } from '@backstage/backend-common';
 import {
   Entity,
-  EntityName,
+  CompoundEntityRef,
   DEFAULT_NAMESPACE,
 } from '@backstage/catalog-model';
 import { ConfigReader } from '@backstage/config';
@@ -45,7 +45,7 @@ const createMockEntity = (annotations = {}): Entity => {
   };
 };
 
-const createMockEntityName = (): EntityName => ({
+const createMockEntityName = (): CompoundEntityRef => ({
   kind: 'TestKind',
   name: 'test-component-name',
   namespace: 'test-namespace',

packages/techdocs-common/src/stages/publish/openStackSwift.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Entity, EntityName } from '@backstage/catalog-model';
+import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 import express from 'express';
 import fs from 'fs-extra';
@@ -194,7 +194,7 @@ export class OpenStackSwiftPublish implements PublisherBase {
   }
 
   async fetchTechDocsMetadata(
-    entityName: EntityName,
+    entityName: CompoundEntityRef,
   ): Promise<TechDocsMetadata> {
     return await new Promise<TechDocsMetadata>(async (resolve, reject) => {
       const entityRootDir = `${entityName.namespace}/${entityName.kind}/${entityName.name}`;

packages/techdocs-common/src/stages/publish/types.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Entity, EntityName } from '@backstage/catalog-model';
+import { Entity, CompoundEntityRef } from '@backstage/catalog-model';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { Logger } from 'winston';
 import express from 'express';
@@ -133,7 +133,9 @@ export interface PublisherBase {
    * Retrieve TechDocs Metadata about a site e.g. name, contributors, last updated, etc.
    * This API uses the techdocs_metadata.json file that co-exists along with the generated docs.
    */
-  fetchTechDocsMetadata(entityName: EntityName): Promise<TechDocsMetadata>;
+  fetchTechDocsMetadata(
+    entityName: CompoundEntityRef,
+  ): Promise<TechDocsMetadata>;
 
   /**
    * Route middleware to serve static documentation files for an entity.