@optique/core 0.9.0-dev.184 → 0.9.0-dev.186

package/dist/index.cjs

@@ -4,6 +4,7 @@ const require_constructs = require('./constructs.cjs');
 const require_doc = require('./doc.cjs');
 const require_completion = require('./completion.cjs');
 const require_modifiers = require('./modifiers.cjs');
+const require_nonempty = require('./nonempty.cjs');
 const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
 const require_parser = require('./parser.cjs');
@@ -21,6 +22,7 @@ exports.commandLine = require_message.commandLine;
 exports.concat = require_constructs.concat;
 exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
+exports.ensureNonEmptyString = require_nonempty.ensureNonEmptyString;
 exports.envVar = require_message.envVar;
 exports.extractArgumentMetavars = require_usage.extractArgumentMetavars;
 exports.extractCommandNames = require_usage.extractCommandNames;
@@ -35,6 +37,7 @@ exports.formatUsageTerm = require_usage.formatUsageTerm;
 exports.getDocPage = require_parser.getDocPage;
 exports.group = require_constructs.group;
 exports.integer = require_valueparser.integer;
+exports.isNonEmptyString = require_nonempty.isNonEmptyString;
 exports.isValueParser = require_valueparser.isValueParser;
 exports.locale = require_valueparser.locale;
 exports.longestMatch = require_constructs.longestMatch;

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message, MessageFormatOptions, MessageTerm, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.cjs";
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
@@ -8,4 +9,4 @@ import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Sugg
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { RunError, RunOptions, RunParserError, run, runParser } from "./facade.cjs";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, RunError, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, passThrough, pwsh, run, runParser, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, RunError, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isNonEmptyString, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, passThrough, pwsh, run, runParser, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message, MessageFormatOptions, MessageTerm, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.js";
@@ -8,4 +9,4 @@ import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Sugg
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { RunError, RunOptions, RunParserError, run, runParser } from "./facade.js";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, RunError, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, passThrough, pwsh, run, runParser, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, RunError, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isNonEmptyString, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, passThrough, pwsh, run, runParser, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.js

@@ -4,9 +4,10 @@ import { DuplicateOptionError, concat, conditional, group, longestMatch, merge,
 import { formatDocPage } from "./doc.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { WithDefaultError, map, multiple, optional, withDefault } from "./modifiers.js";
+import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
 import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
 import { getDocPage, parse, suggest } from "./parser.js";
 import { RunError, RunParserError, run, runParser } from "./facade.js";
 
-export { DuplicateOptionError, RunError, RunParserError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, passThrough, pwsh, run, runParser, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { DuplicateOptionError, RunError, RunParserError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isNonEmptyString, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, passThrough, pwsh, run, runParser, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/message.d.cts

@@ -1,4 +1,7 @@
+import { NonEmptyString } from "./nonempty.cjs";
+
 //#region src/message.d.ts
+
 /**
  * Represents a single term in a message, which can be a text, an option
  * name, a list of option names, a metavariable, a value, or a list of
@@ -60,7 +63,7 @@ type MessageTerm =
    * The metavariable name, which is a string that represents
    * a variable in the message.  For example, `"VALUE"` or `"ARG"`.
    */
-  readonly metavar: string;
+  readonly metavar: NonEmptyString;
 }
 /**
  * A value term in the message, which can be a single value.
@@ -171,7 +174,7 @@ declare function optionNames(names: readonly string[]): MessageTerm;
  *                `"ARG"`.
  * @returns A {@link MessageTerm} representing the metavariable.
  */
-declare function metavar(metavar: string): MessageTerm;
+declare function metavar(metavar: NonEmptyString): MessageTerm;
 /**
  * Creates a {@link MessageTerm} for a single value.  However, you usually
  * don't need to use this function directly, as {@link message} string template

package/dist/message.d.ts

@@ -1,4 +1,7 @@
+import { NonEmptyString } from "./nonempty.js";
+
 //#region src/message.d.ts
+
 /**
  * Represents a single term in a message, which can be a text, an option
  * name, a list of option names, a metavariable, a value, or a list of
@@ -60,7 +63,7 @@ type MessageTerm =
    * The metavariable name, which is a string that represents
    * a variable in the message.  For example, `"VALUE"` or `"ARG"`.
    */
-  readonly metavar: string;
+  readonly metavar: NonEmptyString;
 }
 /**
  * A value term in the message, which can be a single value.
@@ -171,7 +174,7 @@ declare function optionNames(names: readonly string[]): MessageTerm;
  *                `"ARG"`.
  * @returns A {@link MessageTerm} representing the metavariable.
  */
-declare function metavar(metavar: string): MessageTerm;
+declare function metavar(metavar: NonEmptyString): MessageTerm;
 /**
  * Creates a {@link MessageTerm} for a single value.  However, you usually
  * don't need to use this function directly, as {@link message} string template

package/dist/nonempty.cjs

@@ -0,0 +1,26 @@
+
+//#region src/nonempty.ts
+/**
+* Checks if a string is non-empty.
+* Can be used as a type guard for type narrowing.
+* @param value The string to check.
+* @returns `true` if the string is non-empty, `false` otherwise.
+* @since 0.9.0
+*/
+function isNonEmptyString(value) {
+	return value !== "";
+}
+/**
+* Asserts that a string is non-empty.
+* Throws a `TypeError` if the string is empty.
+* @param value The string to validate.
+* @throws {TypeError} If the string is empty.
+* @since 0.9.0
+*/
+function ensureNonEmptyString(value) {
+	if (value === "") throw new TypeError("Expected a non-empty string.");
+}
+
+//#endregion
+exports.ensureNonEmptyString = ensureNonEmptyString;
+exports.isNonEmptyString = isNonEmptyString;

package/dist/nonempty.d.cts

@@ -0,0 +1,29 @@
+//#region src/nonempty.d.ts
+/**
+ * A string type that guarantees at least one character.
+ * Used for `metavar` properties to ensure they are never empty.
+ *
+ * This type uses a template literal pattern that requires at least one
+ * character, providing compile-time rejection of empty string literals.
+ *
+ * @since 0.9.0
+ */
+type NonEmptyString = `${any}${string}`;
+/**
+ * Checks if a string is non-empty.
+ * Can be used as a type guard for type narrowing.
+ * @param value The string to check.
+ * @returns `true` if the string is non-empty, `false` otherwise.
+ * @since 0.9.0
+ */
+declare function isNonEmptyString(value: string): value is NonEmptyString;
+/**
+ * Asserts that a string is non-empty.
+ * Throws a `TypeError` if the string is empty.
+ * @param value The string to validate.
+ * @throws {TypeError} If the string is empty.
+ * @since 0.9.0
+ */
+declare function ensureNonEmptyString(value: string): asserts value is NonEmptyString;
+//#endregion
+export { NonEmptyString, ensureNonEmptyString, isNonEmptyString };

package/dist/nonempty.d.ts

@@ -0,0 +1,29 @@
+//#region src/nonempty.d.ts
+/**
+ * A string type that guarantees at least one character.
+ * Used for `metavar` properties to ensure they are never empty.
+ *
+ * This type uses a template literal pattern that requires at least one
+ * character, providing compile-time rejection of empty string literals.
+ *
+ * @since 0.9.0
+ */
+type NonEmptyString = `${any}${string}`;
+/**
+ * Checks if a string is non-empty.
+ * Can be used as a type guard for type narrowing.
+ * @param value The string to check.
+ * @returns `true` if the string is non-empty, `false` otherwise.
+ * @since 0.9.0
+ */
+declare function isNonEmptyString(value: string): value is NonEmptyString;
+/**
+ * Asserts that a string is non-empty.
+ * Throws a `TypeError` if the string is empty.
+ * @param value The string to validate.
+ * @throws {TypeError} If the string is empty.
+ * @since 0.9.0
+ */
+declare function ensureNonEmptyString(value: string): asserts value is NonEmptyString;
+//#endregion
+export { NonEmptyString, ensureNonEmptyString, isNonEmptyString };

package/dist/nonempty.js

@@ -0,0 +1,24 @@
+//#region src/nonempty.ts
+/**
+* Checks if a string is non-empty.
+* Can be used as a type guard for type narrowing.
+* @param value The string to check.
+* @returns `true` if the string is non-empty, `false` otherwise.
+* @since 0.9.0
+*/
+function isNonEmptyString(value) {
+	return value !== "";
+}
+/**
+* Asserts that a string is non-empty.
+* Throws a `TypeError` if the string is empty.
+* @param value The string to validate.
+* @throws {TypeError} If the string is empty.
+* @since 0.9.0
+*/
+function ensureNonEmptyString(value) {
+	if (value === "") throw new TypeError("Expected a non-empty string.");
+}
+
+//#endregion
+export { ensureNonEmptyString, isNonEmptyString };

package/dist/usage.d.cts

@@ -1,4 +1,7 @@
+import { NonEmptyString } from "./nonempty.cjs";
+
 //#region src/usage.d.ts
+
 /**
  * Represents the name of a command-line option.  There are four types of
  * option syntax:
@@ -26,7 +29,7 @@ type UsageTerm =
    * The name of the argument, which is used to identify it in
    * the command-line usage.
    */
-  readonly metavar: string;
+  readonly metavar: NonEmptyString;
   /**
    * When `true`, hides the argument from help text, shell completion
    * suggestions, and error suggestions.
@@ -51,7 +54,7 @@ type UsageTerm =
    * An optional metavariable name for the option, which is used
    * to indicate what value the option expects.
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * When `true`, hides the option from help text, shell completion
    * suggestions, and "Did you mean?" error suggestions.

package/dist/usage.d.ts

@@ -1,4 +1,7 @@
+import { NonEmptyString } from "./nonempty.js";
+
 //#region src/usage.d.ts
+
 /**
  * Represents the name of a command-line option.  There are four types of
  * option syntax:
@@ -26,7 +29,7 @@ type UsageTerm =
    * The name of the argument, which is used to identify it in
    * the command-line usage.
    */
-  readonly metavar: string;
+  readonly metavar: NonEmptyString;
   /**
    * When `true`, hides the argument from help text, shell completion
    * suggestions, and error suggestions.
@@ -51,7 +54,7 @@ type UsageTerm =
    * An optional metavariable name for the option, which is used
    * to indicate what value the option expects.
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * When `true`, hides the option from help text, shell completion
    * suggestions, and "Did you mean?" error suggestions.

package/dist/valueparser.cjs

@@ -1,4 +1,5 @@
 const require_message = require('./message.cjs');
+const require_nonempty = require('./nonempty.cjs');
 
 //#region src/valueparser.ts
 /**
@@ -22,9 +23,11 @@ function isValueParser(object) {
 *          specified values.
 */
 function choice(choices, options = {}) {
+	const metavar = options.metavar ?? "TYPE";
+	require_nonempty.ensureNonEmptyString(metavar);
 	const normalizedValues = options.caseInsensitive ? choices.map((v) => v.toLowerCase()) : choices;
 	return {
-		metavar: options.metavar ?? "TYPE",
+		metavar,
 		parse(input) {
 			const normalizedInput = options.caseInsensitive ? input.toLowerCase() : input;
 			const index = normalizedValues.indexOf(normalizedInput);
@@ -74,8 +77,10 @@ function choice(choices, options = {}) {
 *          specified options.
 */
 function string(options = {}) {
+	const metavar = options.metavar ?? "STRING";
+	require_nonempty.ensureNonEmptyString(metavar);
 	return {
-		metavar: options.metavar ?? "STRING",
+		metavar,
 		parse(input) {
 			if (options.pattern != null && !options.pattern.test(input)) return {
 				success: false,
@@ -125,38 +130,44 @@ function string(options = {}) {
 *          integer type.
 */
 function integer(options) {
-	if (options?.type === "bigint") return {
-		metavar: options.metavar ?? "INTEGER",
-		parse(input) {
-			let value;
-			try {
-				value = BigInt(input);
-			} catch (e) {
-				if (e instanceof SyntaxError) return {
+	if (options?.type === "bigint") {
+		const metavar$1 = options.metavar ?? "INTEGER";
+		require_nonempty.ensureNonEmptyString(metavar$1);
+		return {
+			metavar: metavar$1,
+			parse(input) {
+				let value;
+				try {
+					value = BigInt(input);
+				} catch (e) {
+					if (e instanceof SyntaxError) return {
+						success: false,
+						error: options.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : require_message.message`Expected a valid integer, but got ${input}.`
+					};
+					throw e;
+				}
+				if (options.min != null && value < options.min) return {
 					success: false,
-					error: options.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : require_message.message`Expected a valid integer, but got ${input}.`
+					error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, options.min) : options.errors.belowMinimum : require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
 				};
-				throw e;
+				else if (options.max != null && value > options.max) return {
+					success: false,
+					error: options.errors?.aboveMaximum ? typeof options.errors.aboveMaximum === "function" ? options.errors.aboveMaximum(value, options.max) : options.errors.aboveMaximum : require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
+				};
+				return {
+					success: true,
+					value
+				};
+			},
+			format(value) {
+				return value.toString();
 			}
-			if (options.min != null && value < options.min) return {
-				success: false,
-				error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, options.min) : options.errors.belowMinimum : require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
-			};
-			else if (options.max != null && value > options.max) return {
-				success: false,
-				error: options.errors?.aboveMaximum ? typeof options.errors.aboveMaximum === "function" ? options.errors.aboveMaximum(value, options.max) : options.errors.aboveMaximum : require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
-			};
-			return {
-				success: true,
-				value
-			};
-		},
-		format(value) {
-			return value.toString();
-		}
-	};
+		};
+	}
+	const metavar = options?.metavar ?? "INTEGER";
+	require_nonempty.ensureNonEmptyString(metavar);
 	return {
-		metavar: options?.metavar ?? "INTEGER",
+		metavar,
 		parse(input) {
 			if (!input.match(/^-?\d+$/)) return {
 				success: false,
@@ -192,8 +203,10 @@ function integer(options) {
 */
 function float(options = {}) {
 	const floatRegex = /^[+-]?(?:(?:\d+\.?\d*)|(?:\d*\.\d+))(?:[eE][+-]?\d+)?$/;
+	const metavar = options.metavar ?? "NUMBER";
+	require_nonempty.ensureNonEmptyString(metavar);
 	return {
-		metavar: options.metavar ?? "NUMBER",
+		metavar,
 		parse(input) {
 			let value;
 			const lowerInput = input.toLowerCase();
@@ -239,8 +252,10 @@ function float(options = {}) {
 */
 function url(options = {}) {
 	const allowedProtocols = options.allowedProtocols?.map((p) => p.toLowerCase());
+	const metavar = options.metavar ?? "URL";
+	require_nonempty.ensureNonEmptyString(metavar);
 	return {
-		metavar: options.metavar ?? "URL",
+		metavar,
 		parse(input) {
 			if (!URL.canParse(input)) return {
 				success: false,
@@ -281,8 +296,10 @@ function url(options = {}) {
 *          objects.
 */
 function locale(options = {}) {
+	const metavar = options.metavar ?? "LOCALE";
+	require_nonempty.ensureNonEmptyString(metavar);
 	return {
-		metavar: options.metavar ?? "LOCALE",
+		metavar,
 		parse(input) {
 			let locale$1;
 			try {
@@ -548,8 +565,10 @@ function locale(options = {}) {
 */
 function uuid(options = {}) {
 	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+	const metavar = options.metavar ?? "UUID";
+	require_nonempty.ensureNonEmptyString(metavar);
 	return {
-		metavar: options.metavar ?? "UUID",
+		metavar,
 		parse(input) {
 			if (!uuidRegex.test(input)) return {
 				success: false,
@@ -584,8 +603,10 @@ function uuid(options = {}) {
 
 //#endregion
 exports.choice = choice;
+exports.ensureNonEmptyString = require_nonempty.ensureNonEmptyString;
 exports.float = float;
 exports.integer = integer;
+exports.isNonEmptyString = require_nonempty.isNonEmptyString;
 exports.isValueParser = isValueParser;
 exports.locale = locale;
 exports.string = string;

package/dist/valueparser.d.cts

@@ -1,3 +1,4 @@
+import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message } from "./message.cjs";
 import { Suggestion } from "./parser.cjs";
 
@@ -17,7 +18,7 @@ interface ValueParser<T> {
    * to indicate what kind of value this parser expects.  Usually
    * a single word in uppercase, like `PORT` or `FILE`.
    */
-  readonly metavar: string;
+  readonly metavar: NonEmptyString;
   /**
    * Parses a string input into a value of type {@link T}.
    *
@@ -75,7 +76,7 @@ interface StringOptions {
    * word in uppercase, like `HOST` or `NAME`.
    * @default `"STRING"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * Optional regular expression pattern that the string must match.
    *
@@ -111,7 +112,7 @@ interface ChoiceOptions {
    * word in uppercase, like `TYPE` or `MODE`.
    * @default `"TYPE"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * If `true`, the parser will perform case-insensitive matching
    * against the enumerated values. This means that input like "value",
@@ -185,7 +186,7 @@ interface IntegerOptionsNumber {
    * word in uppercase, like `PORT`.
    * @default `"INTEGER"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * Minimum allowed value (inclusive). If not specified,
    * no minimum is enforced.
@@ -236,7 +237,7 @@ interface IntegerOptionsBigInt {
    * word in uppercase, like `PORT`.
    * @default `"INTEGER"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * Minimum allowed value (inclusive). If not specified,
    * no minimum is enforced.
@@ -296,7 +297,7 @@ interface FloatOptions {
    * word in uppercase, like `RATE` or `PRICE`.
    * @default `"NUMBER"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * Minimum allowed value (inclusive). If not specified,
    * no minimum is enforced.
@@ -366,7 +367,7 @@ interface UrlOptions {
    * word in uppercase, like `URL` or `ENDPOINT`.
    * @default `"URL"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * List of allowed URL protocols (e.g., `["http:", "https:"]`).
    * If specified, the parsed URL must use one of these protocols.
@@ -413,7 +414,7 @@ interface LocaleOptions {
    * word in uppercase, like `LOCALE` or `LANG`.
    * @default `"LOCALE"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * Custom error messages for locale parsing failures.
    * @since 0.5.0
@@ -456,7 +457,7 @@ interface UuidOptions {
    * word in uppercase, like `UUID` or `ID`.
    * @default `"UUID"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * List of allowed UUID versions (e.g., `[4, 5]` for UUIDs version 4 and 5).
    * If specified, the parser will validate that the UUID matches one of the
@@ -496,4 +497,4 @@ interface UuidOptions {
  */
 declare function uuid(options?: UuidOptions): ValueParser<Uuid>;
 //#endregion
-export { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid };
+export { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, type NonEmptyString, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, ensureNonEmptyString, float, integer, isNonEmptyString, isValueParser, locale, string, url, uuid };

package/dist/valueparser.d.ts

@@ -1,3 +1,4 @@
+import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message } from "./message.js";
 import { Suggestion } from "./parser.js";
 
@@ -17,7 +18,7 @@ interface ValueParser<T> {
    * to indicate what kind of value this parser expects.  Usually
    * a single word in uppercase, like `PORT` or `FILE`.
    */
-  readonly metavar: string;
+  readonly metavar: NonEmptyString;
   /**
    * Parses a string input into a value of type {@link T}.
    *
@@ -75,7 +76,7 @@ interface StringOptions {
    * word in uppercase, like `HOST` or `NAME`.
    * @default `"STRING"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * Optional regular expression pattern that the string must match.
    *
@@ -111,7 +112,7 @@ interface ChoiceOptions {
    * word in uppercase, like `TYPE` or `MODE`.
    * @default `"TYPE"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * If `true`, the parser will perform case-insensitive matching
    * against the enumerated values. This means that input like "value",
@@ -185,7 +186,7 @@ interface IntegerOptionsNumber {
    * word in uppercase, like `PORT`.
    * @default `"INTEGER"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * Minimum allowed value (inclusive). If not specified,
    * no minimum is enforced.
@@ -236,7 +237,7 @@ interface IntegerOptionsBigInt {
    * word in uppercase, like `PORT`.
    * @default `"INTEGER"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * Minimum allowed value (inclusive). If not specified,
    * no minimum is enforced.
@@ -296,7 +297,7 @@ interface FloatOptions {
    * word in uppercase, like `RATE` or `PRICE`.
    * @default `"NUMBER"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * Minimum allowed value (inclusive). If not specified,
    * no minimum is enforced.
@@ -366,7 +367,7 @@ interface UrlOptions {
    * word in uppercase, like `URL` or `ENDPOINT`.
    * @default `"URL"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * List of allowed URL protocols (e.g., `["http:", "https:"]`).
    * If specified, the parsed URL must use one of these protocols.
@@ -413,7 +414,7 @@ interface LocaleOptions {
    * word in uppercase, like `LOCALE` or `LANG`.
    * @default `"LOCALE"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * Custom error messages for locale parsing failures.
    * @since 0.5.0
@@ -456,7 +457,7 @@ interface UuidOptions {
    * word in uppercase, like `UUID` or `ID`.
    * @default `"UUID"`
    */
-  readonly metavar?: string;
+  readonly metavar?: NonEmptyString;
   /**
    * List of allowed UUID versions (e.g., `[4, 5]` for UUIDs version 4 and 5).
    * If specified, the parser will validate that the UUID matches one of the
@@ -496,4 +497,4 @@ interface UuidOptions {
  */
 declare function uuid(options?: UuidOptions): ValueParser<Uuid>;
 //#endregion
-export { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid };
+export { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, type NonEmptyString, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, ensureNonEmptyString, float, integer, isNonEmptyString, isValueParser, locale, string, url, uuid };

package/dist/valueparser.js

@@ -1,4 +1,5 @@
 import { message, text } from "./message.js";
+import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 
 //#region src/valueparser.ts
 /**
@@ -22,9 +23,11 @@ function isValueParser(object) {
 *          specified values.
 */
 function choice(choices, options = {}) {
+	const metavar = options.metavar ?? "TYPE";
+	ensureNonEmptyString(metavar);
 	const normalizedValues = options.caseInsensitive ? choices.map((v) => v.toLowerCase()) : choices;
 	return {
-		metavar: options.metavar ?? "TYPE",
+		metavar,
 		parse(input) {
 			const normalizedInput = options.caseInsensitive ? input.toLowerCase() : input;
 			const index = normalizedValues.indexOf(normalizedInput);
@@ -74,8 +77,10 @@ function choice(choices, options = {}) {
 *          specified options.
 */
 function string(options = {}) {
+	const metavar = options.metavar ?? "STRING";
+	ensureNonEmptyString(metavar);
 	return {
-		metavar: options.metavar ?? "STRING",
+		metavar,
 		parse(input) {
 			if (options.pattern != null && !options.pattern.test(input)) return {
 				success: false,
@@ -125,38 +130,44 @@ function string(options = {}) {
 *          integer type.
 */
 function integer(options) {
-	if (options?.type === "bigint") return {
-		metavar: options.metavar ?? "INTEGER",
-		parse(input) {
-			let value;
-			try {
-				value = BigInt(input);
-			} catch (e) {
-				if (e instanceof SyntaxError) return {
+	if (options?.type === "bigint") {
+		const metavar$1 = options.metavar ?? "INTEGER";
+		ensureNonEmptyString(metavar$1);
+		return {
+			metavar: metavar$1,
+			parse(input) {
+				let value;
+				try {
+					value = BigInt(input);
+				} catch (e) {
+					if (e instanceof SyntaxError) return {
+						success: false,
+						error: options.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : message`Expected a valid integer, but got ${input}.`
+					};
+					throw e;
+				}
+				if (options.min != null && value < options.min) return {
 					success: false,
-					error: options.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : message`Expected a valid integer, but got ${input}.`
+					error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, options.min) : options.errors.belowMinimum : message`Expected a value greater than or equal to ${text(options.min.toLocaleString("en"))}, but got ${input}.`
 				};
-				throw e;
+				else if (options.max != null && value > options.max) return {
+					success: false,
+					error: options.errors?.aboveMaximum ? typeof options.errors.aboveMaximum === "function" ? options.errors.aboveMaximum(value, options.max) : options.errors.aboveMaximum : message`Expected a value less than or equal to ${text(options.max.toLocaleString("en"))}, but got ${input}.`
+				};
+				return {
+					success: true,
+					value
+				};
+			},
+			format(value) {
+				return value.toString();
 			}
-			if (options.min != null && value < options.min) return {
-				success: false,
-				error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, options.min) : options.errors.belowMinimum : message`Expected a value greater than or equal to ${text(options.min.toLocaleString("en"))}, but got ${input}.`
-			};
-			else if (options.max != null && value > options.max) return {
-				success: false,
-				error: options.errors?.aboveMaximum ? typeof options.errors.aboveMaximum === "function" ? options.errors.aboveMaximum(value, options.max) : options.errors.aboveMaximum : message`Expected a value less than or equal to ${text(options.max.toLocaleString("en"))}, but got ${input}.`
-			};
-			return {
-				success: true,
-				value
-			};
-		},
-		format(value) {
-			return value.toString();
-		}
-	};
+		};
+	}
+	const metavar = options?.metavar ?? "INTEGER";
+	ensureNonEmptyString(metavar);
 	return {
-		metavar: options?.metavar ?? "INTEGER",
+		metavar,
 		parse(input) {
 			if (!input.match(/^-?\d+$/)) return {
 				success: false,
@@ -192,8 +203,10 @@ function integer(options) {
 */
 function float(options = {}) {
 	const floatRegex = /^[+-]?(?:(?:\d+\.?\d*)|(?:\d*\.\d+))(?:[eE][+-]?\d+)?$/;
+	const metavar = options.metavar ?? "NUMBER";
+	ensureNonEmptyString(metavar);
 	return {
-		metavar: options.metavar ?? "NUMBER",
+		metavar,
 		parse(input) {
 			let value;
 			const lowerInput = input.toLowerCase();
@@ -239,8 +252,10 @@ function float(options = {}) {
 */
 function url(options = {}) {
 	const allowedProtocols = options.allowedProtocols?.map((p) => p.toLowerCase());
+	const metavar = options.metavar ?? "URL";
+	ensureNonEmptyString(metavar);
 	return {
-		metavar: options.metavar ?? "URL",
+		metavar,
 		parse(input) {
 			if (!URL.canParse(input)) return {
 				success: false,
@@ -281,8 +296,10 @@ function url(options = {}) {
 *          objects.
 */
 function locale(options = {}) {
+	const metavar = options.metavar ?? "LOCALE";
+	ensureNonEmptyString(metavar);
 	return {
-		metavar: options.metavar ?? "LOCALE",
+		metavar,
 		parse(input) {
 			let locale$1;
 			try {
@@ -548,8 +565,10 @@ function locale(options = {}) {
 */
 function uuid(options = {}) {
 	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+	const metavar = options.metavar ?? "UUID";
+	ensureNonEmptyString(metavar);
 	return {
-		metavar: options.metavar ?? "UUID",
+		metavar,
 		parse(input) {
 			if (!uuidRegex.test(input)) return {
 				success: false,
@@ -583,4 +602,4 @@ function uuid(options = {}) {
 }
 
 //#endregion
-export { choice, float, integer, isValueParser, locale, string, url, uuid };
+export { choice, ensureNonEmptyString, float, integer, isNonEmptyString, isValueParser, locale, string, url, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.9.0-dev.184+a94f89b9",
+  "version": "0.9.0-dev.186+976c1c1f",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -99,6 +99,14 @@
       "import": "./dist/modifiers.js",
       "require": "./dist/modifiers.cjs"
     },
+    "./nonempty": {
+      "types": {
+        "import": "./dist/nonempty.d.ts",
+        "require": "./dist/nonempty.d.cts"
+      },
+      "import": "./dist/nonempty.js",
+      "require": "./dist/nonempty.cjs"
+    },
     "./parser": {
       "types": {
         "import": "./dist/parser.d.ts",