@ayapapa-npm/contracts-js 0.2.4 → 0.3.0

package/dist/index.d.cts

@@ -11,14 +11,16 @@ interface Config {
      * If `true`, `DEBUG_MODE` is enabled; otherwise, it is disabled.
      * The default is `false`.
      */
-    debug: boolean;
+    debug?: boolean;
     /**
      * External logger.
      * If specified, it is used instead of the standard logger, `console`.
      * This module uses only the `error` method.
      */
-    logger: LogProvider;
+    logger?: LogProvider;
 }
+/** Type of `Config`'s key. */
+type ConfigKey = keyof Config;
 /**
  * A lightweight Design by Contract library for JavaScript.
  *
@@ -82,7 +84,7 @@ declare 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`.
@@ -113,11 +115,12 @@ declare 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)
@@ -126,7 +129,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
@@ -140,7 +146,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,11 +167,12 @@ declare 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)
@@ -170,7 +181,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
@@ -182,7 +196,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,11 +217,12 @@ declare 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)
@@ -212,7 +231,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
@@ -233,7 +255,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,11 +276,12 @@ declare 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 +290,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
@@ -275,7 +305,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,11 +327,12 @@ declare 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)
@@ -306,7 +341,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
@@ -329,7 +367,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,11 +388,12 @@ declare 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)
@@ -359,7 +402,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
@@ -371,7 +417,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,11 +439,12 @@ declare 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)
@@ -402,7 +453,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
@@ -422,7 +476,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.
      *
@@ -444,6 +502,7 @@ declare 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)
@@ -452,6 +511,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.
      *
@@ -464,7 +526,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.
      *
@@ -478,6 +544,9 @@ declare class Contracts {
      * - When ErrorClass is null,
      *   logs the failure message instead of throwing.
      *
+     *
+     * @internal
+     *
      * @param isOk
      * Condition result.
      *
@@ -488,7 +557,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.
@@ -508,6 +588,8 @@ declare class Contracts {
      * this method returns the original condition value
      * without performing any validation.
      *
+     * @internal
+     *
      * @param isOk
      * Condition result.
      *
@@ -517,8 +599,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.
@@ -527,9 +620,13 @@ declare class Contracts {
      * Returns the original condition value.
      *
      */
-    static checkDebug(isOk: boolean, prefix?: string, ngMsg?: string | null, ErrorClass?: (new (...args: any[]) => Error) | null, eProps?: {}): boolean;
-    /** Get logger */
+    private static checkDebug;
+    /**
+     * Get logger
+     *
+     * @internal
+     */
     private static getLogger;
 }
 
-export { type Config, Contracts, type LogProvider, Contracts as default };
+export { type Config, type ConfigKey, Contracts, type LogProvider, Contracts as default };