@optique/core 1.3.0-dev.2581 → 1.3.0-dev.2583

package/dist/dependency-runtime.d.ts

@@ -3,7 +3,7 @@ import { DependencyRegistryLike } from "./registry-types.js";
 import { ValueParserResult } from "./valueparser.js";
 import { ParserDependencyMetadata } from "./dependency-metadata.js";
 import { InputTrace } from "./input-trace.js";
-import { EffectfulCompletionSession, ExecutionContext } from "./internal/parser.js";
+import { EffectfulCompletionSession, ExecutionContext, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 
 //#region src/dependency-runtime.d.ts
 
@@ -612,13 +612,29 @@ declare function extractRawInputFromState(state: unknown): string | undefined;
  * @since 1.3.0
  */
 declare const effectfulSchedulingNodesKey: unique symbol;
+/**
+ * Options that steer how far a runtime-node expansion walks.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface ExpandRuntimeNodesOptions {
+  /**
+   * Stops the walk at an exclusive parser—an `or()`, `longestMatch()`, or
+   * `conditional()` alternative—that has not opted into source
+   * collection, so a scope of its own is not folded into the enclosing
+   * one.  A hook that expands descendants itself must forward this to
+   * its own expansion.
+   */
+  readonly structuralOnly?: boolean;
+}
 /**
  * The shape of the {@link effectfulSchedulingNodesKey} hook.
  *
  * @internal
  * @since 1.3.0
  */
-type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined) => readonly RuntimeNode[];
+type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined, options?: ExpandRuntimeNodesOptions) => readonly RuntimeNode[];
 /**
  * Opt-in marker for parsers whose {@link effectfulSchedulingNodesKey}
  * hook also defines their explicit-source *collection* scope.
@@ -929,6 +945,22 @@ declare function resolveStateWithRuntime(state: unknown, runtime: DependencyRunt
  * @since 1.0.0
  */
 declare function resolveStateWithRuntimeAsync(state: unknown, runtime: DependencyRuntimeContext): Promise<unknown>;
+/**
+ * Determines whether a parser state represents an explicit match (the user
+ * provided input) rather than an initial/pending state.
+ *
+ * @param fieldState The parser's state.
+ * @param parser The parser owning that state.
+ * @returns `true` when the state reflects command-line input, whether or
+ *          not that input passed validation.
+ * @internal
+ * @since 1.3.0
+ */
+declare function isMatchedState(fieldState: unknown, parser: {
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+  readonly initialState?: unknown;
+  readonly [unmatchedNonCliDependencySourceStateMarker]?: true;
+}): boolean;
 /**
  * Builds {@link RuntimeNode}s from field→parser pairs and a state record.
  *
@@ -961,5 +993,18 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly dependencyMetadata?: ParserDependencyMetadata;
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
+/**
+ * Reads a derived parser state's snapshotted default dependency values.
+ *
+ * Nodes must carry the parse-time snapshot so replay never re-evaluates a
+ * dynamic `getDefaultDependencyValues()` thunk.
+ *
+ * @param state The derived parser's state.
+ * @returns The snapshotted values, or `undefined` when the state carries
+ *          none.
+ * @internal
+ * @since 1.3.0
+ */
+declare function getDefaultDependencySnapshot(state: unknown): readonly unknown[] | undefined;
 //#endregion
-export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ExpandRuntimeNodesOptions, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, getDefaultDependencySnapshot, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, isMatchedState, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.js

@@ -1850,6 +1850,13 @@ async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE_
 /**
 * Determines whether a parser state represents an explicit match (the user
 * provided input) rather than an initial/pending state.
+*
+* @param fieldState The parser's state.
+* @param parser The parser owning that state.
+* @returns `true` when the state reflects command-line input, whether or
+*          not that input passed validation.
+* @internal
+* @since 1.3.0
 */
 function isMatchedState(fieldState, parser) {
 	if (fieldState === void 0) return false;
@@ -1922,6 +1929,18 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 	}
 	return nodes;
 }
+/**
+* Reads a derived parser state's snapshotted default dependency values.
+*
+* Nodes must carry the parse-time snapshot so replay never re-evaluates a
+* dynamic `getDefaultDependencyValues()` thunk.
+*
+* @param state The derived parser's state.
+* @returns The snapshotted values, or `undefined` when the state carries
+*          none.
+* @internal
+* @since 1.3.0
+*/
 function getDefaultDependencySnapshot(state) {
 	return getDefaultDependencySnapshotInner(state, /* @__PURE__ */ new Set());
 }
@@ -1947,4 +1966,4 @@ function getDefaultDependencySnapshotInner(state, visited) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, getDefaultDependencySnapshot, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, isMatchedState, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/index.cjs

@@ -105,6 +105,7 @@ exports.optionName = require_message.optionName;
 exports.optionNames = require_message.optionNames;
 exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
+exports.origin = require_valueparser.origin;
 exports.parse = require_internal_parser.parse;
 exports.parseAsync = require_internal_parser.parseAsync;
 exports.parseDetailed = require_internal_parser.parseDetailed;

package/dist/index.d.cts

@@ -4,7 +4,7 @@ import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOption
 import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.cjs";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.cjs";
 import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
@@ -13,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOption
 import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
 import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -13,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

@@ -9,8 +9,8 @@ import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { WithDefaultError, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
-import { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
+import { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
 import { argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/valueparser.cjs

@@ -2750,6 +2750,178 @@ function url(options = {}) {
 	};
 }
 /**
+* A host name that the WHATWG URL parser has canonicalized into a dotted-quad
+* IPv4 address.  Matching the canonical form is enough, because the parser
+* turns every other spelling (`0x7f.1`, `2130706433`, …) into it.
+*/
+const IPV4_PATTERN = /^\d{1,3}(?:\.\d{1,3}){3}$/u;
+/**
+* Creates a {@link ValueParser} for web origins.
+*
+* An origin is a scheme, a host, and an optional port, and nothing else.  The
+* parser returns a `URL` whose pathname is `/` and which carries no
+* credentials, query, or fragment.
+*
+* Input is canonicalized rather than rejected when it carries more than an
+* origin: the host is lowercased, internationalized names are converted to
+* punycode, and a default port is elided, so `HTTPS://Example.COM/`,
+* `https://example.com:443/path?query#fragment` all parse to
+* `https://example.com`.  Set `extraComponents: "reject"` to fail on a path,
+* query, or fragment instead.  Credentials are always rejected.  Schemes whose
+* origin is opaque (`mailto:`, `data:`, `file:`) are rejected, as is `blob:`,
+* whose origin belongs to the URL it wraps.
+*
+* By default a trailing root-zone dot is stripped, so `example.com.` becomes
+* `example.com`.  This differs from the WHATWG origin, which keeps the dot, so
+* the two strings are not interchangeable when an exact origin comparison
+* matters.  Use `trailingDot: "preserve"` for the WHATWG behavior or
+* `trailingDot: "append"` to force a fully-qualified name.
+*
+* @param options Configuration options for the origin parser.
+* @returns A {@link ValueParser} that converts string input to `URL` objects
+*          that name an origin.
+* @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+*   string ending with a colon (e.g., `"https:"`).
+* @since 1.3.0
+*/
+function origin(options = {}) {
+	const metavar$1 = options.metavar ?? "ORIGIN";
+	require_nonempty.ensureNonEmptyString(metavar$1);
+	checkEnumOption(options, "extraComponents", ["strip", "reject"]);
+	checkEnumOption(options, "trailingDot", [
+		"strip",
+		"preserve",
+		"append"
+	]);
+	const extraComponents = options.extraComponents ?? "strip";
+	const trailingDot = options.trailingDot ?? "strip";
+	const originalProtocolsList = [];
+	const normalizedProtocolsList = [];
+	if (options.allowedProtocols != null) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const protocol of options.allowedProtocols) {
+			if (typeof protocol !== "string" || !/^[a-z][a-z0-9+\-.]*:$/i.test(protocol)) {
+				const rendered = typeof protocol === "string" ? JSON.stringify(protocol) : String(protocol);
+				throw new TypeError(`Each allowed protocol must be a valid protocol ending with a colon (e.g., "https:"), got: ${rendered}.`);
+			}
+			const normalized = protocol.toLowerCase();
+			if (seen.has(normalized)) continue;
+			seen.add(normalized);
+			originalProtocolsList.push(protocol);
+			normalizedProtocolsList.push(normalized);
+		}
+		if (originalProtocolsList.length === 0) throw new TypeError("allowedProtocols must not be empty.");
+	}
+	const originalProtocols = options.allowedProtocols != null ? Object.freeze(originalProtocolsList) : void 0;
+	const allowedProtocols = options.allowedProtocols != null ? Object.freeze(normalizedProtocolsList) : void 0;
+	const invalidOrigin = options.errors?.invalidOrigin;
+	const disallowedProtocol = options.errors?.disallowedProtocol;
+	function invalidOriginError(input) {
+		return invalidOrigin ? typeof invalidOrigin === "function" ? invalidOrigin(input) : invalidOrigin : require_message.message`Invalid origin: ${input}.`;
+	}
+	function disallowedProtocolError(protocol) {
+		return disallowedProtocol ? typeof disallowedProtocol === "function" ? disallowedProtocol(protocol, originalProtocols) : disallowedProtocol : [
+			{
+				type: "text",
+				text: "URL protocol "
+			},
+			{
+				type: "value",
+				value: protocol
+			},
+			{
+				type: "text",
+				text: " is not allowed. Allowed protocols: "
+			},
+			...require_message.valueSet(originalProtocols, {
+				fallback: "",
+				locale: "en-US"
+			}),
+			{
+				type: "text",
+				text: "."
+			}
+		];
+	}
+	function withTrailingDot(url$1) {
+		if (trailingDot === "preserve") return url$1;
+		const { hostname: hostname$1 } = url$1;
+		if (hostname$1.startsWith("[") || IPV4_PATTERN.test(hostname$1)) return url$1;
+		if (trailingDot === "strip") {
+			const stripped = hostname$1.replace(/\.+$/u, "");
+			if (stripped !== "") url$1.hostname = stripped;
+		} else if (!hostname$1.endsWith(".")) url$1.hostname = `${hostname$1}.`;
+		return url$1;
+	}
+	function resolve(url$1, label) {
+		if (allowedProtocols != null && !allowedProtocols.includes(url$1.protocol)) return {
+			success: false,
+			error: disallowedProtocolError(url$1.protocol)
+		};
+		if (url$1.protocol === "blob:") return {
+			success: false,
+			error: require_message.message`The URL ${label} wraps another origin. Pass that origin instead.`
+		};
+		if (url$1.origin === "null") return {
+			success: false,
+			error: require_message.message`The URL ${label} has no origin.`
+		};
+		if (url$1.username !== "" || url$1.password !== "") return {
+			success: false,
+			error: require_message.message`An origin must not contain credentials: ${url$1.origin}`
+		};
+		if (extraComponents === "reject" && (url$1.pathname !== "/" || url$1.search !== "" || url$1.hash !== "")) return {
+			success: false,
+			error: require_message.message`Expected only an origin, but got: ${label}`
+		};
+		return {
+			success: true,
+			value: withTrailingDot(new URL(url$1.origin))
+		};
+	}
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		get placeholder() {
+			return new URL(`${allowedProtocols?.[0] ?? "http:"}//0.invalid`);
+		},
+		parse(input) {
+			if (!URL.canParse(input)) return {
+				success: false,
+				error: invalidOriginError(input)
+			};
+			return resolve(new URL(input), input);
+		},
+		validate(value) {
+			if (!(value instanceof URL)) return {
+				success: false,
+				error: invalidOriginError(String(value))
+			};
+			return resolve(value, value.href);
+		},
+		format(value) {
+			return value.origin;
+		},
+		normalize(value) {
+			if (!(value instanceof URL)) return value;
+			const result = resolve(value, value.href);
+			return result.success ? result.value : value;
+		},
+		*suggest(prefix) {
+			if (allowedProtocols && prefix.length > 0 && !prefix.includes(":")) for (const protocol of allowedProtocols) {
+				const cleanProtocol = protocol.replace(/:+$/, "");
+				if (cleanProtocol.startsWith(prefix.toLowerCase())) {
+					const suffix = SPECIAL_URL_SCHEMES.has(cleanProtocol) ? "://" : ":";
+					yield {
+						kind: "literal",
+						text: `${cleanProtocol}${suffix}`
+					};
+				}
+			}
+		}
+	};
+}
+/**
 * Creates a {@link ValueParser} for locale values.
 *
 * This parser validates that the input is a well-formed locale identifier
@@ -6691,6 +6863,7 @@ exports.json = json;
 exports.keyValue = keyValue;
 exports.locale = locale;
 exports.macAddress = macAddress;
+exports.origin = origin;
 exports.port = port;
 exports.portRange = portRange;
 exports.regExp = regExp;

package/dist/valueparser.d.cts

@@ -1189,6 +1189,91 @@ interface UrlOptions {
  *   string ending with a colon (e.g., `"https:"`).
  */
 declare function url(options?: UrlOptions): ValueParser<"sync", URL>;
+/**
+ * Options for creating an {@link origin} parser.
+ */
+interface OriginOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `ORIGIN` or `BASE_URL`.
+   * @default `"ORIGIN"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * List of allowed URL protocols (e.g., `["http:", "https:"]`).
+   * If specified, the parsed URL must use one of these protocols.
+   * Protocol names should include the trailing colon (e.g., `"https:"`).
+   * If not specified, any protocol with a tuple origin is allowed.
+   */
+  readonly allowedProtocols?: readonly string[];
+  /**
+   * How to treat a URL that carries more than an origin.
+   *
+   * - `"strip"`: return just the origin, discarding any path, query, or
+   *   fragment.
+   * - `"reject"`: fail when the input has a path other than `/`, a query, or
+   *   a fragment.
+   *
+   * Credentials are always rejected, under either setting.
+   * @default `"strip"`
+   */
+  readonly extraComponents?: "strip" | "reject";
+  /**
+   * How to treat a trailing dot on a domain name, as in `example.com.`.
+   *
+   * - `"strip"`: remove it, so `example.com.` becomes `example.com`.
+   * - `"preserve"`: keep it, matching the WHATWG URL origin exactly.
+   * - `"append"`: force it, so `example.com` becomes `example.com.`.  This
+   *   has no effect on an IP address literal.
+   *
+   * @default `"strip"`
+   */
+  readonly trailingDot?: "strip" | "preserve" | "append";
+  /**
+   * Custom error messages for origin parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid absolute URL.
+     */
+    readonly invalidOrigin?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when URL protocol is not allowed.
+     */
+    readonly disallowedProtocol?: Message | ((protocol: string, allowedProtocols: readonly string[]) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} for web origins.
+ *
+ * An origin is a scheme, a host, and an optional port, and nothing else.  The
+ * parser returns a `URL` whose pathname is `/` and which carries no
+ * credentials, query, or fragment.
+ *
+ * Input is canonicalized rather than rejected when it carries more than an
+ * origin: the host is lowercased, internationalized names are converted to
+ * punycode, and a default port is elided, so `HTTPS://Example.COM/`,
+ * `https://example.com:443/path?query#fragment` all parse to
+ * `https://example.com`.  Set `extraComponents: "reject"` to fail on a path,
+ * query, or fragment instead.  Credentials are always rejected.  Schemes whose
+ * origin is opaque (`mailto:`, `data:`, `file:`) are rejected, as is `blob:`,
+ * whose origin belongs to the URL it wraps.
+ *
+ * By default a trailing root-zone dot is stripped, so `example.com.` becomes
+ * `example.com`.  This differs from the WHATWG origin, which keeps the dot, so
+ * the two strings are not interchangeable when an exact origin comparison
+ * matters.  Use `trailingDot: "preserve"` for the WHATWG behavior or
+ * `trailingDot: "append"` to force a fully-qualified name.
+ *
+ * @param options Configuration options for the origin parser.
+ * @returns A {@link ValueParser} that converts string input to `URL` objects
+ *          that name an origin.
+ * @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+ *   string ending with a colon (e.g., `"https:"`).
+ * @since 1.3.0
+ */
+declare function origin(options?: OriginOptions): ValueParser<"sync", URL>;
 /**
  * Options for creating a {@link locale} parser.
  */
@@ -3337,4 +3422,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };

package/dist/valueparser.d.ts

@@ -1189,6 +1189,91 @@ interface UrlOptions {
  *   string ending with a colon (e.g., `"https:"`).
  */
 declare function url(options?: UrlOptions): ValueParser<"sync", URL>;
+/**
+ * Options for creating an {@link origin} parser.
+ */
+interface OriginOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `ORIGIN` or `BASE_URL`.
+   * @default `"ORIGIN"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * List of allowed URL protocols (e.g., `["http:", "https:"]`).
+   * If specified, the parsed URL must use one of these protocols.
+   * Protocol names should include the trailing colon (e.g., `"https:"`).
+   * If not specified, any protocol with a tuple origin is allowed.
+   */
+  readonly allowedProtocols?: readonly string[];
+  /**
+   * How to treat a URL that carries more than an origin.
+   *
+   * - `"strip"`: return just the origin, discarding any path, query, or
+   *   fragment.
+   * - `"reject"`: fail when the input has a path other than `/`, a query, or
+   *   a fragment.
+   *
+   * Credentials are always rejected, under either setting.
+   * @default `"strip"`
+   */
+  readonly extraComponents?: "strip" | "reject";
+  /**
+   * How to treat a trailing dot on a domain name, as in `example.com.`.
+   *
+   * - `"strip"`: remove it, so `example.com.` becomes `example.com`.
+   * - `"preserve"`: keep it, matching the WHATWG URL origin exactly.
+   * - `"append"`: force it, so `example.com` becomes `example.com.`.  This
+   *   has no effect on an IP address literal.
+   *
+   * @default `"strip"`
+   */
+  readonly trailingDot?: "strip" | "preserve" | "append";
+  /**
+   * Custom error messages for origin parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid absolute URL.
+     */
+    readonly invalidOrigin?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when URL protocol is not allowed.
+     */
+    readonly disallowedProtocol?: Message | ((protocol: string, allowedProtocols: readonly string[]) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} for web origins.
+ *
+ * An origin is a scheme, a host, and an optional port, and nothing else.  The
+ * parser returns a `URL` whose pathname is `/` and which carries no
+ * credentials, query, or fragment.
+ *
+ * Input is canonicalized rather than rejected when it carries more than an
+ * origin: the host is lowercased, internationalized names are converted to
+ * punycode, and a default port is elided, so `HTTPS://Example.COM/`,
+ * `https://example.com:443/path?query#fragment` all parse to
+ * `https://example.com`.  Set `extraComponents: "reject"` to fail on a path,
+ * query, or fragment instead.  Credentials are always rejected.  Schemes whose
+ * origin is opaque (`mailto:`, `data:`, `file:`) are rejected, as is `blob:`,
+ * whose origin belongs to the URL it wraps.
+ *
+ * By default a trailing root-zone dot is stripped, so `example.com.` becomes
+ * `example.com`.  This differs from the WHATWG origin, which keeps the dot, so
+ * the two strings are not interchangeable when an exact origin comparison
+ * matters.  Use `trailingDot: "preserve"` for the WHATWG behavior or
+ * `trailingDot: "append"` to force a fully-qualified name.
+ *
+ * @param options Configuration options for the origin parser.
+ * @returns A {@link ValueParser} that converts string input to `URL` objects
+ *          that name an origin.
+ * @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+ *   string ending with a colon (e.g., `"https:"`).
+ * @since 1.3.0
+ */
+declare function origin(options?: OriginOptions): ValueParser<"sync", URL>;
 /**
  * Options for creating a {@link locale} parser.
  */
@@ -3337,4 +3422,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };