paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 23 Packages Projects Releases Wiki Activity

errors: document and update API report for new assertion helpers

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2021-10-16 18:01:55 +02:00
parent 381381bd2b
commit 59714af079
2 changed files with 45 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/errors/api-report.md
+12 -12
View File
@@ -5,10 +5,8 @@
```ts
import { JsonObject } from '@backstage/config';
// Warning: (ae-missing-release-tag) "assertError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export function assertError(val: unknown): asserts val is ErrorLike;
// @public
export function assertError(value: unknown): asserts value is ErrorLike;
// @public
export class AuthenticationError extends CustomErrorBase {}
@@ -18,7 +16,7 @@ export class ConflictError extends CustomErrorBase {}
// @public (undocumented)
export class CustomErrorBase extends Error {
constructor(message?: string, cause?: Error);
constructor(message?: string, cause?: Error | unknown);
// (undocumented)
readonly cause?: Error;
}
@@ -28,13 +26,12 @@ export function deserializeError<T extends Error = Error>(
data: SerializedError,
): T;
// Warning: (ae-missing-release-tag) "ErrorLike" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
// @public
export type ErrorLike = {
name: string;
message: string;
stack?: string;
[unknownKeys: string]: unknown;
};
// @public
@@ -49,13 +46,16 @@ export type ErrorResponse = {
};
};
// @public
export class ForwardedError extends CustomErrorBase {
constructor(message: string, cause: Error | unknown);
}
// @public
export class InputError extends CustomErrorBase {}
// Warning: (ae-missing-release-tag) "isError" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
//
// @public (undocumented)
export function isError(val: unknown): val is ErrorLike;
// @public
export function isError(value: unknown): value is ErrorLike;
// @public
export class NotAllowedError extends CustomErrorBase {}
packages/errors/src/errors/assertion.ts
+33 -9
View File
@@ -14,6 +14,11 @@
* limitations under the License.
*/
/**
* An object that is shaped like an `Error`.
*
* @public
*/
export type ErrorLike = {
name: string;
message: string;
@@ -21,11 +26,19 @@ export type ErrorLike = {
[unknownKeys: string]: unknown;
};
export function isError(val: unknown): val is ErrorLike {
if (typeof val !== 'object' || val === null || Array.isArray(val)) {
/**
* Checks whether an unknown value is an {@link ErrorLike} object, which guarantees that it's
* an object that has at least two string properties: a non-empty `name` and `message`.
*
* @public
* @param value - an unknown value
* @returns true if the value is an {@link ErrorLike} object, false otherwise
*/
export function isError(value: unknown): value is ErrorLike {
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
return false;
}
const maybe = val as Partial<ErrorLike>;
const maybe = value as Partial<ErrorLike>;
if (typeof maybe.name !== 'string' || maybe.name === '') {
return false;
}
@@ -35,15 +48,26 @@ export function isError(val: unknown): val is ErrorLike {
return true;
}
export function assertError(val: unknown): asserts val is ErrorLike {
if (typeof val !== 'object' || val === null || Array.isArray(val)) {
throw new Error(`Encountered invalid error, not an object, got '${val}'`);
/**
* Asserts that an unknown value is an {@link ErrorLike} object, which guarantees that it's
* an object that has at least two string properties: a non-empty `name` and `message`.
*
* If the value is not an {@link ErrorLike} object, an error is thrown.
*
* @public
* @param value - an unknown value
*/
export function assertError(value: unknown): asserts value is ErrorLike {
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
throw new Error(`Encountered invalid error, not an object, got '${value}'`);
}
const maybe = val as Partial<ErrorLike>;
const maybe = value as Partial<ErrorLike>;
if (typeof maybe.name !== 'string' || maybe.name === '') {
throw new Error(`Encountered error object without a name, got '${val}'`);
throw new Error(`Encountered error object without a name, got '${value}'`);
}
if (typeof maybe.message !== 'string') {
throw new Error(`Encountered error object without a message, got '${val}'`);
throw new Error(
`Encountered error object without a message, got '${value}'`,
);
}
}