@optique/core 1.0.0-dev.395 → 1.0.0-dev.401

package/dist/doc.cjs

@@ -3,6 +3,28 @@ const require_usage = require('./usage.cjs');
 
 //#region src/doc.ts
 /**
+* Classifies a {@link DocSection} by its content type for use in the
+* default smart sort.
+*
+* @returns `0` for command-only sections, `1` for mixed sections, `2` for
+*   option/argument/passthrough-only sections.
+*/
+function classifySection(section) {
+	const hasCommand = section.entries.some((e) => e.term.type === "command");
+	const hasNonCommand = section.entries.some((e) => e.term.type !== "command");
+	if (hasCommand && !hasNonCommand) return 0;
+	if (hasCommand && hasNonCommand) return 1;
+	return 2;
+}
+/**
+* The default section comparator: command-only sections come first, then
+* mixed sections, then option/argument-only sections.  Sections with the
+* same score preserve their original relative order (stable sort).
+*/
+function defaultSectionOrder(a, b) {
+	return classifySection(a) - classifySection(b);
+}
+/**
 * Formats a documentation page into a human-readable string.
 *
 * This function takes a structured {@link DocPage} and converts it into
@@ -64,7 +86,16 @@ function formatDocPage(programName, page, options = {}) {
 		});
 		output += "\n";
 	}
-	const sections = page.sections.toSorted((a, b) => a.title == null && b.title == null ? 0 : a.title == null ? -1 : 1);
+	const comparator = options.sectionOrder ?? defaultSectionOrder;
+	const sections = page.sections.map((s, i) => ({
+		section: s,
+		index: i
+	})).toSorted((a, b) => {
+		const cmp = comparator(a.section, b.section);
+		if (cmp !== 0) return cmp;
+		const titleCmp = (a.section.title == null ? 0 : 1) - (b.section.title == null ? 0 : 1);
+		return titleCmp !== 0 ? titleCmp : a.index - b.index;
+	}).map(({ section }) => section);
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";

package/dist/doc.d.cts

@@ -228,6 +228,28 @@ interface DocPageFormatOptions {
    * ```
    */
   showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order (stable sort).
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   *
+   * @example
+   * ```typescript
+   * // Sort sections alphabetically by title
+   * {
+   *   sectionOrder: (a, b) => (a.title ?? "").localeCompare(b.title ?? "")
+   * }
+   * ```
+   */
+  sectionOrder?: (a: DocSection, b: DocSection) => number;
 }
 /**
  * Formats a documentation page into a human-readable string.

package/dist/doc.d.ts

@@ -228,6 +228,28 @@ interface DocPageFormatOptions {
    * ```
    */
   showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order (stable sort).
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   *
+   * @example
+   * ```typescript
+   * // Sort sections alphabetically by title
+   * {
+   *   sectionOrder: (a, b) => (a.title ?? "").localeCompare(b.title ?? "")
+   * }
+   * ```
+   */
+  sectionOrder?: (a: DocSection, b: DocSection) => number;
 }
 /**
  * Formats a documentation page into a human-readable string.

package/dist/doc.js

@@ -3,6 +3,28 @@ import { formatUsage, formatUsageTerm } from "./usage.js";
 
 //#region src/doc.ts
 /**
+* Classifies a {@link DocSection} by its content type for use in the
+* default smart sort.
+*
+* @returns `0` for command-only sections, `1` for mixed sections, `2` for
+*   option/argument/passthrough-only sections.
+*/
+function classifySection(section) {
+	const hasCommand = section.entries.some((e) => e.term.type === "command");
+	const hasNonCommand = section.entries.some((e) => e.term.type !== "command");
+	if (hasCommand && !hasNonCommand) return 0;
+	if (hasCommand && hasNonCommand) return 1;
+	return 2;
+}
+/**
+* The default section comparator: command-only sections come first, then
+* mixed sections, then option/argument-only sections.  Sections with the
+* same score preserve their original relative order (stable sort).
+*/
+function defaultSectionOrder(a, b) {
+	return classifySection(a) - classifySection(b);
+}
+/**
 * Formats a documentation page into a human-readable string.
 *
 * This function takes a structured {@link DocPage} and converts it into
@@ -64,7 +86,16 @@ function formatDocPage(programName, page, options = {}) {
 		});
 		output += "\n";
 	}
-	const sections = page.sections.toSorted((a, b) => a.title == null && b.title == null ? 0 : a.title == null ? -1 : 1);
+	const comparator = options.sectionOrder ?? defaultSectionOrder;
+	const sections = page.sections.map((s, i) => ({
+		section: s,
+		index: i
+	})).toSorted((a, b) => {
+		const cmp = comparator(a.section, b.section);
+		if (cmp !== 0) return cmp;
+		const titleCmp = (a.section.title == null ? 0 : 1) - (b.section.title == null ? 0 : 1);
+		return titleCmp !== 0 ? titleCmp : a.index - b.index;
+	}).map(({ section }) => section);
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";

package/dist/facade.cjs

@@ -369,7 +369,7 @@ function classifyResult(result, args) {
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => {
@@ -392,7 +392,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			const doc = require_parser.getDocPage(completionParser, ["completion"]);
 			if (doc) stderr(require_doc.formatDocPage(programName, doc, {
 				colors,
-				maxWidth
+				maxWidth,
+				sectionOrder
 			}));
 		}
 		if (parser.$mode === "async") return Promise.resolve(callOnError(1));
@@ -457,7 +458,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		args = argsOrOptions;
 		options = optionsParam ?? {};
 	}
-	const { colors, maxWidth, showDefault, showChoices, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
@@ -500,7 +501,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	} : createCompletionParser(completion, programName, availableShells, completionName, completionHelpVisibility);
 	if (options.completion) {
 		const hasHelpOption = args.includes("--help");
-		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 		if (completionMode === "option" || completionMode === "both") for (let i = 0; i < args.length; i++) {
 			const arg = args[i];
 			const singularMatch = completionName === "singular" || completionName === "both" ? arg.startsWith("--completion=") : false;
@@ -508,14 +509,14 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			if (singularMatch || pluralMatch) {
 				const shell = arg.slice(arg.indexOf("=") + 1);
 				const completionArgs = args.slice(i + 1);
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 			} else {
 				const singularMatchExact = completionName === "singular" || completionName === "both" ? arg === "--completion" : false;
 				const pluralMatchExact = completionName === "plural" || completionName === "both" ? arg === "--completions" : false;
 				if (singularMatchExact || pluralMatchExact) {
 					const shell = i + 1 < args.length ? args[i + 1] : "";
 					const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
-					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 				}
 			}
 		}
@@ -636,7 +637,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							colors,
 							maxWidth,
 							showDefault,
-							showChoices
+							showChoices,
+							sectionOrder
 						}));
 					}
 					try {

package/dist/facade.d.cts

@@ -1,5 +1,5 @@
 import { Message } from "./message.cjs";
-import { ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
+import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
@@ -148,6 +148,20 @@ interface RunOptions<THelp, TError> {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order.
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   */
+  readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
   /**
    * Help configuration. When provided, enables help functionality.
    */

package/dist/facade.d.ts

@@ -1,5 +1,5 @@
 import { Message } from "./message.js";
-import { ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
+import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
@@ -148,6 +148,20 @@ interface RunOptions<THelp, TError> {
    * @since 0.10.0
    */
   readonly showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order.
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   */
+  readonly sectionOrder?: (a: DocSection, b: DocSection) => number;
   /**
    * Help configuration. When provided, enables help functionality.
    */

package/dist/facade.js

@@ -369,7 +369,7 @@ function classifyResult(result, args) {
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => {
@@ -392,7 +392,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			const doc = getDocPage(completionParser, ["completion"]);
 			if (doc) stderr(formatDocPage(programName, doc, {
 				colors,
-				maxWidth
+				maxWidth,
+				sectionOrder
 			}));
 		}
 		if (parser.$mode === "async") return Promise.resolve(callOnError(1));
@@ -457,7 +458,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		args = argsOrOptions;
 		options = optionsParam ?? {};
 	}
-	const { colors, maxWidth, showDefault, showChoices, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, sectionOrder, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
@@ -500,7 +501,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	} : createCompletionParser(completion, programName, availableShells, completionName, completionHelpVisibility);
 	if (options.completion) {
 		const hasHelpOption = args.includes("--help");
-		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 		if (completionMode === "option" || completionMode === "both") for (let i = 0; i < args.length; i++) {
 			const arg = args[i];
 			const singularMatch = completionName === "singular" || completionName === "both" ? arg.startsWith("--completion=") : false;
@@ -508,14 +509,14 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			if (singularMatch || pluralMatch) {
 				const shell = arg.slice(arg.indexOf("=") + 1);
 				const completionArgs = args.slice(i + 1);
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 			} else {
 				const singularMatchExact = completionName === "singular" || completionName === "both" ? arg === "--completion" : false;
 				const pluralMatchExact = completionName === "plural" || completionName === "both" ? arg === "--completions" : false;
 				if (singularMatchExact || pluralMatchExact) {
 					const shell = i + 1 < args.length ? args[i + 1] : "";
 					const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
-					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
+					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName, sectionOrder);
 				}
 			}
 		}
@@ -636,7 +637,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							colors,
 							maxWidth,
 							showDefault,
-							showChoices
+							showChoices,
+							sectionOrder
 						}));
 					}
 					try {

package/dist/index.cjs

@@ -47,6 +47,7 @@ exports.envVar = require_message.envVar;
 exports.extractArgumentMetavars = require_usage.extractArgumentMetavars;
 exports.extractCommandNames = require_usage.extractCommandNames;
 exports.extractOptionNames = require_usage.extractOptionNames;
+exports.fail = require_primitives.fail;
 exports.fish = require_completion.fish;
 exports.flag = require_primitives.flag;
 exports.float = require_valueparser.float;

package/dist/index.d.cts

@@ -7,9 +7,9 @@ import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsStr
 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 { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.cjs";
-import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
+import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.cjs";
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { CompletionHelpVisibility, CompletionName, ExtractRequiredOptions, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -7,9 +7,9 @@ import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsStr
 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 { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
-import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
+import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { CompletionHelpVisibility, CompletionName, ExtractRequiredOptions, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -8,8 +8,8 @@ import { formatDocPage } from "./doc.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
-import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
+import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/parser.cjs

@@ -424,6 +424,7 @@ exports.command = require_primitives.command;
 exports.concat = require_constructs.concat;
 exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
+exports.fail = require_primitives.fail;
 exports.flag = require_primitives.flag;
 exports.getDocPage = getDocPage;
 exports.getDocPageAsync = getDocPageAsync;

package/dist/parser.d.cts

@@ -6,7 +6,7 @@ import { DependencyRegistryLike } from "./registry-types.cjs";
 import { ValueParserResult } from "./valueparser.cjs";
 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 { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
-import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
+import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.cjs";
 
 //#region src/parser.d.ts
 
@@ -534,4 +534,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: rea
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.d.ts

@@ -6,7 +6,7 @@ import { DependencyRegistryLike } from "./registry-types.js";
 import { ValueParserResult } from "./valueparser.js";
 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 { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
-import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
+import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 
 //#region src/parser.d.ts
 
@@ -534,4 +534,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: rea
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.js

@@ -3,7 +3,7 @@ import { message } from "./message.js";
 import { normalizeUsage } from "./usage.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
-import { argument, command, constant, flag, option, passThrough } from "./primitives.js";
+import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 
 //#region src/parser.ts
 /**
@@ -417,4 +417,4 @@ function buildDocPage(parser, context, args) {
 }
 
 //#endregion
-export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/primitives.cjs

@@ -53,6 +53,54 @@ function constant(value) {
 	};
 }
 /**
+* Creates a parser that always fails without consuming any input.
+*
+* This is the counterpart to {@link constant}: while `constant(value)` always
+* succeeds, `fail<T>()` always fails.  At the type level it is declared to
+* produce a value of type `T`, so it composes seamlessly with other parsers
+* that expect `Parser<"sync", T, …>`.
+*
+* The primary use case is as the inner parser for
+* `bindConfig(fail<T>(), { … })` when a value should *only* come from a
+* config file and has no corresponding CLI flag or argument.  Because `fail()`
+* always fails, `bindConfig` will always fall back to the config file (or the
+* supplied default).
+*
+* @template T The type of value this parser is declared to produce.
+* @returns A {@link Parser} that always fails at parse time and always fails at
+*          complete time.
+* @since 1.0.0
+*/
+function fail() {
+	return {
+		$valueType: [],
+		$stateType: [],
+		$mode: "sync",
+		priority: 0,
+		usage: [],
+		initialState: void 0,
+		parse(_context) {
+			return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`No value provided.`
+			};
+		},
+		complete(_state) {
+			return {
+				success: false,
+				error: require_message.message`No value provided.`
+			};
+		},
+		suggest(_context, _prefix) {
+			return [];
+		},
+		getDocFragments(_state, _defaultValue) {
+			return { fragments: [] };
+		}
+	};
+}
+/**
 * Internal helper to get suggestions from a value parser, using dependency values
 * if the parser is a derived parser and dependency values are available.
 * @internal
@@ -1185,6 +1233,7 @@ function passThrough(options = {}) {
 exports.argument = argument;
 exports.command = command;
 exports.constant = constant;
+exports.fail = fail;
 exports.flag = flag;
 exports.option = option;
 exports.passThrough = passThrough;

package/dist/primitives.d.cts

@@ -18,6 +18,26 @@ type OptionState<T> = ValueParserResult<T> | DeferredParseState<T> | PendingDepe
  * @template T The type of the constant value produced by the parser.
  */
 declare function constant<const T>(value: T): Parser<"sync", T, T>;
+/**
+ * Creates a parser that always fails without consuming any input.
+ *
+ * This is the counterpart to {@link constant}: while `constant(value)` always
+ * succeeds, `fail<T>()` always fails.  At the type level it is declared to
+ * produce a value of type `T`, so it composes seamlessly with other parsers
+ * that expect `Parser<"sync", T, …>`.
+ *
+ * The primary use case is as the inner parser for
+ * `bindConfig(fail<T>(), { … })` when a value should *only* come from a
+ * config file and has no corresponding CLI flag or argument.  Because `fail()`
+ * always fails, `bindConfig` will always fall back to the config file (or the
+ * supplied default).
+ *
+ * @template T The type of value this parser is declared to produce.
+ * @returns A {@link Parser} that always fails at parse time and always fails at
+ *          complete time.
+ * @since 1.0.0
+ */
+declare function fail<T>(): Parser<"sync", T, undefined>;
 /**
  * Options for the {@link option} parser.
  */
@@ -430,4 +450,4 @@ interface PassThroughOptions {
  */
 declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough };

package/dist/primitives.d.ts

@@ -18,6 +18,26 @@ type OptionState<T> = ValueParserResult<T> | DeferredParseState<T> | PendingDepe
  * @template T The type of the constant value produced by the parser.
  */
 declare function constant<const T>(value: T): Parser<"sync", T, T>;
+/**
+ * Creates a parser that always fails without consuming any input.
+ *
+ * This is the counterpart to {@link constant}: while `constant(value)` always
+ * succeeds, `fail<T>()` always fails.  At the type level it is declared to
+ * produce a value of type `T`, so it composes seamlessly with other parsers
+ * that expect `Parser<"sync", T, …>`.
+ *
+ * The primary use case is as the inner parser for
+ * `bindConfig(fail<T>(), { … })` when a value should *only* come from a
+ * config file and has no corresponding CLI flag or argument.  Because `fail()`
+ * always fails, `bindConfig` will always fall back to the config file (or the
+ * supplied default).
+ *
+ * @template T The type of value this parser is declared to produce.
+ * @returns A {@link Parser} that always fails at parse time and always fails at
+ *          complete time.
+ * @since 1.0.0
+ */
+declare function fail<T>(): Parser<"sync", T, undefined>;
 /**
  * Options for the {@link option} parser.
  */
@@ -430,4 +450,4 @@ interface PassThroughOptions {
  */
 declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough };

package/dist/primitives.js

@@ -53,6 +53,54 @@ function constant(value) {
 	};
 }
 /**
+* Creates a parser that always fails without consuming any input.
+*
+* This is the counterpart to {@link constant}: while `constant(value)` always
+* succeeds, `fail<T>()` always fails.  At the type level it is declared to
+* produce a value of type `T`, so it composes seamlessly with other parsers
+* that expect `Parser<"sync", T, …>`.
+*
+* The primary use case is as the inner parser for
+* `bindConfig(fail<T>(), { … })` when a value should *only* come from a
+* config file and has no corresponding CLI flag or argument.  Because `fail()`
+* always fails, `bindConfig` will always fall back to the config file (or the
+* supplied default).
+*
+* @template T The type of value this parser is declared to produce.
+* @returns A {@link Parser} that always fails at parse time and always fails at
+*          complete time.
+* @since 1.0.0
+*/
+function fail() {
+	return {
+		$valueType: [],
+		$stateType: [],
+		$mode: "sync",
+		priority: 0,
+		usage: [],
+		initialState: void 0,
+		parse(_context) {
+			return {
+				success: false,
+				consumed: 0,
+				error: message`No value provided.`
+			};
+		},
+		complete(_state) {
+			return {
+				success: false,
+				error: message`No value provided.`
+			};
+		},
+		suggest(_context, _prefix) {
+			return [];
+		},
+		getDocFragments(_state, _defaultValue) {
+			return { fragments: [] };
+		}
+	};
+}
+/**
 * Internal helper to get suggestions from a value parser, using dependency values
 * if the parser is a derived parser and dependency values are available.
 * @internal
@@ -1182,4 +1230,4 @@ function passThrough(options = {}) {
 }
 
 //#endregion
-export { argument, command, constant, flag, option, passThrough };
+export { argument, command, constant, fail, flag, option, passThrough };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.395+ace61d13",
+  "version": "1.0.0-dev.401+5769648d",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",