@optique/core 1.0.0-dev.1495 → 1.0.0-dev.1500

package/dist/valueparser.js

@@ -6,9 +6,18 @@ import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 * A predicate function that checks if an object is a {@link ValueParser}.
 * @param object The object to check.
 * @return `true` if the object is a {@link ValueParser}, `false` otherwise.
+* @throws {TypeError} If the object looks like a value parser (has `$mode`,
+*   `metavar`, `parse`, and `format`) but is missing the required
+*   `placeholder` property.
 */
 function isValueParser(object) {
-	return typeof object === "object" && object != null && "$mode" in object && (object.$mode === "sync" || object.$mode === "async") && "metavar" in object && typeof object.metavar === "string" && "parse" in object && typeof object.parse === "function" && "format" in object && typeof object.format === "function";
+	if (typeof object !== "object" || object == null || !("$mode" in object) || object.$mode !== "sync" && object.$mode !== "async") return false;
+	const hasMetavar = "metavar" in object && typeof object.metavar === "string";
+	const hasParse = "parse" in object && typeof object.parse === "function";
+	const hasFormat = "format" in object && typeof object.format === "function";
+	const hasPlaceholder = "placeholder" in object;
+	if (hasMetavar && hasParse && hasFormat && !hasPlaceholder) throw new TypeError("Value parser is missing the required placeholder property. All value parsers must define a placeholder value.");
+	return hasMetavar && hasParse && hasFormat && hasPlaceholder;
 }
 /**
 * Implementation of the choice parser for both string and number types.
@@ -49,6 +58,7 @@ function choice(choices, options = {}) {
 		return {
 			$mode: "sync",
 			metavar,
+			placeholder: choices[0],
 			choices: frozenNumberChoices,
 			parse(input) {
 				const index = numberStrings.indexOf(input);
@@ -130,6 +140,7 @@ function choice(choices, options = {}) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: choices[0],
 		choices: stringChoices,
 		parse(input) {
 			const normalizedInput = caseInsensitive ? input.toLowerCase() : input;
@@ -288,6 +299,7 @@ function string(options = {}) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: options.placeholder ?? "",
 		parse(input) {
 			if (patternSource != null && patternFlags != null) {
 				const pattern = new RegExp(patternSource, patternFlags);
@@ -344,6 +356,8 @@ function string(options = {}) {
 *          integer type.
 * @throws {TypeError} If `options.type` is provided but is neither `"number"`
 *   nor `"bigint"`.
+* @throws {RangeError} If the configured min/max range for number mode contains
+*   no safe integers.
 */
 function integer(options) {
 	if (options?.type !== void 0 && options.type !== "number" && options.type !== "bigint") throw new TypeError(`Expected type to be "number" or "bigint", but got: ${String(options.type)}.`);
@@ -358,6 +372,7 @@ function integer(options) {
 		return {
 			$mode: "sync",
 			metavar: metavar$1,
+			placeholder: options?.placeholder ?? (options?.min != null && options.min > 0n ? options.min : options?.max != null && options.max < 0n ? options.max : 0n),
 			parse(input) {
 				if (!input.match(/^-?\d+$/)) return {
 					success: false,
@@ -386,6 +401,11 @@ function integer(options) {
 	ensureNonEmptyString(metavar);
 	const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
 	const minSafe = BigInt(Number.MIN_SAFE_INTEGER);
+	const safeMin = Math.max(options?.min ?? Number.MIN_SAFE_INTEGER, Number.MIN_SAFE_INTEGER);
+	const safeMax = Math.min(options?.max ?? Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+	const firstAllowed = Math.ceil(safeMin);
+	const lastAllowed = Math.floor(safeMax);
+	if (firstAllowed > lastAllowed) throw new RangeError("The configured integer range contains no safe integers. Use type: \"bigint\" instead.");
 	const unsafeIntegerError = options?.errors?.unsafeInteger;
 	function makeUnsafeIntegerError(input) {
 		return {
@@ -396,6 +416,7 @@ function integer(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? (firstAllowed > 0 ? firstAllowed : lastAllowed < 0 ? lastAllowed : 0),
 		parse(input) {
 			if (!input.match(/^-?\d+$/)) return {
 				success: false,
@@ -446,6 +467,7 @@ function float(options = {}) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? (options?.min != null && options.min > 0 ? options.min : options?.max != null && options.max < 0 ? options.max : 0),
 		parse(input) {
 			const invalidNumber = (i) => ({
 				success: false,
@@ -530,6 +552,9 @@ function url(options = {}) {
 	return {
 		$mode: "sync",
 		metavar,
+		get placeholder() {
+			return new URL(`${allowedProtocols?.[0] ?? "http:"}//0.invalid`);
+		},
 		parse(input) {
 			if (!URL.canParse(input)) return {
 				success: false,
@@ -596,6 +621,7 @@ function locale(options = {}) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: new Intl.Locale("und"),
 		parse(input) {
 			let locale$1;
 			try {
@@ -891,6 +917,7 @@ function uuid(options = {}) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: "00000000-0000-0000-0000-000000000000",
 		parse(input) {
 			if (!uuidRegex.test(input)) return {
 				success: false,
@@ -994,9 +1021,11 @@ function port(options) {
 		const min$1 = options.min ?? 1n;
 		const max$1 = options.max ?? 65535n;
 		if (min$1 > max$1) throw new RangeError(`Expected min to be less than or equal to max, but got min: ${min$1} and max: ${max$1}.`);
+		if (options.disallowWellKnown && min$1 < 1024n && max$1 < 1024n) throw new RangeError(`disallowWellKnown is incompatible with the configured port range: all ports ${min$1}..${max$1} are well-known.`);
 		return {
 			$mode: "sync",
 			metavar: metavar$1,
+			placeholder: options.placeholder ?? (options.disallowWellKnown && min$1 < 1024n ? 1024n > min$1 ? 1024n : min$1 : min$1),
 			parse(input) {
 				if (!input.match(/^-?\d+$/)) return {
 					success: false,
@@ -1032,9 +1061,11 @@ function port(options) {
 	const min = options?.min ?? 1;
 	const max = options?.max ?? 65535;
 	if (min > max) throw new RangeError(`Expected min to be less than or equal to max, but got min: ${min} and max: ${max}.`);
+	if (options?.disallowWellKnown && min < 1024 && max < 1024) throw new RangeError(`disallowWellKnown is incompatible with the configured port range: all ports ${min}..${max} are well-known.`);
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? (options?.disallowWellKnown && min < 1024 ? Math.max(1024, min) : min),
 		parse(input) {
 			if (!input.match(/^-?\d+$/)) return {
 				success: false,
@@ -1128,6 +1159,7 @@ function ipv4(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: allowZero ? "0.0.0.0" : allowLoopback ? "127.0.0.1" : "192.0.2.1",
 		parse(input) {
 			const parts = input.split(".");
 			if (parts.length !== 4) {
@@ -1289,6 +1321,7 @@ function hostname(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? (allowLocalhost ? maxLength >= 9 ? "localhost" : "a.bc" : maxLength >= 11 ? "example.com" : "a.bc"),
 		parse(input) {
 			if (input.length > maxLength) {
 				const errorMsg = options?.errors?.tooLong;
@@ -1408,6 +1441,10 @@ function email(options) {
 	const metavar = options?.metavar ?? "EMAIL";
 	ensureNonEmptyString(metavar);
 	const allowMultiple = options?.allowMultiple ?? false;
+	if (options?.placeholder != null) {
+		if (allowMultiple && !Array.isArray(options.placeholder)) throw new TypeError("email() placeholder must be an array when allowMultiple is true.");
+		if (!allowMultiple && typeof options.placeholder !== "string") throw new TypeError("email() placeholder must be a string when allowMultiple is false.");
+	}
 	const allowDisplayName = options?.allowDisplayName ?? false;
 	const lowercase = options?.lowercase ?? false;
 	const allowedDomains = options?.allowedDomains != null ? Object.freeze([...options.allowedDomains]) : void 0;
@@ -1504,6 +1541,7 @@ function email(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? (options?.allowMultiple ? [`user@${options?.allowedDomains?.[0] ?? "example.com"}`] : `user@${options?.allowedDomains?.[0] ?? "example.com"}`),
 		parse(input) {
 			if (allowMultiple) {
 				const emails = splitEmails(input).map((e) => e.trim());
@@ -1724,6 +1762,12 @@ function socketAddress(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		get placeholder() {
+			return {
+				host: hostType === "ip" ? ipParser.placeholder : hostnameParser.placeholder,
+				port: defaultPort ?? portParser.placeholder
+			};
+		},
 		parse(input) {
 			const trimmed = input.trim();
 			const canOmitPort = defaultPort !== void 0 && !requirePort;
@@ -1936,6 +1980,15 @@ function portRange(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		get placeholder() {
+			return isBigInt ? {
+				start: portParser.placeholder,
+				end: portParser.placeholder
+			} : {
+				start: portParser.placeholder,
+				end: portParser.placeholder
+			};
+		},
 		parse(input) {
 			const trimmed = input.trim();
 			const separatorIndex = trimmed.indexOf(separator);
@@ -2094,6 +2147,20 @@ function macAddress(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		get placeholder() {
+			const octets = [
+				"00",
+				"00",
+				"00",
+				"00",
+				"00",
+				"00"
+			];
+			const sep = outputSeparator ?? (separator === "any" ? ":" : separator);
+			if (sep === ".") return `${octets[0]}${octets[1]}.${octets[2]}${octets[3]}.${octets[4]}${octets[5]}`;
+			if (sep === "none") return octets.join("");
+			return octets.join(sep);
+		},
 		parse(input) {
 			let octets = [];
 			let inputSeparator;
@@ -2250,6 +2317,7 @@ function domain(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? `example.${allowedTldsLower?.[0] ?? "com"}`,
 		parse(input) {
 			if (input.length > maxLength) {
 				const errorMsg = tooLong;
@@ -2489,6 +2557,7 @@ function ipv6(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: allowZero ? "::" : allowLoopback ? "::1" : "2001:db8::1",
 		parse(input) {
 			const normalized = parseAndNormalizeIpv6(input);
 			if (normalized === null) {
@@ -2905,6 +2974,7 @@ function ip(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		placeholder: version === 6 ? ipv6Parser.placeholder : ipv4Parser.placeholder,
 		parse(input) {
 			let ipv4Error = null;
 			let ipv6Error = null;
@@ -3046,6 +3116,17 @@ function cidr(options) {
 	return {
 		$mode: "sync",
 		metavar,
+		get placeholder() {
+			return version === 6 || version === "both" && (minPrefix ?? 0) > 32 ? {
+				address: ipv6Parser.placeholder,
+				prefix: minPrefix ?? 0,
+				version: 6
+			} : {
+				address: ipv4Parser.placeholder,
+				prefix: minPrefix ?? 0,
+				version: 4
+			};
+		},
 		parse(input) {
 			const slashIndex = input.lastIndexOf("/");
 			if (slashIndex === -1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1495+f6fe8a79",
+  "version": "1.0.0-dev.1500+dc0650e5",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",