xdbc 1.0.93 → 1.0.95

package/dist/DBC/OR.js

@@ -1,18 +1,17 @@
-import { DBC } from "../DBC.js";
+import { DBC } from "../DBC";
 /**
  * A {@link DBC } defining that all elements of an {@link object }s have to fulfill
- * one of the given {@link object }s check-methods (( toCheck : any ) => boolean | string ).
+ * one of the given {@link object }s check-methods (**( toCheck : any ) => boolean | string** ).
  *
  * @remarks
  * Maintainer: Callari, Salvatore (XDBC@WaXCode.net) */
 export class OR extends DBC {
     // #region Condition checking.
     /**
-     * Checks each element of the "value"-{@link Array < any >} against the given "condition", if it is one. If it is not
-     * the "value" itself will be checked.
+     * Checks the **value** against the given **conditions**
      *
-     * @param conditions	The { check: (toCheck: any) => boolean | string }-{@link object }s to check the "value" against.
-     * @param value			Either "value"-{@link Array < any >}, which's elements will be checked, or the value to be
+     * @param conditions	The **{ check: (toCheck: any) => boolean | string }**-{@link object }s to check the **value** against.
+     * @param value			Either **value**-{@link Array < any >}, which's elements will be checked, or the value to be
      * 						checked itself.
      * @param index			If specified with "idxEnd" being undefined, this {@link Number } will be seen as the index of
      * 						the value-{@link Array }'s element to check. If value isn't an {@link Array } this parameter
@@ -21,39 +20,39 @@ export class OR extends DBC {
      * 						check within the value-{@link Array }.
      * @param idxEnd		Indicates the last element's index (including) of the span of value-{@link Array } elements to check.
      * 						Setting this parameter to -1 specifies that all value-{@link Array }'s elements beginning from the
-     * 						specified "index" shall be checked.
+     * 						specified **index** shall be checked.
      *
-     * @returns TRUE if at least one of the provided "conditions" is fulfilled, otherwise a {@link string } containing all "conditions" returned {@link string }s separated by " || ". */
+     * @returns TRUE if at least one of the provided **conditions** is fulfilled, otherwise a {@link string } containing all **conditions** returned {@link string }s separated by " || ". */
     static checkAlgorithm(conditions, value) {
         let result = "";
         for (let i = 0; i < conditions.length; i++) {
             const conditionResult = conditions[i].check(value);
-            if (typeof conditionResult !== "boolean") {
-                result += `${conditionResult}${i === conditions.length - 1 ? "" : " || "}`;
+            if (typeof conditionResult === "string") {
+                result += `${conditionResult}${i === conditions.length - 1 ? "" : " or "}`;
             }
             else {
                 return true;
             }
         }
-        return true;
+        return result;
     }
     /**
      * A parameter-decorator factory using the {@link OR.checkAlgorithm } with either multiple or a single one
-     * of the "realConditions" to check the tagged parameter-value against with.
-     * When specifying an "index" and the tagged parameter's "value" is an {@link Array }, the "realConditions" apply to the
-     * element at the specified "index".
+     * of the **realConditions** to check the tagged parameter-value against with.
+     * When specifying an **index** and the tagged parameter's **value** is an {@link Array }, the **realConditions** apply to the
+     * element at the specified **index**.
      * If the {@link Array } is too short the currently processed { check: (toCheck: any) => boolean | string } of
-     * "realConditions" will be verified to TRUE automatically, considering optional parameters.
-     * If an "index" is specified but the tagged parameter's value isn't an array, the "index" is treated as being undefined.
-     * If "index" is undefined and the tagged parameter's value is an {@link Array } each element of it will be checked
-     * against the "realConditions".
+     * **realConditions** will be verified to TRUE automatically, considering optional parameters.
+     * If an **index** is specified but the tagged parameter's value isn't an array, the **index** is treated as being undefined.
+     * If **index** is undefined and the tagged parameter's value is an {@link Array } each element of it will be checked
+     * against the **realConditions**.
      *
-     * @param realConditions	Either one or more { check: (toCheck: any) => boolean | string } to check the tagged parameter-value
+     * @param realConditions	Either one or more **{ check: (toCheck: any) => boolean | string }** to check the tagged parameter-value
      * 							against with.
      * @param path				See {@link DBC.decPrecondition }.
      * @param dbc				See {@link DBC.decPrecondition }.
      *
-     * @returns	A {@link string } as soon as one { check: (toCheck: any) => boolean | string } of "realConditions" returns one.
+     * @returns	A {@link string } as soon as one { check: (toCheck: any) => boolean | string } of **realConditions** returns one.
      * 			Otherwise TRUE. */
     static PRE(conditions, path = undefined, dbc = "WaXCode.DBC") {
         return DBC.decPrecondition((value, target, methodName, parameterIndex) => {
@@ -62,27 +61,40 @@ export class OR extends DBC {
     }
     /**
      * A method-decorator factory using the {@link OR.checkAlgorithm } with either multiple or a single one
-     * of the "realConditions" to check the tagged method's return-value against with.
+     * of the **realConditions** to check the tagged method's return-value against with.
      *
      * @param realConditions	Either one or more { check: (toCheck: any) => boolean | string } to check the tagged parameter-value
      * 							against with.
      * @param path				See {@link DBC.decPrecondition }.
      * @param dbc				See {@link DBC.decPrecondition }.
      *
-     * @returns	A {@link string } as soon as one { check: (toCheck: any) => boolean | string } of "realConditions" return one.
+     * @returns	A {@link string } as soon as one **{ check: (toCheck: any) => boolean | string }** of **realConditions** return one.
      * 			Otherwise TRUE. */
     static POST(conditions, path = undefined, dbc = "WaXCode.DBC") {
         return DBC.decPostcondition((value, target, propertyKey) => {
             return OR.checkAlgorithm(conditions, value);
         }, dbc, path);
     }
+    /**
+     * A field-decorator factory using the {@link OR.checkAlgorithm } with either multiple or a single one
+     * of the **realConditions** to check the tagged field.
+     *
+     * @param realConditions	Either one or more { check: (toCheck: any) => boolean | string } to check the tagged parameter-value
+     * 							against with.
+     * @param path				See {@link DBC.decInvariant }.
+     * @param dbc				See {@link DBC.decInvariant }.
+     *
+     * @returns	See {@link DBC.decInvariant }. */
+    static INVARIANT(conditions, path = undefined, dbc = "WaXCode.DBC") {
+        return DBC.decInvariant([new OR(conditions)], path, dbc);
+    }
     // #endregion Condition checking.
     // #region Referenced Condition checking.
     //
     // For usage in dynamic scenarios (like global functions).
     //
     /**
-     * Invokes the {@link OR.checkAlgorithm } passing the value "toCheck" and {@link OR.conditions }.
+     * Invokes the {@link OR.checkAlgorithm } passing the value **toCheck** and {@link OR.conditions }.
      *
      * @param toCheck See {@link OR.checkAlgorithm }.
      *

package/dist/DBC/REGEX.js

@@ -7,13 +7,13 @@ import { DBC } from "../DBC";
 export class REGEX extends DBC {
     // #region Condition checking.
     /**
-     * Checks if the value "toCheck" is complies to the {@link RegExp } "expression".
+     * Checks if the value **toCheck** is complies to the {@link RegExp } **expression**.
      *
-     * @param toCheck		The value that has comply to the {@link RegExp } "expression" for this {@link DBC } to be fulfilled.
-     * @param expression	The {@link RegExp } the one "toCheck" has comply to in order for this {@link DBC } to be
+     * @param toCheck		The value that has comply to the {@link RegExp } **expression** for this {@link DBC } to be fulfilled.
+     * @param expression	The {@link RegExp } the one **toCheck** has comply to in order for this {@link DBC } to be
      * 						fulfilled.
      *
-     * @returns TRUE if the value "toCheck" complies with the {@link RegExp } "expression", otherwise FALSE. */
+     * @returns TRUE if the value **toCheck** complies with the {@link RegExp } **expression**, otherwise FALSE. */
     static checkAlgorithm(toCheck, expression) {
         if (!expression.test(toCheck)) {
             return `Value has to comply to regular expression "${expression}"`;
@@ -48,15 +48,27 @@ export class REGEX extends DBC {
             return REGEX.checkAlgorithm(value, expression);
         }, dbc, path);
     }
+    /**
+     * A field-decorator factory using the {@link REGEX.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged field.
+     *
+     * @param expression	See {@link REGEX.checkAlgorithm }.
+     * @param path			See {@link DBC.decInvariant }.
+     * @param dbc			See {@link DBC.decInvariant }.
+     *
+     * @returns See {@link DBC.decInvariant }. */
+    static INVARIANT(expression, path = undefined, dbc = "WaXCode.DBC") {
+        return DBC.decInvariant([new REGEX(expression)], path, dbc);
+    }
     // #endregion Condition checking.
     // #region Referenced Condition checking.
     //
     // For usage in dynamic scenarios (like with AE-DBC).
     //
     /**
-     * Invokes the {@link EQ.checkAlgorithm } passing the value "toCheck" and {@link EQ.equivalent }.
+     * Invokes the {@link REGEX.checkAlgorithm } passing the value **toCheck** and {@link REGEX.equivalent }.
      *
-     * @param toCheck See {@link EQ.checkAlgorithm }.
+     * @param toCheck See {@link REGEX.checkAlgorithm }.
      *
      * @returns See {@link EQ.checkAlgorithm}. */
     check(toCheck) {
@@ -73,10 +85,10 @@ export class REGEX extends DBC {
     // #endregion Referenced Condition checking.
     // #region In-Method checking.
     /**
-     * Invokes the {@link JSON_OP.checkAlgorithm } passing the value "toCheck" and {@link JSON_OP.expression }.
+     * Invokes the {@link REGEX.checkAlgorithm } passing the value **toCheck** and {@link REGEX.expression }.
      *
-     * @param toCheck		See {@link JSON_OP.checkAlgorithm} }.
-     * @param expression	See {@link JSON_OP.checkAlgorithm} }.
+     * @param toCheck		See {@link REGEX.checkAlgorithm}.
+     * @param expression	See {@link REGEX.checkAlgorithm}.
      */
     static check(toCheck, expression) {
         const checkResult = REGEX.checkAlgorithm(toCheck, expression);

package/dist/DBC/TYPE.js

@@ -1,18 +1,18 @@
-import { DBC } from "../DBC.js";
+import { DBC } from "../DBC";
 /**
- * A {@link DBC } defining that the an {@link object }s gotta be of certain {@link TYPE.type }.
+ * A {@link DBC } defining that an {@link object }s gotta be of certain {@link TYPE.type }.
  *
  * @remarks
  * Author: 		Salvatore Callari (Callari@WaXCode.net) / 2025
  * Maintainer:	Salvatore Callari (XDBC@WaXCode.net) */
 export class TYPE extends DBC {
     /**
-     * Checks if the value "toCheck" is of the "type" specified.
+     * Checks if the value **toCheck** is of the **type** specified.
      *
-     * @param toCheck	The {@link Object } which'S "type" to check.
-     * @param type		The type the {@link object} "toCheck" has to be of.
+     * @param toCheck	The {@link Object } which's **type** to check.
+     * @param type		The type the {@link object} **toCheck** has to be of.
      *
-     * @returns TRUE if the value "toCheck" is of the specified "type", otherwise FALSE. */
+     * @returns TRUE if the value **toCheck** is of the specified **type**, otherwise FALSE. */
     // biome-ignore lint/suspicious/noExplicitAny: Necessary for dynamic type checking of also UNDEFINED.
     static checkAlgorithm(toCheck, type) {
         // biome-ignore lint/suspicious/useValidTypeof: Necessary
@@ -49,13 +49,25 @@ export class TYPE extends DBC {
             return TYPE.checkAlgorithm(value, type);
         }, dbc, path);
     }
+    /**
+     * A field-decorator factory using the {@link TYPE.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+     * by the tagged field.
+     *
+     * @param type	See {@link TYPE.checkAlgorithm }.
+     * @param path	See {@link DBC.decInvariant }.
+     * @param dbc	See {@link DBC.decInvariant }.
+     *
+     * @returns See {@link DBC.decInvariant }. */
+    static INVARIANT(type, path = undefined, dbc = "WaXCode.DBC") {
+        return DBC.decInvariant([new TYPE(type)], path, dbc);
+    }
     // #endregion Condition checking.
     // #region Referenced Condition checking.
     //
     // For usage in dynamic scenarios (like with AE-DBC).
     //
     /**
-     * Invokes the {@link TYPE.checkAlgorithm } passing the value "toCheck" and the {@link TYPE.type } .
+     * Invokes the {@link TYPE.checkAlgorithm } passing the value **toCheck** and the {@link TYPE.type } .
      *
      * @param toCheck See {@link TYPE.checkAlgorithm }.
      *

package/dist/DBC.js

@@ -1,5 +1,5 @@
 /**
- * Provides a [D]esign [B]y [C]ontract Framework using decorators.
+ * Provides a **D**esign **B**y **C**ontract Framework using decorators.
  *
  * @remarks
  * Maintainer: Callari, Salvatore (XDBC@WaXCode.net) */
@@ -54,7 +54,8 @@ export class DBC {
         return undefined;
     }
     /**
-     * A method-decorator factory checking the {@link paramValueRequests } for value-requests of the method's parameter.
+     * A method-decorator factory checking the {@link paramValueRequests } for value-requests of the method's parameter thus
+     * also usable on setters.
      * When found it will invoke the "receptor" registered there, inter alia by {@link requestParamValue }, with the
      * parameter's value.
      *
@@ -87,7 +88,7 @@ export class DBC {
             }
             // #endregion 	Check if a value of one of the method's parameter has been requested and pass it to the
             // 				receptor, if so.
-            // biome-ignore lint/complexity/noThisInStatic: <explanation>
+            // biome-ignore lint/complexity/noThisInStatic: Necessary.
             return originalMethod.apply(this, args);
         };
         return descriptor;
@@ -95,47 +96,60 @@ export class DBC {
     // #endregion Parameter-value requests.
     // #region Invariant
     /**
+     * A property-decorator factory serving as a **D**esign **B**y **C**ontract Invariant.
+     * Since the value must be initialized or set according to the specified **contracts** the value will only be checked
+     * when assigning it.
      *
-     * @param toCheck
-     * @returns
-     */
-    check(toCheck) {
-        return false;
-    }
-    /**
+     * @param contracts The {@link DBC }-Contracts the value shall uphold.
      *
-     * @param conditions
-     * @param property
-     * @returns
-     */
-    static decInvariant(conditions, property) {
-        return (toCheck) => {
-            for (const condition of conditions) {
-                condition.check(new toCheck(...[])[property]);
-            }
+     * @throws 	A {@link DBC.Infringement } whenever the property is tried to be set to a value that does not comply to the
+     * 			specified **contracts**, by the returned method.*/
+    static decInvariant(contracts, path = undefined, dbc = "WaXCode.DBC") {
+        return (target, propertyKey) => {
+            // biome-ignore lint/suspicious/noExplicitAny: Necessary to intercept UNDEFINED and NULL.
+            let value;
+            // #region Replace original property.
+            Object.defineProperty(target, propertyKey, {
+                set(newValue) {
+                    const realValue = path ? DBC.resolve(newValue, path) : newValue;
+                    // #region Check if all "contracts" are fulfilled.
+                    for (const contract of contracts) {
+                        const result = contract.check(realValue);
+                        if (typeof result === "string") {
+                            DBC.resolveDBCPath(window, dbc).reportFieldInfringement(result, target, path, propertyKey, realValue);
+                        }
+                    }
+                    // #endregion Check if all "contracts" are fulfilled.
+                    value = newValue;
+                },
+                enumerable: true,
+                configurable: true,
+            });
+            // #endregion Replace original property.
         };
     }
     // #endregion Invariant
     // #region Postcondition
     /**
+     * A method decorator factory checking the result of a method whenever it is invoked thus also usable on getters.
      *
-     * @param check
-     * @param dbc
-     * @param path
-     * @returns
+     * @param check	The **(toCheck: any, object, string) => boolean | string** to use for checking.
+     * @param dbc	See {@link DBC.resolveDBCPath }.
+     * @param path	The dotted path referring to the actual value to check, starting form the specified one.
+     *
+     * @returns The **( target : object, propertyKey : string, descriptor : PropertyDescriptor ) : PropertyDescriptor**
+     * 			invoked by Typescript.
      */
     static decPostcondition(
-    // biome-ignore lint/suspicious/noExplicitAny: Gotta be any since parameter-values may be undefined.
+    // biome-ignore lint/suspicious/noExplicitAny: Necessary to intercept UNDEFINED and NULL.
     check, dbc, path = undefined) {
         return (target, propertyKey, descriptor) => {
             const originalMethod = descriptor.value;
-            // biome-ignore lint/suspicious/noExplicitAny: Gotta be any since parameter-values may be undefined.
+            // biome-ignore lint/suspicious/noExplicitAny: Necessary to intercept UNDEFINED and NULL.
             descriptor.value = (...args) => {
                 // biome-ignore lint/complexity/noThisInStatic: <explanation>
                 const result = originalMethod.apply(this, args);
-                const realValue = path
-                    ? path === null || path === void 0 ? void 0 : path.split(".").reduce((accumulator, current) => accumulator[current], result)
-                    : result;
+                const realValue = path ? DBC.resolve(result, path) : result;
                 const checkResult = check(realValue, target, propertyKey);
                 if (typeof checkResult === "string") {
                     DBC.resolveDBCPath(window, dbc).reportReturnvalueInfringement(checkResult, target, path, propertyKey, realValue);
@@ -147,23 +161,21 @@ export class DBC {
     }
     // #endregion Postcondition
     // #region Decorator
-    // #region Parameter
+    // #region Precondition
     /**
      * A parameter-decorator factory that requests the tagged parameter's value passing it to the provided
      * "check"-method when the value becomes available.
      *
      * @param check	The "( unknown ) => void" to be invoked along with the tagged parameter's value as soon
      * 				as it becomes available.
-     * @param path	The dotted path referring to the actual value to check, starting form the specified one.
      * @param dbc  	See {@link DBC.resolveDBCPath }.
+     * @param path	The dotted path referring to the actual value to check, starting form the specified one.
      *
-     * @returns The  { (target: object, methodName: string | symbol, parameterIndex: number ) => void } invoked by Typescript- */
+     * @returns The **(target: object, methodName: string | symbol, parameterIndex: number ) => void** invoked by Typescript- */
     static decPrecondition(check, dbc, path = undefined) {
         return (target, methodName, parameterIndex) => {
             DBC.requestParamValue(target, methodName, parameterIndex, (value) => {
-                const realValue = path
-                    ? path === null || path === void 0 ? void 0 : path.split(".").reduce((accumulator, current) => accumulator[current], value)
-                    : value;
+                const realValue = path ? DBC.resolve(value, path) : value;
                 const result = check(realValue, target, methodName, parameterIndex);
                 if (typeof result === "string") {
                     DBC.resolveDBCPath(window, dbc).reportParameterInfringement(result, target, path, methodName, parameterIndex, realValue);
@@ -196,7 +208,7 @@ export class DBC {
         }
     }
     /**
-     * Reports a parameter-infringement according via {@link reportInfringement } also generating a proper {@link string }-wrapper
+     * Reports a parameter-infringement via {@link reportInfringement } also generating a proper {@link string }-wrapper
      * for the given "message","method", parameter-"index" & value.
      *
      * @param message	The {@link string } describing the infringement and it's provenience.
@@ -207,6 +219,18 @@ export class DBC {
         const properIndex = index + 1;
         this.reportInfringement(`[ Parameter-value "${value}" of the ${properIndex}${properIndex === 1 ? "st" : properIndex === 2 ? "nd" : properIndex === 3 ? "rd" : "th"} parameter did not fulfill one of it's contracts: ${message}]`, method, target, path);
     }
+    /**
+     * Reports a field-infringement via {@link reportInfringement } also generating a proper {@link string }-wrapper
+     * for the given **message** & **name**.
+     *
+     * @param message	A {@link string } describing the infringement and it's provenience.
+     * @param key 		The property key.
+     * @param path		The dotted-path {@link string } that leads to the value not fulfilling the contract starting from
+     * 					the tagged one.
+     * @param value		The value not fulfilling a contract. */
+    reportFieldInfringement(message, target, path, key, value) {
+        this.reportInfringement(`[ New value for "${key}"${path === undefined ? "" : `.${path}`} with value "${value}" did not fulfill one of it's contracts: ${message}]`, key, target, path);
+    }
     /**
      * Reports a returnvalue-infringement according via {@link reportInfringement } also generating a proper {@link string }-wrapper
      * for the given "message","method" & value.
@@ -220,18 +244,19 @@ export class DBC {
         this.reportInfringement(`[ Return-value "${value}" did not fulfill one of it's contracts: ${message}]`, method, target, path);
     }
     /**
+     * Constructs this {@link DBC } by setting the {@link DBC.infringementSettings }, define the **WaXCode** namespace in
+     * **window** if not yet available and setting the property **DBC** in there to the instance of this {@link DBC }.
      *
-     * @param infringementSettings
-     */
+     * @param infringementSettings See {@link DBC.infringementSettings }. */
     constructor(infringementSettings = { throwException: true, logToConsole: false }) {
-        // #endregion Parameter
+        // #endregion Precondition
         // #endregion Decorator
         // #region Warning handling.
         /** Stores settings concerning warnings. */
         this.warningSettings = { logToConsole: true };
         // #endregion Warning handling.
         // #region infringement handling.
-        /** Stores the setting concerning infringements */
+        /** Stores the settings concerning infringements */
         this.infringementSettings = { throwException: true, logToConsole: false };
         this.infringementSettings = infringementSettings;
         // biome-ignore lint/suspicious/noExplicitAny: <explanation>
@@ -240,6 +265,45 @@ export class DBC {
         // biome-ignore lint/suspicious/noExplicitAny: <explanation>
         window.WaXCode.DBC = this;
     }
+    /**
+     * Resolves the desired {@link object } out a given one **toResolveFrom** using the specified **path**.
+     *
+     * @param toResolveFrom The {@link object } starting to resolve from.
+     * @param path			The dotted path-{@link string }.
+     * 						This string uses ., [...], and () to represent accessing nested properties,
+     * 						array elements/object keys, and calling methods, respectively, mimicking JavaScript syntax to navigate
+     * 						an object's structure. Code, e.g. something like a.b( 1 as number ).c, will not be executed and
+     * 						thus make the retrieval fail.
+     *
+     * @returns The requested {@link object }, NULL or UNDEFINED. */
+    static resolve(toResolveFrom, path) {
+        if (!toResolveFrom || typeof path !== "string") {
+            return undefined;
+        }
+        const parts = path.replace(/\[(['"]?)(.*?)\1\]/g, ".$2").split("."); // Handle indexers
+        let current = toResolveFrom;
+        for (const part of parts) {
+            if (current === null || typeof current === "undefined") {
+                return undefined;
+            }
+            const methodMatch = part.match(/(\w+)\((.*)\)/);
+            if (methodMatch) {
+                const methodName = methodMatch[1];
+                const argsStr = methodMatch[2];
+                const args = argsStr.split(",").map((arg) => arg.trim()); // Simple argument parsing
+                if (typeof current[methodName] === "function") {
+                    current = current[methodName].apply(current, args);
+                }
+                else {
+                    return undefined; // Method not found or not a function
+                }
+            }
+            else {
+                current = current[part];
+            }
+        }
+        return current;
+    }
 }
 // #region Parameter-value requests.
 /** Stores all request for parameter values registered by {@link decPrecondition }. */
@@ -259,5 +323,14 @@ DBC.Infringement = class extends Error {
 // #endregion Errors
 // #endregion Classes
 // #endregion infringement handling.
+/**
+ * Resolves the specified dotted {@link string }-path to a {@link DBC }.
+ *
+ * @param obj 	The {@link object } to start resolving from.
+ * @param path 	The dotted {@link string }-path leading to the {@link DBC }.
+ *
+ * @returns The requested {@link DBC }.
+ */
 DBC.resolveDBCPath = (obj, path) => path === null || path === void 0 ? void 0 : path.split(".").reduce((accumulator, current) => accumulator[current], obj);
+// Set the main instance with standard **DBC.infringementSettings**.
 new DBC();