chore: added changeset

Signed-off-by: blam <ben@blam.sh>

.changeset/sour-eggs-kick.md

@@ -0,0 +1,9 @@
+---
+'@backstage/plugin-catalog': patch
+'@backstage/plugin-catalog-react': patch
+---
+
+Added the following deprecations to the `catalog-react` package:
+
+- **DEPRECATION**: `useEntity` will now warn if the entity has not yet been loaded. This hook is now designed only to be used inside of an `EntityPage` where the `entity` prop is guaranteed to be defined. If you would like to use it outside, please use `useAsyncEntity` instead.
+- **DEPRECATION**: the `loading`, `error` and `refresh` properties that are returned from `useEntity` have been deprecated, and are available on `useAsyncEntity` instead.

plugins/catalog-react/api-report.md

@@ -524,12 +524,24 @@ export type UnregisterEntityDialogProps = {
 };
 
 // @public
-export function useEntity<T extends Entity = Entity>(): {
-  entity: T;
+export function useAsyncEntity<
+  T extends Entity = Entity,
+>(): UseAsyncEntityResponse<T>;
+
+// @public
+export interface UseAsyncEntityResponse<T> {
+  // (undocumented)
+  entity?: T;
+  // (undocumented)
+  error?: Error;
+  // (undocumented)
   loading: boolean;
-  error: Error | undefined;
-  refresh: VoidFunction | undefined;
-};
+  // (undocumented)
+  refresh?: VoidFunction;
+}
+
+// @public
+export function useEntity<T extends Entity = Entity>(): UseEntityResponse<T>;
 
 // @public @deprecated
 export const useEntityCompoundName: () => {
@@ -571,6 +583,18 @@ export function useEntityPermission(permission: Permission): {
   error?: Error;
 };
 
+// @public
+export interface UseEntityResponse<T> {
+  // (undocumented)
+  entity: T;
+  // @deprecated (undocumented)
+  error?: Error;
+  // @deprecated (undocumented)
+  loading: boolean;
+  // @deprecated (undocumented)
+  refresh?: VoidFunction;
+}
+
 // @public
 export function useEntityTypeFilter(): {
   loading: boolean;

plugins/catalog-react/src/hooks/useEntity.tsx

@@ -128,16 +128,27 @@ export const useEntityFromUrl = (): EntityLoadingStatus => {
 
   return { entity, loading, error, refresh };
 };
+
+/**
+ * @public
+ *
+ * The response shape for {@link useEntity}
+ */
 export interface UseEntityResponse<T> {
   entity: T;
-  /** @deprecated use useAsyncEntity instead */
+  /** @deprecated use {@link useAsyncEntity} instead */
   loading: boolean;
-  /** @deprecated use useAsyncEntity instead */
+  /** @deprecated use {@link useAsyncEntity} instead */
   error?: Error;
-  /** @deprecated use useAsyncEntity instead */
+  /** @deprecated use {@link useAsyncEntity} instead */
   refresh?: VoidFunction;
 }
 
+/**
+ * @public
+ *
+ * The response shape for {@link useAsyncEntity}
+ */
 export interface UseAsyncEntityResponse<T> {
   entity?: T;
   loading: boolean;
@@ -165,7 +176,14 @@ export function useEntity<T extends Entity = Entity>(): UseEntityResponse<T> {
   }
 
   if (!value.entity) {
-    throw new Error('Entity has not been loaded yet');
+    // Once we have removed the additional fields from being returned we can drop this deprecation
+    // and move to the error instead.
+    // throw new Error('useEntity hook is being called outside of an EntityPage where the entity has not been loaded. If this is intentional, please use useAsyncEntity instead.');
+
+    // eslint-disable-next-line no-console
+    console.warn(
+      'DEPRECATION: useEntity hook is being called outside of an EntityPage where the entity has not been loaded. If this is intentional, please use useAsyncEntity instead. This warning will be replaced with an error in future releases.',
+    );
   }
 
   const { entity, loading, error, refresh } = value;