feat(cactus-common): add createRuntimeErrorWithCause() & newRex()

[m-courtin]

Utility functions to conveniently re-throw excpetions typed as unknown
by their catch block (which is the default since Typescript v4.4).

Example usage can and much more documentation can be seen here:

packages/cactus-common/src/main/typescript/exception/create-runtime-error-with-cause.ts
and here
packages/cactus-common/src/test/typescript/unit/exception/create-runtime-error-with-cause.test.ts

Co-authored-by: Peter Somogyvari peter.somogyvari@accenture.com

Closes: #1702

[skip ci]

Signed-off-by: Michael Courtin michael.courtin@accenture.com
Signed-off-by: Peter Somogyvari peter.somogyvari@accenture.com

[izuru0]

LGTM

[m-courtin]

@izuru0: Thank you very much for reviewing this PR.

[m-courtin]

As an example on how to integrate / use the new generic functions the cactus-cmd-api-server was taken as a show case

[petermetz]

@m-courtin Can you make it support these (and similar) cases of incorrect error throwing as well? Right now these would all result in the loss of the information that the thrower was trying to convey (which would be their fault for not throwing an exception, but since the language allows for it we have to assume it will happen...)

  try {
    throw "Something very important about what went wrong";
  } catch (ex) {
    const theStack = LogHelper.getExceptionStack(ex);
    const theMessage = LogHelper.getExceptionMessage(ex);
    console.log(theStack);
    console.log(theMessage);
  }

  try {
    throw { error: "Something very important about what went wrong" };
  } catch (ex) {
    const theStack = LogHelper.getExceptionStack(ex);
    const theMessage = LogHelper.getExceptionMessage(ex);
    console.log(theStack);
    console.log(theMessage);
  }

The other thing I'd ask is to check for the input being a specific instance of RuntimeError so that this also does not lose information:

  const exA = new RuntimeError("A");
  const exB = new RuntimeError("B", exA);
  const exC = new RuntimeError("C", exB);

  // The nested exceptions here are swallowed, the only stack that is shown
  // is the last one (for "C")
  const x = LogHelper.getExceptionStack(exC);
  console.log(x);

JSON stringifying the RuntimeError above will preserve the full chain[1] of nested exceptions, but with the current code it only preserves the last one.

[1]:

{
    "name": "RuntimeError",
    "stack": "RuntimeError: C\n    at /..../cactus-1/packages/cactus-common/src/test/typescript/unit/logging/log-helper.test.ts:9:15\n    at _dispatchDescribe (/..../cactus-1/node_modules/jest-circus/build/index.js:97:26)\n    at describe (/..../cactus-1/node_modules/jest-circus/build/index.js:60:5)\n    at Object.<anonymous> (/..../cactus-1/packages/cactus-common/src/test/typescript/unit/logging/log-helper.test.ts:6:1)\n    at Runtime._execModule (/..../cactus-1/node_modules/jest-runtime/build/index.js:1646:24)\n    at Runtime._loadModule (/..../cactus-1/node_modules/jest-runtime/build/index.js:1185:12)\n    at Runtime.requireModule (/..../cactus-1/node_modules/jest-runtime/build/index.js:1009:12)\n    at jestAdapter (/..../cactus-1/node_modules/jest-circus/build/legacy-code-todo-rewrite/jestAdapter.js:79:13)\n    at runTestInternal (/..../cactus-1/node_modules/jest-runner/build/runTest.js:389:16)\n    at runTest (/..../cactus-1/node_modules/jest-runner/build/runTest.js:475:34)",
    "message": "C",
    "cause": {
        "name": "RuntimeError",
        "stack": "RuntimeError: B\n    at /..../cactus-1/packages/cactus-common/src/test/typescript/unit/logging/log-helper.test.ts:8:15\n    at _dispatchDescribe (/..../cactus-1/node_modules/jest-circus/build/index.js:97:26)\n    at describe (/..../cactus-1/node_modules/jest-circus/build/index.js:60:5)\n    at Object.<anonymous> (/..../cactus-1/packages/cactus-common/src/test/typescript/unit/logging/log-helper.test.ts:6:1)\n    at Runtime._execModule (/..../cactus-1/node_modules/jest-runtime/build/index.js:1646:24)\n    at Runtime._loadModule (/..../cactus-1/node_modules/jest-runtime/build/index.js:1185:12)\n    at Runtime.requireModule (/..../cactus-1/node_modules/jest-runtime/build/index.js:1009:12)\n    at jestAdapter (/..../cactus-1/node_modules/jest-circus/build/legacy-code-todo-rewrite/jestAdapter.js:79:13)\n    at runTestInternal (/..../cactus-1/node_modules/jest-runner/build/runTest.js:389:16)\n    at runTest (/..../cactus-1/node_modules/jest-runner/build/runTest.js:475:34)",
        "message": "B",
        "cause": {
            "name": "RuntimeError",
            "stack": "RuntimeError: A\n    at /..../cactus-1/packages/cactus-common/src/test/typescript/unit/logging/log-helper.test.ts:7:15\n    at _dispatchDescribe (/..../cactus-1/node_modules/jest-circus/build/index.js:97:26)\n    at describe (/..../cactus-1/node_modules/jest-circus/build/index.js:60:5)\n    at Object.<anonymous> (/..../cactus-1/packages/cactus-common/src/test/typescript/unit/logging/log-helper.test.ts:6:1)\n    at Runtime._execModule (/..../cactus-1/node_modules/jest-runtime/build/index.js:1646:24)\n    at Runtime._loadModule (/..../cactus-1/node_modules/jest-runtime/build/index.js:1185:12)\n    at Runtime.requireModule (/..../cactus-1/node_modules/jest-runtime/build/index.js:1009:12)\n    at jestAdapter (/..../cactus-1/node_modules/jest-circus/build/legacy-code-todo-rewrite/jestAdapter.js:79:13)\n    at runTestInternal (/..../cactus-1/node_modules/jest-runner/build/runTest.js:389:16)\n    at runTest (/..../cactus-1/node_modules/jest-runner/build/runTest.js:475:34)",
            "message": "A",
            "cause": null
        }
    }
}

[m-courtin]

@petermetz: Yes, good point to support similar "false" exceptions as well and try to get their message / load. I will extend the generic handling accordingly

[petermetz]

@m-courtin Also how about something like this for the stack extraction? I came to realize that the stack property contains the message property for valid Error objects anyway.

export const K_FALLBACK_STACK = "NO_STACK_INFORMATION_INCLUDED_IN_EXCEPTION";

export class LogHelper {
  public static getExceptionStack(exception: unknown): string {
    if (exception instanceof RuntimeError) {
      return stringify(exception);
    } else if (exception instanceof Error) {
      return stringify(exception.stack);
    } else if (exception) {
      return stringify(exception);
    } else {
      return K_FALLBACK_STACK;
    }
  }

[m-courtin]

@petermetz: Regarding the stack handling I would prefer to use the typeof exception === "object" part in combination with the call for hasOwnProperty stack over the instance of error to also include custom build errors / exceptions which are having a stack property not based on Error class. The other case of stringify I will include to also cover other stringify-able exceptions and not loosing their stack info

[petermetz]

@m-courtin Sorry I meant the entire newRuntimeError function's code, not the code of the getExceptionMessageInfo function which is being invoked on the line I'm commenting on. Apologies for the confusion!