xdbc 1.0.211 → 1.0.213

package/src/DBC.ts

@@ -30,7 +30,9 @@ export class DBC {
 			DBC.dbcCache.set(path, resolved);
 			return resolved;
 		}
-		throw new Error(`[XDBC] DBC instance not found at path "${path}". Ensure a DBC instance is registered there.`);
+		throw new Error(
+			`[XDBC] DBC instance not found at path "${path}". Ensure a DBC instance is registered there.`,
+		);
 	}
 	// #endregion Internal caches.
 	// #region Parameter-value requests.
@@ -48,8 +50,14 @@ export class DBC {
 	 * Generate a unique key for storing parameter value requests.
 	 * Format: "ClassName:methodName"
 	 */
-	private static getRequestKey(target: object, methodName: string | symbol): string {
-		const className = typeof target === 'function' ? target.name : target.constructor?.name || 'Unknown';
+	private static getRequestKey(
+		target: object,
+		methodName: string | symbol,
+	): string {
+		const className =
+			typeof target === "function"
+				? target.name
+				: target.constructor?.name || "Unknown";
 		return `${className}:${String(methodName)}`;
 	}
 	/**
@@ -74,7 +82,7 @@ export class DBC {
 		if (DBC.paramValueRequests.has(key)) {
 			const paramMap = DBC.paramValueRequests.get(key)!;
 			if (paramMap.has(index)) {
-				paramMap.get(index)!.push(receptor);
+				paramMap.get(index)?.push(receptor);
 			} else {
 				paramMap.set(index, new Array<(value: unknown) => undefined>(receptor));
 			}
@@ -90,25 +98,62 @@ export class DBC {
 		return undefined;
 	}
 	/**
-	 * 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.
+	 * A decorator usable on both **methods** (including setters) and **classes**.
 	 *
-	 * @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.
+	 * - **On a method**: wraps the method so that any {@link DBC } preconditions registered on its parameters
+	 *   via XDBC parameter-decorator factories are dispatched with the actual argument values on each call.
+	 * - **On a class**: wraps the constructor so that preconditions registered on constructor parameters are
+	 *   dispatched **before** the original constructor body runs, upholding true precondition semantics.
 	 *
-	 * @returns The {@link PropertyDescriptor } that was passed by the runtime. */
-	public static ParamvalueProvider(
-		target: object,
-		propertyKey: string,
-		descriptor: PropertyDescriptor,
-	): PropertyDescriptor {
+	 * In both cases the "receptor" callbacks enlisted in {@link paramValueRequests } by {@link requestParamValue }
+	 * are invoked with the live argument values.
+	 *
+	 * @param targetOrConstructor	When used as a **method** decorator: the {@link object } hosting the tagged method.
+	 * 								When used as a **class** decorator: the class constructor.
+	 * @param propertyKey 			*(method decorator only)* The tagged method's name as provided by the runtime.
+	 * @param descriptor 			*(method decorator only)* The {@link PropertyDescriptor } as provided by the runtime.
+	 *
+	 * @returns 	When used as a **method** decorator: the (modified) {@link PropertyDescriptor }.
+	 * 				When used as a **class** decorator: a replacement constructor that performs precondition checks. */
+	// biome-ignore lint/suspicious/noExplicitAny: Must handle both method and class decorator signatures
+	public static ParamvalueProvider(target: object, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+	// biome-ignore lint/suspicious/noExplicitAny: Must handle both method and class decorator signatures
+	public static ParamvalueProvider<T extends new (...args: any[]) => any>(constructor: T): T;
+	// biome-ignore lint/suspicious/noExplicitAny: Must handle both method and class decorator signatures
+	public static ParamvalueProvider(...args: any[]): any {
+		if (args.length === 1 && typeof args[0] === "function") {
+			// #region Class decorator path
+			// biome-ignore lint/suspicious/noExplicitAny: Must accept any constructor signature
+			const constructor = args[0] as new (...args: any[]) => any;
+			const key = `${constructor.name}:undefined`;
+			// biome-ignore lint/suspicious/noExplicitAny: Must accept any constructor signature
+			const WrappedClass = class extends constructor {
+				// biome-ignore lint/suspicious/noExplicitAny: Must accept any constructor signature
+				constructor(...ctorArgs: any[]) {
+					if (DBC.paramValueRequests.has(key)) {
+						const paramMap = DBC.paramValueRequests.get(key)!;
+						for (const index of paramMap.keys()) {
+							if (index < ctorArgs.length) {
+								for (const receptor of paramMap.get(index)!) {
+									receptor(ctorArgs[index]);
+								}
+							}
+						}
+					}
+					super(...ctorArgs);
+				}
+			} as typeof constructor;
+			Object.defineProperty(WrappedClass, "name", { value: constructor.name });
+			return WrappedClass;
+			// #endregion Class decorator path
+		}
+
+		// #region Method decorator path
+		const [target, propertyKey, descriptor] = args as [object, string, PropertyDescriptor];
 		const originalMethod = descriptor.value;
-		const isStatic = typeof target === 'function';
+		const isStatic = typeof target === "function";
 		// biome-ignore lint/suspicious/noExplicitAny: Gotta be any since parameter-values may be undefined.
-		descriptor.value = function (...args: any[]) {
+		descriptor.value = function (...methodArgs: any[]) {
 			// #region   Check if a value of one of the method's parameter has been requested and pass it to the
 			//           receptor, if so.
 			const actualTarget = isStatic ? this : (this as any).constructor;
@@ -117,9 +162,9 @@ export class DBC {
 			if (DBC.paramValueRequests.has(key)) {
 				const paramMap = DBC.paramValueRequests.get(key)!;
 				for (const index of paramMap.keys()) {
-					if (index < args.length) {
+					if (index < methodArgs.length) {
 						for (const receptor of paramMap.get(index)!) {
-							receptor(args[index]);
+							receptor(methodArgs[index]);
 						}
 					}
 				}
@@ -128,10 +173,10 @@ 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.
-			return originalMethod.apply(this, args);
+			return originalMethod.apply(this, methodArgs);
 		};
-
 		return descriptor;
+		// #endregion Method decorator path
 	}
 	// #endregion Parameter-value requests.
 	// #region Class
@@ -151,7 +196,11 @@ export class DBC {
 		dbc = "WaXCode.DBC",
 	) {
 		let dbcInstance: DBC | undefined;
-		return (target: unknown, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
+		return (
+			target: unknown,
+			propertyKey: string | symbol,
+			descriptor: PropertyDescriptor,
+		) => {
 			if (!dbcInstance) dbcInstance = DBC.getDBC(dbc);
 			if (!dbcInstance.executionSettings.checkInvariants) {
 				return;
@@ -163,7 +212,7 @@ export class DBC {
 			// #region Replace original property.
 			Object.defineProperty(target, propertyKey, {
 				get() {
-					if (!dbcInstance!.executionSettings.checkInvariants) {
+					if (!dbcInstance?.executionSettings.checkInvariants) {
 						return;
 					}
 
@@ -173,7 +222,7 @@ export class DBC {
 						const result = contract.check(realValue);
 
 						if (typeof result === "string") {
-							dbcInstance!.reportFieldInfringement(
+							dbcInstance?.reportFieldInfringement(
 								result,
 								target as object,
 								path,
@@ -186,7 +235,7 @@ export class DBC {
 					return originalGetter ? (originalGetter as any)[propertyKey] : value;
 				},
 				set(newValue) {
-					if (!dbcInstance!.executionSettings.checkInvariants) {
+					if (!dbcInstance?.executionSettings.checkInvariants) {
 						return;
 					}
 
@@ -196,7 +245,7 @@ export class DBC {
 						const result = contract.check(realValue);
 
 						if (typeof result === "string") {
-							dbcInstance!.reportFieldInfringement(
+							dbcInstance?.reportFieldInfringement(
 								result,
 								target as object,
 								path,
@@ -244,7 +293,7 @@ export class DBC {
 			// #region Replace original property.
 			Object.defineProperty(target, propertyKey, {
 				set(newValue) {
-					if (!dbcInstance!.executionSettings.checkInvariants) {
+					if (!dbcInstance?.executionSettings.checkInvariants) {
 						return;
 					}
 
@@ -254,13 +303,13 @@ export class DBC {
 						const result = contract.check(realValue);
 
 						if (typeof result === "string") {
-							dbcInstance!.reportFieldInfringement(
+							dbcInstance?.reportFieldInfringement(
 								result,
 								target as object,
 								path,
 								propertyKey as string,
 								realValue,
-								hint
+								hint,
 							);
 						}
 					}
@@ -288,7 +337,11 @@ export class DBC {
 	// biome-ignore lint/suspicious/noExplicitAny: Necessary to intercept UNDEFINED and NULL.
 	public static decPostcondition(
 		// biome-ignore lint/suspicious/noExplicitAny: Necessary to intercept UNDEFINED and NULL.
-		check: (toCheck: any, target: object, propertyKey: string) => boolean | string,
+		check: (
+			toCheck: any,
+			target: object,
+			propertyKey: string,
+		) => boolean | string,
 		dbc: string | undefined = undefined,
 		path: string | undefined = undefined,
 		hint: string | undefined = undefined,
@@ -318,7 +371,7 @@ export class DBC {
 						path,
 						propertyKey,
 						realValue,
-						hint
+						hint,
 					);
 				}
 
@@ -344,7 +397,12 @@ export class DBC {
 	 * @returns The **(target: object, methodName: string | symbol, parameterIndex: number ) => void** invoked by Typescript- */
 	protected static decPrecondition(
 		// biome-ignore lint/suspicious/noExplicitAny: Necessary to check any parameter value
-		check: (value: unknown, target: object, methodName: string | symbol, parameterIndex: number) => boolean | string,
+		check: (
+			value: unknown,
+			target: object,
+			methodName: string | symbol,
+			parameterIndex: number,
+		) => boolean | string,
 		dbc: string | undefined = undefined,
 		path: string | undefined = undefined,
 		hint: string | undefined = undefined,
@@ -371,7 +429,9 @@ export class DBC {
 					}
 
 					for (const singlePath of paths) {
-						const realValue = singlePath ? DBC.resolve(value, singlePath) : value;
+						const realValue = singlePath
+							? DBC.resolve(value, singlePath)
+							: value;
 						const result = check(realValue, target, methodName, parameterIndex);
 
 						if (typeof result === "string") {
@@ -382,7 +442,7 @@ export class DBC {
 								methodName as string,
 								parameterIndex,
 								realValue,
-								hint
+								hint,
 							);
 						}
 					}
@@ -459,19 +519,16 @@ export class DBC {
 	 */
 	public static createINVARIANT(
 		// biome-ignore lint/suspicious/noExplicitAny: Must accept any contract constructor
-		ContractClass: new (...args: any[]) => { check: (toCheck: unknown | null | undefined) => boolean | string },
+		ContractClass: new (
+			...args: any[]
+		) => { check: (toCheck: unknown | null | undefined) => boolean | string },
 		// biome-ignore lint/suspicious/noExplicitAny: Arguments vary per contract
 		ctorArgs: any[],
 		dbc?: string,
 		path?: string,
 		hint?: string,
 	) {
-		return DBC.decInvariant(
-			[new ContractClass(...ctorArgs)],
-			path,
-			dbc,
-			hint,
-		);
+		return DBC.decInvariant([new ContractClass(...ctorArgs)], path, dbc, hint);
 	}
 	// #endregion Contract Factory Helpers
 	// #region Execution Handling
@@ -481,10 +538,10 @@ export class DBC {
 		checkPostconditions: boolean;
 		checkInvariants: boolean;
 	} = {
-			checkPreconditions: true,
-			checkPostconditions: true,
-			checkInvariants: true,
-		};
+		checkPreconditions: true,
+		checkPostconditions: true,
+		checkInvariants: true,
+	};
 	// #endregion Execution Handling
 	// #region Warning handling.
 	/** Stores settings concerning warnings. */
@@ -512,12 +569,18 @@ export class DBC {
 		const str = typeof value === "string" ? value : String(value);
 		return str.replace(/[<>&"']/g, (ch) => {
 			switch (ch) {
-				case "<": return "&lt;";
-				case ">": return "&gt;";
-				case "&": return "&amp;";
-				case "\"": return "&quot;";
-				case "'": return "&#39;";
-				default: return ch;
+				case "<":
+					return "&lt;";
+				case ">":
+					return "&gt;";
+				case "&":
+					return "&amp;";
+				case '"':
+					return "&quot;";
+				case "'":
+					return "&#39;";
+				default:
+					return ch;
 			}
 		});
 	}
@@ -536,7 +599,14 @@ export class DBC {
 		hint: string | undefined = undefined,
 	): undefined {
 		const safeViolator = DBC.sanitize(violator);
-		const targetName = typeof target === "function" ? DBC.sanitize(target.name) : typeof target === "object" && target !== null && typeof target.constructor === "function" ? DBC.sanitize(target.constructor.name) : DBC.sanitize(target);
+		const targetName =
+			typeof target === "function"
+				? DBC.sanitize(target.name)
+				: typeof target === "object" &&
+						target !== null &&
+						typeof target.constructor === "function"
+					? DBC.sanitize(target.constructor.name)
+					: DBC.sanitize(target);
 		const finalMessage: string = `[ From "${safeViolator}" in "${targetName}"${path ? ` > "${DBC.sanitize(path)}"` : ""}: ${message} ${hint ? `✨ ${hint} ✨` : ""}]`;
 
 		if (this.infringementSettings.throwException) {
@@ -572,7 +642,7 @@ export class DBC {
 			target,
 			value,
 			path,
-			hint
+			hint,
 		);
 	}
 	/**
@@ -622,7 +692,7 @@ export class DBC {
 			target,
 			value,
 			path,
-			hint
+			hint,
 		);
 	}
 	// #region Classes
@@ -670,10 +740,10 @@ export class DBC {
 			checkPostconditions: boolean;
 			checkInvariants: boolean;
 		} = {
-				checkPreconditions: true,
-				checkPostconditions: true,
-				checkInvariants: true,
-			},
+			checkPreconditions: true,
+			checkPostconditions: true,
+			checkInvariants: true,
+		},
 	) {
 		this.infringementSettings = infringementSettings;
 		this.executionSettings = executionSettings;
@@ -727,20 +797,25 @@ export class DBC {
 	 *
 	 * @returns The requested {@link object }, NULL or UNDEFINED. */
 	public static resolve(toResolveFrom: unknown, path: string) {
-		if (!toResolveFrom || typeof path !== "string") { return undefined; }
+		if (!toResolveFrom || typeof path !== "string") {
+			return undefined;
+		}
 
 		// Security: block prototype pollution paths
 		const dangerousTokens = ["__proto__", "constructor", "prototype"];
 
 		const cachedParts = DBC.pathTokenCache.get(path);
-		const parts = cachedParts ?? path.replace(/\[(['"]?)(.*?)\1\]/g, ".$2").split(".");
+		const parts =
+			cachedParts ?? path.replace(/\[(['"]?)(.*?)\1\]/g, ".$2").split(".");
 
 		if (!cachedParts) {
 			// Validate tokens before caching
 			for (const part of parts) {
 				const tokenName = part.replace(/\(.*\)$/, "");
 				if (dangerousTokens.indexOf(tokenName) >= 0) {
-					throw new Error(`[XDBC] Path "${path}" contains forbidden token "${tokenName}".`);
+					throw new Error(
+						`[XDBC] Path "${path}" contains forbidden token "${tokenName}".`,
+					);
 				}
 			}
 			DBC.evictIfNeeded(DBC.pathTokenCache);
@@ -751,7 +826,9 @@ export class DBC {
 		let current: any = toResolveFrom;
 
 		for (const part of parts) {
-			if (current === null || typeof current === "undefined") { return undefined; }
+			if (current === null || typeof current === "undefined") {
+				return undefined;
+			}
 
 			const methodMatch = part.match(/(\w+)\((.*)\)/);
 
@@ -762,13 +839,32 @@ export class DBC {
 
 				if (typeof current[methodName] === "function") {
 					current = current[methodName].apply(current, args);
-				} else { return undefined; }
+				} else {
+					return undefined;
+				}
 			} else {
-				if (typeof window !== "undefined" && typeof HTMLElement !== "undefined" && current instanceof HTMLElement && part.startsWith("@")) {
+				if (
+					typeof window !== "undefined" &&
+					typeof HTMLElement !== "undefined" &&
+					current instanceof HTMLElement &&
+					part.startsWith("@")
+				) {
 					current = current.getAttribute(part.slice(1));
-				} else if (typeof current === "object" && current !== null && part in current) { current = current[part]; }
-				else if (typeof window !== "undefined" && typeof HTMLElement !== "undefined" && current instanceof HTMLElement) { current = undefined; }
-				else { current = undefined; }
+				} else if (
+					typeof current === "object" &&
+					current !== null &&
+					part in current
+				) {
+					current = current[part];
+				} else if (
+					typeof window !== "undefined" &&
+					typeof HTMLElement !== "undefined" &&
+					current instanceof HTMLElement
+				) {
+					current = undefined;
+				} else {
+					current = undefined;
+				}
 			}
 		}
 

package/src/Demo.ts

@@ -1,14 +1,14 @@
 import { DBC } from "./DBC";
-import { REGEX } from "./DBC/REGEX";
-import { EQ } from "./DBC/EQ";
-import { TYPE } from "./DBC/TYPE";
 import { AE } from "./DBC/AE";
-import { INSTANCE } from "./DBC/INSTANCE";
 import { GREATER } from "./DBC/COMPARISON/GREATER";
 import { GREATER_OR_EQUAL } from "./DBC/COMPARISON/GREATER_OR_EQUAL";
 import { LESS } from "./DBC/COMPARISON/LESS";
 import { LESS_OR_EQUAL } from "./DBC/COMPARISON/LESS_OR_EQUAL";
+import { EQ } from "./DBC/EQ";
 import { DIFFERENT } from "./DBC/EQ/DIFFERENT";
+import { INSTANCE } from "./DBC/INSTANCE";
+import { REGEX } from "./DBC/REGEX";
+import { TYPE } from "./DBC/TYPE";
 /** Demonstrative use of **D**esign **B**y **C**ontract Decorators */
 export class Demo {
 	// #region Check Property Decorator
@@ -32,65 +32,68 @@ export class Demo {
 	@DBC.ParamvalueProvider
 	public testEQAndPath(
 		@EQ.PRE("SELECT" as unknown as object, false, "tagName") o: HTMLElement,
-	) { }
+	) {}
 	// #endregion Check EQ-DBC & Path to property of Parameter-value
 	// #region Check EQ-DBC & Path to property of Parameter-value with Inversion
 	@DBC.ParamvalueProvider
 	public testEQAndPathWithInversion(
 		@EQ.PRE("SELECT" as unknown as object, true, "tagName") o: HTMLElement,
-	) { }
+	) {}
 	// #endregion Check EQ-DBC & Path to property of Parameter-value with Inversion
 	// #region Check TYPE
 	@DBC.ParamvalueProvider
-	public testTYPE(@TYPE.PRE("string") o: unknown) { }
+	public testTYPE(@TYPE.PRE("string") o: unknown) {}
 	// #endregion Check TYPE
 	// #region Check AE
 	@DBC.ParamvalueProvider
-	public testAE(@AE.PRE([new TYPE("string")]) x: Array<unknown>) { }
+	public testAE(@AE.PRE([new TYPE("string")]) x: Array<unknown>) {}
 	// #endregion Check AE
 	// #region Check REGEX with AE
 	@DBC.ParamvalueProvider
 	public testREGEXWithAE(
 		@AE.PRE(new REGEX(/^(?i:(NOW)|([+-]\d+[dmy]))$/i)) x: Array<string>,
-	) { }
+	) {}
 	// #endregion Check REGEX with AE
 	// #region Check INSTANCE
 	@DBC.ParamvalueProvider
 	// biome-ignore lint/suspicious/noExplicitAny: Test
-	public testINSTANCE(@INSTANCE.PRE(Date) candidate: any): undefined { }
+	public testINSTANCE(@INSTANCE.PRE(Date) candidate: any): undefined {}
 	// #endregion Check INSTANCE
 	// #region Check AE Range
 	@DBC.ParamvalueProvider
 	public testAERange(
 		@AE.PRE([new TYPE("string"), new REGEX(/^abc$/)], 1, 2) x: Array<unknown>,
-	) { }
+	) {}
 	// #endregion Check AE Range
 	// #region Check AE Index
 	@DBC.ParamvalueProvider
 	public testAEIndex(
 		@AE.PRE([new TYPE("string"), new REGEX(/^abc$/)], 1) x: Array<unknown>,
-	) { }
+	) {}
 	// #endregion Check AE Index
 	// #region Check Comparison
 	@DBC.ParamvalueProvider
-	public testGREATER(@GREATER.PRE(2) input: number) { }
+	public testGREATER(@GREATER.PRE(2) input: number) {}
 
 	@DBC.ParamvalueProvider
-	public testGREATER_OR_EQUAL(@GREATER_OR_EQUAL.PRE(2) input: number) { }
+	public testGREATER_OR_EQUAL(@GREATER_OR_EQUAL.PRE(2) input: number) {}
 
 	@DBC.ParamvalueProvider
-	public testLESS(@LESS.PRE(20) input: number) { }
+	public testLESS(@LESS.PRE(20) input: number) {}
 
 	@DBC.ParamvalueProvider
-	public testLESS_OR_EQUAL(@LESS_OR_EQUAL.PRE(20) input: number) { }
+	public testLESS_OR_EQUAL(@LESS_OR_EQUAL.PRE(20) input: number) {}
 
 	@DBC.ParamvalueProvider
-	public testDIFFERENT(@DIFFERENT.PRE(20) input: number) { }
+	public testDIFFERENT(@DIFFERENT.PRE(20) input: number) {}
 	// #endregion Check Comparison
 
 	// #region Check Static Method with ParamvalueProvider
 	@DBC.ParamvalueProvider
-	public static testStaticMethod(@TYPE.PRE("string") message: string, @TYPE.PRE("number") count: number): string {
+	public static testStaticMethod(
+		@TYPE.PRE("string") message: string,
+		@TYPE.PRE("number") count: number,
+	): string {
 		return `${message} repeated ${count} times`;
 	}
 	// #endregion Check Static Method with ParamvalueProvider

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
 	"compilerOptions": {
 		"target": "ES6",
+		"declaration": true,
 		"experimentalDecorators": true,
 		"emitDecoratorMetadata": true,
 		"outDir": "./dist",
@@ -13,8 +14,5 @@
 	"include": [
 		"./src/**/*.ts" // or your source directories
 	],
-	"exclude": [
-		"node_modules",
-		"__tests__"
-	]
-}
+	"exclude": ["node_modules", "__tests__"]
+}

package/tsconfig.test.json

@@ -1,12 +1,7 @@
 {
-    "extends": "./tsconfig.json",
-    "compilerOptions": {
-        "typeRoots": [
-            "./node_modules/@types"
-        ]
-    },
-    "include": [
-        "./src/**/*.ts",
-        "./__tests__/**/*.ts"
-    ]
-}
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"typeRoots": ["./node_modules/@types"]
+	},
+	"include": ["./src/**/*.ts", "./__tests__/**/*.ts"]
+}

package/webpack.config.js

@@ -1,4 +1,4 @@
-const path = require("path");
+const path = require("node:path");
 
 module.exports = {
 	mode: "development", // or 'production' for optimized builds