API reports and Changelog

Signed-off-by: Joon Park <joonp@spotify.com>

.changeset/smart-fans-complain.md

@@ -0,0 +1,42 @@
+---
+'@backstage/plugin-catalog-backend': minor
+---
+
+**BREAKING** EntitiesSearchFilter fields have changed.
+
+EntitiesSearchFilter now has only two fields: `key` and `value`. The `matchValueIn` and `matchValueExists` fields are no longer are supported. Previous filters written using the `matchValueIn` and `matchValueExists` fields can be rewritten as follows:
+
+Filtering by existence of key only:
+
+```diff
+  filter: {
+    {
+      key: 'abc',
+-     matchValueExists: true,
+    },
+  }
+```
+
+Filtering by key and values:
+
+```diff
+  filter: {
+    {
+      key: 'abc',
+-     matchValueExists: true,
+-     matchValueIn: ['xyz'],
++     values: ['xyz'],
+    },
+  }
+```
+
+Negation of filters can now be achieved through a `not` object:
+
+```
+filter: {
+  not: {
+    key: 'abc',
+    values: ['xyz'],
+  },
+}
+```

plugins/catalog-backend/api-report.md

@@ -846,8 +846,7 @@ export type EntitiesResponse = {
 // @public
 export type EntitiesSearchFilter = {
   key: string;
-  matchValueIn?: string[];
-  matchValueExists?: boolean;
+  values?: string[];
 };
 
 // Warning: (ae-missing-release-tag) "entity" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -877,6 +876,9 @@ export type EntityFilter =
   | {
       anyOf: EntityFilter[];
     }
+  | {
+      not: EntityFilter;
+    }
   | EntitiesSearchFilter;
 
 // Warning: (ae-missing-release-tag) "EntityPagination" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -1546,9 +1548,9 @@ export class UrlReaderProcessor implements CatalogProcessor {
 
 // Warnings were encountered during analysis:
 //
-// src/catalog/types.d.ts:97:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
-// src/catalog/types.d.ts:98:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
-// src/catalog/types.d.ts:99:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
+// src/catalog/types.d.ts:94:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
+// src/catalog/types.d.ts:95:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
+// src/catalog/types.d.ts:96:8 - (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
 // src/ingestion/processors/GithubMultiOrgReaderProcessor.d.ts:23:9 - (ae-forgotten-export) The symbol "GithubMultiOrgConfig" needs to be exported by the entry point index.d.ts
 // src/ingestion/types.d.ts:8:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/legacy/database/types.d.ts:98:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen

plugins/catalog-backend/src/service/request/basicEntityFilter.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { EntitiesValuesFilter, EntityFilter } from '../../catalog';
+import { EntitiesSearchFilter, EntityFilter } from '../../catalog';
 
 /**
  * Forms a full EntityFilter based on a single key-value(s) object.
@@ -22,7 +22,7 @@ import { EntitiesValuesFilter, EntityFilter } from '../../catalog';
 export function basicEntityFilter(
   items: Record<string, string | string[]>,
 ): EntityFilter {
-  const filtersByKey: Record<string, EntitiesValuesFilter> = {};
+  const filtersByKey: Record<string, EntitiesSearchFilter> = {};
 
   for (const [key, value] of Object.entries(items)) {
     const values = [value].flat();

plugins/catalog-backend/src/service/request/parseEntityFilterParams.ts

@@ -15,11 +15,7 @@
  */
 
 import { InputError } from '@backstage/errors';
-import {
-  EntitiesSearchFilter,
-  EntitiesValuesFilter,
-  EntityFilter,
-} from '../../catalog';
+import { EntitiesSearchFilter, EntityFilter } from '../../catalog';
 import { parseStringsParam } from './common';
 
 /**
@@ -80,9 +76,8 @@ export function parseEntityFilterString(
       key in filtersByKey ? filtersByKey[key] : (filtersByKey[key] = { key });
 
     if (value !== undefined) {
-      const valuesFilter = f as EntitiesValuesFilter;
-      valuesFilter.values = valuesFilter.values || [];
-      valuesFilter.values.push(value);
+      f.values = f.values || [];
+      f.values.push(value);
     }
   }