xdbc 1.0.73

package/src/DBC/JSON.Parse.ts

@@ -0,0 +1,138 @@
+import { DBC } from "../DBC";
+/**
+ * A {@link DBC } demanding that a {@link string } is {@link JSON.parse}able.
+ *
+ * @remarks
+ * Maintainer: Callari, Salvatore (XDBC@WaXCode.net) */
+export class JSON_Parse extends DBC {
+	// #region Condition checking.
+	/**
+	 * Tries to {@link JSON.parse } the {@link string } "toCheck" invoking the "receptor" with the result, if so.
+	 *
+	 * @param toCheck	The {@link string } to be {@link JSON.parse }d.
+	 * @param receptor	The ( json : object ) => void to receive the {@link JSON.parse }d {@link string } "toCheck".
+	 * 								check needs to have.
+	 *
+	 * @returns TRUE if the value "toCheck" is a valid JSON, otherwise a {@link string } to report the infringement. */
+	public static checkAlgorithm(
+		toCheck: string,
+		receptor: (json: object) => void,
+	): boolean | string {
+		// biome-ignore lint/suspicious/noExplicitAny: JSON.parse returns any.
+		let parsed: any;
+
+		try {
+			parsed = JSON.parse(toCheck);
+		} catch (X: unknown) {
+			return `[ Following string is not a valid JSON: ${toCheck}]`;
+		}
+
+		if (receptor) {
+			receptor(parsed);
+		}
+
+		return true;
+	}
+	/**
+	 * A parameter-decorator factory using the {@link JSON_Parse.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged parameter.
+	 *
+	 * @param receptor	See {@link JSON.checkAlgorithm }.
+	 * @param path			See {@link DBC.decPrecondition }.
+	 * @param dbc			See {@link DBC.decPrecondition }.
+	 *
+	 * @returns See {@link DBC.decPrecondition }. */
+	public static PRE(
+		receptor: (json: object) => void,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	): (
+		target: object,
+		methodName: string | symbol,
+		parameterIndex: number,
+	) => void {
+		return DBC.decPrecondition(
+			(
+				value: string,
+				target: object,
+				methodName: string,
+				parameterIndex: number,
+			) => {
+				return JSON_Parse.checkAlgorithm(value, receptor);
+			},
+			dbc,
+			path,
+		);
+	}
+	/**
+	 * A method-decorator factory using the {@link JSON_Parse.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged method's returnvalue.
+	 *
+	 * @param expression	See {@link JSON.checkAlgorithm }.
+	 * @param path			See {@link DBC.Postcondition }.
+	 * @param dbc			See {@link DBC.decPostcondition }.
+	 *
+	 * @returns See {@link DBC.decPostcondition }. */
+	public static POST(
+		receptor: (json: object) => void,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	): (
+		target: object,
+		propertyKey: string,
+		descriptor: PropertyDescriptor,
+	) => PropertyDescriptor {
+		return DBC.decPostcondition(
+			// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+			(value: any, target: object, propertyKey: string) => {
+				return JSON_Parse.checkAlgorithm(value, receptor);
+			},
+			dbc,
+			path,
+		);
+	}
+	// #endregion Condition checking.
+	// #region Referenced Condition checking.
+	//
+	// For usage in dynamic scenarios (like with AE-DBC).
+	//
+	/**
+	 * Invokes the {@link JSON_Parse.checkAlgorithm } passing the value "toCheck" and {@link JSON_Parse.receptor }.
+	 *
+	 * @param toCheck See {@link JSON_Parse.checkAlgorithm }.
+	 *
+	 * @returns See {@link JSON_Parse.checkAlgorithm}. */
+	// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+	public check(toCheck: any) {
+		return JSON_Parse.checkAlgorithm(toCheck, this.receptor);
+	}
+	/**
+	 * Creates this {@link JSON_Parse } by setting the protected property {@link JSON_Parse.necessaryProperties } and {@link checkElements } used by {@link JSON_Parse.check }.
+	 *
+	 * @param necessaryProperties	See {@link JSON_Parse.check }.
+	 * @param checkElements 		See {@link JSON_Parse.check }. */
+	public constructor(public receptor: (json: object) => void) {
+		super();
+	}
+	// #endregion Referenced Condition checking.
+	// #region In-Method checking.
+	/**
+	 * Invokes the {@link JSON_Parse.checkAlgorithm } passing the value "toCheck", {@link JSON_Parse.necessaryProperties } and {@link JSON_Parse.checkElements }.
+	 *
+	 * @param toCheck				See {@link JSON_Parse.checkAlgorithm} }.
+	 * @param necessaryProperties	See {@link JSON_Parse.checkAlgorithm} }.
+	 * @param checkElements			See {@link JSON_Parse.checkAlgorithm} }.
+	 */
+	public static check(
+		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+		toCheck: any,
+		receptor: (json: object) => void,
+	) {
+		const checkResult = JSON_Parse.checkAlgorithm(toCheck, receptor);
+
+		if (typeof checkResult === "string") {
+			throw new DBC.Infringement(checkResult);
+		}
+	}
+	// #endregion In-Method checking.
+}

package/src/DBC/REGEX.ts

@@ -0,0 +1,139 @@
+import { DBC } from "../DBC.js";
+/**
+ * A {@link DBC } providing {@link REGEX }-contracts and standard {@link RegExp } for common use cases in {@link REGEX.stdExp }.
+ *
+ * @remarks
+ * Maintainer: Callari, Salvatore (XDBC@WaXCode.net) */
+export class REGEX extends DBC {
+	/** Stores often used {@link RegExp }s. */
+	public static stdExp = {
+		property: /^[$_A-Za-z][$_A-Za-z0-9]*$/,
+		url: /^(?:(?:https?|ftp):\/\/)(?:\S+(?::\S*)?@)?(?:(?!(?:10|127)(?:\.\d{1,3}){3})(?!(?:169\.254|192\.168)(?:\.\d{1,3}){2})(?!172\.(?:1[6-9]|2\d|3[0-1])(?:\.\d{1,3}){2})(?:[1-9]\d?|1\d\d|2[01]\d|22[0-3])(?:\.(?:1?\d{1,2}|2[0-4]\d|25[0-5])){2}(?:\.(?:[1-9]\d?|1\d\d|2[0-4]\d|25[0-4]))|(?:(?:[a-z\u00a1-\uffff0-9]-*)*[a-z\u00a1-\uffff0-9]+)(?:\.(?:[a-z\u00a1-\uffff0-9]-*)*[a-z\u00a1-\uffff0-9]+)*(?:\.(?:[a-z\u00a1-\uffff]{2,}))\.?)(?::\d{2,5})?(?:[/?#]\S*)?$/i,
+		keyPath: /^([a-zA-Z_$][a-zA-Z0-9_$]*\.)*[a-zA-Z_$][a-zA-Z0-9_$]*$/,
+		date: /^\d{1,4}[.\/-]\d{1,2}[.\/-]\d{1,4}$/i,
+		dateFormat:
+			/^((D{1,2}[./-]M{1,2}[./-]Y{1,4})|(M{1,2}[./-]D{1,2}[./-]Y{1,4})|Y{1,4}[./-]D{1,2}[./-]M{1,2}|(Y{1,4}[./-]M{1,2}[./-]D{1,2}))$/i,
+		cssSelector:
+			/^(?:\*|#[\w-]+|\.[\w-]+|(?:[\w-]+|\*)(?::(?:[\w-]+(?:\([\w-]+\))?)+)?(?:\[(?:[\w-]+(?:(?:=|~=|\|=|\*=|\$=|\^=)\s*(?:"[^"]*"|'[^']*'|[\w-]+)\s*)?)?\])+|\[\s*[\w-]+\s*=\s*(?:"[^"]*"|'[^']*'|[\w-]+)\s*\])(?:,\s*(?:\*|#[\w-]+|\.[\w-]+|(?:[\w-]+|\*)(?::(?:[\w-]+(?:\([\w-]+\))?)+)?(?:\[(?:[\w-]+(?:(?:=|~=|\|=|\*=|\$=|\^=)\s*(?:"[^"]*"|'[^']*'|[\w-]+)\s*)?)?\])+|\[\s*[\w-]+\s*=\s*(?:"[^"]*"|'[^']*'|[\w-]+)\s*\]))*$/,
+	};
+	// #region Condition checking.
+	/**
+	 * 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
+	 * 						fulfilled.
+	 *
+	 * @returns TRUE if the value "toCheck" complies with the {@link RegExp } "expression", otherwise FALSE. */
+	public static checkAlgorithm(
+		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+		toCheck: any,
+		expression: RegExp,
+	): boolean | string {
+		if (!expression.test(toCheck as string)) {
+			return `Value has to comply to regular expression "${expression}"`;
+		}
+
+		return true;
+	}
+	/**
+	 * A parameter-decorator factory using the {@link REGEX.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged parameter.
+	 *
+	 * @param expression	See {@link REGEX.checkAlgorithm }.
+	 * @param path			See {@link DBC.decPrecondition }.
+	 * @param dbc			See {@link DBC.decPrecondition }.
+	 *
+	 * @returns See {@link DBC.decPrecondition }. */
+	public static PRE(
+		expression: RegExp,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	): (
+		target: object,
+		methodName: string | symbol,
+		parameterIndex: number,
+	) => void {
+		return DBC.decPrecondition(
+			(
+				value: string,
+				target: object,
+				methodName: string,
+				parameterIndex: number,
+			) => {
+				return REGEX.checkAlgorithm(value, expression);
+			},
+			dbc,
+			path,
+		);
+	}
+	/**
+	 * A method-decorator factory using the {@link REGEX.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged method's returnvalue.
+	 *
+	 * @param expression	See {@link REGEX.checkAlgorithm }.
+	 * @param path			See {@link DBC.Postcondition }.
+	 * @param dbc			See {@link DBC.decPostcondition }.
+	 *
+	 * @returns See {@link DBC.decPostcondition }. */
+	public static POST(
+		expression: RegExp,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	): (
+		target: object,
+		propertyKey: string,
+		descriptor: PropertyDescriptor,
+	) => PropertyDescriptor {
+		return DBC.decPostcondition(
+			// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+			(value: any, target: object, propertyKey: string) => {
+				return REGEX.checkAlgorithm(value, expression);
+			},
+			dbc,
+			path,
+		);
+	}
+	// #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 }.
+	 *
+	 * @param toCheck See {@link EQ.checkAlgorithm }.
+	 *
+	 * @returns See {@link EQ.checkAlgorithm}. */
+	// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+	public check(toCheck: any) {
+		return REGEX.checkAlgorithm(toCheck, this.expression);
+	}
+	/**
+	 * Creates this {@link REGEX } by setting the protected property {@link REGEX.expression } used by {@link REGEX.check }.
+	 *
+	 * @param expression See {@link REGEX.check }. */
+	public constructor(protected expression: RegExp) {
+		super();
+	}
+	// #endregion Referenced Condition checking.
+	// #region In-Method checking.
+	/**
+	 * Invokes the {@link JSON_OP.checkAlgorithm } passing the value "toCheck" and {@link JSON_OP.expression }.
+	 *
+	 * @param toCheck		See {@link JSON_OP.checkAlgorithm} }.
+	 * @param expression	See {@link JSON_OP.checkAlgorithm} }.
+	 */
+	public static check(
+		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+		toCheck: any,
+		expression: RegExp,
+	) {
+		const checkResult = REGEX.checkAlgorithm(toCheck, expression);
+
+		if (typeof checkResult === "string") {
+			throw new DBC.Infringement(checkResult);
+		}
+	}
+	// #endregion In-Method checking.
+}

package/src/DBC/TYPE.ts

@@ -0,0 +1,104 @@
+import { DBC } from "../DBC.js";
+/**
+ * A {@link DBC } defining that the 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.
+	 *
+	 * @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. */
+	// biome-ignore lint/suspicious/noExplicitAny: Necessary for dynamic type checking of also UNDEFINED.
+	public static checkAlgorithm(toCheck: any, type: string): boolean | string {
+		// biome-ignore lint/suspicious/useValidTypeof: Necessary
+		if (typeof toCheck !== type) {
+			return `Value has to to be of type "${type}" but is of type "${typeof toCheck}"`;
+		}
+
+		return true;
+	}
+	/**
+	 * A parameter-decorator factory using the {@link TYPE.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged parameter.
+	 *
+	 * @param type	See {@link TYPE.checkAlgorithm }.
+	 * @param path	See {@link DBC.decPrecondition }.
+	 * @param dbc	See {@link DBC.decPrecondition }.
+	 *
+	 * @returns See {@link DBC.decPrecondition }. */
+	public static PRE(
+		type: string,
+		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 TYPE.checkAlgorithm(value, type);
+			},
+			dbc,
+			path,
+		);
+	}
+	/**
+	 * A method-decorator factory using the {@link TYPE.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged method's returnvalue.
+	 *
+	 * @param type	See {@link TYPE.checkAlgorithm }.
+	 * @param path	See {@link DBC.Postcondition }.
+	 * @param dbc	See {@link DBC.decPostcondition }.
+	 *
+	 * @returns See {@link DBC.decPostcondition }. */
+	public static POST(
+		type: string,
+		path: string | undefined = undefined,
+		dbc = "WaXCode.DBC",
+	): (
+		target: object,
+		propertyKey: string,
+		descriptor: PropertyDescriptor,
+	) => PropertyDescriptor {
+		return DBC.decPostcondition(
+			(value: object, target: object, propertyKey: string) => {
+				return TYPE.checkAlgorithm(value, type);
+			},
+			dbc,
+			path,
+		);
+	}
+	// #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 } .
+	 *
+	 * @param toCheck See {@link TYPE.checkAlgorithm }.
+	 *
+	 * @returns See {@link TYPE.checkAlgorithm}. */
+	// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+	public check(toCheck: any) {
+		return TYPE.checkAlgorithm(toCheck, this.type);
+	}
+	/**
+	 * Creates this {@link TYPE } by setting the protected property {@link TYPE.type } used by {@link TYPE.check }.
+	 *
+	 * @param type See {@link TYPE.check }. */
+	public constructor(protected type: string) {
+		super();
+	}
+}