Merge pull request #9479 from backstage/jhaals/remove-serializeEntityRef

catalog-model: Remove serializeEntityRef

.changeset/dry-lies-move.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-catalog-react': patch
+'@backstage/plugin-todo-backend': patch
+---
+
+Replace usage of `serializeEntityRef` with `stringifyEntityRef`

.changeset/plenty-boxes-wink.md

@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-model': minor
+---
+
+**BREAKING**: Remove deprecated `serializeEntityRef` which is replaced by `stringifyEntityRef`.

packages/catalog-model/api-report.md

@@ -489,17 +489,6 @@ export class SchemaValidEntityPolicy implements EntityPolicy {
   enforce(entity: Entity): Promise<Entity>;
 }
 
-// @public @deprecated
-export function serializeEntityRef(
-  ref:
-    | Entity
-    | {
-        kind?: string;
-        namespace?: string;
-        name: string;
-      },
-): EntityRef;
-
 // @public
 export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location';
 

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

@@ -40,7 +40,6 @@ export {
   getEntityName,
   parseEntityName,
   parseEntityRef,
-  serializeEntityRef,
   stringifyEntityRef,
 } from './ref';
 export type { EntityRefContext } from './ref';

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

@@ -16,12 +16,7 @@
 
 import { ENTITY_DEFAULT_NAMESPACE } from './constants';
 import { Entity } from './Entity';
-import {
-  compareEntityToRef,
-  parseEntityName,
-  parseEntityRef,
-  serializeEntityRef,
-} from './ref';
+import { compareEntityToRef, parseEntityName, parseEntityRef } from './ref';
 
 describe('ref', () => {
   describe('parseEntityName', () => {
@@ -329,64 +324,6 @@ describe('ref', () => {
     });
   });
 
-  describe('serializeEntityRef', () => {
-    it('handles partials', () => {
-      expect(
-        serializeEntityRef({ kind: 'a', namespace: 'b', name: 'c' }),
-      ).toEqual('a:b/c');
-      expect(serializeEntityRef({ namespace: 'b', name: 'c' })).toEqual('b/c');
-      expect(serializeEntityRef({ kind: 'a', name: 'c' })).toEqual('a:c');
-      expect(serializeEntityRef({ name: 'c' })).toEqual('c');
-    });
-
-    it('handles entities', () => {
-      const entityWithNamespace: Entity = {
-        apiVersion: 'a',
-        kind: 'b',
-        metadata: {
-          name: 'c',
-          namespace: 'd',
-        },
-      };
-      const entityWithoutNamespace: Entity = {
-        apiVersion: 'a',
-        kind: 'b',
-        metadata: {
-          name: 'c',
-        },
-      };
-      expect(serializeEntityRef(entityWithNamespace)).toEqual('b:d/c');
-      expect(serializeEntityRef(entityWithoutNamespace)).toEqual('b:c');
-    });
-
-    it('picks the least complex form', () => {
-      expect(
-        serializeEntityRef({ kind: 'a', namespace: 'b', name: 'c' }),
-      ).toEqual('a:b/c');
-      expect(serializeEntityRef({ namespace: 'b', name: 'c' })).toEqual('b/c');
-      expect(serializeEntityRef({ kind: 'a', name: 'c' })).toEqual('a:c');
-      expect(serializeEntityRef({ name: 'c' })).toEqual('c');
-      expect(
-        serializeEntityRef({ kind: 'a:x', namespace: 'b', name: 'c' }),
-      ).toEqual({ kind: 'a:x', namespace: 'b', name: 'c' });
-      expect(
-        serializeEntityRef({ kind: 'a/x', namespace: 'b', name: 'c' }),
-      ).toEqual({ kind: 'a/x', namespace: 'b', name: 'c' });
-      expect(
-        serializeEntityRef({ kind: 'a', namespace: 'b:x', name: 'c' }),
-      ).toEqual({ kind: 'a', namespace: 'b:x', name: 'c' });
-      expect(
-        serializeEntityRef({ kind: 'a', namespace: 'b/x', name: 'c' }),
-      ).toEqual({ kind: 'a', namespace: 'b/x', name: 'c' });
-      expect(
-        serializeEntityRef({ kind: 'a', namespace: 'b', name: 'c:x' }),
-      ).toEqual({ kind: 'a', namespace: 'b', name: 'c:x' });
-      expect(
-        serializeEntityRef({ kind: 'a', namespace: 'b', name: 'c/x' }),
-      ).toEqual({ kind: 'a', namespace: 'b', name: 'c/x' });
-    });
-  });
-
   describe('compareEntityToRef', () => {
     const entityWithNamespace: Entity = {
       apiVersion: 'a',

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

@@ -184,54 +184,6 @@ export function parseEntityRef(
   };
 }
 
-/**
- * Takes an entity reference or name, and outputs an entity reference on the
- * most compact form possible. I.e. if the parts do not contain any
- * special/reserved characters, it outputs the string form, otherwise it
- * outputs the compound form.
- *
- * @public
- * @deprecated Use `stringifyEntityRef` instead
- * @param ref - The reference to serialize
- * @returns The same reference on either string or compound form
- */
-export function serializeEntityRef(
-  ref:
-    | Entity
-    | {
-        kind?: string;
-        namespace?: string;
-        name: string;
-      },
-): EntityRef {
-  let kind;
-  let namespace;
-  let name;
-
-  if ('metadata' in ref) {
-    kind = ref.kind;
-    namespace = ref.metadata.namespace;
-    name = ref.metadata.name;
-  } else {
-    kind = ref.kind;
-    namespace = ref.namespace;
-    name = ref.name;
-  }
-
-  if (
-    kind?.includes(':') ||
-    kind?.includes('/') ||
-    namespace?.includes(':') ||
-    namespace?.includes('/') ||
-    name.includes(':') ||
-    name.includes('/')
-  ) {
-    return { kind, namespace, name };
-  }
-
-  return `${kind ? `${kind}:` : ''}${namespace ? `${namespace}/` : ''}${name}`;
-}
-
 /**
  * Takes an entity or entity name/reference, and returns the string form of an
  * entity ref.

plugins/catalog-react/src/components/EntityRefLink/format.ts

@@ -18,7 +18,6 @@ import {
   Entity,
   EntityName,
   ENTITY_DEFAULT_NAMESPACE,
-  serializeEntityRef,
 } from '@backstage/catalog-model';
 
 export function formatEntityRefTitle(
@@ -45,13 +44,9 @@ export function formatEntityRefTitle(
   }
 
   kind = kind.toLocaleLowerCase('en-US');
-
-  return `${serializeEntityRef({
-    kind:
-      defaultKind && defaultKind.toLocaleLowerCase('en-US') === kind
-        ? undefined
-        : kind,
-    name,
-    namespace,
-  })}`;
+  kind =
+    defaultKind && defaultKind.toLocaleLowerCase('en-US') === kind
+      ? undefined
+      : kind;
+  return `${kind ? `${kind}:` : ''}${namespace ? `${namespace}/` : ''}${name}`;
 }

plugins/todo-backend/src/service/TodoReaderService.test.ts

@@ -301,7 +301,7 @@ describe('TodoReaderService', () => {
     await expect(service.listTodos({ entity: entityName })).rejects.toEqual(
       expect.objectContaining({
         name: 'NotFoundError',
-        message: 'Entity not found, Component:default/my-component',
+        message: 'Entity not found, component:default/my-component',
       }),
     );
     expect(catalogClient.getEntityByName).toHaveBeenCalledWith(entityName, {
@@ -321,7 +321,7 @@ describe('TodoReaderService', () => {
       expect.objectContaining({
         name: 'InputError',
         message:
-          'No entity location annotation found for Component:my-component',
+          'No entity location annotation found for component:default/my-component',
       }),
     );
   });
@@ -342,7 +342,7 @@ describe('TodoReaderService', () => {
     await expect(service.listTodos({ entity: entityName })).rejects.toEqual(
       expect.objectContaining({
         name: 'InputError',
-        message: `Invalid entity location type for Component:my-component, got 'file'`,
+        message: `Invalid entity location type for component:default/my-component, got 'file'`,
       }),
     );
   });
@@ -363,7 +363,7 @@ describe('TodoReaderService', () => {
     await expect(service.listTodos({ entity: entityName })).rejects.toEqual(
       expect.objectContaining({
         name: 'InputError',
-        message: `Invalid entity source location type for Component:my-component, got 'file'`,
+        message: `Invalid entity source location type for component:default/my-component, got 'file'`,
       }),
     );
   });

plugins/todo-backend/src/service/TodoReaderService.ts

@@ -19,9 +19,9 @@ import { CatalogApi } from '@backstage/catalog-client';
 import {
   LOCATION_ANNOTATION,
   SOURCE_LOCATION_ANNOTATION,
-  serializeEntityRef,
   Entity,
   parseLocationRef,
+  stringifyEntityRef,
 } from '@backstage/catalog-model';
 import { TodoReader } from '../lib';
 import { ListTodosRequest, ListTodosResponse, TodoService } from './types';
@@ -71,7 +71,7 @@ export class TodoReaderService implements TodoService {
     });
     if (!entity) {
       throw new NotFoundError(
-        `Entity not found, ${serializeEntityRef(req.entity)}`,
+        `Entity not found, ${stringifyEntityRef(req.entity)}`,
       );
     }
 
@@ -133,7 +133,7 @@ export class TodoReaderService implements TodoService {
       const parsed = parseLocationRef(sourceLocation);
       if (parsed.type !== 'url') {
         throw new InputError(
-          `Invalid entity source location type for ${serializeEntityRef(
+          `Invalid entity source location type for ${stringifyEntityRef(
             entity,
           )}, got '${parsed.type}'`,
         );
@@ -146,7 +146,7 @@ export class TodoReaderService implements TodoService {
       const parsed = parseLocationRef(location);
       if (parsed.type !== 'url') {
         throw new InputError(
-          `Invalid entity location type for ${serializeEntityRef(
+          `Invalid entity location type for ${stringifyEntityRef(
             entity,
           )}, got '${parsed.type}'`,
         );
@@ -154,7 +154,7 @@ export class TodoReaderService implements TodoService {
       return parsed.target;
     }
     throw new InputError(
-      `No entity location annotation found for ${serializeEntityRef(entity)}`,
+      `No entity location annotation found for ${stringifyEntityRef(entity)}`,
     );
   }
 }