diff --git a/packages/errors/api-report.md b/packages/errors/api-report.md index 6aa69592b7..019b6dd387 100644 --- a/packages/errors/api-report.md +++ b/packages/errors/api-report.md @@ -5,18 +5,12 @@ ```ts import { JsonObject } from '@backstage/config'; -// Warning: (ae-missing-release-tag) "AuthenticationError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class AuthenticationError extends CustomErrorBase {} -// Warning: (ae-missing-release-tag) "ConflictError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class ConflictError extends CustomErrorBase {} -// Warning: (ae-missing-release-tag) "CustomErrorBase" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public (undocumented) export class CustomErrorBase extends Error { constructor(message?: string, cause?: Error); @@ -24,15 +18,11 @@ export class CustomErrorBase extends Error { readonly cause?: Error; } -// Warning: (ae-missing-release-tag) "deserializeError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function deserializeError( data: SerializedError, ): T; -// Warning: (ae-missing-release-tag) "ErrorResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type ErrorResponse = { error: SerializedError; @@ -45,34 +35,21 @@ export type ErrorResponse = { }; }; -// Warning: (ae-missing-release-tag) "InputError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class InputError extends CustomErrorBase {} -// Warning: (ae-missing-release-tag) "NotAllowedError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class NotAllowedError extends CustomErrorBase {} -// Warning: (ae-missing-release-tag) "NotFoundError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class NotFoundError extends CustomErrorBase {} -// Warning: (ae-missing-release-tag) "NotModifiedError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class NotModifiedError extends CustomErrorBase {} -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (ae-missing-release-tag) "parseErrorResponse" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function parseErrorResponse(response: Response): Promise; -// Warning: (ae-missing-release-tag) "ResponseError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export class ResponseError extends Error { constructor(props: { @@ -87,8 +64,6 @@ export class ResponseError extends Error { readonly response: Response; } -// Warning: (ae-missing-release-tag) "SerializedError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export type SerializedError = JsonObject & { name: string; @@ -97,10 +72,6 @@ export type SerializedError = JsonObject & { code?: string; }; -// Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen -// Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters -// Warning: (ae-missing-release-tag) "serializeError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// // @public export function serializeError( error: Error, diff --git a/packages/errors/src/errors/CustomErrorBase.ts b/packages/errors/src/errors/CustomErrorBase.ts index fc374287c7..a392135c13 100644 --- a/packages/errors/src/errors/CustomErrorBase.ts +++ b/packages/errors/src/errors/CustomErrorBase.ts @@ -14,6 +14,7 @@ * limitations under the License. */ +/** @public */ export class CustomErrorBase extends Error { readonly cause?: Error; diff --git a/packages/errors/src/errors/ResponseError.ts b/packages/errors/src/errors/ResponseError.ts index c8927a447c..f74ad2fa0c 100644 --- a/packages/errors/src/errors/ResponseError.ts +++ b/packages/errors/src/errors/ResponseError.ts @@ -24,6 +24,8 @@ import { * An error thrown as the result of a failed server request. * * The server is expected to respond on the ErrorResponse format. + * + * @public */ export class ResponseError extends Error { /** diff --git a/packages/errors/src/errors/common.ts b/packages/errors/src/errors/common.ts index 51c82eeda5..dad236d4b5 100644 --- a/packages/errors/src/errors/common.ts +++ b/packages/errors/src/errors/common.ts @@ -29,16 +29,22 @@ import { CustomErrorBase } from './CustomErrorBase'; /** * The given inputs are malformed and cannot be processed. + * + * @public */ export class InputError extends CustomErrorBase {} /** * The request requires authentication, which was not properly supplied. + * + * @public */ export class AuthenticationError extends CustomErrorBase {} /** * The authenticated caller is not allowed to perform this request. + * + * @public */ export class NotAllowedError extends CustomErrorBase {} @@ -47,16 +53,22 @@ export class NotAllowedError extends CustomErrorBase {} * * Note that this error usually is used to indicate that an entity with a given * ID does not exist, rather than signalling that an entire route is missing. + * + * @public */ export class NotFoundError extends CustomErrorBase {} /** * The request could not complete due to a conflict in the current state of the * resource. + * + * @public */ export class ConflictError extends CustomErrorBase {} /** * The requested resource has not changed since last request. + * + * @public */ export class NotModifiedError extends CustomErrorBase {} diff --git a/packages/errors/src/serialization/error.ts b/packages/errors/src/serialization/error.ts index 46a2c2f74c..ab543164d8 100644 --- a/packages/errors/src/serialization/error.ts +++ b/packages/errors/src/serialization/error.ts @@ -22,6 +22,8 @@ import { /** * The serialized form of an Error. + * + * @public */ export type SerializedError = JsonObject & { /** The name of the exception that was thrown */ @@ -37,12 +39,16 @@ export type SerializedError = JsonObject & { /** * Serializes an error object to a JSON friendly form. * - * @param error The error - * @param options.includeStackTraces: Include stack trace in the output (default false) + * @public + * @param error - The error. + * @param options - Optional serialization options. */ export function serializeError( error: Error, - options?: { includeStack?: boolean }, + options?: { + /** Include stack trace in the output (default false) */ + includeStack?: boolean; + }, ): SerializedError { const serialized = serializeErrorInternal(error); const result: SerializedError = { @@ -60,6 +66,8 @@ export function serializeError( /** * Deserializes a serialized error object back to an Error. + * + * @public */ export function deserializeError( data: SerializedError, diff --git a/packages/errors/src/serialization/response.ts b/packages/errors/src/serialization/response.ts index 0196b2d597..50bf8f7ab1 100644 --- a/packages/errors/src/serialization/response.ts +++ b/packages/errors/src/serialization/response.ts @@ -18,6 +18,8 @@ import { SerializedError } from './error'; /** * A standard shape of JSON data returned as the body of backend errors. + * + * @public */ export type ErrorResponse = { /** Details of the error that was caught */ @@ -47,7 +49,8 @@ export type ErrorResponse = { * The code is forgiving, and constructs a useful synthetic body as best it can * if the response body wasn't on the expected form. * - * @param response The response of a failed request + * @public + * @param response - The response of a failed request */ export async function parseErrorResponse( response: Response,