xdbc 1.0.95 → 1.0.97

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.0.95",
+	"version": "1.0.97",
 	"name": "xdbc",
 	"scripts": {
 		"docs": "typedoc",
@@ -25,7 +25,8 @@
 		"typescript": "^5.8.3",
 		"undici-types": "^7.8.0",
 		"webpack": "^5.99.8",
-		"webpack-cli": "^6.0.1"
+		"webpack-cli": "^6.0.1",
+		"webpack-dev-server": "^5.2.1"
 	},
 	"dependencies": {
 		"@types/reflect-metadata": "^0.1.0",
@@ -37,7 +38,11 @@
 		"type": "git",
 		"url": "git+https://github.com/CallariS/XDBC.git"
 	},
-	"keywords": ["DbC", "DesignByContract", "Typescript"],
+	"keywords": [
+		"DbC",
+		"DesignByContract",
+		"Typescript"
+	],
 	"author": "Callari, Salvatore",
 	"license": "MIT",
 	"bugs": {

package/src/DBC/COMPARISON.ts

@@ -20,7 +20,7 @@ export class COMPARISON extends DBC {
 		}
 
 		if (equalityPermitted && invert && toCheck > equivalent) {
-			return `Value must not to be less than or equal to "${equivalent}"`;
+			return `Value has to be less than or equal to "${equivalent}"`;
 		}
 
 		if (!equalityPermitted && !invert && toCheck <= equivalent) {
@@ -28,7 +28,7 @@ export class COMPARISON extends DBC {
 		}
 
 		if (!equalityPermitted && invert && toCheck >= equivalent) {
-			return `Value must not to be less than "${equivalent}"`;
+			return `Value has to be less than "${equivalent}"`;
 		}
 
 		return true;

package/src/DBC/EQ/DIFFERENT.ts

@@ -0,0 +1,35 @@
+import { EQ } from "../EQ";
+/** See {@link COMPARISON }. */
+export class DIFFERENT extends EQ {
+	/** See {@link COMPARISON.PRE }. */
+	public static override PRE(
+		equivalent,
+		invert = false,
+		path: string = undefined,
+		dbc = "WaXCode.DBC",
+	) {
+		return EQ.PRE(equivalent, true, path, dbc);
+	}
+	/** See {@link COMPARISON.POST }. */
+	public static override POST(
+		equivalent,
+		invert = false,
+		path: string = undefined,
+		dbc = "WaXCode.DBC",
+	) {
+		return EQ.POST(equivalent, true, path, dbc);
+	}
+	/** See {@link COMPARISON.INVARIANT }. */
+	public static INVARIANT(
+		equivalent,
+		invert = false,
+		path: string = undefined,
+		dbc = "WaXCode.DBC",
+	) {
+		return EQ.INVARIANT(equivalent, true, path, dbc);
+	}
+	/** See {@link COMPARISON.constructor }. */
+	constructor(public equivalent) {
+		super(equivalent, true);
+	}
+}

package/src/DBC/HasAttribute.ts

@@ -0,0 +1,140 @@
+import { DBC } from "../DBC";
+/**
+ * A {@link DBC } defining that a {@link HTMLElement } gotta have a certain attribute set.
+ *
+ * @remarks
+ * Maintainer: Callari, Salvatore (XDBC@WaXCode.net) */
+export class HasAttribute extends DBC {
+	// #region Condition checking.
+	/**
+	 * Checks if the {@link HTMLElement } **toCheck** has the attribute **toCheckFor**.
+	 *
+	 * @param toCheckFor  name of the attribute to check for whether it is set or not.
+	 *
+	 * @returns TRUE if the {@link HTMLElement } **toCheck** has set the attribute **toCheckFor**,
+	 * 			otherwise a proper errormessage. */
+	public static checkAlgorithm(
+		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+		toCheck: any,
+		toCheckFor: string,
+		invert,
+	): boolean | string {
+		if(!( toCheck instanceof HTMLElement )) {
+			return `The object to check for whether it has the attribute "${ toCheckFor }" is not a HTMLElement. It is of type "${ typeof toCheck }".`;
+		}
+
+		if (!invert && !( toCheck as HTMLElement ).hasAttribute( toCheckFor )) {
+			return `Required Attribute "${ toCheckFor }" is not set.`;
+		}
+
+		if (invert && ( toCheck as HTMLElement ).hasAttribute( toCheckFor )) {
+			return `Forbidden Attribute "${ toCheckFor }" is set.`;
+		}
+
+		return true;
+	}
+	/**
+	 * A parameter-decorator factory using the {@link HasAttribute.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged parameter.
+	 *
+	 * @param toCheckFor	See {@link HasAttribute.checkAlgorithm }.
+	 * @param path			See {@link DBC.decPrecondition }.
+	 * @param dbc			See {@link DBC.decPrecondition }.
+	 *
+	 * @returns See {@link DBC.decPrecondition }. */
+	public static PRE(
+		toCheckFor: string,
+		invert = false,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	): (
+		target: object,
+		methodName: string | symbol,
+		parameterIndex: number,
+	) => void {
+		return DBC.decPrecondition(
+			(
+				value: object,
+				target: object,
+				methodName: string,
+				parameterIndex: number,
+			) => {
+				return HasAttribute.checkAlgorithm(value, toCheckFor, invert);
+			},
+			dbc,
+			path,
+		);
+	}
+	/**
+	 * A method-decorator factory using the {@link HasAttribute.checkAlgorithm } to determine whether this {@link DBC } is
+	 * fulfilled by the tagged method's returnvalue.
+	 *
+	 * @param toCheckFor	See {@link HasAttribute.checkAlgorithm }.
+	 * @param path			See {@link DBC.Postcondition }.
+	 * @param dbc			See {@link DBC.decPostcondition }.
+	 *
+	 * @returns See {@link DBC.decPostcondition }. */
+	public static POST(
+		toCheckFor: string,
+		invert = false,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	): (
+		target: object,
+		propertyKey: string,
+		descriptor: PropertyDescriptor,
+	) => PropertyDescriptor {
+		return DBC.decPostcondition(
+			(value: object, target: object, propertyKey: string) => {
+				return HasAttribute.checkAlgorithm(value, toCheckFor, invert);
+			},
+			dbc,
+			path,
+		);
+	}
+	/**
+	 * A field-decorator factory using the {@link hasAttribute.checkAlgorithm } to determine whether this {@link DBC } is
+	 * fulfilled by the tagged field.
+	 *
+	 * @param toCheckFor	See {@link hasAttribute.checkAlgorithm }.
+	 * @param path			See {@link DBC.decInvariant }.
+	 * @param dbc			See {@link DBC.decInvariant }.
+	 *
+	 * @returns See {@link DBC.decInvariant }. */
+	public static INVARIANT(
+		toCheckFor: any,
+		invert = false,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	) {
+		return DBC.decInvariant([new HasAttribute(toCheckFor, invert)], path, dbc);
+	}
+	// #endregion Condition checking.
+	// #region Referenced Condition checking.
+	//
+	// For usage in dynamic scenarios (like with AE-DBC).
+	//
+	/**
+	 * Invokes the {@link hasAttribute.checkAlgorithm } passing the value **toCheck**, {@link hasAttribute.equivalent } and
+	 * {@link hasAttribute.invert }.
+	 *
+	 * @param toCheck See {@link EQ.checkAlgorithm }.
+	 *
+	 * @returns See {@link EQ.checkAlgorithm}. */
+	// biome-ignore lint/suspicious/noExplicitAny: Necessary to check against NULL & UNDEFINED.
+	public check(toCheck: any) {
+		return HasAttribute.checkAlgorithm(toCheck, this.toCheckFor, this.invert);
+	}
+	/**
+	 * Creates this {@link DBC } by setting the protected property {@link hasAttribute.equivalent } used by
+	 * {@link hasAttribute.check }.
+	 *
+	 * @param toCheckFor See {@link hasAttribute.check }. */
+	public constructor(
+		protected toCheckFor: string,
+		protected invert = false,
+	) {
+		super();
+	}
+	// #endregion Referenced Condition checking.
+}

package/src/DBC/IF.ts

@@ -0,0 +1,147 @@
+import { DBC } from "../DBC";
+/**
+ * A {@link DBC } defining that an {@link object } has also to comply to a certain {@link DBC } if it complies to
+ * another specified one.
+ *
+ * @remarks
+ * Maintainer: Callari, Salvatore (XDBC@WaXCode.net) */
+export class IF extends DBC {
+	// #region Condition checking.
+	/**
+	 * Checks if the value **toCheck** complies to the specified **condition** and if so does also comply to the one **inCase**.
+	 *
+	 * @param toCheck	The value that has to be equal to it's possible **equivalent** for this {@link DBC } to be fulfilled.
+	 * @param condition	The contract **toCheck** has to comply to in order to also have to comply to the one **inCase**.
+	 * @param inCase	The contract **toCheck** has to also comply to if it complies to **condition**.
+	 *
+	 * @returns TRUE if the value **toCheck** and the **equivalent** are equal to each other, otherwise FALSE. */
+	public static checkAlgorithm(
+		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+		toCheck: any,
+		condition: {check: (toCheck: unknown | undefined | null | object) => boolean | string;},
+		inCase:{
+			check: (toCheck: unknown | undefined | null | object) => boolean | string;
+		},
+		invert,
+	): boolean | string {
+		if (!invert && condition.check(toCheck)&&!inCase.check(toCheck)) {
+			return `In case that the value complies to "${condition}" it also has to comply to "${inCase}"`;
+		}
+
+		if (!invert && !condition.check(toCheck)&&!inCase.check(toCheck)) {
+			return `In case that the value does not comply to "${condition}" it has to comply to "${inCase}"`;
+		}
+
+		return true;
+	}
+	/**
+	 * A parameter-decorator factory using the {@link EQ.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged parameter.
+	 *
+	 * @param condition	See {@link IF.checkAlgorithm }.
+	 * @param inCase	See {@link IF.checkAlgorithm }.
+	 * @param path		See {@link DBC.decPrecondition }.
+	 * @param dbc		See {@link DBC.decPrecondition }.
+	 *
+	 * @returns See {@link DBC.decPrecondition }. */
+	public static PRE(
+		condition: {check: (toCheck: unknown | undefined | null | object) => boolean | string;},
+		inCase: {check: (toCheck: unknown | undefined | null | object) => boolean | string;},
+		invert = false,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	): (
+		target: object,
+		methodName: string | symbol,
+		parameterIndex: number,
+	) => void {
+		return DBC.decPrecondition(
+			(
+				value: object,
+				target: object,
+				methodName: string,
+				parameterIndex: number,
+			) => {
+				return IF.checkAlgorithm(value, condition, inCase, invert);
+			},
+			dbc,
+			path,
+		);
+	}
+	/**
+	 * A method-decorator factory using the {@link IF.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged method's returnvalue.
+	 *
+	 * @param condition	See {@link IF.checkAlgorithm }.
+	 * @param inCase	See {@link IF.checkAlgorithm }.
+	 * @param path		See {@link DBC.Postcondition }.
+	 * @param dbc		See {@link DBC.decPostcondition }.
+	 *
+	 * @returns See {@link DBC.decPostcondition }. */
+	public static POST(
+		condition: {check: (toCheck: unknown | undefined | null | object) => boolean | string;},
+		inCase: {check: (toCheck: unknown | undefined | null | object) => boolean | string;},
+		invert = false,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	): (
+		target: object,
+		propertyKey: string,
+		descriptor: PropertyDescriptor,
+	) => PropertyDescriptor {
+		return DBC.decPostcondition(
+			(value: object, target: object, propertyKey: string) => {
+				return IF.checkAlgorithm(value, condition, inCase, invert);
+			},
+			dbc,
+			path,
+		);
+	}
+	/**
+	 * A field-decorator factory using the {@link IF.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged field.
+	 *
+	 * @param condition	See {@link IF.checkAlgorithm }.
+	 * @param inCase	See {@link IF.checkAlgorithm }.
+	 * @param path			See {@link DBC.decInvariant }.
+	 * @param dbc			See {@link DBC.decInvariant }.
+	 *
+	 * @returns See {@link DBC.decInvariant }. */
+	public static INVARIANT(
+		condition: {check: (toCheck: unknown | undefined | null | object) => boolean | string;},
+		inCase: {check: (toCheck: unknown | undefined | null | object) => boolean | string;},
+		invert = false,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	) {
+		return DBC.decInvariant([new IF(condition, inCase, invert)], path, dbc);
+	}
+	// #endregion Condition checking.
+	// #region Referenced Condition checking.
+	//
+	// For usage in dynamic scenarios (like with AE-DBC).
+	//
+	/**
+	 * Invokes the {@link IF.checkAlgorithm } passing the value **toCheck**, {@link IF.equivalent } and {@link IF.invert }.
+	 *
+	 * @param toCheck See {@link IF.checkAlgorithm }.
+	 *
+	 * @returns See {@link IF.checkAlgorithm}. */
+	// biome-ignore lint/suspicious/noExplicitAny: Necessary to check against NULL & UNDEFINED.
+	public check(toCheck: any) {
+		return IF.checkAlgorithm(toCheck, this.condition, this.inCase, this.invert);
+	}
+	/**
+	 * Creates this {@link IF } by setting the protected property {@link IF.equivalent } used by {@link IF.check }.
+	 *
+	 * @param equivalent See {@link IF.check }. */
+	public constructor(
+		// biome-ignore lint/suspicious/noExplicitAny: To be able to match UNDEFINED and NULL.
+		protected condition: {check: (toCheck: unknown | undefined | null | object) => boolean | string;},
+		protected inCase: {check: (toCheck: unknown | undefined | null | object) => boolean | string;},
+		protected invert = false,
+	) {
+		super();
+	}
+	// #endregion Referenced Condition checking.
+}

package/src/DBC.ts

@@ -141,11 +141,20 @@ export class DBC {
 		dbc = "WaXCode.DBC",
 	) {
 		return (target: unknown, propertyKey: string | symbol) => {
+			if (!DBC.resolveDBCPath(window, dbc).executionSettings.checkInvariants) {
+				return;
+			}
 			// biome-ignore lint/suspicious/noExplicitAny: Necessary to intercept UNDEFINED and NULL.
 			let value: any;
 			// #region Replace original property.
 			Object.defineProperty(target, propertyKey, {
 				set(newValue) {
+					if (
+						!DBC.resolveDBCPath(window, dbc).executionSettings.checkInvariants
+					) {
+						return;
+					}
+
 					const realValue = path ? DBC.resolve(newValue, path) : newValue;
 					// #region Check if all "contracts" are fulfilled.
 					for (const contract of contracts) {
@@ -196,6 +205,11 @@ export class DBC {
 			const originalMethod = descriptor.value;
 			// biome-ignore lint/suspicious/noExplicitAny: Necessary to intercept UNDEFINED and NULL.
 			descriptor.value = (...args: any[]) => {
+				if (
+					!DBC.resolveDBCPath(window, dbc).executionSettings.checkPostconditions
+				) {
+					return;
+				}
 				// biome-ignore lint/complexity/noThisInStatic: <explanation>
 				const result = originalMethod.apply(this, args);
 				const realValue = path ? DBC.resolve(result, path) : result;
@@ -249,6 +263,13 @@ export class DBC {
 				methodName,
 				parameterIndex,
 				(value: unknown) => {
+					if (
+						!DBC.resolveDBCPath(window, dbc).executionSettings
+							.checkPreconditions
+					) {
+						return;
+					}
+
 					const realValue = path ? DBC.resolve(value, path) : value;
 					const result = check(realValue, target, methodName, parameterIndex);
 
@@ -268,6 +289,18 @@ export class DBC {
 	}
 	// #endregion Precondition
 	// #endregion Decorator
+	// #region Execution Handling
+	/** Stores settings concerning the execution of checks. */
+	public executionSettings: {
+		checkPreconditions: boolean;
+		checkPostconditions: boolean;
+		checkInvariants: boolean;
+	} = {
+		checkPreconditions: true,
+		checkPostconditions: true,
+		checkInvariants: true,
+	};
+	// #endregion Execution Handling
 	// #region Warning handling.
 	/** Stores settings concerning warnings. */
 	public warningSettings: {
@@ -412,12 +445,22 @@ export class DBC {
 	 * 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 See {@link DBC.infringementSettings }. */
+	 * @param infringementSettings 	See {@link DBC.infringementSettings }.
+	 * @param executionSettings		See {@link DBC.executionSettings }. */
 	constructor(
 		infringementSettings: {
 			throwException: boolean;
 			logToConsole: boolean;
 		} = { throwException: true, logToConsole: false },
+		executionSettings: {
+			checkPreconditions: boolean;
+			checkPostconditions: boolean;
+			checkInvariants: boolean;
+		} = {
+			checkPreconditions: true,
+			checkPostconditions: true,
+			checkInvariants: true,
+		},
 	) {
 		this.infringementSettings = infringementSettings;