@ayapapa-npm/contracts-js 0.2.5 → 0.4.0

package/README.md

@@ -1,4 +1,10 @@
 [![CI](https://github.com/ayapapa/contracts-js/actions/workflows/ci.yml/badge.svg)](https://github.com/ayapapa/contracts-js/actions/workflows/ci.yml)
+![Coverage](https://raw.githubusercontent.com/ayapapa/pretty-console-js/main/badges/coverage-total.svg)
+![Branches](https://raw.githubusercontent.com/ayapapa/pretty-console-js/main/badges/coverage-branches.svg)
+![Functions](https://raw.githubusercontent.com/ayapapa/pretty-console-js/main/badges/coverage-functions.svg)
+![Lines](https://raw.githubusercontent.com/ayapapa/pretty-console-js/main/badges/coverage-lines.svg)
+![Statements](https://raw.githubusercontent.com/ayapapa/pretty-console-js/main/badges/coverage-statements.svg)
+
 # contracts-js
 A lightweight Design by Contract library for JavaScript.</br>
 Provides runtime contract checks based on Design by Contract principles.</br>
@@ -126,6 +132,9 @@ Contracts.INVARIANT(
 );
 ```
 
+## API Reference
+[API document](docs/api.md)
+
 ## Usage
 
 ```javascript

package/dist/index.cjs

@@ -1,3 +1,4 @@
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -32,30 +33,39 @@ var Contracts = class _Contracts {
   /** Debug mode state */
   static DEBUG_MODE = false;
   /** default configuration */
-  static defaultConf = {
+  static #defaultConf = {
     debug: false,
     logger: console
   };
+  /** Current config. */
+  static #config = { ..._Contracts.#defaultConf };
   /** logger */
-  static logger = console;
+  //private static logger: LogProvider = console;
   /**
    * Configures contract checking behavior.
    *
    * @param config
-   * Configuration options.
-   *
-   * The `debug` property enables or disables
-   * debug-only contract checks.
-   *
+   * Configuration options. <br>
+   * <br>
+   * The `debug` property toggles the behavior—specifically, 
+   * throwing an exception or outputting to the console when the condition is 
+   * false—for the validation of contracts intended for use during debugging (methods ending in `_DEBUG`). <br>
+   * <br>
    * When `debug` is `true`,
-   * methods ending with `_DEBUG` perform validation.
-   *
-   * When `debug` is `false` or omitted,
-   * methods ending with `_DEBUG` skip validation.
-   * 
+   * methods ending with `_DEBUG` perform validation. <br>
+   * <br>
+   * When `debug` is `false`,
+   * methods ending with `_DEBUG` skip validation. <br>
+   *  <br>
    * Is the `logger` property is specified, 
    * it is used instead of the standard logger, `console`.
-   * This module uses only the `error` method of the `logger`.
+   * This module uses only the `error` method of the `logger`. <br>
+   * <br>
+   * Note: If the value of a property is `undefined`, it is treated as unspecified.
+   * 
+   * @param reset
+   * If `true`, unspecified values ​​are saved to the settings as default values. <br>
+   * If `false`, unspecified values ​​remain at their current settings.
    *
    * @example
    * // Use a logger that is slightly more advanced than the standard logger—namely, `console`.
@@ -65,9 +75,36 @@ var Contracts = class _Contracts {
    * Contracts.setConfig({ debug: true, logger: prettyConsole });
    * // Node: ` The `logger` property is optional.
    */
-  static setConfig(config) {
-    _Contracts.DEBUG_MODE = Boolean(config?.debug);
-    _Contracts.logger = config?.logger ?? console;
+  static setConfig(config, reset = true) {
+    const rConf = { ...config };
+    for (let key of Object.keys(rConf)) {
+      if (rConf[key] == null) delete rConf[key];
+    }
+    if (reset) _Contracts.#config = { ..._Contracts.getDefaultConfig() };
+    Object.assign(_Contracts.#config, rConf);
+    _Contracts.DEBUG_MODE = _Contracts.#config.debug;
+  }
+  /**
+   * Get the default configurations.
+   * @returns Default configurations.
+   */
+  static getDefaultConfig() {
+    return { ..._Contracts.#defaultConf };
+  }
+  /**
+   * Get the current configurations.
+   * @returns Default configurations.
+   */
+  static getConfig() {
+    _Contracts.#config.debug = _Contracts.DEBUG_MODE;
+    return { ..._Contracts.#config };
+  }
+  /**
+   * Reset the current configurations to the default configurations.
+   * @returns Default configurations.
+   */
+  static resetConfig() {
+    _Contracts.setConfig({}, true);
   }
   /**
    * Verifies an intermediate condition during execution.
@@ -87,13 +124,14 @@ var Contracts = class _Contracts {
    * - Check temporary assumptions during execution.
    *
    * @param isOk
-   * Condition result to verify.
+   * Condition result(`boolean`)  to be verified.
    *
-   * @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 +140,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 +157,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
     );
   }
@@ -139,13 +181,14 @@ var Contracts = class _Contracts {
    * - Check internal assumptions while debugging.
    *
    * @param isOk
-   * Condition result to verify.
+   * Condition result(`boolean`)  to be verified.
    *
-   * @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 +197,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 +212,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
     );
   }
@@ -189,13 +236,14 @@ var Contracts = class _Contracts {
    * - Check required external conditions.
    *
    * @param isOk
-   * Condition result to verify.
+   * Condition result(`boolean`)  to be verified.
    *
-   * @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 +252,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 +276,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
     );
   }
@@ -248,13 +300,14 @@ var Contracts = class _Contracts {
    * - Perform additional argument checks while debugging.
    *
    * @param isOk
-   * Condition result to verify.
+   * Condition result(`boolean`)  to be verified.
    *
-   * @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 +316,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 +331,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
     );
   }
@@ -299,13 +356,14 @@ var Contracts = class _Contracts {
    * - Verify that processing completed correctly.
    *
    * @param isOk
-   * Condition result to verify.
+   * Condition result(`boolean`)  to be verified.
    *
-   * @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 +372,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 +398,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
     );
   }
@@ -360,13 +422,14 @@ var Contracts = class _Contracts {
    * - Confirm internal behavior while debugging.
    *
    * @param isOk
-   * Condition result to verify.
+   * Condition result(`boolean`)  to be verified.
    *
-   * @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 +438,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 +453,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
     );
   }
@@ -411,13 +478,14 @@ var Contracts = class _Contracts {
    * INVARIANT represents conditions that must always remain true.
    *
    * @param isOk
-   * Condition result to verify.
+   * Condition result(`boolean`)  to be verified.
    *
-   * @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 +494,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 +517,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
     );
   }
@@ -469,13 +541,14 @@ var Contracts = class _Contracts {
    * - Detect unexpected state changes while debugging.
    *
    * @param isOk
-   * Condition result to verify.
+   * Condition result(`boolean`)  to be verified.
    *
    * @param [ngMsg]
    * Failure message.
    *
    * @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 +557,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 +572,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
     );
   }
@@ -522,7 +599,7 @@ var Contracts = class _Contracts {
    * @internal
    * 
    * @param isOk
-   * Condition result.
+   * Condition result(`boolean`)  to be verified.
    *
    * @param prefix
    * Contract type prefix used in the error message.
@@ -531,8 +608,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.
    *
@@ -540,14 +628,19 @@ 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);
+        eProps && Object.assign(err, eProps);
+        throw err;
       }
       if (ngMsg) {
         _Contracts.getLogger().error(msg, eProps);
@@ -568,7 +661,7 @@ var Contracts = class _Contracts {
    * @internal
    * 
    * @param isOk
-   * Condition result.
+   * Condition result(`boolean`)  to be verified.
    *
    * @param prefix
    * Contract type prefix used in the error message.
@@ -576,8 +669,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.
@@ -586,12 +690,13 @@ 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;
   }
@@ -601,7 +706,7 @@ var Contracts = class _Contracts {
    * @internal
    */
   static getLogger() {
-    return _Contracts.logger ?? console;
+    return _Contracts.#config.logger;
   }
 };