@ayapapa-npm/contracts-js 0.2.5 → 0.4.0

package/dist/index.d.ts

@@ -58,33 +58,38 @@ type ConfigKey = keyof Config;
  * @module Contracts
  */
 declare class Contracts {
+    #private;
     /**
      * Static fields
      */
     /** Debug mode state */
     static DEBUG_MODE: boolean;
-    /** default configuration */
-    private static readonly defaultConf;
     /** logger */
-    private static logger;
     /**
      * 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`.
@@ -94,7 +99,22 @@ declare class Contracts {
      * Contracts.setConfig({ debug: true, logger: prettyConsole });
      * // Node: ` The `logger` property is optional.
      */
-    static setConfig(config: Config): void;
+    static setConfig(config: Config, reset?: boolean): void;
+    /**
+     * Get the default configurations.
+     * @returns Default configurations.
+     */
+    static getDefaultConfig(): Required<Config>;
+    /**
+     * Get the current configurations.
+     * @returns Default configurations.
+     */
+    static getConfig(): Required<Config>;
+    /**
+     * Reset the current configurations to the default configurations.
+     * @returns Default configurations.
+     */
+    static resetConfig(): void;
     /**
      * Verifies an intermediate condition during execution.
      *
@@ -113,13 +133,14 @@ declare 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)
@@ -128,7 +149,10 @@ declare 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
@@ -142,7 +166,11 @@ declare class Contracts {
      *   'Calculation result must not be negative'
      * );
      */
-    static VERIFY(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eProps?: {}): boolean;
+    static VERIFY(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eParams?: {
+        [key: string]: any;
+    } | null, eProps?: {
+        [key: string]: any;
+    } | null): boolean;
     /**
      * Verifies an intermediate condition in debug mode only.
      *
@@ -157,13 +185,14 @@ declare 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)
@@ -172,7 +201,10 @@ declare 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
@@ -184,7 +216,11 @@ declare class Contracts {
      *   'Intermediate value must not be null'
      * );
      */
-    static VERIFY_DEBUG(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eProps?: {}): boolean;
+    static VERIFY_DEBUG(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eParams?: {
+        [key: string]: any;
+    } | null, eProps?: {
+        [key: string]: any;
+    } | null): boolean;
     /**
      * Checks a precondition before execution.
      *
@@ -199,13 +235,14 @@ declare 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)
@@ -214,7 +251,10 @@ declare 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
@@ -235,7 +275,11 @@ declare class Contracts {
      *   return a / b;
      * }
      */
-    static REQUIRE(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eProps?: {}): boolean;
+    static REQUIRE(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eParams?: {
+        [key: string]: any;
+    } | null, eProps?: {
+        [key: string]: any;
+    } | null): boolean;
     /**
      * Checks a precondition in debug mode only.
      *
@@ -250,13 +294,14 @@ declare 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)
@@ -265,7 +310,10 @@ declare 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
@@ -277,7 +325,11 @@ declare class Contracts {
      *   'User must exist during debugging'
      * );
      */
-    static REQUIRE_DEBUG(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eProps?: {}): boolean;
+    static REQUIRE_DEBUG(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eParams?: {
+        [key: string]: any;
+    } | null, eProps?: {
+        [key: string]: any;
+    } | null): boolean;
     /**
      * Checks a postcondition after execution.
      *
@@ -293,13 +345,14 @@ declare 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)
@@ -308,7 +361,10 @@ declare 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
@@ -331,7 +387,11 @@ declare class Contracts {
      *   return result;
      * }
      */
-    static ENSURE(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eProps?: {}): boolean;
+    static ENSURE(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eParams?: {
+        [key: string]: any;
+    } | null, eProps?: {
+        [key: string]: any;
+    } | null): boolean;
     /**
      * Checks a postcondition in debug mode only.
      *
@@ -346,13 +406,14 @@ declare 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)
@@ -361,7 +422,10 @@ declare 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
@@ -373,7 +437,11 @@ declare class Contracts {
      *   'Result should exist during debugging'
      * );
      */
-    static ENSURE_DEBUG(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eProps?: {}): boolean;
+    static ENSURE_DEBUG(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eParams?: {
+        [key: string]: any;
+    } | null, eProps?: {
+        [key: string]: any;
+    } | null): boolean;
     /**
      * Checks an invariant condition.
      *
@@ -389,13 +457,14 @@ declare 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)
@@ -404,7 +473,10 @@ declare 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
@@ -424,7 +496,11 @@ declare class Contracts {
      *
      * }
      */
-    static INVARIANT(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eProps?: {}): boolean;
+    static INVARIANT(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eParams?: {
+        [key: string]: any;
+    } | null, eProps?: {
+        [key: string]: any;
+    } | null): boolean;
     /**
      * Checks an invariant condition in debug mode only.
      *
@@ -439,13 +515,14 @@ declare 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)
@@ -454,6 +531,9 @@ declare 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.
      *
@@ -466,7 +546,11 @@ declare class Contracts {
      *   'Cache size exceeded expected limit'
      * );
      */
-    static INVARIANT_DEBUG(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eProps?: {}): boolean;
+    static INVARIANT_DEBUG(isOk: boolean, ngMsg: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eParams?: {
+        [key: string]: any;
+    } | null, eProps?: {
+        [key: string]: any;
+    } | null): boolean;
     /**
      * Core contract evaluation logic.
      *
@@ -484,7 +568,7 @@ declare class Contracts {
      * @internal
      *
      * @param isOk
-     * Condition result.
+     * Condition result(`boolean`)  to be verified.
      *
      * @param prefix
      * Contract type prefix used in the error message.
@@ -493,7 +577,18 @@ declare 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.
@@ -516,7 +611,7 @@ declare class Contracts {
      * @internal
      *
      * @param isOk
-     * Condition result.
+     * Condition result(`boolean`)  to be verified.
      *
      * @param prefix
      * Contract type prefix used in the error message.
@@ -524,8 +619,19 @@ declare 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.