@mongosh/errors - npm Package Compare versions

Comparing version 0.6.1 to 0.7.7

index.spec.ts

 import { expect } from 'chai';
 import {
-  MongoshRuntimeError,
-  MongoshInternalError,
-  MongoshInvalidInputError,
-  MongoshUnimplementedError
+  getScopeFromErrorCode,
+  MongoshBaseError, MongoshInternalError,
+  MongoshInvalidInputError, MongoshRuntimeError,
+  MongoshUnimplementedError, MongoshWarning, MongoshDeprecatedError,
+  MongoshCommandFailed
 } from './index';
+import { CommonErrors } from './lib';
 
 describe('errors', () => {
+  it('properly extracts the scope from error codes', () => {
+    expect(getScopeFromErrorCode('')).to.be.undefined;
+    expect(getScopeFromErrorCode(null)).to.be.undefined;
+    expect(getScopeFromErrorCode(undefined)).to.be.undefined;
+
+    expect(getScopeFromErrorCode('asldkjfaksjdf')).to.be.undefined;
+    expect(getScopeFromErrorCode('?="§-kajsdf')).to.be.undefined;
+
+    expect(getScopeFromErrorCode('ASYNC-')).to.be.equal('ASYNC');
+    expect(getScopeFromErrorCode('SHUPS-42')).to.be.equal('SHUPS');
+    expect(getScopeFromErrorCode('e1337-291')).to.be.equal('e1337');
+  });
+
   it('creates MongoshInternalError', () => {
     const error = new MongoshInternalError('Something went wrong.');
-    expect(error).to.be.instanceOf(Error);
+    expect(error).to.be.instanceOf(MongoshBaseError);
     expect(error.name).to.be.equal('MongoshInternalError');
-    expect(error.message).to.be.equal('Something went wrong.\nThis is an error inside Mongosh. Please file a bug report. Please include a log file from this session.');
+    expect(error.message).to.be.equal('[COMMON-90001] Something went wrong.\nThis is an error inside Mongosh. Please file a bug report for the MONGOSH project here: https://jira.mongodb.org.');
+    expect(error.code).to.be.equal(CommonErrors.UnexpectedInternalError);
+    expect(error.scope).to.be.equal('COMMON');
   });
   it('creates MongoshUnimplementedError', () => {
-    const error = new MongoshUnimplementedError('Something went wrong.');
-    expect(error).to.be.instanceOf(Error);
-    expect(error.name).to.be.equal('MongoshUnimplementedError');
-    expect(error.message).to.be.equal('Something went wrong.');
+    const errorNoCode = new MongoshUnimplementedError('Something went wrong.');
+    expect(errorNoCode).to.be.instanceOf(MongoshBaseError);
+    expect(errorNoCode.name).to.be.equal('MongoshUnimplementedError');
+    expect(errorNoCode.message).to.be.equal('Something went wrong.');
+    expect(errorNoCode.code).to.be.undefined;
+
+    const errorWithCode = new MongoshUnimplementedError('Something went wrong.', 'SHUPS-42');
+    expect(errorWithCode).to.be.instanceOf(MongoshBaseError);
+    expect(errorWithCode.name).to.be.equal('MongoshUnimplementedError');
+    expect(errorWithCode.message).to.be.equal('[SHUPS-42] Something went wrong.');
+    expect(errorWithCode.code).to.be.equal('SHUPS-42');
+    expect(errorWithCode.scope).to.be.equal('SHUPS');
   });
   it('creates MongoshRuntimeError', () => {
-    const error = new MongoshRuntimeError('Something went wrong.');
-    expect(error).to.be.instanceOf(Error);
-    expect(error.name).to.be.equal('MongoshRuntimeError');
-    expect(error.message).to.be.equal('Something went wrong.');
+    const errorNoCode = new MongoshRuntimeError('Something went wrong.');
+    expect(errorNoCode).to.be.instanceOf(MongoshBaseError);
+    expect(errorNoCode.name).to.be.equal('MongoshRuntimeError');
+    expect(errorNoCode.message).to.be.equal('Something went wrong.');
+    expect(errorNoCode.code).to.be.undefined;
+
+    const errorWithCode = new MongoshRuntimeError('Something went wrong.', 'SHUPS-42');
+    expect(errorWithCode).to.be.instanceOf(MongoshBaseError);
+    expect(errorWithCode.name).to.be.equal('MongoshRuntimeError');
+    expect(errorWithCode.message).to.be.equal('[SHUPS-42] Something went wrong.');
+    expect(errorWithCode.code).to.be.equal('SHUPS-42');
+    expect(errorWithCode.scope).to.be.equal('SHUPS');
   });
   it('creates MongoshInvalidInputError', () => {
-    const error = new MongoshInvalidInputError('Something went wrong.');
-    expect(error).to.be.instanceOf(Error);
-    expect(error.name).to.be.equal('MongoshInvalidInputError');
-    expect(error.message).to.be.equal('Something went wrong.');
+    const errorNoCode = new MongoshInvalidInputError('Something went wrong.');
+    expect(errorNoCode).to.be.instanceOf(MongoshBaseError);
+    expect(errorNoCode.name).to.be.equal('MongoshInvalidInputError');
+    expect(errorNoCode.message).to.be.equal('Something went wrong.');
+    expect(errorNoCode.code).to.be.undefined;
+
+    const errorWithCode = new MongoshInvalidInputError('Something went wrong.', 'SHUPS-42');
+    expect(errorWithCode).to.be.instanceOf(MongoshBaseError);
+    expect(errorWithCode.name).to.be.equal('MongoshInvalidInputError');
+    expect(errorWithCode.message).to.be.equal('[SHUPS-42] Something went wrong.');
+    expect(errorWithCode.code).to.be.equal('SHUPS-42');
+    expect(errorWithCode.scope).to.be.equal('SHUPS');
   });
+  it('creates MongoshWarning', () => {
+    const errorNoCode = new MongoshWarning('Something went wrong.');
+    expect(errorNoCode).to.be.instanceOf(MongoshBaseError);
+    expect(errorNoCode.name).to.be.equal('MongoshWarning');
+    expect(errorNoCode.message).to.be.equal('Something went wrong.');
+    expect(errorNoCode.code).to.be.undefined;
+
+    const errorWithCode = new MongoshWarning('Something went wrong.', 'SHUPS-42');
+    expect(errorWithCode).to.be.instanceOf(MongoshBaseError);
+    expect(errorWithCode.name).to.be.equal('MongoshWarning');
+    expect(errorWithCode.message).to.be.equal('[SHUPS-42] Something went wrong.');
+    expect(errorWithCode.code).to.be.equal('SHUPS-42');
+    expect(errorWithCode.scope).to.be.equal('SHUPS');
+  });
+  it('creates MongoshDeprecatedError', () => {
+    const errorNoCode = new MongoshDeprecatedError('Something went wrong.');
+    expect(errorNoCode).to.be.instanceOf(MongoshBaseError);
+    expect(errorNoCode.name).to.be.equal('MongoshDeprecatedError');
+    expect(errorNoCode.message).to.be.equal('[COMMON-10003] Something went wrong.');
+    expect(errorNoCode.code).to.equal('COMMON-10003');
+  });
+  it('creates MongoshCommandFailed', () => {
+    const errorNoCode = new MongoshCommandFailed('Something went wrong.');
+    expect(errorNoCode).to.be.instanceOf(MongoshBaseError);
+    expect(errorNoCode.name).to.be.equal('MongoshCommandFailed');
+    expect(errorNoCode.message).to.be.equal("[COMMON-10004] Command Something went wrong. returned ok: 0. To see the raw results of the command, use 'runCommand' instead.");
+    expect(errorNoCode.code).to.equal('COMMON-10004');
+  });
 });

index.ts

@@ -1,47 +0,86 @@
-class MongoshRuntimeError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'MongoshRuntimeError';
+import { CommonErrors } from './common-errors';
+
+function getScopeFromErrorCode(code: string | null | undefined): string | undefined {
+  if (!code) {
+    return undefined;
   }
+  const match = code.match(/^([a-zA-Z0-9]+)-/);
+  return !match ? undefined : match[1];
 }
 
-class MongoshInternalError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'MongoshInternalError';
-    this.message =
-      this.message + '\nThis is an error inside Mongosh. Please file a bug report. '
-      + 'Please include a log file from this session.';
+abstract class MongoshBaseError extends Error {
+  readonly code: string | undefined;
+  readonly scope: string | undefined;
+  readonly metadata: Object | undefined;
+
+  constructor(name: string, message: string, code?: string, metadata?: Object) {
+    super(code ? `[${code}] ${message}` : message);
+    this.name = name;
+    this.code = code;
+    this.scope = getScopeFromErrorCode(code);
+    this.metadata = metadata;
   }
 }
 
-class MongoshUnimplementedError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'MongoshUnimplementedError';
+class MongoshRuntimeError extends MongoshBaseError {
+  constructor(message: string, code?: string, metadata?: Object) {
+    super('MongoshRuntimeError', message, code, metadata);
   }
 }
 
-class MongoshInvalidInputError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'MongoshInvalidInputError';
+class MongoshInternalError extends MongoshBaseError {
+  constructor(message: string, metadata?: Object) {
+    super(
+      'MongoshInternalError',
+      `${message}
+This is an error inside Mongosh. Please file a bug report for the MONGOSH project here: https://jira.mongodb.org.`,
+      CommonErrors.UnexpectedInternalError,
+      metadata
+    );
   }
 }
 
-class MongoshWarning extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'MongoshWarning';
+class MongoshUnimplementedError extends MongoshBaseError {
+  constructor(message: string, code?: string, metadata?: Object) {
+    super('MongoshUnimplementedError', message, code, metadata);
   }
 }
 
-class MongoshCommandFailed extends Error {
-  constructor(message: string) {
-    super(`Command ${message} returned ok: 0. To see the raw results of the command, use 'runCommand' instead.`);
-    this.name = 'MongoshCommandFailed';
+class MongoshInvalidInputError extends MongoshBaseError {
+  constructor(message: string, code?: string, metadata?: Object) {
+    super('MongoshInvalidInputError', message, code, metadata);
   }
 }
 
+class MongoshWarning extends MongoshBaseError {
+  constructor(message: string, code?: string, metadata?: Object) {
+    super('MongoshWarning', message, code, metadata);
+  }
+}
+
+class MongoshDeprecatedError extends MongoshBaseError {
+  constructor(message: string, metadata?: Object) {
+    super(
+      'MongoshDeprecatedError',
+      message,
+      CommonErrors.Deprecated,
+      metadata
+    );
+  }
+}
+
+class MongoshCommandFailed extends MongoshBaseError {
+  constructor(message: string, metadata?: Object) {
+    super(
+      'MongoshCommandFailed',
+      `Command ${message} returned ok: 0. To see the raw results of the command, use 'runCommand' instead.`,
+      CommonErrors.CommandFailed,
+      metadata
+    );
+  }
+}
+
 export {
+  getScopeFromErrorCode,
+  MongoshBaseError,
   MongoshWarning,
@@ -52,3 +91,5 @@ MongoshRuntimeError,
   MongoshUnimplementedError,
-  MongoshCommandFailed
+  MongoshDeprecatedError,
+  MongoshCommandFailed,
+  CommonErrors
 };

lib/index.d.ts

@@ -1,19 +0,30 @@
-declare class MongoshRuntimeError extends Error {
-    constructor(message: string);
+import { CommonErrors } from './common-errors';
+declare function getScopeFromErrorCode(code: string | null | undefined): string | undefined;
+declare abstract class MongoshBaseError extends Error {
+    readonly code: string | undefined;
+    readonly scope: string | undefined;
+    readonly metadata: Object | undefined;
+    constructor(name: string, message: string, code?: string, metadata?: Object);
 }
-declare class MongoshInternalError extends Error {
-    constructor(message: string);
+declare class MongoshRuntimeError extends MongoshBaseError {
+    constructor(message: string, code?: string, metadata?: Object);
 }
-declare class MongoshUnimplementedError extends Error {
-    constructor(message: string);
+declare class MongoshInternalError extends MongoshBaseError {
+    constructor(message: string, metadata?: Object);
 }
-declare class MongoshInvalidInputError extends Error {
-    constructor(message: string);
+declare class MongoshUnimplementedError extends MongoshBaseError {
+    constructor(message: string, code?: string, metadata?: Object);
 }
-declare class MongoshWarning extends Error {
-    constructor(message: string);
+declare class MongoshInvalidInputError extends MongoshBaseError {
+    constructor(message: string, code?: string, metadata?: Object);
 }
-declare class MongoshCommandFailed extends Error {
-    constructor(message: string);
+declare class MongoshWarning extends MongoshBaseError {
+    constructor(message: string, code?: string, metadata?: Object);
 }
-export { MongoshWarning, MongoshRuntimeError, MongoshInternalError, MongoshInvalidInputError, MongoshUnimplementedError, MongoshCommandFailed };
+declare class MongoshDeprecatedError extends MongoshBaseError {
+    constructor(message: string, metadata?: Object);
+}
+declare class MongoshCommandFailed extends MongoshBaseError {
+    constructor(message: string, metadata?: Object);
+}
+export { getScopeFromErrorCode, MongoshBaseError, MongoshWarning, MongoshRuntimeError, MongoshInternalError, MongoshInvalidInputError, MongoshUnimplementedError, MongoshDeprecatedError, MongoshCommandFailed, CommonErrors };

lib/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MongoshCommandFailed = exports.MongoshUnimplementedError = exports.MongoshInvalidInputError = exports.MongoshInternalError = exports.MongoshRuntimeError = exports.MongoshWarning = void 0;
-class MongoshRuntimeError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'MongoshRuntimeError';
+exports.CommonErrors = exports.MongoshCommandFailed = exports.MongoshDeprecatedError = exports.MongoshUnimplementedError = exports.MongoshInvalidInputError = exports.MongoshInternalError = exports.MongoshRuntimeError = exports.MongoshWarning = exports.MongoshBaseError = exports.getScopeFromErrorCode = void 0;
+const common_errors_1 = require("./common-errors");
+Object.defineProperty(exports, "CommonErrors", { enumerable: true, get: function () { return common_errors_1.CommonErrors; } });
+function getScopeFromErrorCode(code) {
+    if (!code) {
+        return undefined;
     }
+    const match = code.match(/^([a-zA-Z0-9]+)-/);
+    return !match ? undefined : match[1];
 }
+exports.getScopeFromErrorCode = getScopeFromErrorCode;
+class MongoshBaseError extends Error {
+    constructor(name, message, code, metadata) {
+        super(code ? `[${code}] ${message}` : message);
+        this.name = name;
+        this.code = code;
+        this.scope = getScopeFromErrorCode(code);
+        this.metadata = metadata;
+    }
+}
+exports.MongoshBaseError = MongoshBaseError;
+class MongoshRuntimeError extends MongoshBaseError {
+    constructor(message, code, metadata) {
+        super('MongoshRuntimeError', message, code, metadata);
+    }
+}
 exports.MongoshRuntimeError = MongoshRuntimeError;
-class MongoshInternalError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'MongoshInternalError';
-        this.message =
-            this.message + '\nThis is an error inside Mongosh. Please file a bug report. '
-                + 'Please include a log file from this session.';
+class MongoshInternalError extends MongoshBaseError {
+    constructor(message, metadata) {
+        super('MongoshInternalError', `${message}
+This is an error inside Mongosh. Please file a bug report for the MONGOSH project here: https://jira.mongodb.org.`, common_errors_1.CommonErrors.UnexpectedInternalError, metadata);
     }
 }
 exports.MongoshInternalError = MongoshInternalError;
-class MongoshUnimplementedError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'MongoshUnimplementedError';
+class MongoshUnimplementedError extends MongoshBaseError {
+    constructor(message, code, metadata) {
+        super('MongoshUnimplementedError', message, code, metadata);
     }
 }
 exports.MongoshUnimplementedError = MongoshUnimplementedError;
-class MongoshInvalidInputError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'MongoshInvalidInputError';
+class MongoshInvalidInputError extends MongoshBaseError {
+    constructor(message, code, metadata) {
+        super('MongoshInvalidInputError', message, code, metadata);
     }
 }
 exports.MongoshInvalidInputError = MongoshInvalidInputError;
-class MongoshWarning extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'MongoshWarning';
+class MongoshWarning extends MongoshBaseError {
+    constructor(message, code, metadata) {
+        super('MongoshWarning', message, code, metadata);
     }
 }
 exports.MongoshWarning = MongoshWarning;
-class MongoshCommandFailed extends Error {
-    constructor(message) {
-        super(`Command ${message} returned ok: 0. To see the raw results of the command, use 'runCommand' instead.`);
-        this.name = 'MongoshCommandFailed';
+class MongoshDeprecatedError extends MongoshBaseError {
+    constructor(message, metadata) {
+        super('MongoshDeprecatedError', message, common_errors_1.CommonErrors.Deprecated, metadata);
     }
 }
+exports.MongoshDeprecatedError = MongoshDeprecatedError;
+class MongoshCommandFailed extends MongoshBaseError {
+    constructor(message, metadata) {
+        super('MongoshCommandFailed', `Command ${message} returned ok: 0. To see the raw results of the command, use 'runCommand' instead.`, common_errors_1.CommonErrors.CommandFailed, metadata);
+    }
+}
 exports.MongoshCommandFailed = MongoshCommandFailed;
 //# sourceMappingURL=index.js.map

package.json

 {
   "name": "@mongosh/errors",
-  "version": "0.6.1",
+  "version": "0.7.7",
   "description": "MongoDB Shell Errors Package",
@@ -25,5 +25,6 @@ "homepage": "https://github.com/mongodb-js/mongosh",
     "compile-ts": "tsc -p tsconfig.json",
-    "prepublish": "npm run compile-ts"
+    "prepublish": "npm run compile-ts",
+    "generate-error-overview": "ts-node scripts/extract-errors.ts .. ../../error-overview.md"
   },
-  "gitHead": "b8db879ff567d72cd0c040b04a2ee55bca0203b7"
+  "gitHead": "9d8be6957c3ef53f4cdaa23547225806652f8ef9"
 }

README.md

@@ -19,15 +19,53 @@ # `@mongosh/errors`
 ```
+
+### Error Codes
+The idea of error codes is to allow easy identification of specific errors and map them to a proper documentation.
+Error codes consist of a _scope_ and a numeric part. They follow the pattern `/^([a-zA-Z0-9]+)-/`.
+
+Example: `code='ASYNC-01005'` produces `scope='ASYNC'`.
+
+To better group error codes by their meaning, we suggest the following numbering scheme:
+
+* Use 5 digit numbers for error codes to have enough spacing
+* Use the `10000 - 89999` range for error codes that can be solved immediately by the user.
+* Use the `90000 - 99999` range for error codes that are caused by internal limitations or violated assumptions.
+
+To generate an overview of all errors inside all packages with their documentation, you can run:
+```
+npx ts-node scripts/extract-errors.ts <path to /packages>
+```
+This will generate an `error-overview.md` file in the current directory.
+
+Remembery you can also use the `metadata` of an error to provide additional information.
+
 ### API
 
-#### MongoshWarning(msg)
+#### CommonErrors
+This enum provides common error codes that can be used throughout all packages for errors that do not need individual tracking.
+
+#### MongoshBaseError
+All errors inherit from the abstract `MongoshBaseError` which in turn inherits from `Error`.
+
+All `MongoshBaseError`s have the following properties:
+* `name`: _inherited from `Error`_. The name of the error, corresponding to the concrete class name.
+* `message`: _inherited from `Error`_. Descriptive message of the error.
+* `code`: _optional_. A unique identification code given when constructing the error.
+* `scope`: _optional_. The scope is automatically extracted from a given `code`.
+* `metadata`: _optional_. Additional metadata for further analysis of the error cause.
+
+#### MongoshWarning(msg, code?, metadata?)
 This error is used to give user a warning about the current execution.
 __args:__
 - __msg:__ type string. Describes the warning.
+- __code:__ *optional* type string. Unique identification code of the warning.
+- __metadata:__ *optional* type Object. Additional metadata for further analysis.
 
-#### MongoshUnimplementedError(msg)
+#### MongoshUnimplementedError(msg, code?, metadata?)
 This error is used to API endpoints that are not yet implemented. 
 __args:__
 - __msg:__ type string. Describes what is not yet implemented.
+- __code:__ *optional* type string. Unique identification code of the error.
+- __metadata:__ *optional* type Object. Additional metadata for further analysis.
 
-#### MongoshRuntimeError(msg)
+#### MongoshRuntimeError(msg, code?, metadata?)
 Used for errors in evaluation, specific to MongoDB Shell. Should not be used for
@@ -39,4 +77,6 @@ JavaScript runtime errors.
   avaialable.
+- __code:__ *optional* type string. Unique identification code of the error.
+- __metadata:__ *optional* type Object. Additional metadata for further analysis.
 
-#### MongoshInternalError(msg)
+#### MongoshInternalError(msg, metadata?)
 Used for rare cases when MongoDB Shell is not able to parse and evaluate the
@@ -47,9 +87,12 @@ input.
   it.
+- __metadata:__ *optional* type Object. Additional metadata for further analysis.
 
 `e.message` will be appended with the following information:
-```js
-This is an error inside Mongosh. Please file a bug report. Please include a log file from this session.
 ```
+This is an error inside Mongosh. Please file a bug report for the MONGOSH project here: https://jira.mongodb.org.
+```
 
-#### MongoshInvalidInputError(msg)
+_Note: The error code will automatically be set to `CommonErrors.UnexpectedInternalError`._
+
+#### MongoshInvalidInputError(msg, code?, metadata?)
 This error is used for invalid MongoDB input. This should not be used for
@@ -60,3 +103,24 @@ JavaScript syntax errors, but rather for those specific to MongoDB.
   input, and a fix, if available. 
+- __code:__ *optional* type string. Unique identification code of the error.
+- __metadata:__ *optional* type Object. Additional metadata for further analysis.
 
+#### MongoshDeprecatedError(msg, metadata?)
+This error is used when using a method or property that has been deprecated and was therefore already removed.
+__args:__
+- __msg:__ type string. Describes error in detail, providing current invalid
+  input, and a fix, if available. 
+- __metadata:__ *optional* type Object. Additional metadata for further analysis.
+
+_Note: The error code will automatically be set to `CommonErrors.Deprecated`._
+
+#### MongoshCommandFailed(msg, metadata?)
+This error is used when running a database command unexpectedly failed but can be tried using `runCommand` to get more details.
+This should only be used when the result of a command returns with `{ok: 0}`.
+__args:__
+- __msg:__ type string. Describes error in detail, providing current invalid
+  input, and a fix, if available. 
+- __metadata:__ *optional* type Object. Additional metadata for further analysis.
+
+_Note: The error code will automatically be set to `CommonErrors.CommandFailed`._
+
 ## Installation
@@ -63,0 +127,0 @@ ```shell

tsconfig.json

@@ -11,4 +11,5 @@ {
   "exclude": [
-    "./*.spec.*"
+    "./*.spec.*",
+    "./scripts/*"
   ]
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

42980

increased by107.31%

Number of package files

19

increased by58.33%

Lines of code

588

increased by265.22%

Number of lines in readme file

129

increased by98.46%

Worsened metrics

Number of medium supply chain risk alerts

2

increased byInfinity%

No dependency changes