Improve custom ShapeDiver error objects

Author: matthiasreisacher

package.json

@@ -20,7 +20,6 @@
         "downstream": "bash ./scripts/downstream.sh"
     },
     "devDependencies": {
-        "axios-mock-adapter": "~2.1.0",
         "eslint": "~9.12.0",
         "@eslint/js": "~9.12.0",
         "eslint-plugin-jest": "~28.8.3",

packages/sdk.geometry-api-sdk-v2/README.md

@@ -108,30 +108,44 @@ The SDK provides a helper function to extract ShapeDiver error information from
 ```typescript
 import {
   processError,
-  SdError,
-  SdRequestError,
-  SdResponseError,
+  SdGeometryError,
+  RequestError,
+  ResponseError,
 } from "@shapediver/sdk.geometry-api-sdk-v2"
 
 try {
   sdk.model.get("be5d4ce5-f76d-417d-8496-1f038e6f0cab")
-catch (err) {
+} catch (err) {
   const e = processError(err);
 
-  if (e instanceof SdRequestError) {
-    // e is a request error.
-    // In this case, the request was made but no response was received.
+  if (e instanceof SdGeometryError) {
+    /*
+     * Generic ShapeDiver error.
+     *
+     * Generic errors are the base class of all custom ShapeDiver errors, like RequestError,
+     * ResponseError, IllegalArgumentError, TimeoutError, etc.
+     *
+     * Warning:
+     *  Generic Axios errors (non-request/response errors) that are thrown when setting up the
+     *  request are not converted into a SdGeometryError!
+     */
   }
 
-  if (e instanceof SdResponseError) {
-    // e is a response error.
-    // In this case, the request was made and the server responded with a status code that falls
-    // out of the range of 2xx.
+  if (e instanceof RequestError) {
+    /*
+     * Wrapper around an Axios request error.
+     *
+     * In this case, the request was made but no response was received.
+     */
   }
 
-  if (e instanceof SdError) {
-    // e is a generic error.
-    // Generic errors are used for everything that is neither a request error nor a response error.
+  if (e instanceof ResponseError) {
+    /*
+     * Wrapper around an Axios response error.
+     *
+     * In this case, the request was made and the server responded with a status code that falls
+     * out of the range of 2xx.
+     */
   }
 }
 ```

packages/sdk.geometry-api-sdk-v2/package.json

@@ -46,6 +46,7 @@
         "axios": "~1.7.7"
     },
     "devDependencies": {
+        "axios-mock-adapter": "~2.1.0",
         "jest": "~29.7.0",
         "lerna": "8.1.8",
         "typescript": "~5.5.4",

packages/sdk.geometry-api-sdk-v2/src/error.ts

@@ -1,17 +1,17 @@
 import { ResErrorType } from './client';
 
 /**
- * Represents a generic (non-request and non-response) error.
+ * Represents a generic ShapeDiver error.
  *
  * Something happened in setting up the request that triggered an Error.
  * @export
- * @class SdError
+ * @class SdGeometryError
  * @extends {Error}
  */
-export class SdError extends Error {
-    constructor(message: string) {
+export class SdGeometryError extends Error {
+    constructor(message?: string) {
         super(message);
-        this.name = 'SdError';
+        this.name = 'SdGeometryError';
     }
 }
 
@@ -20,13 +20,13 @@ export class SdError extends Error {
  *
  * The request was made but no response was received.
  * @export
- * @class SdRequestError
- * @extends {Error}
+ * @class RequestError
+ * @extends {SdGeometryError}
  */
-export class SdRequestError extends Error {
+export class RequestError extends SdGeometryError {
     constructor(message: string) {
         super(message);
-        this.name = 'SdRequestError';
+        this.name = 'RequestError';
     }
 }
 
@@ -36,10 +36,10 @@ export class SdRequestError extends Error {
  * The request was made and the server responded with a status code that falls out of the range of
  * 2xx.
  * @export
- * @class SdResponseError
- * @extends {Error}
+ * @class ResponseError
+ * @extends {SdGeometryError}
  */
-export class SdResponseError extends Error {
+export class ResponseError extends SdGeometryError {
     /** The HTTP status code from the server response. */
     public readonly status: number;
 
@@ -51,7 +51,7 @@ export class SdResponseError extends Error {
 
     constructor(status: number, message: string, desc: string, type?: string) {
         super(message);
-        this.name = 'SdResponseError';
+        this.name = 'ResponseError';
         this.status = status;
         this.description = desc;
         this.type =
@@ -64,9 +64,9 @@ export class SdResponseError extends Error {
 /**
  * @export
  * @class IllegalArgumentError
- * @extends {Error}
+ * @extends {SdGeometryError}
  */
-export class IllegalArgumentError extends Error {
+export class IllegalArgumentError extends SdGeometryError {
     constructor(
         public field: string,
         msg?: string
@@ -79,9 +79,9 @@ export class IllegalArgumentError extends Error {
 /**
  * @export
  * @class TimeoutError
- * @extends {Error}
+ * @extends {SdGeometryError}
  */
-export class TimeoutError extends Error {
+export class TimeoutError extends SdGeometryError {
     constructor(
         public field: string,
         msg?: string

packages/sdk.geometry-api-sdk-v2/src/utils.ts

@@ -1,5 +1,5 @@
 import { AxiosError, AxiosPromise } from 'axios';
-import { SdError, SdRequestError, SdResponseError } from './error';
+import { RequestError, ResponseError } from './error';
 
 /** Delays the response for the given number of milliseconds */
 export function sleep(ms: number): Promise<void> {
@@ -93,12 +93,11 @@ export async function exists(apiCall: () => AxiosPromise<unknown>): Promise<bool
 }
 
 /**
- * Converts a generic Axios error into a more specific ShapeDiver error.
+ * Tries to convert a generic Axios error into a more specific ShapeDiver error. When no match is
+ * found, the original error is returned instead.
  * @param error The Axios error to convert.
  */
-export function processError(
-    error: AxiosError | Error
-): SdError | SdRequestError | SdResponseError {
+export function processError(error: AxiosError | Error): Error | RequestError | ResponseError {
     if ('response' in error) {
         const err = error as AxiosError,
             status = err.response!.status,
@@ -114,13 +113,13 @@ export function processError(
             'message' in data &&
             typeof data.message === 'string'
         ) {
-            return new SdResponseError(status, data.message, data.desc, data.error);
+            return new ResponseError(status, data.message, data.desc, data.error);
         } else {
-            return new SdResponseError(status, err.message, 'No error description provided');
+            return new ResponseError(status, err.message, 'No error description provided');
         }
     } else if ('request' in error) {
-        return new SdRequestError(error.message);
+        return new RequestError(error.message);
     } else {
-        return new SdError(error.message);
+        return error;
     }
 }