xdbc 1.0.207 → 1.0.209

package/src/DBC.ts

@@ -5,21 +5,32 @@
  * Maintainer: Callari, Salvatore (XDBC@WaXCode.net) */
 export class DBC {
 	// #region Internal caches.
+	private static readonly MAX_CACHE_SIZE = 1000;
 	private static dbcCache: Map<string, DBC> = new Map();
 	private static pathTokenCache: Map<string, string[]> = new Map();
+	/** Evicts the oldest entry if the cache exceeds the maximum size. */
+	private static evictIfNeeded<K, V>(cache: Map<K, V>): void {
+		if (cache.size > DBC.MAX_CACHE_SIZE) {
+			const oldest = cache.keys().next().value;
+			if (oldest !== undefined) cache.delete(oldest);
+		}
+	}
 	private static getHost(): unknown {
 		return typeof window !== "undefined" ? window : globalThis;
 	}
-	private static getDBC(dbc: string | undefined): DBC {
+	private static getDBC(dbc: string | DBC | undefined): DBC {
+		if (dbc instanceof DBC) return dbc;
 		const path = dbc ?? "WaXCode.DBC";
 		if (DBC.dbcCache.has(path)) {
-			return DBC.dbcCache.get(path);
+			return DBC.dbcCache.get(path) as DBC;
 		}
 		const resolved = DBC.resolveDBCPath(DBC.getHost(), path);
 		if (resolved) {
+			DBC.evictIfNeeded(DBC.dbcCache);
 			DBC.dbcCache.set(path, resolved);
+			return resolved;
 		}
-		return resolved;
+		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.
@@ -61,10 +72,11 @@ export class DBC {
 		const key = DBC.getRequestKey(target, methodName);
 
 		if (DBC.paramValueRequests.has(key)) {
-			if (DBC.paramValueRequests.get(key).has(index)) {
-				DBC.paramValueRequests.get(key).get(index).push(receptor);
+			const paramMap = DBC.paramValueRequests.get(key)!;
+			if (paramMap.has(index)) {
+				paramMap.get(index)!.push(receptor);
 			} else {
-				DBC.paramValueRequests.get(key).set(index, new Array<(value: unknown) => undefined>(receptor));
+				paramMap.set(index, new Array<(value: unknown) => undefined>(receptor));
 			}
 		} else {
 			DBC.paramValueRequests.set(
@@ -103,9 +115,10 @@ export class DBC {
 			const key = DBC.getRequestKey(actualTarget, propertyKey);
 
 			if (DBC.paramValueRequests.has(key)) {
-				for (const index of DBC.paramValueRequests.get(key).keys()) {
+				const paramMap = DBC.paramValueRequests.get(key)!;
+				for (const index of paramMap.keys()) {
 					if (index < args.length) {
-						for (const receptor of DBC.paramValueRequests.get(key).get(index)) {
+						for (const receptor of paramMap.get(index)!) {
 							receptor(args[index]);
 						}
 					}
@@ -137,8 +150,10 @@ export class DBC {
 		path: string | undefined = undefined,
 		dbc = "WaXCode.DBC",
 	) {
+		let dbcInstance: DBC | undefined;
 		return (target: unknown, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
-			if (!DBC.getDBC(dbc).executionSettings.checkInvariants) {
+			if (!dbcInstance) dbcInstance = DBC.getDBC(dbc);
+			if (!dbcInstance.executionSettings.checkInvariants) {
 				return;
 			}
 			const originalSetter = descriptor.set;
@@ -148,7 +163,7 @@ export class DBC {
 			// #region Replace original property.
 			Object.defineProperty(target, propertyKey, {
 				get() {
-					if (!DBC.getDBC(dbc).executionSettings.checkInvariants) {
+					if (!dbcInstance!.executionSettings.checkInvariants) {
 						return;
 					}
 
@@ -158,7 +173,7 @@ export class DBC {
 						const result = contract.check(realValue);
 
 						if (typeof result === "string") {
-							DBC.getDBC(dbc).reportFieldInfringement(
+							dbcInstance!.reportFieldInfringement(
 								result,
 								target as object,
 								path,
@@ -168,10 +183,10 @@ export class DBC {
 						}
 					}
 					// #endregion Check if all "contracts" are fulfilled.
-					return originalGetter[propertyKey];
+					return originalGetter ? (originalGetter as any)[propertyKey] : value;
 				},
 				set(newValue) {
-					if (!DBC.getDBC(dbc).executionSettings.checkInvariants) {
+					if (!dbcInstance!.executionSettings.checkInvariants) {
 						return;
 					}
 
@@ -181,7 +196,7 @@ export class DBC {
 						const result = contract.check(realValue);
 
 						if (typeof result === "string") {
-							DBC.getDBC(dbc).reportFieldInfringement(
+							dbcInstance!.reportFieldInfringement(
 								result,
 								target as object,
 								path,
@@ -218,8 +233,10 @@ export class DBC {
 		dbc: string | undefined = undefined,
 		hint: string | undefined = undefined,
 	) {
+		let dbcInstance: DBC | undefined;
 		return (target: unknown, propertyKey: string | symbol) => {
-			if (!DBC.getDBC(dbc).executionSettings.checkInvariants) {
+			if (!dbcInstance) dbcInstance = DBC.getDBC(dbc);
+			if (!dbcInstance.executionSettings.checkInvariants) {
 				return;
 			}
 			// biome-ignore lint/suspicious/noExplicitAny: Necessary to intercept UNDEFINED and NULL.
@@ -227,7 +244,7 @@ export class DBC {
 			// #region Replace original property.
 			Object.defineProperty(target, propertyKey, {
 				set(newValue) {
-					if (!DBC.getDBC(dbc).executionSettings.checkInvariants) {
+					if (!dbcInstance!.executionSettings.checkInvariants) {
 						return;
 					}
 
@@ -237,7 +254,7 @@ export class DBC {
 						const result = contract.check(realValue);
 
 						if (typeof result === "string") {
-							DBC.getDBC(dbc).reportFieldInfringement(
+							dbcInstance!.reportFieldInfringement(
 								result,
 								target as object,
 								path,
@@ -268,13 +285,15 @@ export class DBC {
 	 * @returns The **( target : object, propertyKey : string, descriptor : PropertyDescriptor ) : PropertyDescriptor**
 	 * 			invoked by Typescript.
 	 */
+	// 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, object, string) => boolean | string,
+		check: (toCheck: any, target: object, propertyKey: string) => boolean | string,
 		dbc: string | undefined = undefined,
 		path: string | undefined = undefined,
 		hint: string | undefined = undefined,
 	) {
+		let dbcInstance: DBC | undefined;
 		return (
 			target: object,
 			propertyKey: string,
@@ -283,7 +302,8 @@ export class DBC {
 			const originalMethod = descriptor.value;
 			// biome-ignore lint/suspicious/noExplicitAny: Necessary to intercept UNDEFINED and NULL.
 			descriptor.value = (...args: any[]) => {
-				if (!DBC.getDBC(dbc).executionSettings.checkPostconditions) {
+				if (!dbcInstance) dbcInstance = DBC.getDBC(dbc);
+				if (!dbcInstance.executionSettings.checkPostconditions) {
 					return;
 				}
 				// biome-ignore lint/complexity/noThisInStatic: <explanation>
@@ -292,7 +312,7 @@ export class DBC {
 				const checkResult = check(realValue, target, propertyKey);
 
 				if (typeof checkResult === "string") {
-					DBC.getDBC(dbc).reportReturnvalueInfringement(
+					dbcInstance.reportReturnvalueInfringement(
 						checkResult,
 						target,
 						path,
@@ -323,7 +343,8 @@ export class DBC {
 	 *
 	 * @returns The **(target: object, methodName: string | symbol, parameterIndex: number ) => void** invoked by Typescript- */
 	protected static decPrecondition(
-		check: (unknown, object, string, number) => boolean | string,
+		// biome-ignore lint/suspicious/noExplicitAny: Necessary to check any parameter value
+		check: (value: unknown, target: object, methodName: string | symbol, parameterIndex: number) => boolean | string,
 		dbc: string | undefined = undefined,
 		path: string | undefined = undefined,
 		hint: string | undefined = undefined,
@@ -333,6 +354,7 @@ export class DBC {
 		parameterIndex: number,
 	) => void {
 		const paths = path ? path.replace(/ /g, "").split("::") : [undefined];
+		let dbcInstance: DBC | undefined;
 		return (
 			target: object,
 			methodName: string | symbol,
@@ -343,7 +365,8 @@ export class DBC {
 				methodName,
 				parameterIndex,
 				(value: unknown) => {
-					if (!DBC.getDBC(dbc).executionSettings.checkPreconditions) {
+					if (!dbcInstance) dbcInstance = DBC.getDBC(dbc);
+					if (!dbcInstance.executionSettings.checkPreconditions) {
 						return;
 					}
 
@@ -352,7 +375,7 @@ export class DBC {
 						const result = check(realValue, target, methodName, parameterIndex);
 
 						if (typeof result === "string") {
-							DBC.getDBC(dbc).reportParameterInfringement(
+							dbcInstance.reportParameterInfringement(
 								result,
 								target,
 								singlePath,
@@ -369,6 +392,88 @@ export class DBC {
 	}
 	// #endregion Precondition
 	// #endregion Decorator
+	// #region Contract Factory Helpers
+	/**
+	 * Creates a PRE decorator from a checkAlgorithm function and its bound arguments.
+	 * Reduces boilerplate across contract classes.
+	 *
+	 * @param checkFn  A function that takes (value, ...boundArgs) and returns true or an error string.
+	 * @param boundArgs The arguments to bind to the check function after the value.
+	 * @param dbc      See {@link DBC.decPrecondition}.
+	 * @param path     See {@link DBC.decPrecondition}.
+	 * @param hint     See {@link DBC.decPrecondition}.
+	 */
+	public static createPRE(
+		// biome-ignore lint/suspicious/noExplicitAny: Must accept any checkAlgorithm signature
+		checkFn: (...args: any[]) => boolean | string,
+		// biome-ignore lint/suspicious/noExplicitAny: Arguments vary per contract
+		boundArgs: any[],
+		dbc?: string,
+		path?: string,
+		hint?: string,
+	) {
+		return DBC.decPrecondition(
+			(value, _target, _methodName, _parameterIndex) => {
+				return checkFn(value, ...boundArgs);
+			},
+			dbc,
+			path,
+			hint,
+		);
+	}
+	/**
+	 * Creates a POST decorator from a checkAlgorithm function and its bound arguments.
+	 *
+	 * @param checkFn  A function that takes (value, ...boundArgs) and returns true or an error string.
+	 * @param boundArgs The arguments to bind to the check function after the value.
+	 * @param dbc      See {@link DBC.decPostcondition}.
+	 * @param path     See {@link DBC.decPostcondition}.
+	 * @param hint     See {@link DBC.decPostcondition}.
+	 */
+	public static createPOST(
+		// biome-ignore lint/suspicious/noExplicitAny: Must accept any checkAlgorithm signature
+		checkFn: (...args: any[]) => boolean | string,
+		// biome-ignore lint/suspicious/noExplicitAny: Arguments vary per contract
+		boundArgs: any[],
+		dbc?: string,
+		path?: string,
+		hint?: string,
+	) {
+		return DBC.decPostcondition(
+			(value, _target, _propertyKey) => {
+				return checkFn(value, ...boundArgs);
+			},
+			dbc,
+			path,
+			hint,
+		);
+	}
+	/**
+	 * Creates an INVARIANT decorator from a contract constructor and its bound arguments.
+	 *
+	 * @param ContractClass A class with a constructor that produces an object with a `check` method.
+	 * @param ctorArgs      The arguments to pass to the contract constructor.
+	 * @param dbc           See {@link DBC.decInvariant}.
+	 * @param path          See {@link DBC.decInvariant}.
+	 * @param hint          See {@link DBC.decInvariant}.
+	 */
+	public static createINVARIANT(
+		// biome-ignore lint/suspicious/noExplicitAny: Must accept any contract constructor
+		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,
+		);
+	}
+	// #endregion Contract Factory Helpers
 	// #region Execution Handling
 	/** Stores settings concerning the execution of checks. */
 	public executionSettings: {
@@ -402,6 +507,20 @@ export class DBC {
 		throwException: boolean;
 		logToConsole: boolean;
 	} = { throwException: true, logToConsole: false };
+	/** Sanitizes a value for safe inclusion in error messages. */
+	private static sanitize(value: unknown): string {
+		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;
+			}
+		});
+	}
 	/**
 	 * Reports an infringement according to the {@link infringementSettings } also generating a proper {@link string }-wrapper
 	 * for the given "message" & violator.
@@ -413,10 +532,12 @@ export class DBC {
 		violator: string,
 		target: object,
 		value: unknown,
-		path: string,
+		path: string | undefined,
 		hint: string | undefined = undefined,
 	): undefined {
-		const finalMessage: string = `[ From "${violator}"${typeof target === "function" ? ` in "${target.name}"` : typeof target === "object" && target !== null && typeof target.constructor === "function" ? ` in "${target.constructor.name}"` : `in "${target}"`}${path ? ` > "${path}"` : ""}: ${message} ${hint ? `✨ ${hint} ✨` : ""}]`;
+		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 finalMessage: string = `[ From "${safeViolator}" in "${targetName}"${path ? ` > "${DBC.sanitize(path)}"` : ""}: ${message} ${hint ? `✨ ${hint} ✨` : ""}]`;
 
 		if (this.infringementSettings.throwException) {
 			throw new DBC.Infringement(finalMessage);
@@ -437,7 +558,7 @@ export class DBC {
 	public reportParameterInfringement(
 		message: string,
 		target: object,
-		path: string,
+		path: string | undefined,
 		method: string,
 		index: number,
 		value: unknown,
@@ -466,7 +587,7 @@ export class DBC {
 	public reportFieldInfringement(
 		message: string,
 		target: object,
-		path: string,
+		path: string | undefined,
 		key: string,
 		value: unknown,
 		hint: string | undefined = undefined,
@@ -489,7 +610,7 @@ export class DBC {
 	public reportReturnvalueInfringement(
 		message: string,
 		target: object,
-		path: string,
+		path: string | undefined,
 		method: string,
 		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
 		value: any,
@@ -527,13 +648,15 @@ export class DBC {
 	 *
 	 * @returns The requested {@link DBC }.
 	 */
-	static resolveDBCPath = (obj, path): DBC =>
+	// biome-ignore lint/suspicious/noExplicitAny: Must traverse arbitrary object graphs
+	static resolveDBCPath = (obj: any, path: string): DBC =>
 		path
 			?.split(".")
-			.reduce((accumulator, current) => accumulator[current], obj);
+			// biome-ignore lint/suspicious/noExplicitAny: Must traverse arbitrary object graphs
+			.reduce((accumulator: any, current: string) => accumulator[current], obj);
 	/**
-	 * 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 }.
+	 * Constructs this {@link DBC } without mounting it on the global namespace.
+	 * Use {@link DBC.register } to make the instance available at a specific path on globalThis.
 	 *
 	 * @param infringementSettings 	See {@link DBC.infringementSettings }.
 	 * @param executionSettings		See {@link DBC.executionSettings }. */
@@ -553,12 +676,44 @@ export class DBC {
 			},
 	) {
 		this.infringementSettings = infringementSettings;
-
-		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
-		if ((DBC.getHost() as any).WaXCode === undefined) (DBC.getHost() as any).WaXCode = {};
-		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
-		(DBC.getHost() as any).WaXCode.DBC = this;
-		DBC.dbcCache.set("WaXCode.DBC", this);
+		this.executionSettings = executionSettings;
+	}
+	/**
+	 * Registers a {@link DBC } instance at the specified dotted path on globalThis (or window),
+	 * making it available for decorator resolution via string paths.
+	 *
+	 * @param instance	The {@link DBC } instance to register.
+	 * @param path		The dotted path to register at (default: `"WaXCode.DBC"`). */
+	static register(instance: DBC, path = "WaXCode.DBC"): void {
+		const segments = path.split(".");
+		// biome-ignore lint/suspicious/noExplicitAny: Must walk dynamic global namespace.
+		let obj: any = DBC.getHost();
+		for (let i = 0; i < segments.length - 1; i++) {
+			if (obj[segments[i]] === undefined) obj[segments[i]] = {};
+			obj = obj[segments[i]];
+		}
+		obj[segments[segments.length - 1]] = instance;
+		DBC.dbcCache.set(path, instance);
+	}
+	/**
+	 * Executes a callback with an isolated {@link DBC } instance temporarily registered at the default path.
+	 * The previous instance (if any) is restored after the callback completes — even if it throws.
+	 * Useful for test isolation.
+	 *
+	 * @param fn The callback receiving the isolated {@link DBC } instance. */
+	static isolated(fn: (dbc: DBC) => void): void {
+		const saved = DBC.dbcCache.get("WaXCode.DBC");
+		const testDbc = new DBC();
+		DBC.register(testDbc);
+		try {
+			fn(testDbc);
+		} finally {
+			if (saved) {
+				DBC.register(saved);
+			} else {
+				DBC.dbcCache.delete("WaXCode.DBC");
+			}
+		}
 	}
 	/**
 	 * Resolves the desired {@link object } out a given one **toResolveFrom** using the specified **path**.
@@ -572,40 +727,53 @@ 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("."); // Handle indexers
+		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}".`);
+				}
+			}
+			DBC.evictIfNeeded(DBC.pathTokenCache);
 			DBC.pathTokenCache.set(path, parts);
 		}
 
-		let current = toResolveFrom;
+		// biome-ignore lint/suspicious/noExplicitAny: Must traverse arbitrary object graphs
+		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+)\((.*)\)/);
+
 			if (methodMatch) {
 				const methodName = methodMatch[1];
 				const argsStr = methodMatch[2];
-				const args = argsStr.split(",").map((arg) => arg.trim()); // Simple argument parsing
+				const args = argsStr.split(",").map((arg) => arg.trim());
+
 				if (typeof current[methodName] === "function") {
 					current = current[methodName].apply(current, args);
-				} else {
-					return undefined; // Method not found or not a function
-				}
+				} else { return undefined; }
 			} else {
-				current = current[part];
+				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; }
 			}
 		}
 
 		return current;
 	}
 }
-// Set the main instance with standard **DBC.infringementSettings**.
-new DBC();
+// Register the default instance with standard settings.
+DBC.register(new DBC());

package/tsconfig.json

@@ -4,14 +4,17 @@
 		"experimentalDecorators": true,
 		"emitDecoratorMetadata": true,
 		"outDir": "./dist",
+		"rootDir": "./src",
 		"esModuleInterop": true,
 		"module": "es6",
-		"moduleResolution": "node",
+		"moduleResolution": "bundler",
 		"typeRoots": []
 	},
-
 	"include": [
 		"./src/**/*.ts" // or your source directories
 	],
-	"exclude": ["node_modules", "__tests__"]
-}
+	"exclude": [
+		"node_modules",
+		"__tests__"
+	]
+}

package/tsconfig.test.json

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