@optique/core 1.0.0-dev.908 → 1.0.0-dev.921

package/dist/facade.cjs

@@ -1334,7 +1334,8 @@ async function runWith(parser, programName, contexts, options) {
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	try {
-		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, options);
+		const ctxOptions = options?.contextOptions;
+		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
 		if (!needsTwoPhase) {
 			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
@@ -1359,7 +1360,7 @@ async function runWith(parser, programName, contexts, options) {
 			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
 			return Promise.resolve(runParser(augmentedParser, programName, args, options));
 		}
-		const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, options);
+		const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions);
 		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 		if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
@@ -1391,7 +1392,8 @@ function runWithSync(parser, programName, contexts, options) {
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	try {
-		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, options);
+		const ctxOptions = options?.contextOptions;
+		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
 		if (!needsTwoPhase) {
 			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 			return runParser(augmentedParser, programName, args, options);
@@ -1405,7 +1407,7 @@ function runWithSync(parser, programName, contexts, options) {
 		} catch {
 			return runParser(augmentedParser1, programName, args, options);
 		}
-		const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, options);
+		const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, ctxOptions);
 		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 		return runParser(augmentedParser2, programName, args, options);

package/dist/facade.d.cts

@@ -367,7 +367,32 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
    * `process.argv.slice(2)` on Node.js/Bun or `Deno.args` on Deno.
    */
   readonly args?: readonly string[];
+  /**
+   * Options to forward to source contexts.  When contexts declare
+   * required options (via `$requiredOptions`), pass them here to
+   * avoid name collisions with runner-level options such as `args`,
+   * `help`, or `colors`.
+   *
+   * @since 1.0.0
+   */
+  readonly contextOptions?: Record<string, unknown>;
 }
+/**
+ * When contexts require options, demands a `contextOptions` property
+ * typed to those requirements.  When no context needs options
+ * (`void`, `unknown`, or `{}`), resolves to `unknown` (intersection no-op).
+ * When all context option keys are optional, `contextOptions` itself becomes
+ * optional so callers are not forced to pass an empty wrapper.
+ *
+ * @template TContexts The tuple/array type of source contexts.
+ * @template TValue The parser value type for placeholder substitution.
+ * @since 1.0.0
+ */
+type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TValue> = keyof ExtractRequiredOptions<TContexts, TValue> extends never ? unknown : Record<string, never> extends ExtractRequiredOptions<TContexts, TValue> ? {
+  readonly contextOptions?: ExtractRequiredOptions<TContexts, TValue>;
+} : {
+  readonly contextOptions: ExtractRequiredOptions<TContexts, TValue>;
+};
 /**
  * Runs a parser with multiple source contexts.
  *
@@ -416,7 +441,7 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
  * );
  * ```
  */
-declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
+declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 /**
  * Runs a synchronous parser with multiple source contexts.
  *
@@ -435,7 +460,7 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * `[Symbol.asyncDispose]` returns a Promise.
  * @since 0.10.0
  */
-declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): InferValue<TParser>;
+declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): InferValue<TParser>;
 /**
  * Runs any parser asynchronously with multiple source contexts.
  *
@@ -452,6 +477,6 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @returns Promise that resolves to the parsed result.
  * @since 0.10.0
  */
-declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
+declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.d.ts

@@ -367,7 +367,32 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
    * `process.argv.slice(2)` on Node.js/Bun or `Deno.args` on Deno.
    */
   readonly args?: readonly string[];
+  /**
+   * Options to forward to source contexts.  When contexts declare
+   * required options (via `$requiredOptions`), pass them here to
+   * avoid name collisions with runner-level options such as `args`,
+   * `help`, or `colors`.
+   *
+   * @since 1.0.0
+   */
+  readonly contextOptions?: Record<string, unknown>;
 }
+/**
+ * When contexts require options, demands a `contextOptions` property
+ * typed to those requirements.  When no context needs options
+ * (`void`, `unknown`, or `{}`), resolves to `unknown` (intersection no-op).
+ * When all context option keys are optional, `contextOptions` itself becomes
+ * optional so callers are not forced to pass an empty wrapper.
+ *
+ * @template TContexts The tuple/array type of source contexts.
+ * @template TValue The parser value type for placeholder substitution.
+ * @since 1.0.0
+ */
+type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TValue> = keyof ExtractRequiredOptions<TContexts, TValue> extends never ? unknown : Record<string, never> extends ExtractRequiredOptions<TContexts, TValue> ? {
+  readonly contextOptions?: ExtractRequiredOptions<TContexts, TValue>;
+} : {
+  readonly contextOptions: ExtractRequiredOptions<TContexts, TValue>;
+};
 /**
  * Runs a parser with multiple source contexts.
  *
@@ -416,7 +441,7 @@ interface RunWithOptions<THelp, TError> extends RunOptions<THelp, TError> {
  * );
  * ```
  */
-declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
+declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 /**
  * Runs a synchronous parser with multiple source contexts.
  *
@@ -435,7 +460,7 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * `[Symbol.asyncDispose]` returns a Promise.
  * @since 0.10.0
  */
-declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): InferValue<TParser>;
+declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): InferValue<TParser>;
 /**
  * Runs any parser asynchronously with multiple source contexts.
  *
@@ -452,6 +477,6 @@ declare function runWithSync<TParser extends Parser<"sync", unknown, unknown>, T
  * @returns Promise that resolves to the parsed result.
  * @since 0.10.0
  */
-declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ExtractRequiredOptions<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
+declare function runWithAsync<TParser extends Parser<Mode, unknown, unknown>, TContexts extends readonly SourceContext<unknown>[], THelp = void, TError = never>(parser: TParser, programName: string, contexts: TContexts, options: RunWithOptions<THelp, TError> & ContextOptionsParam<TContexts, InferValue<TParser>>): Promise<InferValue<TParser>>;
 //#endregion
-export { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };
+export { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, type ParserValuePlaceholder, RunOptions, RunParserError, RunWithOptions, type SourceContext, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync };

package/dist/facade.js

@@ -1334,7 +1334,8 @@ async function runWith(parser, programName, contexts, options) {
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	try {
-		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, options);
+		const ctxOptions = options?.contextOptions;
+		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
 		if (!needsTwoPhase) {
 			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
@@ -1359,7 +1360,7 @@ async function runWith(parser, programName, contexts, options) {
 			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
 			return Promise.resolve(runParser(augmentedParser, programName, args, options));
 		}
-		const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, options);
+		const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, ctxOptions);
 		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 		if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
@@ -1391,7 +1392,8 @@ function runWithSync(parser, programName, contexts, options) {
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
 	try {
-		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, options);
+		const ctxOptions = options?.contextOptions;
+		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
 		if (!needsTwoPhase) {
 			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 			return runParser(augmentedParser, programName, args, options);
@@ -1405,7 +1407,7 @@ function runWithSync(parser, programName, contexts, options) {
 		} catch {
 			return runParser(augmentedParser1, programName, args, options);
 		}
-		const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, options);
+		const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, ctxOptions);
 		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
 		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 		return runParser(augmentedParser2, programName, args, options);

package/dist/index.d.cts

@@ -11,5 +11,5 @@ import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOpti
 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 { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig, 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, CommandSubConfig, 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, GroupOptions, HiddenVisibility, 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, OptionSubConfig, 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, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, 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 };
+import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, 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, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, 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, GroupOptions, HiddenVisibility, 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, OptionSubConfig, 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, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, 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

@@ -11,5 +11,5 @@ import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOpti
 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 { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig, 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, CommandSubConfig, 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, GroupOptions, HiddenVisibility, 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, OptionSubConfig, 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, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, 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 };
+import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, 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, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, 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, GroupOptions, HiddenVisibility, 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, OptionSubConfig, 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, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, 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/valueparser.cjs

@@ -1386,6 +1386,8 @@ function email(options) {
 *
 * @param options - Options for socket address validation.
 * @returns A value parser for socket addresses.
+* @throws {TypeError} If `separator` contains digit characters, since digits
+*   in the separator would cause ambiguous splitting of port input.
 * @since 0.10.0
 *
 * @example
@@ -1406,9 +1408,10 @@ function email(options) {
 * ```
 */
 function socketAddress(options) {
-	const metavar = options?.metavar ?? "HOST:PORT";
-	require_nonempty.ensureNonEmptyString(metavar);
 	const separator = options?.separator ?? ":";
+	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
+	const metavar = options?.metavar ?? `HOST${separator}PORT`;
+	require_nonempty.ensureNonEmptyString(metavar);
 	const defaultPort = options?.defaultPort;
 	const requirePort = options?.requirePort ?? false;
 	const hostType = options?.host?.type ?? "both";
@@ -1512,9 +1515,10 @@ function socketAddress(options) {
 function portRange(options) {
 	if (options?.disallowWellKnown !== void 0 && typeof options.disallowWellKnown !== "boolean") throw new TypeError(`Expected disallowWellKnown to be a boolean, but got ${typeof options.disallowWellKnown}: ${String(options.disallowWellKnown)}.`);
 	if (options?.allowSingle !== void 0 && typeof options.allowSingle !== "boolean") throw new TypeError(`Expected allowSingle to be a boolean, but got ${typeof options.allowSingle}: ${String(options.allowSingle)}.`);
-	const metavar = options?.metavar ?? "PORT-PORT";
-	require_nonempty.ensureNonEmptyString(metavar);
 	const separator = options?.separator ?? "-";
+	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
+	const metavar = options?.metavar ?? `PORT${separator}PORT`;
+	require_nonempty.ensureNonEmptyString(metavar);
 	const allowSingle = options?.allowSingle ?? false;
 	const isBigInt = options?.type === "bigint";
 	const portParser = isBigInt ? port({

package/dist/valueparser.d.cts

@@ -1049,8 +1049,8 @@ interface SocketAddressValue {
  */
 interface SocketAddressOptions {
   /**
-   * The metavariable name for this parser.
-   * @default "HOST:PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"HOST:PORT"` for `":"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1123,6 +1123,8 @@ interface SocketAddressOptions {
  *
  * @param options - Options for socket address validation.
  * @returns A value parser for socket addresses.
+ * @throws {TypeError} If `separator` contains digit characters, since digits
+ *   in the separator would cause ambiguous splitting of port input.
  * @since 0.10.0
  *
  * @example
@@ -1185,8 +1187,8 @@ interface PortRangeOptionsNumber {
    */
   readonly type?: "number";
   /**
-   * The metavariable name for this parser.
-   * @default "PORT-PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"PORT-PORT"` for `"-"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1265,8 +1267,8 @@ interface PortRangeOptionsBigInt {
    */
   readonly type: "bigint";
   /**
-   * The metavariable name for this parser.
-   * @default "PORT-PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"PORT-PORT"` for `"-"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1346,6 +1348,8 @@ interface PortRangeOptionsBigInt {
  *
  * @param options - Options for port range validation.
  * @returns A value parser for port ranges.
+ * @throws {TypeError} If `separator` contains digit characters, since digits
+ *   in the separator would cause ambiguous splitting of numeric port input.
  * @since 0.10.0
  *
  * @example

package/dist/valueparser.d.ts

@@ -1049,8 +1049,8 @@ interface SocketAddressValue {
  */
 interface SocketAddressOptions {
   /**
-   * The metavariable name for this parser.
-   * @default "HOST:PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"HOST:PORT"` for `":"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1123,6 +1123,8 @@ interface SocketAddressOptions {
  *
  * @param options - Options for socket address validation.
  * @returns A value parser for socket addresses.
+ * @throws {TypeError} If `separator` contains digit characters, since digits
+ *   in the separator would cause ambiguous splitting of port input.
  * @since 0.10.0
  *
  * @example
@@ -1185,8 +1187,8 @@ interface PortRangeOptionsNumber {
    */
   readonly type?: "number";
   /**
-   * The metavariable name for this parser.
-   * @default "PORT-PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"PORT-PORT"` for `"-"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1265,8 +1267,8 @@ interface PortRangeOptionsBigInt {
    */
   readonly type: "bigint";
   /**
-   * The metavariable name for this parser.
-   * @default "PORT-PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"PORT-PORT"` for `"-"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1346,6 +1348,8 @@ interface PortRangeOptionsBigInt {
  *
  * @param options - Options for port range validation.
  * @returns A value parser for port ranges.
+ * @throws {TypeError} If `separator` contains digit characters, since digits
+ *   in the separator would cause ambiguous splitting of numeric port input.
  * @since 0.10.0
  *
  * @example

package/dist/valueparser.js

@@ -1386,6 +1386,8 @@ function email(options) {
 *
 * @param options - Options for socket address validation.
 * @returns A value parser for socket addresses.
+* @throws {TypeError} If `separator` contains digit characters, since digits
+*   in the separator would cause ambiguous splitting of port input.
 * @since 0.10.0
 *
 * @example
@@ -1406,9 +1408,10 @@ function email(options) {
 * ```
 */
 function socketAddress(options) {
-	const metavar = options?.metavar ?? "HOST:PORT";
-	ensureNonEmptyString(metavar);
 	const separator = options?.separator ?? ":";
+	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
+	const metavar = options?.metavar ?? `HOST${separator}PORT`;
+	ensureNonEmptyString(metavar);
 	const defaultPort = options?.defaultPort;
 	const requirePort = options?.requirePort ?? false;
 	const hostType = options?.host?.type ?? "both";
@@ -1512,9 +1515,10 @@ function socketAddress(options) {
 function portRange(options) {
 	if (options?.disallowWellKnown !== void 0 && typeof options.disallowWellKnown !== "boolean") throw new TypeError(`Expected disallowWellKnown to be a boolean, but got ${typeof options.disallowWellKnown}: ${String(options.disallowWellKnown)}.`);
 	if (options?.allowSingle !== void 0 && typeof options.allowSingle !== "boolean") throw new TypeError(`Expected allowSingle to be a boolean, but got ${typeof options.allowSingle}: ${String(options.allowSingle)}.`);
-	const metavar = options?.metavar ?? "PORT-PORT";
-	ensureNonEmptyString(metavar);
 	const separator = options?.separator ?? "-";
+	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
+	const metavar = options?.metavar ?? `PORT${separator}PORT`;
+	ensureNonEmptyString(metavar);
 	const allowSingle = options?.allowSingle ?? false;
 	const isBigInt = options?.type === "bigint";
 	const portParser = isBigInt ? port({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.908+f60f037d",
+  "version": "1.0.0-dev.921+754748bd",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",