xdbc 1.0.73

package/src/DBC.ts

@@ -0,0 +1,355 @@
+/**
+ * Provides a [D]esign [B]y [C]ontract Framework using decorators.
+ *
+ * @remarks
+ * Maintainer: Callari, Salvatore (XDBC@WaXCode.net) */
+export class DBC {
+	// #region Parameter-value requests.
+	/** Stores all request for parameter values registered by {@link decPrecondition }. */
+	static paramValueRequests: Map<
+		object,
+		// biome-ignore lint/suspicious/noExplicitAny: Gotta be any since parameter-values may be undefined.
+		Map<string | symbol, Map<number, Array<(value: any) => undefined>>>
+	> = new Map<
+		object,
+		// biome-ignore lint/suspicious/noExplicitAny: Gotta be any since parameter-values may be undefined.
+		Map<string | symbol, Map<number, Array<(value: any) => undefined>>>
+	>();
+	/**
+	 * Make a request to get the value of a certain parameter of specific method in a specific {@link object }.
+	 * That request gets enlisted in {@link paramValueRequests } which is used by {@link ParamvalueProvider} to invoke the
+	 * given "receptor" with the parameter value stored in there. Thus a parameter decorator using this method will
+	 * not receive any value of the top method is not tagged with {@link ParamvalueProvider}.
+	 *
+	 * @param target		The {@link object } containing the method with the parameter which's value is requested.
+	 * @param methodName	The name of the method with the parameter which's value is requested.
+	 * @param index			The index of the parameter which's value is requested.
+	 * @param receptor		The method the requested parameter-value shall be passed to when it becomes available. */
+	protected static requestParamValue(
+		target: object,
+		methodName: string | symbol,
+		index: number,
+		// biome-ignore lint/suspicious/noExplicitAny: Gotta be any since parameter-values may be undefined.
+		receptor: (value: any) => undefined,
+	): undefined {
+		if (DBC.paramValueRequests.has(target)) {
+			if (DBC.paramValueRequests.get(target).has(methodName)) {
+				if (DBC.paramValueRequests.get(target).get(methodName).has(index)) {
+					DBC.paramValueRequests
+						.get(target)
+						.get(methodName)
+						.get(index)
+						.push(receptor);
+				} else {
+					DBC.paramValueRequests
+						.get(target)
+						.get(methodName)
+						.set(index, new Array<(value: unknown) => undefined>(receptor));
+				}
+			} else {
+				DBC.paramValueRequests
+					.get(target)
+					.set(
+						methodName,
+						new Map<number, Array<(value: unknown) => undefined>>([
+							[index, new Array<(value: unknown) => undefined>(receptor)],
+						]),
+					);
+			}
+		} else {
+			DBC.paramValueRequests.set(
+				target,
+				new Map<
+					string | symbol,
+					Map<number, Array<(value: unknown) => undefined>>
+				>([
+					[
+						methodName,
+						new Map<number, Array<(value: unknown) => undefined>>([
+							[index, new Array<(value: unknown) => undefined>(receptor)],
+						]),
+					],
+				]),
+			);
+		}
+
+		return undefined;
+	}
+	/**
+	 * A method-decorator factory checking the {@link paramValueRequests } for value-requests of the method's parameter.
+	 * When found it will invoke the "receptor" registered there, inter alia by {@link requestParamValue }, with the
+	 * parameter's value.
+	 *
+	 * @param target 		The {@link object } hosting the tagged method as provided by the runtime.
+	 * @param propertyKey 	The tagged method's name as provided by the runtime.
+	 * @param descriptor 	The {@link PropertyDescriptor } as provided by the runtime.
+	 *
+	 * @returns The {@link PropertyDescriptor } that was passed by the runtime. */
+	public static ParamvalueProvider(
+		target: object,
+		propertyKey: string,
+		descriptor: PropertyDescriptor,
+	): PropertyDescriptor {
+		const originalMethod = descriptor.value;
+		// biome-ignore lint/suspicious/noExplicitAny: Gotta be any since parameter-values may be undefined.
+		descriptor.value = (...args: any[]) => {
+			// #region	Check if a value of one of the method's parameter has been requested and pass it to the
+			//			receptor, if so.
+			if (
+				DBC.paramValueRequests.has(target) &&
+				DBC.paramValueRequests.get(target).has(propertyKey)
+			) {
+				for (const index of DBC.paramValueRequests
+					.get(target)
+					.get(propertyKey)
+					.keys()) {
+					if (index < args.length) {
+						for (const receptor of DBC.paramValueRequests
+							.get(target)
+							.get(propertyKey)
+							.get(index)) {
+							receptor(args[index]);
+						}
+					}
+				}
+			}
+			// #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>
+			return originalMethod.apply(this, args);
+		};
+
+		return descriptor;
+	}
+	// #endregion Parameter-value requests.
+	// #region Postcondition
+	/**
+	 *
+	 * @param check
+	 * @param dbc
+	 * @param path
+	 * @returns
+	 */
+	public static decPostcondition(
+		// biome-ignore lint/suspicious/noExplicitAny: Gotta be any since parameter-values may be undefined.
+		check: (toCheck: any, object, string) => boolean | string,
+		dbc: string,
+		path: string | undefined = undefined,
+	) {
+		return (
+			target: object,
+			propertyKey: string,
+			descriptor: PropertyDescriptor,
+		): PropertyDescriptor => {
+			const originalMethod = descriptor.value;
+			// biome-ignore lint/suspicious/noExplicitAny: Gotta be any since parameter-values may be undefined.
+			descriptor.value = (...args: any[]) => {
+				// biome-ignore lint/complexity/noThisInStatic: <explanation>
+				const result = originalMethod.apply(this, args);
+				const realValue = path
+					? path
+							?.split(".")
+							.reduce((accumulator, current) => accumulator[current], result)
+					: result;
+				const checkResult = check(realValue, target, propertyKey);
+
+				if (typeof checkResult === "string") {
+					DBC.resolveDBCPath(window, dbc).reportReturnvalueInfringement(
+						checkResult,
+						target,
+						path,
+						propertyKey,
+						realValue,
+					);
+				}
+
+				return result;
+			};
+
+			return descriptor;
+		};
+	}
+	// #endregion Postcondition
+	// #region Decorator
+	// #region Parameter
+	/**
+	 * 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 }.
+	 *
+	 * @returns The  { (target: object, methodName: string | symbol, parameterIndex: number ) => void } invoked by Typescript- */
+	protected static decPrecondition(
+		check: (unknown, object, string, number) => boolean | string,
+		dbc: string,
+		path: string | undefined = undefined,
+	): (
+		target: object,
+		methodName: string | symbol,
+		parameterIndex: number,
+	) => void {
+		return (
+			target: object,
+			methodName: string | symbol,
+			parameterIndex: number,
+		): void => {
+			DBC.requestParamValue(
+				target,
+				methodName,
+				parameterIndex,
+				(value: unknown) => {
+					const realValue = path
+						? path
+								?.split(".")
+								.reduce((accumulator, current) => accumulator[current], value)
+						: value;
+					const result = check(realValue, target, methodName, parameterIndex);
+
+					if (typeof result === "string") {
+						DBC.resolveDBCPath(window, dbc).reportParameterInfringement(
+							result,
+							target,
+							path,
+							methodName as string,
+							parameterIndex,
+							realValue,
+						);
+					}
+				},
+			);
+		};
+	}
+	// #endregion Parameter
+	// #endregion Decorator
+	// #region Warning handling.
+	/** Stores settings concerning warnings. */
+	public warningSettings: {
+		logToConsole: boolean;
+	} = { logToConsole: true };
+	/**
+	 * Reports a warning.
+	 *
+	 * @param message The message containing the warning. */
+	protected reportWarning(message: string): undefined {
+		if (this.warningSettings.logToConsole) {
+			console.warn(message);
+		}
+	}
+	// #endregion Warning handling.
+	// #region infringement handling.
+	/** Stores the setting concerning infringements */
+	public infringementSettings: {
+		throwException: boolean;
+		logToConsole: boolean;
+	} = { throwException: true, logToConsole: false };
+	/**
+	 * Reports an infringement according to the {@link infringementSettings } also generating a proper {@link string }-wrapper
+	 * for the given "message" & violator.
+	 *
+	 * @param message	The {@link string } describing the infringement and it's provenience.
+	 * @param violator 	The {@link string } describing or naming the violator. */
+	protected reportInfringement(
+		message: string,
+		violator: string,
+		target: object,
+		path: string,
+	): undefined {
+		const finalMessage: string = `[ From "${violator}"${path ? `'s member "${path}"` : ""}${typeof target === "function" ? ` in "${target.name}"` : typeof target === "object" && target !== null && typeof target.constructor === "function" ? ` in "${target.constructor.name}"` : ""}: ${message}]`;
+
+		if (this.infringementSettings.throwException) {
+			throw new DBC.Infringement(finalMessage);
+		}
+
+		if (this.infringementSettings.logToConsole) {
+			console.log(finalMessage);
+		}
+	}
+	/**
+	 * Reports a parameter-infringement according 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.
+	 * @param method 	The {@link string } describing or naming the violator.
+	 * @param index		The index of the parameter within the argument listing.
+	 * @param value 	The parameter's value. */
+	public reportParameterInfringement(
+		message: string,
+		target: object,
+		path: string,
+		method: string,
+		index: number,
+		value: unknown,
+	): undefined {
+		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 returnvalue-infringement according via {@link reportInfringement } also generating a proper {@link string }-wrapper
+	 * for the given "message","method" & value.
+	 *
+	 * @param message	The {@link string } describing the infringement and it's provenience.
+	 * @param method 	The {@link string } describing or naming the violator.
+	 * @param value		The parameter's value. */
+	public reportReturnvalueInfringement(
+		message: string,
+		target: object,
+		path: string,
+		method: string,
+		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+		value: any,
+	) {
+		this.reportInfringement(
+			`[ Return-value "${value}" did not fulfill one of it's contracts: ${message}]`,
+			method,
+			target,
+			path,
+		);
+	}
+	// #region Classes
+	// #region Errors
+	/** An {@link Error } to be thrown whenever an infringement is detected. */
+	public static Infringement = class extends Error {
+		/**
+		 * Constructs this {@link Error } by tagging the specified message-{@link string } as an XDBC-Infringement.
+		 *
+		 * @param message The {@link string } describing the infringement. */
+		constructor(message: string) {
+			super(`[ XDBC Infringement ${message}]`);
+		}
+	};
+	// #endregion Errors
+	// #endregion Classes
+	// #endregion infringement handling.
+	static resolveDBCPath = (obj, path): DBC =>
+		path
+			?.split(".")
+			.reduce((accumulator, current) => accumulator[current], obj);
+	/**
+	 *
+	 * @param infringementSettings
+	 */
+	constructor(
+		infringementSettings: {
+			throwException: boolean;
+			logToConsole: boolean;
+		} = { throwException: true, logToConsole: false },
+	) {
+		this.infringementSettings = infringementSettings;
+
+		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+		if ((window as any).WaXCode === undefined) (window as any).WaXCode = {};
+		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+		(window as any).WaXCode.DBC = this;
+	}
+}
+
+new DBC();

package/src/test.ts

@@ -0,0 +1,61 @@
+import { DBC } from "./DBC.js";
+import { REGEX } from "./DBC/REGEX.js";
+import { EQ } from "./DBC/EQ.js";
+import { TYPE } from "./DBC/TYPE.js";
+import { AE } from "./DBC/AE.js";
+import { INSTANCE } from "./DBC/INSTANCE.js";
+
+export class Calculator {
+	@REGEX.POST(/xxxx*/g)
+	@DBC.ParamvalueProvider
+	public divide(@REGEX.PRE(/holla*/g) a: string, b: number): string {
+		console.log(a);
+
+		return a;
+	}
+	@DBC.ParamvalueProvider
+	public HT(
+		@EQ.PRE("SELECT" as unknown as object, true, "tagName") o: HTMLElement,
+	) {}
+	@DBC.ParamvalueProvider
+	public type(@TYPE.PRE("string") o: unknown) {}
+
+	@DBC.ParamvalueProvider
+	public array(@AE.PRE([new TYPE("string")]) x: Array<unknown>) {}
+
+	@DBC.ParamvalueProvider
+	public regex(
+		@AE.PRE(new REGEX(/^(?i:(NOW)|([+-]\d+[dmy]))$/i)) x: Array<string>,
+	) {}
+
+	@DBC.ParamvalueProvider
+	public index(
+		@AE.PRE(new REGEX(/^\d$/i), 0)
+		@AE.PRE(new REGEX(/^(?i:(NOW)|([+-]\d+[dmy]))$/i), 1)
+		x: Array<string>,
+	) {}
+
+	@DBC.ParamvalueProvider
+	// biome-ignore lint/suspicious/noExplicitAny: Test
+	public instance(@INSTANCE.PRE(Date) candidate: any): undefined {}
+	@DBC.ParamvalueProvider
+	public range(
+		// biome-ignore lint/suspicious/noExplicitAny: Test
+		@AE.PRE([new TYPE("string"), new REGEX(/^abc$/)], 1, 2) x: Array<any>,
+	) {}
+	// biome-ignore lint/suspicious/noExplicitAny: Test
+	@AE.POST(new EQ(null, true), 0)
+	public invert(g: string) {
+		return null;
+	}
+}
+
+console.log("s");
+//new Calculator().divide("xxxx", 1);
+//new Calculator().HT(document.createElement("select"));
+//new Calculator().type("10");
+//new Calculator().array([11, "10", "b"]);
+//new Calculator().index(["1a", "+d1m", "-x10y"]);
+//new Calculator().instance(new Date());
+//new Calculator().range([11, "abc", "abc"]);
+new Calculator().invert("");

package/test.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Calculator = void 0;
+var Calculator = /** @class */ (function () {
+    function Calculator() {
+    }
+    //	@DBC.log
+    Calculator.prototype.divide = function (@REGEX.PRE("r") a, b) {
+        return a / b;
+    };
+    return Calculator;
+}());
+exports.Calculator = Calculator;
+alert(new Calculator().divide(2, 1));

package/test.ts

@@ -0,0 +1,11 @@
+import { DBC } from "./DBC.js";
+import { REGEX } from "./DBC/REGEX.js";
+
+export class Calculator {
+	@DBC.log
+	public divide(@REGEX.PRE("r") a: number, b: number): number {
+		return a / b;
+	}
+}
+
+alert(new Calculator().divide(2, 1));

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+	"compilerOptions": {
+		"target": "ES6",
+		"experimentalDecorators": true,
+		"emitDecoratorMetadata": true,
+		"outDir": "./dist",
+		"module": "es6",
+		"typeRoots": []
+	},
+
+	"include": [
+		"./src/**/*.ts" // or your source directories
+	],
+	"exclude": ["node_modules"]
+}