Merge pull request #8053 from backstage/rugvip/errapi

core-plugin-api: added ErrorApi* prefix to Error and ErrorContext types

.changeset/nine-bananas-mate.md

@@ -0,0 +1,6 @@
+---
+'@backstage/core-app-api': patch
+'@backstage/test-utils': patch
+---
+
+Migrated to using new `ErrorApiError` and `ErrorApiErrorContext` names.

.changeset/yellow-deers-act.md

@@ -0,0 +1,5 @@
+---
+'@backstage/core-plugin-api': patch
+---
+
+Deprecated the `Error` and `ErrorContext` types, replacing them with identical `ErrorApiError` and `ErrorApiErrorContext` types.

docs/api/utility-apis.md

@@ -199,7 +199,7 @@ export a class that `implements` the target API, for example:
 
 ```ts
 export class IgnoringErrorApi implements ErrorApi {
-  post(error: Error, context?: ErrorContext) {
+  post(error: ErrorApiError, context?: ErrorApiErrorContext) {
     // ignore error
   }
 }

packages/core-app-api/api-report.md

@@ -28,9 +28,9 @@ import { bitbucketAuthApiRef } from '@backstage/core-plugin-api';
 import { ComponentType } from 'react';
 import { ConfigReader } from '@backstage/config';
 import { DiscoveryApi } from '@backstage/core-plugin-api';
-import { Error as Error_2 } from '@backstage/core-plugin-api';
 import { ErrorApi } from '@backstage/core-plugin-api';
-import { ErrorContext } from '@backstage/core-plugin-api';
+import { ErrorApiError } from '@backstage/core-plugin-api';
+import { ErrorApiErrorContext } from '@backstage/core-plugin-api';
 import { ExternalRouteRef } from '@backstage/core-plugin-api';
 import { FeatureFlag } from '@backstage/core-plugin-api';
 import { FeatureFlagsApi } from '@backstage/core-plugin-api';
@@ -327,11 +327,11 @@ export class ErrorAlerter implements ErrorApi {
   constructor(alertApi: AlertApi, errorApi: ErrorApi);
   // (undocumented)
   error$(): Observable<{
-    error: Error_2;
-    context?: ErrorContext | undefined;
+    error: ErrorApiError;
+    context?: ErrorApiErrorContext | undefined;
   }>;
   // (undocumented)
-  post(error: Error, context?: ErrorContext): void;
+  post(error: ErrorApiError, context?: ErrorApiErrorContext): void;
 }
 
 // @public
@@ -339,10 +339,10 @@ export class ErrorApiForwarder implements ErrorApi {
   // (undocumented)
   error$(): Observable<{
     error: Error;
-    context?: ErrorContext;
+    context?: ErrorApiErrorContext;
   }>;
   // (undocumented)
-  post(error: Error, context?: ErrorContext): void;
+  post(error: ErrorApiError, context?: ErrorApiErrorContext): void;
 }
 
 // @public
@@ -603,7 +603,7 @@ export type SignInResult = {
 
 // @public
 export class UnhandledErrorForwarder {
-  static forward(errorApi: ErrorApi, errorContext: ErrorContext): void;
+  static forward(errorApi: ErrorApi, errorContext: ErrorApiErrorContext): void;
 }
 
 // @public

packages/core-app-api/src/apis/implementations/ErrorApi/ErrorAlerter.ts

@@ -13,7 +13,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { ErrorApi, ErrorContext, AlertApi } from '@backstage/core-plugin-api';
+import {
+  ErrorApi,
+  ErrorApiError,
+  ErrorApiErrorContext,
+  AlertApi,
+} from '@backstage/core-plugin-api';
 
 /**
  * Decorates an ErrorApi by also forwarding error messages
@@ -27,7 +32,7 @@ export class ErrorAlerter implements ErrorApi {
     private readonly errorApi: ErrorApi,
   ) {}
 
-  post(error: Error, context?: ErrorContext) {
+  post(error: ErrorApiError, context?: ErrorApiErrorContext) {
     if (!context?.hidden) {
       this.alertApi.post({ message: error.message, severity: 'error' });
     }

packages/core-app-api/src/apis/implementations/ErrorApi/ErrorApiForwarder.ts

@@ -14,7 +14,11 @@
  * limitations under the License.
  */
 
-import { ErrorApi, ErrorContext } from '@backstage/core-plugin-api';
+import {
+  ErrorApi,
+  ErrorApiError,
+  ErrorApiErrorContext,
+} from '@backstage/core-plugin-api';
 import { Observable } from '@backstage/types';
 import { PublishSubject } from '../../../lib/subjects';
 
@@ -26,14 +30,14 @@ import { PublishSubject } from '../../../lib/subjects';
 export class ErrorApiForwarder implements ErrorApi {
   private readonly subject = new PublishSubject<{
     error: Error;
-    context?: ErrorContext;
+    context?: ErrorApiErrorContext;
   }>();
 
-  post(error: Error, context?: ErrorContext) {
+  post(error: ErrorApiError, context?: ErrorApiErrorContext) {
     this.subject.next({ error, context });
   }
 
-  error$(): Observable<{ error: Error; context?: ErrorContext }> {
+  error$(): Observable<{ error: Error; context?: ErrorApiErrorContext }> {
     return this.subject;
   }
 }

packages/core-app-api/src/apis/implementations/ErrorApi/UnhandledErrorForwarder.ts

@@ -1,4 +1,8 @@
-import { ErrorApi, ErrorContext } from '@backstage/core-plugin-api';
+import {
+  ErrorApi,
+  ErrorApiError,
+  ErrorApiErrorContext,
+} from '@backstage/core-plugin-api';
 
 /*
  * Copyright 2020 Spotify AB
@@ -25,11 +29,11 @@ export class UnhandledErrorForwarder {
   /**
    * Add event listener, such that unhandled errors can be forwarded using an given `ErrorApi` instance
    */
-  static forward(errorApi: ErrorApi, errorContext: ErrorContext) {
+  static forward(errorApi: ErrorApi, errorContext: ErrorApiErrorContext) {
     window.addEventListener(
       'unhandledrejection',
       (e: PromiseRejectionEvent) => {
-        errorApi.post(e.reason as Error, errorContext);
+        errorApi.post(e.reason as ErrorApiError, errorContext);
       },
     );
   }

packages/core-plugin-api/api-report.md

@@ -404,23 +404,31 @@ export interface ElementCollection {
   }): ElementCollection;
 }
 
-// @public
-type Error_2 = {
-  name: string;
-  message: string;
-  stack?: string;
-};
+// @public @deprecated (undocumented)
+type Error_2 = ErrorApiError;
 export { Error_2 as Error };
 
 // @public
 export type ErrorApi = {
-  post(error: Error_2, context?: ErrorContext): void;
+  post(error: ErrorApiError, context?: ErrorApiErrorContext): void;
   error$(): Observable_2<{
-    error: Error_2;
-    context?: ErrorContext;
+    error: ErrorApiError;
+    context?: ErrorApiErrorContext;
   }>;
 };
 
+// @public
+export type ErrorApiError = {
+  name: string;
+  message: string;
+  stack?: string;
+};
+
+// @public
+export type ErrorApiErrorContext = {
+  hidden?: boolean;
+};
+
 // @public
 export const errorApiRef: ApiRef<ErrorApi>;
 
@@ -431,10 +439,8 @@ export type ErrorBoundaryFallbackProps = {
   resetError: () => void;
 };
 
-// @public
-export type ErrorContext = {
-  hidden?: boolean;
-};
+// @public @deprecated (undocumented)
+export type ErrorContext = ErrorApiErrorContext;
 
 // @public
 export type Extension<T> = {

packages/core-plugin-api/src/apis/definitions/ErrorApi.ts

@@ -23,22 +23,34 @@ import { Observable } from '@backstage/types';
  *
  * @public
  */
-export type Error = {
+export type ErrorApiError = {
   name: string;
   message: string;
   stack?: string;
 };
 
+/**
+ * @public
+ * @deprecated Use ErrorApiError instead
+ */
+export type Error = ErrorApiError;
+
 /**
  * Provides additional information about an error that was posted to the application.
  *
  * @public
  */
-export type ErrorContext = {
+export type ErrorApiErrorContext = {
   // If set to true, this error should not be displayed to the user. Defaults to false.
   hidden?: boolean;
 };
 
+/**
+ * @public
+ * @deprecated Use ErrorApiErrorContext instead
+ */
+export type ErrorContext = ErrorApiErrorContext;
+
 /**
  * The error API is used to report errors to the app, and display them to the user.
  *
@@ -62,12 +74,15 @@ export type ErrorApi = {
   /**
    * Post an error for handling by the application.
    */
-  post(error: Error, context?: ErrorContext): void;
+  post(error: ErrorApiError, context?: ErrorApiErrorContext): void;
 
   /**
    * Observe errors posted by other parts of the application.
    */
-  error$(): Observable<{ error: Error; context?: ErrorContext }>;
+  error$(): Observable<{
+    error: ErrorApiError;
+    context?: ErrorApiErrorContext;
+  }>;
 };
 
 /**

packages/test-utils/api-report.md

@@ -7,7 +7,8 @@ import { AnalyticsApi } from '@backstage/core-plugin-api';
 import { AnalyticsEvent } from '@backstage/core-plugin-api';
 import { ComponentType } from 'react';
 import { ErrorApi } from '@backstage/core-plugin-api';
-import { ErrorContext } from '@backstage/core-plugin-api';
+import { ErrorApiError } from '@backstage/core-plugin-api';
+import { ErrorApiErrorContext } from '@backstage/core-plugin-api';
 import { ExternalRouteRef } from '@backstage/core-plugin-api';
 import { Observable } from '@backstage/types';
 import { ReactElement } from 'react';
@@ -27,8 +28,8 @@ export type CollectedLogs<T extends LogFuncs> = {
 
 // @public
 export type ErrorWithContext = {
-  error: Error;
-  context?: ErrorContext;
+  error: ErrorApiError;
+  context?: ErrorApiErrorContext;
 };
 
 // @public @deprecated (undocumented)
@@ -109,13 +110,13 @@ export class MockErrorApi implements ErrorApi {
   constructor(options?: MockErrorApiOptions);
   // (undocumented)
   error$(): Observable<{
-    error: Error;
-    context?: ErrorContext;
+    error: ErrorApiError;
+    context?: ErrorApiErrorContext;
   }>;
   // (undocumented)
   getErrors(): ErrorWithContext[];
   // (undocumented)
-  post(error: Error, context?: ErrorContext): void;
+  post(error: ErrorApiError, context?: ErrorApiErrorContext): void;
   // (undocumented)
   waitForError(pattern: RegExp, timeoutMs?: number): Promise<ErrorWithContext>;
 }

packages/test-utils/src/testUtils/apis/ErrorApi/MockErrorApi.ts

@@ -14,7 +14,11 @@
  * limitations under the License.
  */
 
-import { ErrorApi, ErrorContext } from '@backstage/core-plugin-api';
+import {
+  ErrorApi,
+  ErrorApiError,
+  ErrorApiErrorContext,
+} from '@backstage/core-plugin-api';
 import { Observable } from '@backstage/types';
 
 /**
@@ -27,12 +31,12 @@ export type MockErrorApiOptions = {
 };
 
 /**
- * ErrorWithContext contains error and ErrorContext
+ * ErrorWithContext contains error and ErrorApiErrorContext
  * @public
  */
 export type ErrorWithContext = {
-  error: Error;
-  context?: ErrorContext;
+  error: ErrorApiError;
+  context?: ErrorApiErrorContext;
 };
 
 type Waiter = {
@@ -59,7 +63,7 @@ export class MockErrorApi implements ErrorApi {
 
   constructor(private readonly options: MockErrorApiOptions = {}) {}
 
-  post(error: Error, context?: ErrorContext) {
+  post(error: ErrorApiError, context?: ErrorApiErrorContext) {
     if (this.options.collect) {
       this.errors.push({ error, context });
 
@@ -76,7 +80,10 @@ export class MockErrorApi implements ErrorApi {
     throw new Error(`MockErrorApi received unexpected error, ${error}`);
   }
 
-  error$(): Observable<{ error: Error; context?: ErrorContext }> {
+  error$(): Observable<{
+    error: ErrorApiError;
+    context?: ErrorApiErrorContext;
+  }> {
     return nullObservable;
   }