@ayapapa-npm/contracts-js 0.2.5 → 0.4.0

package/dist/index.js

@@ -6,30 +6,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`.
@@ -39,9 +48,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.
@@ -61,13 +97,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)
@@ -76,7 +113,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 
@@ -90,12 +130,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
     );
   }
@@ -113,13 +154,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)
@@ -128,7 +170,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 
@@ -140,12 +185,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
     );
   }
@@ -163,13 +209,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)
@@ -178,7 +225,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 
@@ -199,12 +249,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
     );
   }
@@ -222,13 +273,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)
@@ -237,7 +289,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 
@@ -249,12 +304,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
     );
   }
@@ -273,13 +329,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)
@@ -288,7 +345,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 
@@ -311,12 +371,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
     );
   }
@@ -334,13 +395,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)
@@ -349,7 +411,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 
@@ -361,12 +426,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
     );
   }
@@ -385,13 +451,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)
@@ -400,7 +467,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 
@@ -420,12 +490,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
     );
   }
@@ -443,13 +514,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)
@@ -458,6 +530,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.
    *
@@ -470,12 +545,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
     );
   }
@@ -496,7 +572,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.
@@ -505,8 +581,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.
    *
@@ -514,14 +601,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);
@@ -542,7 +634,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.
@@ -550,8 +642,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.
@@ -560,12 +663,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;
   }
@@ -575,7 +679,7 @@ var Contracts = class _Contracts {
    * @internal
    */
   static getLogger() {
-    return _Contracts.logger ?? console;
+    return _Contracts.#config.logger;
   }
 };
 

package/package.json

@@ -1,38 +1,43 @@
-{
-  "name": "@ayapapa-npm/contracts-js",
-  "version": "0.2.5",
-  "description": "A lightweight Design by Contract library for JavaScript.",
-  "license": "MIT",
-  "author": "ayapapa",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --out-dir dist --clean --dts",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:debug": "vitest --inspect-brk --run",
-    "test:watch": "vitest",
-    "check": "npm run typecheck && npm run build && npm run test",
-    "release:check": "npm run typecheck && npm run build && npm run test",
-    "prepublishOnly": "npm run release:check"
-  },
-  "devDependencies": {
-    "@types/node": "^26.2.0",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.10"
-  },
-  "allowScripts": {
-    "esbuild@0.28.1": true
-  }
-}
+{
+  "name": "@ayapapa-npm/contracts-js",
+  "version": "0.4.0",
+  "description": "A lightweight Design by Contract library for JavaScript.",
+  "license": "MIT",
+  "author": "ayapapa",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --out-dir dist --clean --dts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:debug": "vitest --inspect-brk --run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "coverage": "vitest run --coverage",
+    "coverage:ui": "vitest run --coverage && start coverage/index.html",
+    "check": "npm run typecheck && npm run build && npm run test",
+    "release:check": "npm run check",
+    "prepublishOnly": "npm run release:check"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/ui": "^4.1.11",
+    "tsup": "^8.5.1",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.13.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
+  }
+}