feat: let cause be unknown for constructor, create (like wrap)

src/messages.ts

@@ -363,14 +363,14 @@ export class Messages<T extends string> {
     }
 
     if (!packageName) {
-      const errMessage = `Invalid or missing package.json file at '${moduleMessagesDirPath}'. If not using a package.json, pass in a packageName.`;
+      const message = `Invalid or missing package.json file at '${moduleMessagesDirPath}'. If not using a package.json, pass in a packageName.`;
       try {
         packageName = asString(ensureJsonMap(Messages.readFile(path.join(moduleMessagesDirPath, 'package.json'))).name);
         if (!packageName) {
-          throw new NamedError('MissingPackageName', errMessage);
+          throw SfError.create({ message, name: 'MissingPackageName' });
         }
       } catch (err) {
-        throw new NamedError('MissingPackageName', errMessage, err as Error);
+        throw SfError.create({ message, name: 'MissingPackageName', cause: err });
       }
     }
 

src/sfError.ts

@@ -12,7 +12,8 @@ export type SfErrorOptions<T extends ErrorDataProperties = ErrorDataProperties>
   exitCode?: number;
   name?: string;
   data?: T;
-  cause?: Error;
+  /** pass an Error.  For convenience in catch blocks, code will check that it is, in fact, an Error */
+  cause?: unknown;
   context?: string;
   actions?: string[];
 };
@@ -74,12 +75,14 @@ export class SfError<T extends ErrorDataProperties = ErrorDataProperties> extend
     name = 'SfError',
     actions?: string[],
     exitCodeOrCause?: number | Error,
-    cause?: Error
+    cause?: unknown
   ) {
-    const derivedCause = exitCodeOrCause instanceof Error ? exitCodeOrCause : cause;
+    if (typeof cause !== 'undefined' && !(cause instanceof Error)) {
+      throw new TypeError(`The cause, if provided, must be an instance of Error. Received: ${typeof cause}`);
+    }
     super(message);
     this.name = name;
-    this.cause = derivedCause;
+    this.cause = exitCodeOrCause instanceof Error ? exitCodeOrCause : cause;
     this.actions = actions;
     if (typeof exitCodeOrCause === 'number') {
       this.exitCode = exitCodeOrCause;
@@ -88,12 +91,7 @@ export class SfError<T extends ErrorDataProperties = ErrorDataProperties> extend
     }
   }
 
-  public get fullStack(): string | undefined {
-    return recursiveStack(this).join('\nCaused by: ');
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  public get code(): any {
+  public get code(): string {
     return this.#code ?? this.name;
   }
 
@@ -127,7 +125,9 @@ export class SfError<T extends ErrorDataProperties = ErrorDataProperties> extend
         ? // a basic error with message and name.  We make it the cause to preserve any other properties
           new SfError<T>(err.message, err.name, undefined, err)
         : // ok, something was throws that wasn't error or string.  Convert it to an Error that preserves the information as the cause and wrap that.
-          SfError.wrap<T>(new TypeError('An unexpected error occurred', { cause: err }));
+          SfError.wrap<T>(
+            new TypeError(`SfError.wrap received type ${typeof err} but expects type Error or string`, { cause: err })
+          );
 
     // If the original error has a code, use that instead of name.
     if (hasString(err, 'code')) {
@@ -171,6 +171,3 @@ export class SfError<T extends ErrorDataProperties = ErrorDataProperties> extend
     };
   }
 }
-
-const recursiveStack = (err: Error): string[] =>
-  (err.cause && err.cause instanceof Error ? [err.stack, ...recursiveStack(err.cause)] : [err.stack]).filter(isString);

test/unit/org/scratchOrgInfoApiTest.ts

@@ -192,7 +192,7 @@ describe('requestScratchOrgCreation', () => {
         expect.fail('should have thrown SfError');
       }
       expect(error).to.exist;
-      expect(error).to.have.keys(['cause', 'name', 'actions', 'exitCode']);
+      expect(error).to.include.keys(['cause', 'name', 'actions', 'exitCode']);
       expect((error as Error).toString()).to.include('SignupDuplicateSettingsSpecifiedError');
     }
   });
@@ -216,7 +216,7 @@ describe('requestScratchOrgCreation', () => {
         expect.fail('should have thrown SfError');
       }
       expect(error).to.exist;
-      expect(error).to.have.keys(['cause', 'name', 'actions', 'exitCode']);
+      expect(error).to.include.keys(['cause', 'name', 'actions', 'exitCode']);
       expect((error as Error).toString()).to.include(messages.getMessage('DeprecatedPrefFormat'));
     }
   });

test/unit/sfErrorTest.ts

@@ -4,12 +4,15 @@
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
+import { inspect } from 'node:util';
 import { expect, assert } from 'chai';
 import { Messages } from '../../src/messages';
 import { SfError } from '../../src/sfError';
 
 Messages.importMessageFile('pname', 'testMessages.json');
 
+const causeDelimiter = 'cause:';
+
 describe('SfError', () => {
   describe('constructor', () => {
     it('should return a mutable SfError', () => {
@@ -70,32 +73,38 @@ describe('SfError', () => {
     });
   });
 
-  describe('fullStack', () => {
+  describe('nested errors', () => {
+    const causeRegex = new RegExp(causeDelimiter, 'g');
+    const nestedCauseRegex = new RegExp(/\[cause:\]/, 'g');
     it('returned `name:message` when no cause', () => {
       const err = new SfError('test');
-      expect(err.fullStack).to.include('SfError: test');
-      expect(err.fullStack).to.include('sfErrorTest.ts');
-      expect(err.fullStack).to.not.include('Caused by:');
+      expect(inspect(err)).to.include('SfError: test');
+      expect(inspect(err)).to.include('sfErrorTest.ts');
+      // there's always 1 cause from the `cause:` property, even if undefined
+      expect(inspect(err)?.match(causeRegex)).to.have.lengthOf(1);
     });
     it('1 cause', () => {
       const nestedError = new Error('nested');
       const err = new SfError('test', undefined, undefined, nestedError);
-      expect(err.fullStack).to.include('SfError: test');
-      expect(err.fullStack).to.include('sfErrorTest.ts');
-      expect(err.fullStack).to.include('nested');
-      expect(err.fullStack?.match(/Caused by:/g)).to.have.lengthOf(1);
+      expect(inspect(err)).to.include('SfError: test');
+      expect(inspect(err)).to.include('sfErrorTest.ts');
+      expect(inspect(err)).to.include('nested');
+      expect(inspect(err)?.match(causeRegex)).to.have.lengthOf(1);
+      expect(inspect(err)?.match(nestedCauseRegex)).to.be.null;
     });
     it('recurse through stacked causes', () => {
       const nestedError = new Error('nested');
       const nestedError2 = new Error('nested2', { cause: nestedError });
       const err = new SfError('test', undefined, undefined, nestedError2);
-      expect(err.fullStack).to.include('SfError: test');
-      expect(err.fullStack).to.include('sfErrorTest.ts');
-      expect(err.fullStack).to.include('nested');
-      expect(err.fullStack).to.include('nested2');
-      expect(err.fullStack?.match(/Caused by:/g)).to.have.lengthOf(2);
+      expect(inspect(err)).to.include('SfError: test');
+      expect(inspect(err)).to.include('sfErrorTest.ts');
+      expect(inspect(err)).to.include('nested');
+      expect(inspect(err)).to.include('nested2');
+      expect(inspect(err)?.match(causeRegex)).to.have.lengthOf(1);
+      expect(inspect(err)?.match(causeRegex)).to.have.lengthOf(1);
     });
   });
+
   describe('wrap', () => {
     it('should return a wrapped error', () => {
       const myErrorMsg = 'yikes! What did you do?';
@@ -106,7 +115,8 @@ describe('SfError', () => {
       expect(mySfError).to.be.an.instanceOf(SfError);
       expect(mySfError.message).to.equal(myErrorMsg);
       expect(mySfError.name).to.equal(myErrorName);
-      expect(mySfError.fullStack).to.contain('Caused by:').and.contain(myError.stack);
+      expect(mySfError.cause).to.equal(myError);
+      expect(inspect(mySfError)).to.contain(causeDelimiter).and.contain(myErrorMsg);
     });
 
     it('should return a wrapped error with a code', () => {