xdbc 1.0.215 → 1.0.217

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "1.0.215",
+	"version": "1.0.217",
 	"name": "xdbc",
 	"main": "dist/bundle.js",
 	"types": "dist/DBC.d.ts",

package/src/DBC/ARR/PLAIN_OBJECT.ts

@@ -0,0 +1,133 @@
+import { DBC } from "../../DBC";
+import { ARRAY } from "../ARRAY";
+/**
+ * A {@link DBC } defining that a value must be a plain object — i.e. `typeof value === "object"`,
+ * not `null`, and not an array.
+ *
+ * @remarks
+ * Maintainer: Salvatore Callari (XDBC@WaXCode.net) */
+export class PLAIN_OBJECT extends ARRAY {
+	/**
+	 * Checks if the value **toCheck** is a plain object (non-null, non-array object).
+	 *
+	 * @param toCheck	The value to check.
+	 *
+	 * @returns TRUE if the value **toCheck** is a plain object, otherwise a string describing the infringement. */
+	// biome-ignore lint/suspicious/noExplicitAny: Necessary for dynamic type checking.
+	public static checkAlgorithm(toCheck: any): boolean | string {
+		if (toCheck === undefined || toCheck === null) return true;
+
+		if (typeof toCheck !== "object") {
+			return `Value has to be a PLAIN_OBJECT but is of type "${typeof toCheck}"`;
+		}
+
+		if (Array.isArray(toCheck)) {
+			return "Value has to be a PLAIN_OBJECT but is an ARRAY";
+		}
+
+		return true;
+	}
+	/**
+	 * A parameter-decorator factory using the {@link PLAIN_OBJECT.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged parameter.
+	 *
+	 * @param path	See {@link DBC.decPrecondition }.
+	 * @param hint	See {@link DBC.decPrecondition }.
+	 * @param dbc	See {@link DBC.decPrecondition }.
+	 *
+	 * @returns See {@link DBC.decPrecondition }. */
+	public static PRE(
+		path: string | undefined = undefined,
+		hint: string | undefined = undefined,
+		dbc: string | undefined = undefined,
+	): (
+		target: object,
+		methodName: string | symbol | undefined,
+		parameterIndex: number,
+	) => void {
+		return DBC.createPRE(PLAIN_OBJECT.checkAlgorithm, [], dbc, path, hint);
+	}
+	/**
+	 * A method-decorator factory using the {@link PLAIN_OBJECT.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged method's returnvalue.
+	 *
+	 * @param path	See {@link DBC.decPostcondition }.
+	 * @param hint	See {@link DBC.decPostcondition }.
+	 * @param dbc	See {@link DBC.decPostcondition }.
+	 *
+	 * @returns See {@link DBC.decPostcondition }. */
+	public static POST(
+		path: string | undefined = undefined,
+		hint: string | undefined = undefined,
+		dbc: string | undefined = undefined,
+	): (
+		target: object,
+		propertyKey: string,
+		descriptor: PropertyDescriptor,
+	) => PropertyDescriptor {
+		return DBC.createPOST(PLAIN_OBJECT.checkAlgorithm, [], dbc, path, hint);
+	}
+	/**
+	 * A field-decorator factory using the {@link PLAIN_OBJECT.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged field.
+	 *
+	 * @param path	See {@link DBC.decInvariant }.
+	 * @param hint	See {@link DBC.decInvariant }.
+	 * @param dbc	See {@link DBC.decInvariant }.
+	 *
+	 * @returns See {@link DBC.decInvariant }. */
+	public static INVARIANT(
+		path: string | undefined = undefined,
+		hint: string | undefined = undefined,
+		dbc: string | undefined = undefined,
+	) {
+		return DBC.createINVARIANT(PLAIN_OBJECT, [], dbc, path, hint);
+	}
+	// #endregion Condition checking.
+	// #region Referenced Condition checking.
+	//
+	// For usage in dynamic scenarios (like with AE-DBC).
+	//
+	/**
+	 * Invokes the {@link PLAIN_OBJECT.checkAlgorithm } passing the value **toCheck**.
+	 *
+	 * @param toCheck See {@link PLAIN_OBJECT.checkAlgorithm }.
+	 *
+	 * @returns See {@link PLAIN_OBJECT.checkAlgorithm}. */
+	// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+	public check(toCheck: any) {
+		return PLAIN_OBJECT.checkAlgorithm(toCheck);
+	}
+	/**
+	 * Invokes the {@link PLAIN_OBJECT.checkAlgorithm } passing the value **toCheck**.
+	 *
+	 * @param toCheck	See {@link PLAIN_OBJECT.checkAlgorithm }.
+	 * @param hint		An optional {@link string } providing extra information in case of an infringement.
+	 * @param id		A {@link string } identifying this {@link PLAIN_OBJECT } via the {@link DBC.Infringement }-Message.
+	 *
+	 * @returns The **CANDIDATE** **toCheck** if this {@link PLAIN_OBJECT } is fulfilled.
+	 *
+	 * @throws A {@link DBC.Infringement } if the **CANDIDATE** **toCheck** does not fulfill this {@link PLAIN_OBJECT }. */
+	public static tsCheck<CANDIDATE extends object = object>(
+		toCheck: CANDIDATE | undefined | null,
+		hint: string | undefined = undefined,
+		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
+	): CANDIDATE {
+		const result = PLAIN_OBJECT.checkAlgorithm(toCheck);
+
+		if (result === true) {
+			return toCheck as CANDIDATE;
+		}
+		DBC.reportTsCheckInfringement(
+			`${id ? `(${id}) ` : ""}${result as string}${hint ? ` ✨ ${hint} ✨` : ""}`,
+			dbc,
+		);
+		return toCheck as CANDIDATE;
+	}
+	/**
+	 * Creates this {@link PLAIN_OBJECT } instance. No parameters needed — the check is always the same. */
+	public constructor() {
+		super();
+	}
+}

package/src/DBC/ARRAY.ts

@@ -0,0 +1,127 @@
+import { DBC } from "../DBC";
+/**
+ * A {@link DBC } defining that a value must be an array.
+ *
+ * @remarks
+ * Maintainer: Salvatore Callari (XDBC@WaXCode.net) */
+export class ARRAY extends DBC {
+	/**
+	 * Checks if the value **toCheck** is an array.
+	 *
+	 * @param toCheck	The value to check.
+	 *
+	 * @returns TRUE if the value **toCheck** is an array, otherwise a string describing the infringement. */
+	// biome-ignore lint/suspicious/noExplicitAny: Necessary for dynamic type checking.
+	public static checkAlgorithm(toCheck: any): boolean | string {
+		if (toCheck === undefined || toCheck === null) return true;
+
+		if (!Array.isArray(toCheck)) {
+			return `Value has to be an ARRAY but is of type "${typeof toCheck}"`;
+		}
+
+		return true;
+	}
+	/**
+	 * A parameter-decorator factory using the {@link ARRAY.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged parameter.
+	 *
+	 * @param path	See {@link DBC.decPrecondition }.
+	 * @param hint	See {@link DBC.decPrecondition }.
+	 * @param dbc	See {@link DBC.decPrecondition }.
+	 *
+	 * @returns See {@link DBC.decPrecondition }. */
+	public static PRE(
+		path: string | undefined = undefined,
+		hint: string | undefined = undefined,
+		dbc: string | undefined = undefined,
+	): (
+		target: object,
+		methodName: string | symbol | undefined,
+		parameterIndex: number,
+	) => void {
+		return DBC.createPRE(ARRAY.checkAlgorithm, [], dbc, path, hint);
+	}
+	/**
+	 * A method-decorator factory using the {@link ARRAY.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged method's returnvalue.
+	 *
+	 * @param path	See {@link DBC.decPostcondition }.
+	 * @param hint	See {@link DBC.decPostcondition }.
+	 * @param dbc	See {@link DBC.decPostcondition }.
+	 *
+	 * @returns See {@link DBC.decPostcondition }. */
+	public static POST(
+		path: string | undefined = undefined,
+		hint: string | undefined = undefined,
+		dbc: string | undefined = undefined,
+	): (
+		target: object,
+		propertyKey: string,
+		descriptor: PropertyDescriptor,
+	) => PropertyDescriptor {
+		return DBC.createPOST(ARRAY.checkAlgorithm, [], dbc, path, hint);
+	}
+	/**
+	 * A field-decorator factory using the {@link ARRAY.checkAlgorithm } to determine whether this {@link DBC } is fulfilled
+	 * by the tagged field.
+	 *
+	 * @param path	See {@link DBC.decInvariant }.
+	 * @param hint	See {@link DBC.decInvariant }.
+	 * @param dbc	See {@link DBC.decInvariant }.
+	 *
+	 * @returns See {@link DBC.decInvariant }. */
+	public static INVARIANT(
+		path: string | undefined = undefined,
+		hint: string | undefined = undefined,
+		dbc: string | undefined = undefined,
+	) {
+		return DBC.createINVARIANT(ARRAY, [], dbc, path, hint);
+	}
+	// #endregion Condition checking.
+	// #region Referenced Condition checking.
+	//
+	// For usage in dynamic scenarios (like with AE-DBC).
+	//
+	/**
+	 * Invokes the {@link ARRAY.checkAlgorithm } passing the value **toCheck**.
+	 *
+	 * @param toCheck See {@link ARRAY.checkAlgorithm }.
+	 *
+	 * @returns See {@link ARRAY.checkAlgorithm}. */
+	// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+	public check(toCheck: any) {
+		return ARRAY.checkAlgorithm(toCheck);
+	}
+	/**
+	 * Invokes the {@link ARRAY.checkAlgorithm } passing the value **toCheck**.
+	 *
+	 * @param toCheck	See {@link ARRAY.checkAlgorithm }.
+	 * @param hint		An optional {@link string } providing extra information in case of an infringement.
+	 * @param id		A {@link string } identifying this {@link ARRAY } via the {@link DBC.Infringement }-Message.
+	 *
+	 * @returns The **CANDIDATE** **toCheck** if this {@link ARRAY } is fulfilled.
+	 *
+	 * @throws A {@link DBC.Infringement } if the **CANDIDATE** **toCheck** does not fulfill this {@link ARRAY }. */
+	public static tsCheck<CANDIDATE extends unknown[] = unknown[]>(
+		toCheck: CANDIDATE | undefined | null,
+		hint: string | undefined = undefined,
+		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
+	): CANDIDATE {
+		const result = ARRAY.checkAlgorithm(toCheck);
+
+		if (result === true) {
+			return toCheck as CANDIDATE;
+		}
+		DBC.reportTsCheckInfringement(
+			`${id ? `(${id}) ` : ""}${result as string}${hint ? ` ✨ ${hint} ✨` : ""}`,
+			dbc,
+		);
+		return toCheck as CANDIDATE;
+	}
+	/**
+	 * Creates this {@link ARRAY } instance.  No parameters needed — the check is always {@link Array.isArray }. */
+	public constructor() {
+		super();
+	}
+}

package/src/DBC/DEFINED.ts

@@ -106,14 +106,17 @@ export class DEFINED extends DBC {
 		toCheck: CANDIDATE | undefined | null,
 		hint: string | undefined = undefined,
 		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
 	): CANDIDATE {
 		const result = DEFINED.checkAlgorithm(toCheck);
 
 		if (result === true) {
 			return toCheck as CANDIDATE;
 		}
-		throw new DBC.Infringement(
+		DBC.reportTsCheckInfringement(
 			`${id ? `(${id}) ` : ""}${result as string}${hint ? ` ✨ ${hint} ✨` : ""}`,
+			dbc,
 		);
+		return toCheck as CANDIDATE;
 	}
 }

package/src/DBC/EQ.ts

@@ -135,15 +135,18 @@ export class EQ extends DBC {
 		equivalent: any,
 		hint: string | undefined = undefined,
 		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
 	): CANDIDATE {
 		const result = EQ.checkAlgorithm(toCheck, equivalent, false);
 
-		if (result) {
+		if (result === true) {
 			return toCheck as CANDIDATE;
 		}
-		throw new DBC.Infringement(
+		DBC.reportTsCheckInfringement(
 			`${id ? `(${id}) ` : ""}${result as string} ${hint ? `✨ ${hint} ✨` : ""}`,
+			dbc,
 		);
+		return toCheck as CANDIDATE;
 	}
 	/**
 	 * Creates this {@link EQ } by setting the protected property {@link EQ.equivalent } used by {@link EQ.check }.

package/src/DBC/INSTANCE.ts

@@ -127,8 +127,9 @@ export class INSTANCE extends DBC {
 		reference: any,
 		hint: string = undefined,
 		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
 	): CANDIDATE {
-		return INSTANCE.tsCheckMulti<CANDIDATE>(toCheck, [reference], hint, id);
+		return INSTANCE.tsCheckMulti<CANDIDATE>(toCheck, [reference], hint, id, dbc);
 	}
 	/**
 	 * Invokes the {@link INSTANCE.checkAlgorithm } passing the value **toCheck** and the {@link INSTANCE.reference } .
@@ -146,15 +147,18 @@ export class INSTANCE extends DBC {
 		references: any[],
 		hint: string = undefined,
 		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
 	): CANDIDATE {
 		const result = INSTANCE.checkAlgorithm(toCheck, ...references);
 
 		if (result === true) {
 			return toCheck;
 		}
-		throw new DBC.Infringement(
+		DBC.reportTsCheckInfringement(
 			`${id ? `(${id}) ` : ""}${result as string} ${hint ? `✨ ${hint} ✨` : ""}`,
+			dbc,
 		);
+		return toCheck as CANDIDATE;
 	}
 	/**
 	 * Creates this {@link INSTANCE } by setting the protected property {@link INSTANCE.reference } used by {@link INSTANCE.check }.

package/src/DBC/JSON.OP.ts

@@ -170,6 +170,7 @@ export class JSON_OP extends DBC {
 		toCheck: any,
 		necessaryProperties: Array<{ name: string; type: string }>,
 		checkElements = false,
+		dbc: string | undefined = undefined,
 	) {
 		const checkResult = JSON_OP.checkAlgorithm(
 			toCheck,
@@ -178,7 +179,7 @@ export class JSON_OP extends DBC {
 		);
 
 		if (typeof checkResult === "string") {
-			throw new DBC.Infringement(checkResult);
+			DBC.reportTsCheckInfringement(checkResult, dbc);
 		}
 	}
 	// #endregion In-Method checking.

package/src/DBC/JSON.Parse.ts

@@ -145,11 +145,12 @@ export class JSON_Parse extends DBC {
 		// biome-ignore lint/suspicious/noExplicitAny: <explanation>
 		toCheck: any,
 		receptor: (json: object) => void,
+		dbc: string | undefined = undefined,
 	) {
 		const checkResult = JSON_Parse.checkAlgorithm(toCheck, receptor);
 
 		if (typeof checkResult === "string") {
-			throw new DBC.Infringement(checkResult);
+			DBC.reportTsCheckInfringement(checkResult, dbc);
 		}
 	}
 	// #endregion In-Method checking.

package/src/DBC/OR.ts

@@ -159,15 +159,18 @@ export class OR extends DBC {
 		}>,
 		hint: string = undefined,
 		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
 	): CANDIDATE {
 		const result = OR.checkAlgorithm(conditions, toCheck);
 
 		if (result === true) {
 			return toCheck as CANDIDATE;
 		}
-		throw new DBC.Infringement(
+		DBC.reportTsCheckInfringement(
 			`${id ? `(${id}) ` : ""}${result as string}${hint ? ` ✨ ${hint} ✨` : ""}`,
+			dbc,
 		);
+		return toCheck as CANDIDATE;
 	}
 	/**
 	 * Creates this {@link OR } by setting the protected property {@link OR.conditions } used by {@link OR.check }.

package/src/DBC/REGEX.ts

@@ -157,15 +157,18 @@ export class REGEX extends DBC {
 		expression: RegExp,
 		hint: string | undefined = undefined,
 		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
 	): CANDIDATE {
 		const result = REGEX.checkAlgorithm(toCheck, expression);
 
 		if (result === true) {
 			return toCheck;
 		}
-		throw new DBC.Infringement(
+		DBC.reportTsCheckInfringement(
 			`${id ? `(${id}) ` : ""}${result as string}${hint ? ` ✨ ${hint} ✨` : ""}`,
+			dbc,
 		);
+		return toCheck as CANDIDATE;
 	}
 	/**
 	 * Creates this {@link REGEX } by setting the protected property {@link REGEX.expression } used by {@link REGEX.check }.
@@ -182,11 +185,11 @@ export class REGEX extends DBC {
 	 * @param toCheck		See {@link REGEX.checkAlgorithm}.
 	 * @param expression	See {@link REGEX.checkAlgorithm}.
 	 */
-	public static check(toCheck: unknown | null | undefined, expression: RegExp) {
+	public static check(toCheck: unknown | null | undefined, expression: RegExp, dbc: string | undefined = undefined) {
 		const checkResult = REGEX.checkAlgorithm(toCheck, expression);
 
 		if (typeof checkResult === "string") {
-			throw new DBC.Infringement(checkResult);
+			DBC.reportTsCheckInfringement(checkResult, dbc);
 		}
 	}
 	// #endregion In-Method checking.

package/src/DBC/TYPE.ts

@@ -126,15 +126,18 @@ export class TYPE extends DBC {
 		type: string,
 		hint: string | undefined = undefined,
 		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
 	): CANDIDATE {
 		const result = TYPE.checkAlgorithm(toCheck, type);
 
 		if (result === true) {
 			return toCheck;
 		}
-		throw new DBC.Infringement(
+		DBC.reportTsCheckInfringement(
 			`${id ? `(${id}) ` : ""}${result as string}${hint ? ` ✨ ${hint} ✨` : ""}`,
+			dbc,
 		);
+		return toCheck as CANDIDATE;
 	}
 	/**
 	 * Creates this {@link TYPE } by setting the protected property {@link TYPE.type } used by {@link TYPE.check }.

package/src/DBC/UNDEFINED.ts

@@ -104,12 +104,14 @@ export class UNDEFINED extends DBC {
 	public static tsCheck<CANDIDATE = unknown>(
 		toCheck: CANDIDATE | undefined | null,
 		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
 	): CANDIDATE {
 		const result = UNDEFINED.checkAlgorithm(toCheck);
 
 		if (result === true) {
 			return toCheck as CANDIDATE;
 		}
-		throw new DBC.Infringement(`${id ? `(${id}) ` : ""}${result as string}`);
+		DBC.reportTsCheckInfringement(`${id ? `(${id}) ` : ""}${result as string}`, dbc);
+		return toCheck as CANDIDATE;
 	}
 }

package/src/DBC/ZOD.ts

@@ -114,13 +114,15 @@ export class ZOD extends DBC {
 		toCheck: any,
 		schema: z.ZodType,
 		id: string | undefined = undefined,
+		dbc: string | undefined = undefined,
 	): CANDIDATE {
 		const result = ZOD.checkAlgorithm(toCheck, schema);
 
 		if (result === true) {
 			return toCheck;
 		}
-		throw new DBC.Infringement(`${id ? `(${id}) ` : ""}${result as string}`);
+		DBC.reportTsCheckInfringement(`${id ? `(${id}) ` : ""}${result as string}`, dbc);
+		return toCheck as CANDIDATE;
 	}
 	/**
 	 * Creates this {@link ZOD } by setting the protected property {@link ZOD.schema } used by {@link ZOD.check }.

package/src/DBC.ts

@@ -697,6 +697,33 @@ export class DBC {
 			hint,
 		);
 	}
+	/**
+	 * Routes an imperative infringement (from {@link tsCheck } or static {@link check } calls) through the
+	 * registered DBC instance's {@link infringementSettings }, respecting whether to throw, log, or both.
+	 * Falls back to throwing {@link DBC.Infringement } directly if no DBC instance is registered at the
+	 * specified path, preserving the pre-existing behaviour for code that does not register a DBC instance.
+	 *
+	 * @param message	The fully formatted infringement message.
+	 * @param dbc		The path to the DBC instance. Defaults to `"WaXCode.DBC"`. */
+	public static reportTsCheckInfringement(
+		message: string,
+		dbc: string | undefined = undefined,
+	): void {
+		let dbcInstance: DBC | undefined;
+		try {
+			dbcInstance = DBC.getDBC(dbc);
+		} catch {
+			throw new DBC.Infringement(message);
+		}
+
+		if (dbcInstance.infringementSettings.throwException) {
+			throw new DBC.Infringement(message);
+		}
+
+		if (dbcInstance.infringementSettings.logToConsole) {
+			console.log(message);
+		}
+	}
 	// #region Classes
 	// #region Errors
 	/** An {@link Error } to be thrown whenever an infringement is detected. */