@ayapapa-npm/contracts-js 0.2.4 → 0.3.0

package/dist/index.cjs

@@ -55,7 +55,7 @@ var Contracts = class _Contracts {
    * 
    * Is the `logger` property is specified, 
    * it is used instead of the standard logger, `console`.
-   * This module uses only the `error` method.
+   * This module uses only the `error` method of the `logger`.
    *
    * @example
    * // Use a logger that is slightly more advanced than the standard logger—namely, `console`.
@@ -89,11 +89,12 @@ var Contracts = class _Contracts {
    * @param isOk
    * Condition result to verify.
    *
-   * @param [ngMsg]
+   * @param ngMsg
    * Failure message.
    *
-   * @param [ErrorClass=Error]
+   * @param ErrorClass
    * Error constructor used when the check fails.
+   * This is used as follows: throw Object.assign(new ErrorClass(msg, eParams), eProps);
    *
    * Supported values:
    * - `Error` (default)
@@ -102,7 +103,10 @@ var Contracts = class _Contracts {
    * - Custom Error subclasses
    * - `null` to skip throwing and log the failure.
    *
-   * @param [eProps = {}]
+   * @param eParams
+   * Parameter options following the message passed to the Error constructor.
+   *
+   * @param eProps
    * Additional properties assigned to the error object.
    *
    * @returns 
@@ -116,12 +120,13 @@ var Contracts = class _Contracts {
    *   'Calculation result must not be negative'
    * );
    */
-  static VERIFY(isOk, ngMsg, ErrorClass = Error, eProps = {}) {
+  static VERIFY(isOk, ngMsg, ErrorClass = Error, eParams, eProps) {
     return _Contracts.check(
       isOk,
       "VERIFY",
       ngMsg,
       ErrorClass,
+      eParams,
       eProps
     );
   }
@@ -141,11 +146,12 @@ var Contracts = class _Contracts {
    * @param isOk
    * Condition result to verify.
    *
-   * @param [ngMsg]
+   * @param ngMsg
    * Failure message.
    *
-   * @param [ErrorClass=Error]
+   * @param ErrorClass
    * Error constructor used when the check fails.
+   * This is used as follows: throw Object.assign(new ErrorClass(msg, eParams), eProps);
    *
    * Supported values:
    * - `Error` (default)
@@ -154,7 +160,10 @@ var Contracts = class _Contracts {
    * - Custom Error subclasses
    * - `null` to skip throwing and log the failure.
    *
-   * @param [eProps = {}]
+   * @param eParams
+   * Parameter options following the message passed to the Error constructor.
+   *
+   * @param eProps
    * Additional properties assigned to the error object.
    *
    * @returns 
@@ -166,12 +175,13 @@ var Contracts = class _Contracts {
    *   'Intermediate value must not be null'
    * );
    */
-  static VERIFY_DEBUG(isOk, ngMsg, ErrorClass = Error, eProps = {}) {
+  static VERIFY_DEBUG(isOk, ngMsg, ErrorClass = Error, eParams, eProps) {
     return _Contracts.checkDebug(
       isOk,
       "VERIFY_DEBUG",
       ngMsg,
       ErrorClass,
+      eParams,
       eProps
     );
   }
@@ -191,11 +201,12 @@ var Contracts = class _Contracts {
    * @param isOk
    * Condition result to verify.
    *
-   * @param [ngMsg]
+   * @param ngMsg
    * Failure message.
    *
-   * @param [ErrorClass=Error]
+   * @param ErrorClass
    * Error constructor used when the check fails.
+   * This is used as follows: throw Object.assign(new ErrorClass(msg, eParams), eProps);
    *
    * Supported values:
    * - `Error` (default)
@@ -204,7 +215,10 @@ var Contracts = class _Contracts {
    * - Custom Error subclasses
    * - `null` to skip throwing and log the failure.
    *
-   * @param [eProps = {}]
+   * @param eParams
+   * Parameter options following the message passed to the Error constructor.
+   *
+   * @param eProps
    * Additional properties assigned to the error object.
    *
    * @returns 
@@ -225,12 +239,13 @@ var Contracts = class _Contracts {
    *   return a / b;
    * }
    */
-  static REQUIRE(isOk, ngMsg, ErrorClass = Error, eProps = {}) {
+  static REQUIRE(isOk, ngMsg, ErrorClass = Error, eParams, eProps) {
     return _Contracts.check(
       isOk,
       "REQUIRE",
       ngMsg,
       ErrorClass,
+      eParams,
       eProps
     );
   }
@@ -250,11 +265,12 @@ var Contracts = class _Contracts {
    * @param isOk
    * Condition result to verify.
    *
-   * @param [ngMsg]
+   * @param ngMsg
    * Failure message.
    *
-   * @param [ErrorClass=Error]
+   * @param ErrorClass
    * Error constructor used when the check fails.
+   * This is used as follows: throw Object.assign(new ErrorClass(msg, eParams), eProps);
    *
    * Supported values:
    * - `Error` (default)
@@ -263,7 +279,10 @@ var Contracts = class _Contracts {
    * - Custom Error subclasses
    * - `null` to skip throwing and log the failure.
    *
-   * @param [eProps = {}]
+   * @param eParams
+   * Parameter options following the message passed to the Error constructor.
+   *
+   * @param eProps
    * Additional properties assigned to the error object.
    *
    * @returns 
@@ -275,12 +294,13 @@ var Contracts = class _Contracts {
    *   'User must exist during debugging'
    * );
    */
-  static REQUIRE_DEBUG(isOk, ngMsg, ErrorClass = Error, eProps = {}) {
+  static REQUIRE_DEBUG(isOk, ngMsg, ErrorClass = Error, eParams, eProps) {
     return _Contracts.checkDebug(
       isOk,
       "REQUIRE_DEBUG",
       ngMsg,
       ErrorClass,
+      eParams,
       eProps
     );
   }
@@ -301,11 +321,12 @@ var Contracts = class _Contracts {
    * @param isOk
    * Condition result to verify.
    *
-   * @param [ngMsg]
+   * @param ngMsg
    * Failure message.
    *
-   * @param [ErrorClass=Error]
+   * @param ErrorClass
    * Error constructor used when the check fails.
+   * This is used as follows: throw Object.assign(new ErrorClass(msg, eParams), eProps);
    *
    * Supported values:
    * - `Error` (default)
@@ -314,7 +335,10 @@ var Contracts = class _Contracts {
    * - Custom Error subclasses
    * - `null` to skip throwing and log the failure.
    *
-   * @param [eProps = {}]
+   * @param eParams
+   * Parameter options following the message passed to the Error constructor.
+   *
+   * @param eProps
    * Additional properties assigned to the error object.
    *
    * @returns 
@@ -337,12 +361,13 @@ var Contracts = class _Contracts {
    *   return result;
    * }
    */
-  static ENSURE(isOk, ngMsg, ErrorClass = Error, eProps = {}) {
+  static ENSURE(isOk, ngMsg, ErrorClass = Error, eParams, eProps) {
     return _Contracts.check(
       isOk,
       "ENSURE",
       ngMsg,
       ErrorClass,
+      eParams,
       eProps
     );
   }
@@ -362,11 +387,12 @@ var Contracts = class _Contracts {
    * @param isOk
    * Condition result to verify.
    *
-   * @param [ngMsg]
+   * @param ngMsg
    * Failure message.
    *
-   * @param [ErrorClass=Error]
+   * @param ErrorClass
    * Error constructor used when the check fails.
+   * This is used as follows: throw Object.assign(new ErrorClass(msg, eParams), eProps);
    *
    * Supported values:
    * - `Error` (default)
@@ -375,7 +401,10 @@ var Contracts = class _Contracts {
    * - Custom Error subclasses
    * - `null` to skip throwing and log the failure.
    *
-   * @param [eProps = {}]
+   * @param eParams
+   * Parameter options following the message passed to the Error constructor.
+   *
+   * @param eProps
    * Additional properties assigned to the error object.
    *
    * @returns 
@@ -387,12 +416,13 @@ var Contracts = class _Contracts {
    *   'Result should exist during debugging'
    * );
    */
-  static ENSURE_DEBUG(isOk, ngMsg, ErrorClass = Error, eProps = {}) {
+  static ENSURE_DEBUG(isOk, ngMsg, ErrorClass = Error, eParams, eProps) {
     return _Contracts.checkDebug(
       isOk,
       "ENSURE_DEBUG",
       ngMsg,
       ErrorClass,
+      eParams,
       eProps
     );
   }
@@ -413,11 +443,12 @@ var Contracts = class _Contracts {
    * @param isOk
    * Condition result to verify.
    *
-   * @param [ngMsg]
+   * @param ngMsg
    * Failure message.
    *
-   * @param [ErrorClass=Error]
+   * @param ErrorClass
    * Error constructor used when the check fails.
+   * This is used as follows: throw Object.assign(new ErrorClass(msg, eParams), eProps);
    *
    * Supported values:
    * - `Error` (default)
@@ -426,7 +457,10 @@ var Contracts = class _Contracts {
    * - Custom Error subclasses
    * - `null` to skip throwing and log the failure.
    *
-   * @param [eProps = {}]
+   * @param eParams
+   * Parameter options following the message passed to the Error constructor.
+   *
+   * @param eProps
    * Additional properties assigned to the error object.
    *
    * @returns 
@@ -446,12 +480,13 @@ var Contracts = class _Contracts {
    *
    * }
    */
-  static INVARIANT(isOk, ngMsg, ErrorClass = Error, eProps = {}) {
+  static INVARIANT(isOk, ngMsg, ErrorClass = Error, eParams, eProps) {
     return _Contracts.check(
       isOk,
       "INVARIANT",
       ngMsg,
       ErrorClass,
+      eParams,
       eProps
     );
   }
@@ -476,6 +511,7 @@ var Contracts = class _Contracts {
    *
    * @param [ErrorClass=Error]
    * Error constructor used when the check fails.
+   * This is used as follows: throw Object.assign(new ErrorClass(msg, eParams), eProps);
    *
    * Supported values:
    * - `Error` (default)
@@ -484,6 +520,9 @@ var Contracts = class _Contracts {
    * - Custom Error subclasses
    * - `null` to skip throwing and log the failure.
    *
+   * @param eParams
+   * Parameter options following the message passed to the Error constructor.
+   *
    * @param [eProps = {}]
    * Additional properties assigned to the error object.
    *
@@ -496,12 +535,13 @@ var Contracts = class _Contracts {
    *   'Cache size exceeded expected limit'
    * );
    */
-  static INVARIANT_DEBUG(isOk, ngMsg, ErrorClass = Error, eProps = {}) {
+  static INVARIANT_DEBUG(isOk, ngMsg, ErrorClass = Error, eParams, eProps) {
     return _Contracts.checkDebug(
       isOk,
       "INVARIANT_DEBUG",
       ngMsg,
       ErrorClass,
+      eParams,
       eProps
     );
   }
@@ -518,6 +558,9 @@ var Contracts = class _Contracts {
    * - When ErrorClass is null,
    *   logs the failure message instead of throwing.
    *
+   *
+   * @internal
+   * 
    * @param isOk
    * Condition result.
    *
@@ -528,8 +571,19 @@ var Contracts = class _Contracts {
    * Failure message.
    *
    * @param ErrorClass
-   * Error constructor.
+   * Error constructor used when the check fails.
+   * This is used as follows: throw Object.assign(new ErrorClass(msg, eParams), eProps);
+   *
+   * Supported values:
+   * - `Error` (default)
+   * - `TypeError`
+   * - `RangeError`
+   * - Custom Error subclasses
+   * - `null` to skip throwing and log the failure.
    *
+   * @param eParams
+   * Parameter options following the message passed to the Error constructor.
+   * 
    * @param eProps
    * Additional properties assigned to the error object.
    *
@@ -537,14 +591,21 @@ var Contracts = class _Contracts {
    * Returns the original condition value.
    *
    */
-  static check(isOk, prefix = "CHECK", ngMsg = "", ErrorClass = Error, eProps = {}) {
+  static check(isOk, prefix = "CHECK", ngMsg = "", ErrorClass = Error, eParams, eProps) {
+    if (eProps === void 0) {
+      eProps = eParams ?? {};
+      eParams = null;
+    } else {
+      eProps ??= {};
+    }
     if (!isOk) {
       const msg = `[${prefix}] ${ngMsg ?? ""}`;
       if (ErrorClass) {
-        throw Object.assign(
-          new ErrorClass(msg),
-          eProps
-        );
+        const err = eParams ? new ErrorClass(msg, eParams) : new ErrorClass(msg);
+        if (eProps) {
+          Object.assign(err, eProps);
+        }
+        throw err;
       }
       if (ngMsg) {
         _Contracts.getLogger().error(msg, eProps);
@@ -562,6 +623,8 @@ var Contracts = class _Contracts {
    * this method returns the original condition value
    * without performing any validation.
    *
+   * @internal
+   * 
    * @param isOk
    * Condition result.
    *
@@ -571,8 +634,19 @@ var Contracts = class _Contracts {
    * @param ngMsg
    * Failure message.
    *
-   * @param ErrorClass
-   * Error constructor.
+   * @param ErrorClass=Error
+   * Error constructor used when the check fails.
+   * This is used as follows: throw Object.assign(new ErrorClass(msg, eParams), eProps);
+   *
+   * Supported values:
+   * - `Error` (default)
+   * - `TypeError`
+   * - `RangeError`
+   * - Custom Error subclasses
+   * - `null` to skip throwing and log the failure.
+   *
+   * @param eParams
+   * Parameter options following the message passed to the Error constructor.
    *
    * @param eProps
    * Additional properties assigned to the error object.
@@ -581,16 +655,21 @@ var Contracts = class _Contracts {
    * Returns the original condition value.
    *
    */
-  static checkDebug(isOk, prefix = "CHECK", ngMsg = "", ErrorClass = Error, eProps = {}) {
+  static checkDebug(isOk, prefix = "CHECK", ngMsg = "", ErrorClass = Error, eParams, eProps) {
     return _Contracts.DEBUG_MODE ? _Contracts.check(
       isOk,
       prefix,
       ngMsg,
       ErrorClass,
+      eParams,
       eProps
     ) : isOk;
   }
-  /** Get logger */
+  /** 
+   * Get logger 
+   *
+   * @internal
+   */
   static getLogger() {
     return _Contracts.logger ?? console;
   }