feat(common): add error options object

packages/common/exceptions/http.exception.ts

@@ -1,5 +1,9 @@
 import { isObject, isString } from '../utils/shared.utils';
 
+export type HttpExceptionOptions = {
+  cause?: Error;
+};
+
 /**
  * Defines the base Nest HTTP exception, which is handled by the default
  * Exceptions Handler.
@@ -13,12 +17,22 @@ export class HttpException extends Error {
    * Instantiate a plain HTTP Exception.
    *
    * @example
-   * `throw new HttpException()`
+   * throw new HttpException()
+   * throw new HttpException('message', HttpStatus.BAD_REQUEST)
+   * throw new HttpException({ reason: 'this can be a human readable reason' }, HttpStatus.BAD_REQUEST)
+   * throw new HttpException(new Error('Cause Error'), HttpStatus.BAD_REQUEST)
+   * throw new HttpException('custom message', HttpStatus.BAD_REQUEST, {
+   *  cause: new Error('Cause Error'),
+   * })
+   *
    *
    * @usageNotes
    * The constructor arguments define the response and the HTTP response status code.
-   * - The `response` argument (required) defines the JSON response body.
+   * - The `response` argument (required) defines the JSON response body. alternatively, it can also be
+   *  an error object that is used to define an error [cause](https://nodejs.org/en/blog/release/v16.9.0/#error-cause).
    * - The `status` argument (required) defines the HTTP Status Code.
+   * - The `options` argument (optional) defines additional error options. Currently, it supports the `cause` attribute,
+   *  and can be used as an alternative way to specify the error cause: `const error = new HttpException('description', 400, { cause: new Error() });`
    *
    * By default, the JSON response body contains two properties:
    * - `statusCode`: the Http Status Code.
@@ -31,12 +45,14 @@ export class HttpException extends Error {
    * The `status` argument is required, and should be a valid HTTP status code.
    * Best practice is to use the `HttpStatus` enum imported from `nestjs/common`.
    *
-   * @param response string or object describing the error condition.
+   * @param response string, object describing the error condition or the error cause.
    * @param status HTTP response status code.
+   * @param options An object used to add an error cause.
    */
   constructor(
     private readonly response: string | Record<string, any>,
     private readonly status: number,
+    private readonly options?: HttpExceptionOptions,
   ) {
     super();
     this.initMessage();
@@ -53,7 +69,12 @@ export class HttpException extends Error {
    * - https://nodejs.org/en/blog/release/v16.9.0/#error-cause
    * - https://github.com/microsoft/TypeScript/issues/45167
    */
-  public initCause() {
+  public initCause(): void {
+    if (this.options?.cause) {
+      this.cause = this.options.cause;
+      return;
+    }
+
     if (this.response instanceof Error) {
       this.cause = this.response;
     }

packages/common/test/exceptions/http.exception.spec.ts

@@ -139,5 +139,19 @@ describe('HttpException', () => {
 
       expect(cause).to.be.eql(message);
     });
+
+    it('configures a cause when message is a string and the options object is passed', () => {
+      const causeError = new Error('Some Error');
+
+      const customDescription = 'custom description';
+      const error = new HttpException(customDescription, 400, {
+        cause: causeError,
+      });
+
+      expect(`${error}`).to.be.eql(`HttpException: ${customDescription}`);
+      const { cause } = error;
+
+      expect(cause).to.be.eql(causeError);
+    });
   });
 });