xdbc 1.0.96 → 1.0.98

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.0.96",
+	"version": "1.0.98",
 	"name": "xdbc",
 	"scripts": {
 		"docs": "typedoc",

package/src/DBC/HasAttribute.ts

@@ -109,6 +109,23 @@ export class HasAttribute extends DBC {
 	) {
 		return DBC.decInvariant([new HasAttribute(toCheckFor, invert)], path, dbc);
 	}
+	/**
+	 * A field-decorator factory using the {@link hasAttribute.checkAlgorithm } to determine whether this {@link DBC } is
+	 * fulfilled by the tagged field's class instance.
+	 *
+	 * @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 cINVARIANT(
+		toCheckFor: any,
+		invert = false,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	) {
+		return DBC.decClassInvariant([new HasAttribute(toCheckFor, invert)], path, dbc);
+	}
 	// #endregion Condition checking.
 	// #region 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

@@ -123,6 +123,89 @@ export class DBC {
 		return descriptor;
 	}
 	// #endregion Parameter-value requests.
+	// #region Class
+	/**
+	 * A property-decorator factory serving as a **D**esign **B**y **C**ontract Invariant.
+	 * This invariant aims to check the instance of the class not the value to be get or set.
+	 *
+	 * @param contracts The {@link DBC }-Contracts the value shall uphold.
+	 *
+	 * @throws 	A {@link DBC.Infringement } whenever the property is tried to be get or set without the instance of it's class
+	 * 			fulfilling the specified **contracts**. */
+	public static decClassInvariant(
+		contracts: Array<{
+			check: (toCheck: unknown | null | undefined) => boolean | string;
+		}>,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	) {
+		return (target: unknown, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+			if (!DBC.resolveDBCPath(window, dbc).executionSettings.checkInvariants) {
+				return;
+			}
+			const originalSetter = descriptor.set;
+    		const originalGetter = descriptor.get;
+			// biome-ignore lint/suspicious/noExplicitAny: Necessary to intercept UNDEFINED and NULL.
+			let value: any;
+			// #region Replace original property.
+			Object.defineProperty(target, propertyKey, {
+				get() {
+					if (
+						!DBC.resolveDBCPath(window, dbc).executionSettings.checkInvariants
+					) {
+						return;
+					}
+
+					const realValue = path ? DBC.resolve(this, path) : this;
+					// #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 as object,
+								path,
+								propertyKey as string,
+								realValue,
+							);
+						}
+					}
+					// #endregion Check if all "contracts" are fulfilled.
+					return originalGetter[ propertyKey ];
+				},
+				set(newValue) {
+					if (
+						!DBC.resolveDBCPath(window, dbc).executionSettings.checkInvariants
+					) {
+						return;
+					}
+
+					const realValue = path ? DBC.resolve(this, path) : this;
+					// #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 as object,
+								path,
+								propertyKey as string,
+								realValue,
+							);
+						}
+					}
+					// #endregion Check if all "contracts" are fulfilled.
+					value = newValue;
+				},
+				enumerable: true,
+				configurable: true,
+			});
+			// #endregion Replace original property.
+		};
+	}
+	// #endregion Class
 	// #region Invariant
 	/**
 	 * A property-decorator factory serving as a **D**esign **B**y **C**ontract Invariant.