@cqse/commons 1.0.0-beta.7 → 1.0.4

package/lib/index.mjs

@@ -0,0 +1,822 @@
+import process from "node:process";
+import { createHash } from "node:crypto";
+
+//#region src/Exceptions.ts
+/**
+* Excepting signaling that there is functionality that is supposed
+* to be implemented in case the exception is thrown.
+*
+* This is helpful for writing prototypes and not yet handling all possible cases.
+*/
+var ImplementMeException = class extends Error {
+	constructor(implementMeFor) {
+		super("Implement me!");
+		this._implementMeFor = implementMeFor;
+	}
+	get message() {
+		if (this._implementMeFor) return `Implement me for: ${this._implementMeFor}`;
+		else return "Implement me!";
+	}
+};
+/**
+* Exception signaling that the application is in an invalid state.
+*/
+var IllegalStateException = class extends Error {};
+/**
+* Exception signaling that an invalid argument has been passed for a parameter.
+*/
+var IllegalArgumentException = class extends Error {};
+/**
+* Exception signaling that a component is mis-configured.
+*/
+var InvalidConfigurationException = class extends Error {};
+
+//#endregion
+//#region src/Contract.ts
+/**
+* Methods to express and check code contracts.
+*/
+var Contract = class {
+	/**
+	* The given predicate `condition` has to be satisfied.
+	*
+	* @param condition Condition predicate (boolean value)
+	* @param message Message describing the condition.
+	*/
+	static require(condition, message) {
+		if (!condition) throw new IllegalArgumentException(message);
+	}
+	/**
+	* Require that the given argument `obj` is defined.
+	*
+	* @param obj The object that has to be defined.
+	* @param message The message describing this requirement.
+	*/
+	static requireDefined(obj, message) {
+		if (obj) return obj;
+		if (typeof obj === "number" || typeof obj === "boolean") return obj;
+		if (typeof obj === "string" || obj instanceof String) return obj;
+		if (message) throw new IllegalArgumentException(message);
+		else throw new IllegalArgumentException("Reference must be defined.");
+	}
+	/**
+	* Require that the given string is not empty.
+	*
+	* @param text The string to check.
+	* @param message The message that describes the requirement.
+	*/
+	static requireNonEmpty(text, message) {
+		this.requireDefined(text);
+		if (text.length === 0) throw new IllegalArgumentException(message);
+		return text;
+	}
+	/**
+	* Require that the string adheres to a particular pattern.
+	*
+	* @param text The string to check.
+	* @param regexp The regular expression to satisfy.
+	* @param message The message describing the requirement.
+	*/
+	static requireStringPattern(text, regexp, message) {
+		this.requireDefined(text);
+		this.requireDefined(regexp);
+		if (!text.match(regexp)) throw new IllegalArgumentException(message);
+		return text;
+	}
+};
+
+//#endregion
+//#region src/Strings.ts
+/**
+* Remove the given prefix, if present, from the given string.
+*
+* @param prefix - The prefix to remove.
+* @param removeFrom - The string to remove the prefix from.
+*
+* @returns a new string where the prefix is removed.
+*/
+function removePrefix(prefix, removeFrom) {
+	if (removeFrom.startsWith(prefix)) return removeFrom.substring(prefix.length);
+	return removeFrom;
+}
+
+//#endregion
+//#region src/ConfigParser.ts
+/**
+* Configuration parser module that handles command-line arguments, environment variables,
+* and configuration files for TypeScript/JavaScript applications.
+*
+* @module ConfigParser
+*/
+/** Parameter group for --version and --help */
+const CONFIG_GROUP_APP = {
+	order: 999,
+	title: "Application"
+};
+function expectedArgumentCount(parameterDescriptor) {
+	if (parameterDescriptor.type === "int" || parameterDescriptor.type === "string") return 1;
+	else if (parameterDescriptor.type === "bool") return 0;
+	else if (parameterDescriptor.type === "string[]") return Number.POSITIVE_INFINITY;
+	else throw new InvalidConfigurationException(`Unsupported parameter type "${parameterDescriptor.type}" for parameter "${parameterDescriptor.longParameter}".`);
+}
+/**
+* Converts a parameter name (with dashes) to a camelCase parameter ID.
+*
+* @param parameterName - The parameter name to convert (e.g., --my-param)
+* @returns The camelCase parameter ID (e.g., myParam)
+*/
+function parameterNameToParameterId(parameterName) {
+	return parameterName.replace(/^-+/, "").replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}
+/**
+* Converts a long parameter name to an environment variable name.
+*
+* @param longParameter - The long parameter name (e.g., --my-param)
+* @returns The environment variable name (e.g., MY_PARAM)
+*/
+function longParameterToEnvironmentVariableName(longParameter) {
+	return longParameter.replace(/^--/, "").toUpperCase().replace(/-/g, "_");
+}
+/**
+* Manages configuration parameters and their properties.
+* Provides functionality to add, describe, and parse parameters.
+*/
+var ConfigurationParameters = class ConfigurationParameters {
+	constructor() {
+		this.parameters = /* @__PURE__ */ new Map();
+		this.shortToLongParameterMap = /* @__PURE__ */ new Map();
+		this.sequentialParameters = [];
+		this.argumentChecks = [];
+	}
+	/**
+	* Adds a new parameter to the configuration.
+	*
+	* @param shortParameter - Optional short form of the parameter (e.g., -p)
+	* @param longParameter - Long form of the parameter (e.g., --port)
+	* @param type - Parameter's data type
+	* @param options - Additional parameter options including a help text and default value
+	*/
+	addParameter(shortParameter, longParameter, type, options = {}) {
+		const parameterId = parameterNameToParameterId(longParameter);
+		const environmentVariableName = longParameterToEnvironmentVariableName(longParameter);
+		this.describeParameter(parameterId, {
+			parameterId,
+			longParameter,
+			type,
+			shortParameter,
+			help: options.help ?? "",
+			default: options.default,
+			internal: options.internal ?? false,
+			group: options.group,
+			environmentVariableName
+		});
+	}
+	/**
+	* Adds a new argument check function to the list of checks.
+	*
+	* @param check - A function that takes an options object as input and returns a string containing an
+	* error message if a validation fails, or undefined if the validation passes.
+	*/
+	addArgumentCheck(check) {
+		this.argumentChecks.push(check);
+	}
+	/**
+	* Makes the given parameter mandatory.
+	*/
+	addRequiredArgumentFor(parameterId) {
+		const parameter = this.lookupParameter(parameterId);
+		if (parameter === void 0) throw new InvalidConfigurationException(`Unknown parameter "${parameterId}".`);
+		if (parameter.default !== void 0) throw new InvalidConfigurationException(`Parameter "${parameterId}" is required, but has a default value.`);
+		this.argumentChecks.push((parsedArguments) => {
+			if (parsedArguments[parameterId] === void 0) return `Missing required argument for parameter "${parameter.longParameter}"\n\tParameter description: ${parameter.help}`;
+		});
+	}
+	/**
+	* Describes a parameter with its complete set of properties.
+	*
+	* @param parameterId - Internal identifier for the parameter
+	* @param descriptor - Complete parameter descriptor
+	* @throws Error if short parameter is invalid or already mapped
+	*/
+	describeParameter(parameterId, descriptor) {
+		this.parameters.set(parameterId, descriptor);
+		if (descriptor.shortParameter) {
+			const shortParameterId = descriptor.shortParameter.replace(/^-/, "").trim().toLowerCase();
+			if (shortParameterId.length < 1 || shortParameterId.length > 3) throw new InvalidConfigurationException(`Short parameter "${shortParameterId}" is invalid.`);
+			const existingMapping = this.shortToLongParameterMap.get(shortParameterId);
+			if (existingMapping !== void 0 && existingMapping !== parameterId) throw new InvalidConfigurationException(`Short parameter "${shortParameterId}" is already mapped to parameter "${existingMapping}".`);
+			this.shortToLongParameterMap.set(shortParameterId, descriptor.parameterId);
+		}
+		if (!descriptor.longParameter.startsWith("--")) this.sequentialParameters.push(parameterId);
+	}
+	/**
+	* Looks up a parameter descriptor by its ID.
+	*
+	* @param parameterId - Parameter identifier to look up
+	* @returns Parameter descriptor if found, undefined otherwise
+	*/
+	lookupParameter(parameterId) {
+		let result = this.parameters.get(parameterId);
+		if (result === void 0) {
+			const longParameterId = this.shortToLongParameterMap.get(parameterId);
+			if (longParameterId !== void 0) result = this.parameters.get(longParameterId);
+		}
+		return result;
+	}
+	/**
+	* Returns all registered parameter descriptors.
+	*
+	* @returns Array of all parameter descriptors
+	*/
+	getParameters() {
+		return Array.from(this.parameters.values());
+	}
+	/**
+	* Retrieves the collection of functions used for argument validation.
+	*/
+	getArgumentChecks() {
+		return this.argumentChecks;
+	}
+	/**
+	* Returns an array of parameter IDs that are configured as sequential parameters.
+	* That is, parameters that are given without a name but where their mapping
+	* to concrete parameters is defined by their position in the command line.
+	*/
+	getSequentialParameters() {
+		return this.sequentialParameters;
+	}
+	/**
+	* @returns A new configuration object with the same parameters as this one.
+	*/
+	clone() {
+		const clone = new ConfigurationParameters();
+		for (const parameter of this.parameters.values()) clone.describeParameter(parameter.parameterId, parameter);
+		for (const check of this.argumentChecks) clone.addArgumentCheck(check);
+		return clone;
+	}
+	/**
+	* Adds all parameters and checks from the given configuration to this one.
+	*/
+	addAllOf(toAdd) {
+		for (const parameter of toAdd.getParameters()) this.describeParameter(parameter.parameterId, parameter);
+		for (const check of toAdd.getArgumentChecks()) this.addArgumentCheck(check);
+	}
+};
+/**
+* Parses command line arguments according to parameter definitions.
+*
+* @param args - Array of command line arguments to parse
+* @param parameters - Configuration parameters defining valid options
+* @returns Parsed options object with parameter values
+* @throws Error if parameter values are invalid or missing
+*/
+function parseArguments(args, parameters) {
+	const result = {};
+	let activeParameter;
+	let activeArguments = [];
+	let awaitingArguments = 0;
+	function finishParameter() {
+		if (!activeParameter) return;
+		if (awaitingArguments < Number.POSITIVE_INFINITY && awaitingArguments > 0) throw new InvalidConfigurationException(`Missing value for parameter "${activeParameter.longParameter}".`);
+		if (activeParameter.type === "bool") {
+			result[activeParameter.parameterId] = true;
+			activeParameter = void 0;
+		} else if (activeParameter.type === "string[]") {
+			const targetList = result[activeParameter.parameterId];
+			const argumentsNormalizedAsList = parseStringListArgument(activeArguments.join(","));
+			if (isDefinedStringList(targetList)) result[activeParameter.parameterId] = targetList.concat(argumentsNormalizedAsList);
+			else result[activeParameter.parameterId] = argumentsNormalizedAsList;
+		} else {
+			if (activeArguments.length !== 1) throw new InvalidConfigurationException(`Invalid value for parameter "${activeParameter.longParameter}": Expected a single value, got ${activeArguments.length}.`);
+			result[activeParameter.parameterId] = parseWithProperType(activeArguments[0], activeParameter);
+		}
+		activeParameter = void 0;
+		activeArguments = [];
+	}
+	for (const argument of args) {
+		if (argument.startsWith("-")) {
+			finishParameter();
+			const parameterId = parameterNameToParameterId(argument);
+			activeParameter = parameters.lookupParameter(parameterId);
+			if (!activeParameter) throw new InvalidConfigurationException(`Unknown configuration parameter: ${argument}`);
+			awaitingArguments = expectedArgumentCount(activeParameter);
+		} else {
+			if (!activeParameter) throw new InvalidConfigurationException(`Unexpected or unnamed argument, or unknown parameter '${argument}' supplied. Please specify a parameter name (for example, --input) for each argument.`);
+			activeArguments.push(argument);
+			awaitingArguments--;
+		}
+		if (awaitingArguments === 0) finishParameter();
+	}
+	finishParameter();
+	for (const parameter of parameters.getParameters()) if (result[parameter.parameterId] === void 0) {
+		result[parameter.parameterId] = parameter.default;
+		const environmentValue = process.env[parameter.environmentVariableName];
+		if (environmentValue && !parameter.disableEnvironmentVariableOverride) result[parameter.parameterId] = parseWithProperType(environmentValue, parameter);
+	}
+	return result;
+}
+function unquoteString(text) {
+	text = text.trim();
+	if (text.startsWith("\"") && text.endsWith("\"") || text.startsWith("'") && text.endsWith("'") || text.startsWith("`") && text.endsWith("`")) return text.substring(1, text.length - 1);
+	else return text;
+}
+function parseStringListArgument(value) {
+	if (!value) return [];
+	return value.split(",").map((item) => unquoteString(item));
+}
+function parseWithProperType(value, parameterDescriptor) {
+	if (parameterDescriptor.type === "int") {
+		const parsedValue = parseInt(value, 10);
+		if (isNaN(parsedValue)) throw new InvalidConfigurationException(`Invalid value for parameter "${parameterDescriptor.longParameter}": Expected an integer, got "${value}".`);
+		return parsedValue;
+	} else if (parameterDescriptor.type === "bool") {
+		const lowerValue = value.toLowerCase();
+		if (lowerValue === "true" || lowerValue === "1") return true;
+		else if (lowerValue === "false" || lowerValue === "0") return false;
+		else throw new InvalidConfigurationException(`Invalid value for parameter "${parameterDescriptor.longParameter}": Expected a boolean, got "${value}".`);
+	} else if (parameterDescriptor.type === "string") return unquoteString(value);
+	else if (parameterDescriptor.type === "string[]") return parseStringListArgument(value);
+	else throw new InvalidConfigurationException(`Unsupported parameter type "${parameterDescriptor.type}" for parameter "${parameterDescriptor.longParameter}".`);
+}
+function isDefinedStringList(option) {
+	return Array.isArray(option) && option.every((item) => typeof item === "string");
+}
+/**
+* Parses a configuration file content into options and unnamed arguments.
+*
+* @param fileContent - Content of the configuration file to parse
+* @param parameters - Configuration parameters defining valid options
+* @returns Object containing parsed options and unnamed arguments
+* @throws Error if the configuration file contains invalid parameters or values
+*/
+function parseConfigFile(fileContent, parameters) {
+	const options = {};
+	const unnamedArguments = [];
+	for (const line of fileContent.split("\n")) {
+		const trimmedLine = line.trim();
+		if (trimmedLine.startsWith("#") || trimmedLine.length === 0) continue;
+		if (!trimmedLine.includes("=") && parameters.getSequentialParameters().length > 0) {
+			unnamedArguments.push(trimmedLine);
+			continue;
+		}
+		const [key, value] = trimmedLine.split("=");
+		const parameterId = parameterNameToParameterId(key);
+		const parameterDescriptor = parameters.lookupParameter(parameterId);
+		if (parameterDescriptor) if (isDefinedStringList(options[parameterId]) && parameterDescriptor.type === "string[]") {
+			const newListValue = parseWithProperType(value, parameterDescriptor);
+			if (isDefinedStringList(newListValue)) options[parameterId] = options[parameterId].concat(newListValue);
+			else throw new InvalidConfigurationException(`Invalid value for parameter "${parameterDescriptor.longParameter}": Expected a list of strings, got "${value}".`);
+		} else options[parameterId] = parseWithProperType(value, parameterDescriptor);
+		else throw new InvalidConfigurationException(`Unknown configuration parameter: ${key}`);
+	}
+	return {
+		options,
+		unnamedArguments
+	};
+}
+/**
+* Prints help information for all registered parameters.
+*
+* @param parameters - Configuration parameters to display help for
+* @param aboutText - Optional descriptive text to display before parameter help
+* @param printParamterId - Print the ID of the parameter instead of the command line parameter names?
+*/
+function printHelp(parameters, aboutText, printParamterId = false) {
+	const lines = [];
+	if (aboutText) {
+		lines.push(aboutText);
+		lines.push("");
+	}
+	if (!printParamterId) lines.push("Usage:");
+	const grouped = groupAndSortParameterDescriptors(parameters);
+	for (const group of grouped) {
+		if (group.groupTitle) {
+			lines.push("");
+			lines.push(`# ${group.groupTitle}`);
+			lines.push("");
+		}
+		if (group.groupHint) {
+			lines.push(restrictLineLengthTo(group.groupHint, 80));
+			lines.push("");
+		}
+		for (const descriptor of group.parameters) {
+			if (descriptor.internal) continue;
+			function getArgumentPlaceholder() {
+				const singleArgumentName = descriptor.environmentVariableName;
+				if (descriptor.type === "bool") return "";
+				else if (descriptor.type === "string[]") return ` ${singleArgumentName}, .., ${singleArgumentName}`;
+				else return ` ${singleArgumentName}`;
+			}
+			const options = [];
+			if (printParamterId) options.push(`Parameter "${descriptor.parameterId}" (${descriptor.type})`);
+			else {
+				if (descriptor.shortParameter) options.push(`${descriptor.shortParameter}${getArgumentPlaceholder()}`);
+				options.push(`${descriptor.longParameter}${getArgumentPlaceholder()}`);
+			}
+			const help = ensureTabAfterNewline(restrictLineLengthTo(descriptor.help, 80));
+			const defaultValue = descriptor.default ? `Default: ${descriptor.default}` : void 0;
+			lines.push(`  ${options.join(", ")}`);
+			if (help) lines.push(`\t${help}`);
+			if (defaultValue) lines.push(`\t${defaultValue}`);
+		}
+	}
+	lines.push("");
+	console.log(lines.join("\n"));
+}
+/**
+* Add breaks after words (replace space by newline) in case a sentence gets longer
+* on one line than the specified `maxLineLength`.
+*/
+function restrictLineLengthTo(text, maxLineLength) {
+	text = text.replace(/\n/g, " ");
+	const words = text.split(" ");
+	const lines = [];
+	let currentLine = "";
+	for (const word of words) {
+		if (currentLine.length + word.length + 1 > maxLineLength) {
+			lines.push(currentLine);
+			currentLine = "";
+		}
+		if (currentLine.length > 0) currentLine += " ";
+		currentLine += word;
+	}
+	if (currentLine.length > 0) lines.push(currentLine);
+	return lines.join("\n");
+}
+function ensureTabAfterNewline(text) {
+	if (!text) return;
+	return text.replace(/\n/g, "\n	");
+}
+function groupAndSortParameterDescriptors(parameters) {
+	const parametersByGroup = /* @__PURE__ */ new Map();
+	const groupOrders = /* @__PURE__ */ new Map();
+	const groupHints = /* @__PURE__ */ new Map();
+	for (const parameter of parameters.getParameters()) {
+		const groupTitle = parameter.group?.title;
+		if (parameter.group) groupOrders.set(groupTitle, parameter.group.order);
+		if (parameter.group?.hints) groupHints.set(groupTitle, parameter.group?.hints);
+		const groupParameters = parametersByGroup.get(groupTitle) || [];
+		groupParameters.push(parameter);
+		parametersByGroup.set(groupTitle, groupParameters);
+	}
+	return Array.from(parametersByGroup.entries()).sort(([groupTitle1], [groupTitle2]) => {
+		return (groupOrders.get(groupTitle1) ?? Number.MAX_VALUE) - (groupOrders.get(groupTitle2) ?? Number.MAX_VALUE);
+	}).map(([groupTitle, parameters$1]) => ({
+		groupTitle,
+		groupHint: groupHints.get(groupTitle),
+		parameters: parameters$1.sort((a, b) => a.longParameter.localeCompare(b.longParameter))
+	}));
+}
+/**
+* Runs the config parameter checks for the given options.
+*/
+function checkArguments(configParameters, options, errorReceiver) {
+	let argumentsValid = true;
+	if (!errorReceiver) errorReceiver = (error) => {
+		console.error(error);
+	};
+	for (const argumentCheck of configParameters.getArgumentChecks()) {
+		const checkError = argumentCheck(options);
+		if (checkError) {
+			errorReceiver("Invalid configuration: " + checkError);
+			argumentsValid = false;
+		}
+	}
+	return argumentsValid;
+}
+/**
+* Parses the command-line arguments.
+*/
+function processCommandLine(parameters, appInfos, args, beforeCheckCallback) {
+	args = args ?? process.argv.slice(2);
+	const configParameters = parameters.clone();
+	configParameters.addParameter("-h", "--help", "bool", {
+		help: "Show this help message and exit.",
+		group: CONFIG_GROUP_APP,
+		disableEnvironmentVariableOverride: true
+	});
+	configParameters.addParameter("-v", "--version", "bool", {
+		help: "Show the version number and exit.",
+		group: CONFIG_GROUP_APP,
+		disableEnvironmentVariableOverride: true
+	});
+	const options = parseArguments(args, configParameters);
+	if (options.version) {
+		console.log(`${appInfos.name} v${appInfos.version}`);
+		process.exit(0);
+	}
+	if (options.help) {
+		printHelp(configParameters, appInfos.about);
+		process.exit(0);
+	}
+	if (beforeCheckCallback) beforeCheckCallback(options);
+	if (!checkArguments(configParameters, options)) {
+		console.error("\nArguments were missing or invalid. Please check the --help for more information. Exiting with error code 1.");
+		process.exit(1);
+	}
+	return options;
+}
+/**
+* Creates a new configuration object by merging two configuration objects.
+*/
+function parameterUnion(parameters1, parameters2) {
+	const result = parameters1.clone();
+	result.addAllOf(parameters2);
+	return result;
+}
+
+//#endregion
+//#region src/ConfigWithOverwrites.ts
+/**
+* Configuration with a possibility to overwrite configuration values for this app run,
+* delegating to the base configuration if no overwrite was performed.
+* For type-safe access, use `makeConfigProxy` to create a proxy object.
+*/
+var ConfigurationWithOverwrites = class ConfigurationWithOverwrites {
+	constructor(allParameters, redefinableParameters, baseConfiguration, overwrites) {
+		this.baseConfiguration = Contract.requireDefined(baseConfiguration);
+		this.redefinableParameters = Contract.requireDefined(redefinableParameters);
+		this.allParameters = Contract.requireDefined(allParameters);
+		this.overwrites = overwrites ?? {};
+		this.hash = void 0;
+	}
+	/**
+	* Retrieves the value of a configuration parameter based on the provided parameter ID.
+	*/
+	get(parameterId) {
+		this.assertParameterExists(parameterId);
+		return this.overwrites[parameterId] ?? this.baseConfiguration[parameterId];
+	}
+	/**
+	* Sets the specified parameter with a given value in the `overwrites` map.
+	*/
+	set(parameterId, value) {
+		if (this.redefinableParameters.lookupParameter(parameterId) === void 0) throw new Error(`Unknown configuration parameter: ${parameterId}`);
+		this.overwriteConfig(parameterId, value);
+		this.hash = void 0;
+	}
+	/**
+	* Updates or removes a configuration-overwrite for the given parameter.
+	*/
+	overwriteConfig(parameter, value) {
+		const parameterId = parameterNameToParameterId(parameter);
+		this.assertParameterExists(parameterId);
+		if (value === void 0) {
+			delete this.overwrites[parameterId];
+			return;
+		}
+		this.overwrites[parameterId] = this.castConfigArgument(parameterId, value);
+		this.hash = void 0;
+	}
+	castConfigArgument(parameterId, value) {
+		const type = this.getParameter(parameterId).type;
+		if (type === "int") {
+			if (typeof value === "number") return Math.floor(value);
+			if (typeof value === "string") return parseInt(value, 10);
+			if (typeof value === "boolean") return value ? 1 : 0;
+		} else if (type === "bool") {
+			if (typeof value === "boolean") return value;
+			if (typeof value === "string") return value.toLowerCase() === "true";
+			if (typeof value === "number") return value !== 0;
+		} else if (type === "string[]") {
+			if (value === void 0 || value == null) return [];
+			if (Array.isArray(value)) return value.map(String);
+			if (typeof value === "string") return value.split(",").map((s) => s.trim());
+		} else return String(value);
+		throw new Error(`Cannot cast value of type ${typeof value} to ${type}`);
+	}
+	assertParameterExists(parameterId) {
+		if (this.allParameters.lookupParameter(parameterId) === void 0) throw new Error(`Unknown configuration parameter: ${parameterId}`);
+	}
+	getParameter(parameterId) {
+		const parameter = this.redefinableParameters.lookupParameter(parameterId);
+		if (parameter === void 0) throw new Error(`Unknown configuration parameter: ${parameterId}`);
+		return parameter;
+	}
+	/**
+	* Computes a hash for the given (possibly overwritten) configuration.
+	*/
+	getHash() {
+		if (this.hash === void 0) {
+			const hash = createHash("sha256");
+			for (const [key, value] of Object.entries(this.baseConfiguration)) {
+				hash.update(key);
+				hash.update(String(value));
+			}
+			for (const [key, value] of Object.entries(this.overwrites)) {
+				hash.update(key);
+				hash.update(String(value));
+			}
+			this.hash = hash.digest("hex");
+		}
+		return this.hash;
+	}
+	/**
+	* Copies the given configuration along with the overrides.
+	*/
+	copy() {
+		const overwritesCopy = JSON.parse(JSON.stringify(this.overwrites));
+		return new ConfigurationWithOverwrites(this.allParameters, this.redefinableParameters, this.baseConfiguration, overwritesCopy);
+	}
+};
+/**
+* Creates a proxy object to retrieve and set config options via the attributes in the `BaseConfigType` interface.
+*/
+function makeConfigProxy(configuration) {
+	return new Proxy(configuration, {
+		get(_, property) {
+			return configuration.get(property.toString());
+		},
+		set(target, property, value) {
+			configuration.set(property.toString(), value);
+			return true;
+		}
+	});
+}
+
+//#endregion
+//#region src/CollectorConfig.ts
+const CONFIG_GROUP_COLLECTOR_CONNECTIVITY = {
+	order: 1,
+	title: "Collector Connectivity"
+};
+const CONFIG_GROUP_TEAMSCALE_SERVER = {
+	order: 1,
+	title: "Teamscale Server"
+};
+const CONFIG_GROUP_TEAMSCALE_UPLOAD = {
+	order: 2,
+	title: "Upload to Teamscale",
+	hints: "NOTE: We generally recommend to set these parameters per app during the instrumentation process, that is, on the instrumenter side, for example, by setting `--config-id` or specifying single options via `--collector-option`. The following parameters are supposed to take effect if the application is instrumented with the `--coverage-target-from-collector` flag."
+};
+const CONFIG_GROUP_COVERAGE_DUMP = {
+	order: 3,
+	title: "Coverage Dumping"
+};
+const CONFIG_GROUP_ARTIFACTORY_UPLOAD = {
+	order: 4,
+	title: "Upload to Artifactory"
+};
+const CONFIG_GROUP_LOGGING = {
+	order: 5,
+	title: "Logging Behavior"
+};
+/**
+* Build the collector parameters that can be overwritten by instrumented apps.
+*/
+function buildPredefinableParameters() {
+	const parameters = new ConfigurationParameters();
+	function add(shortParameter, longParameter, type, options) {
+		parameters.addParameter(shortParameter, longParameter, type, options);
+	}
+	add("-k", "--keep-coverage-files", "bool", {
+		help: "Whether to keep the coverage files on disk after a successful upload to Teamscale.",
+		default: false,
+		group: CONFIG_GROUP_COVERAGE_DUMP
+	});
+	add("-t", "--dump-after-mins", "int", {
+		help: "Dump the coverage information every N minutes.",
+		default: 120,
+		group: CONFIG_GROUP_COVERAGE_DUMP
+	});
+	add(void 0, "--artifactory-server-url", "string", {
+		help: "Upload the coverage to the given Artifactory server URL. The URL may include a subpath on the artifactory server, e.g. https://artifactory.acme.com/my-repo/my/subpath",
+		group: CONFIG_GROUP_ARTIFACTORY_UPLOAD
+	});
+	add(void 0, "--artifactory-user", "string", {
+		help: "The user for uploading coverage to Artifactory. Only needed when not using the --artifactory-access-token option",
+		group: CONFIG_GROUP_ARTIFACTORY_UPLOAD
+	});
+	add(void 0, "--artifactory-password", "string", {
+		help: "The password for uploading coverage to Artifactory. Only needed when not using the --artifactory-access-token option",
+		group: CONFIG_GROUP_ARTIFACTORY_UPLOAD
+	});
+	add(void 0, "--artifactory-access-token", "string", {
+		help: "The access_token for uploading coverage to Artifactory.",
+		group: CONFIG_GROUP_ARTIFACTORY_UPLOAD
+	});
+	add(void 0, "--artifactory-path-suffix", "string", {
+		help: "(optional): The path within the storage location between the default path and the uploaded artifact.",
+		group: CONFIG_GROUP_ARTIFACTORY_UPLOAD
+	});
+	add(void 0, "--teamscale-project", "string", {
+		help: "The project ID to upload coverage to.",
+		group: CONFIG_GROUP_TEAMSCALE_UPLOAD
+	});
+	add(void 0, "--teamscale-partition", "string", {
+		help: "The partition to upload coverage to.",
+		group: CONFIG_GROUP_TEAMSCALE_UPLOAD
+	});
+	add(void 0, "--teamscale-repository", "string", {
+		help: "The repository to upload coverage for. Optional: Only needed when uploading via revision to a project that has more than one connector.",
+		group: CONFIG_GROUP_TEAMSCALE_UPLOAD
+	});
+	add(void 0, "--teamscale-message", "string", {
+		help: "The commit message shown within Teamscale for the coverage upload.",
+		default: "JavaScript coverage upload",
+		group: CONFIG_GROUP_TEAMSCALE_UPLOAD
+	});
+	return parameters;
+}
+/**
+* Builds and returns the configuration parameters for the collector.
+* This includes all available command line arguments and their default values.
+*
+* @returns {ConfigurationParameters} Configuration parameters instance with all defined options
+*/
+function buildStaticCollectorParameters() {
+	const parameters = buildPredefinableParameters();
+	function add(shortParameter, longParameter, type, options) {
+		parameters.addParameter(shortParameter, longParameter, type, options);
+	}
+	add("-p", "--port", "int", {
+		help: "The port to receive coverage information on.",
+		default: 54678,
+		group: CONFIG_GROUP_COLLECTOR_CONNECTIVITY,
+		disableEnvironmentVariableOverride: true
+	});
+	add("-l", "--log-to-file", "string", {
+		help: "Log file",
+		default: "logs/collector-combined.log",
+		group: CONFIG_GROUP_LOGGING,
+		disableEnvironmentVariableOverride: true
+	});
+	add("-e", "--log-level", "string", {
+		help: "Log level",
+		default: "info",
+		group: CONFIG_GROUP_LOGGING,
+		disableEnvironmentVariableOverride: true
+	});
+	add("-j", "--json-log", "bool", {
+		help: "Additional JSON-like log file format.",
+		group: CONFIG_GROUP_LOGGING,
+		disableEnvironmentVariableOverride: true
+	});
+	add("-c", "--enable-control-port", "int", {
+		help: "Enables the remote control API on the specified port (<=0 means \"disabled\").",
+		default: 0,
+		group: CONFIG_GROUP_COLLECTOR_CONNECTIVITY
+	});
+	add("-s", "--teamscale-server-url", "string", {
+		help: "Upload the coverage to the given Teamscale server URL, for example, https://teamscale.dev.example.com:8080/production.",
+		group: CONFIG_GROUP_TEAMSCALE_SERVER
+	});
+	add("-u", "--teamscale-user", "string", {
+		help: "The user for uploading coverage to Teamscale.",
+		group: CONFIG_GROUP_TEAMSCALE_SERVER
+	});
+	add("-a", "--teamscale-access-token", "string", {
+		help: "The API key to use for uploading to Teamscale.",
+		group: CONFIG_GROUP_TEAMSCALE_SERVER
+	});
+	add(void 0, "--http-proxy", "string", {
+		help: "(optional): The HTTP/HTTPS proxy address that should be used in the format: http://host:port/ or http://username:password@host:port/.",
+		group: CONFIG_GROUP_COLLECTOR_CONNECTIVITY
+	});
+	add("-f", "--dump-folder", "string", {
+		help: "Target folder for coverage files.",
+		default: "./coverage",
+		group: CONFIG_GROUP_COVERAGE_DUMP
+	});
+	parameters.addArgumentCheck((options) => {
+		if (options.teamscaleServerUrl) {
+			if (!options.teamscaleUser || !options.teamscaleAccessToken) return "The Teamscale user name and access token must be given if the Teamscale server URL is given.";
+		}
+	});
+	return parameters;
+}
+/**
+* Builds and returns the during run-time reconfigurable configuration parameters for the collector.
+*/
+function buildReconfigurableCollectorParameters() {
+	const parameters = buildPredefinableParameters();
+	function addShort(shortParameter, longParameter, type, options) {
+		parameters.addParameter(shortParameter, longParameter, type, options);
+	}
+	function add(longArgument, type, options) {
+		addShort(void 0, longArgument, type, options);
+	}
+	add("--dump-to-folder", "string", {
+		help: "Coverage should be dumped to a folder on the server that the collector is running on.\nSpecifies the name of the subfolder within the collector's dump folder (--dump-folder of the collector) where coverage files should be placed.",
+		group: CONFIG_GROUP_COVERAGE_DUMP
+	});
+	return parameters;
+}
+
+//#endregion
+//#region src/Validation.ts
+/**
+* Checks if the given string describes a commit in a valid fashion.
+*/
+function isValidCommitInfo(commit) {
+	if (typeof commit === "string") {
+		if (/^[a-zA-Z0-9_-]+:([0-9]+|HEAD|head)$/.test(commit)) return true;
+		if (/^[0-9]+$/.test(commit)) return false;
+		if (/^[a-zA-Z0-9]{7,40}$/.test(commit)) return true;
+	}
+	return false;
+}
+
+//#endregion
+export { CONFIG_GROUP_APP, ConfigurationParameters, ConfigurationWithOverwrites, Contract, IllegalArgumentException, IllegalStateException, ImplementMeException, InvalidConfigurationException, buildPredefinableParameters, buildReconfigurableCollectorParameters, buildStaticCollectorParameters, checkArguments, isValidCommitInfo, longParameterToEnvironmentVariableName, makeConfigProxy, parameterNameToParameterId, parameterUnion, parseArguments, parseConfigFile, printHelp, processCommandLine, removePrefix };
+//# sourceMappingURL=index.mjs.map