@optique/core 1.2.0-dev.2301 → 1.2.0-dev.2302

package/dist/index.cjs

@@ -17,6 +17,7 @@ exports.RunParserError = require_facade.RunParserError;
 exports.WithDefaultError = require_modifiers.WithDefaultError;
 exports.argument = require_primitives.argument;
 exports.bash = require_completion.bash;
+exports.biject = require_valueparser.biject;
 exports.checkBooleanOption = require_valueparser.checkBooleanOption;
 exports.checkEnumOption = require_valueparser.checkEnumOption;
 exports.choice = require_valueparser.choice;
@@ -121,6 +122,7 @@ exports.suggest = require_internal_parser.suggest;
 exports.suggestAsync = require_internal_parser.suggestAsync;
 exports.suggestSync = require_internal_parser.suggestSync;
 exports.text = require_message.text;
+exports.transform = require_valueparser.transform;
 exports.tuple = require_constructs.tuple;
 exports.url = require_valueparser.url;
 exports.uuid = require_valueparser.uuid;

package/dist/index.d.cts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.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, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, 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, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, 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, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.cjs";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, 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";
@@ -12,4 +12,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, 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, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, 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, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, 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, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, 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, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, 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, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, 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, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, 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, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, parseSync, passThrough, port, portRange, pwsh, 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

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.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, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, 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, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, 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, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, 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";
@@ -12,4 +12,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, 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, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, 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, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, 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, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, 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, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, 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, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, 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, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, 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, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, parseSync, passThrough, port, portRange, pwsh, 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

@@ -8,8 +8,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 { checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, 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, port, portRange, 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, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, 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, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, parseSync, passThrough, port, portRange, pwsh, 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/internal/mode-dispatch.cjs

@@ -37,6 +37,42 @@ function mapModeValue(mode, value, mapFn) {
 	return mapFn(value);
 }
 /**
+* Maps a value or promise while preserving the declared execution mode.
+*
+* Some internal extension hooks predate `ModeValue` and expose a plain
+* `T | Promise<T>` return type. This helper adapts those hooks back into the
+* mode-dispatch boundary before applying a mapping function.
+*
+* @param mode The execution mode.
+* @param value The value or promise to transform.
+* @param mapFn Mapping function applied to the unwrapped value.
+* @returns The mapped value with correct mode wrapping.
+* @internal
+*/
+function mapMaybePromiseByMode(mode, value, mapFn) {
+	return mapModeValue(mode, wrapForMode(mode, value), mapFn);
+}
+/**
+* Adapts an iterable or async iterable to the declared execution mode.
+*
+* @param mode The execution mode.
+* @param value The iterable to adapt.
+* @returns The iterable with correct mode wrapping.
+* @throws {TypeError} If a synchronous mode receives an async iterable.
+* @internal
+*/
+function wrapIterableForMode(mode, value) {
+	return dispatchIterableByMode(mode, () => {
+		if (Symbol.asyncIterator in value) throw new TypeError("Synchronous mode cannot wrap AsyncIterable value.");
+		return value;
+	}, () => {
+		if (Symbol.asyncIterator in value) return value;
+		return async function* () {
+			yield* value;
+		}();
+	});
+}
+/**
 * Dispatches iterable to sync or async implementation based on mode.
 *
 * @param mode The execution mode.
@@ -54,5 +90,7 @@ function dispatchIterableByMode(mode, syncFn, asyncFn) {
 //#endregion
 exports.dispatchByMode = dispatchByMode;
 exports.dispatchIterableByMode = dispatchIterableByMode;
+exports.mapMaybePromiseByMode = mapMaybePromiseByMode;
 exports.mapModeValue = mapModeValue;
-exports.wrapForMode = wrapForMode;
+exports.wrapForMode = wrapForMode;
+exports.wrapIterableForMode = wrapIterableForMode;

package/dist/internal/mode-dispatch.d.cts

@@ -38,14 +38,17 @@ declare function wrapForMode<M extends Mode, T>(mode: M, value: T | Promise<T>):
  */
 declare function mapModeValue<M extends Mode, T, U>(mode: M, value: ModeValue<M, T>, mapFn: (value: T) => U): ModeValue<M, U>;
 /**
- * Dispatches iterable to sync or async implementation based on mode.
+ * Maps a value or promise while preserving the declared execution mode.
+ *
+ * Some internal extension hooks predate `ModeValue` and expose a plain
+ * `T | Promise<T>` return type. This helper adapts those hooks back into the
+ * mode-dispatch boundary before applying a mapping function.
  *
  * @param mode The execution mode.
- * @param syncFn Function returning sync iterable.
- * @param asyncFn Function returning async iterable.
- * @returns The iterable with correct mode wrapping.
+ * @param value The value or promise to transform.
+ * @param mapFn Mapping function applied to the unwrapped value.
+ * @returns The mapped value with correct mode wrapping.
  * @internal
- * @since 0.10.0
  */
 //#endregion
 export { dispatchByMode, mapModeValue, wrapForMode };

package/dist/internal/mode-dispatch.d.ts

@@ -38,14 +38,17 @@ declare function wrapForMode<M extends Mode, T>(mode: M, value: T | Promise<T>):
  */
 declare function mapModeValue<M extends Mode, T, U>(mode: M, value: ModeValue<M, T>, mapFn: (value: T) => U): ModeValue<M, U>;
 /**
- * Dispatches iterable to sync or async implementation based on mode.
+ * Maps a value or promise while preserving the declared execution mode.
+ *
+ * Some internal extension hooks predate `ModeValue` and expose a plain
+ * `T | Promise<T>` return type. This helper adapts those hooks back into the
+ * mode-dispatch boundary before applying a mapping function.
  *
  * @param mode The execution mode.
- * @param syncFn Function returning sync iterable.
- * @param asyncFn Function returning async iterable.
- * @returns The iterable with correct mode wrapping.
+ * @param value The value or promise to transform.
+ * @param mapFn Mapping function applied to the unwrapped value.
+ * @returns The mapped value with correct mode wrapping.
  * @internal
- * @since 0.10.0
  */
 //#endregion
 export { dispatchByMode, mapModeValue, wrapForMode };

package/dist/internal/mode-dispatch.js

@@ -36,6 +36,42 @@ function mapModeValue(mode, value, mapFn) {
 	return mapFn(value);
 }
 /**
+* Maps a value or promise while preserving the declared execution mode.
+*
+* Some internal extension hooks predate `ModeValue` and expose a plain
+* `T | Promise<T>` return type. This helper adapts those hooks back into the
+* mode-dispatch boundary before applying a mapping function.
+*
+* @param mode The execution mode.
+* @param value The value or promise to transform.
+* @param mapFn Mapping function applied to the unwrapped value.
+* @returns The mapped value with correct mode wrapping.
+* @internal
+*/
+function mapMaybePromiseByMode(mode, value, mapFn) {
+	return mapModeValue(mode, wrapForMode(mode, value), mapFn);
+}
+/**
+* Adapts an iterable or async iterable to the declared execution mode.
+*
+* @param mode The execution mode.
+* @param value The iterable to adapt.
+* @returns The iterable with correct mode wrapping.
+* @throws {TypeError} If a synchronous mode receives an async iterable.
+* @internal
+*/
+function wrapIterableForMode(mode, value) {
+	return dispatchIterableByMode(mode, () => {
+		if (Symbol.asyncIterator in value) throw new TypeError("Synchronous mode cannot wrap AsyncIterable value.");
+		return value;
+	}, () => {
+		if (Symbol.asyncIterator in value) return value;
+		return async function* () {
+			yield* value;
+		}();
+	});
+}
+/**
 * Dispatches iterable to sync or async implementation based on mode.
 *
 * @param mode The execution mode.
@@ -51,4 +87,4 @@ function dispatchIterableByMode(mode, syncFn, asyncFn) {
 }
 
 //#endregion
-export { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode };
+export { dispatchByMode, dispatchIterableByMode, mapMaybePromiseByMode, mapModeValue, wrapForMode, wrapIterableForMode };

package/dist/valueparser.cjs

@@ -1,9 +1,34 @@
 const require_message = require('./message.cjs');
+const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_internal_dependency = require('./internal/dependency.cjs');
 const require_suggestion = require('./suggestion.cjs');
 const require_nonempty = require('./nonempty.cjs');
 
 //#region src/valueparser.ts
+function transformValueParserResult(result, mapping) {
+	if (!result.success) return result;
+	const preserveSnapshot = (mapped) => {
+		const snapshot = require_internal_dependency.getSnapshottedDefaultDependencyValues(result);
+		return snapshot == null ? mapped : require_internal_dependency.snapshotDefaultDependencyValues(mapped, snapshot);
+	};
+	if (result.deferred) try {
+		return preserveSnapshot({
+			success: true,
+			value: mapping.map(result.value),
+			deferred: true
+		});
+	} catch {
+		return preserveSnapshot({
+			success: true,
+			value: void 0,
+			deferred: true
+		});
+	}
+	return preserveSnapshot({
+		success: true,
+		value: mapping.map(result.value)
+	});
+}
 /**
 * A predicate function that checks if an object is a {@link ValueParser}.
 * @param object The object to check.
@@ -191,6 +216,187 @@ function choice(choices, options = {}) {
 		}
 	};
 }
+function biject(mapping) {
+	if (Array.isArray(mapping)) throw new TypeError("Expected biject mapping to be a non-array object.");
+	const keys = [];
+	for (const key in mapping) if (Object.prototype.hasOwnProperty.call(mapping, key)) keys.push(key);
+	if (keys.length < 1) throw new RangeError("Expected at least one biject entry.");
+	const source = choice(keys);
+	const forward = /* @__PURE__ */ new Map();
+	const reverse = /* @__PURE__ */ new Map();
+	for (const key of keys) {
+		const value = mapping[key];
+		if (reverse.has(value)) throw new RangeError(`Duplicate biject value for key ${JSON.stringify(key)}.`);
+		forward.set(key, value);
+		reverse.set(value, key);
+	}
+	const parser = transform(source, {
+		map(value) {
+			return forward.get(value);
+		},
+		unmap(value) {
+			const key = reverse.get(value);
+			if (key !== void 0) return key;
+			try {
+				return String(value);
+			} catch {
+				return "";
+			}
+		}
+	});
+	Object.defineProperty(parser, "validate", {
+		value(value) {
+			if (reverse.has(value)) return {
+				success: true,
+				value
+			};
+			let input;
+			try {
+				input = String(value);
+			} catch {
+				input = "";
+			}
+			const result = source.parse(input);
+			if (!result.success) return result;
+			return {
+				success: false,
+				error: formatDefaultChoiceError(input, keys)
+			};
+		},
+		configurable: true,
+		enumerable: true
+	});
+	return parser;
+}
+/**
+* Creates a value parser that transforms the result of another value parser.
+*
+* This is useful when an existing value parser already describes the accepted
+* CLI spelling, suggestions, and error messages, but your application wants a
+* different result type.  For example, a string `choice()` can be transformed
+* into an internal enum, tagged object, or other domain type.
+*
+* Unlike parser-level `map()`, value parser transformation needs an inverse
+* mapping.  The `unmap` function lets the transformed parser format values,
+* validate fallback/default values, and reuse the wrapped parser's metadata
+* without guessing how to serialize the transformed type.
+*
+* Transform functions are synchronous.  If the wrapped parser is async, the
+* returned parser is async too, but `map` and `unmap` still run synchronously
+* after the wrapped parser resolves.
+*
+* @template M The execution mode of the wrapped parser.
+* @template T The value type produced by the wrapped parser.
+* @template U The value type produced by the transformed parser.
+* @param parser The value parser to transform.
+* @param mapping Mapping functions between the wrapped and transformed value
+*                types.
+* @returns A value parser that accepts the same input as `parser` and produces
+*          transformed values.
+* @since 1.2.0
+*/
+function transform(parser, mapping) {
+	const normalize = parser.normalize?.bind(parser);
+	const suggest = parser.suggest?.bind(parser);
+	const transformedChoices = parser.choices == null ? void 0 : Object.freeze(parser.choices.map((choice$1) => mapping.map(choice$1)));
+	const transformed = {
+		mode: parser.mode,
+		metavar: parser.metavar,
+		placeholder: void 0,
+		...transformedChoices == null ? {} : { choices: transformedChoices },
+		parse(input) {
+			return require_mode_dispatch.mapModeValue(parser.mode, parser.parse(input), (result) => transformValueParserResult(result, mapping));
+		},
+		format(value) {
+			return parser.format(mapping.unmap(value));
+		},
+		...normalize == null ? {} : { normalize(value) {
+			return mapping.map(normalize(mapping.unmap(value)));
+		} },
+		...suggest == null ? {} : { suggest(prefix) {
+			return suggest(prefix);
+		} }
+	};
+	Object.defineProperty(transformed, "placeholder", {
+		get() {
+			try {
+				return mapping.map(parser.placeholder);
+			} catch {
+				return void 0;
+			}
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validate === "function") {
+		const validate = parser.validate.bind(parser);
+		Object.defineProperty(transformed, "validate", {
+			value(value) {
+				const result = validate(mapping.unmap(value));
+				return result.success ? {
+					success: true,
+					value: mapping.map(result.value)
+				} : result;
+			},
+			configurable: true,
+			enumerable: true
+		});
+	} else if (parser.mode === "sync") {
+		const syncParser = parser;
+		Object.defineProperty(transformed, "validate", {
+			value(value) {
+				const result = syncParser.parse(syncParser.format(mapping.unmap(value)));
+				return result.success ? {
+					success: true,
+					value: mapping.map(result.value)
+				} : result;
+			},
+			configurable: true,
+			enumerable: true
+		});
+	}
+	if (require_internal_dependency.isDerivedValueParser(parser)) preserveTransformedDerivedMetadata(transformed, parser, mapping);
+	return transformed;
+}
+function preserveTransformedDerivedMetadata(transformed, parser, mapping) {
+	Object.defineProperties(transformed, {
+		[require_internal_dependency.derivedValueParserMarker]: {
+			value: true,
+			enumerable: true
+		},
+		[require_internal_dependency.dependencyId]: {
+			value: parser[require_internal_dependency.dependencyId],
+			enumerable: true
+		},
+		[require_internal_dependency.parseWithDependency]: {
+			value(input, dependencyValue) {
+				return require_mode_dispatch.mapMaybePromiseByMode(parser.mode, parser[require_internal_dependency.parseWithDependency](input, dependencyValue), (result) => transformValueParserResult(result, mapping));
+			},
+			enumerable: true
+		}
+	});
+	if (require_internal_dependency.dependencyIds in parser && parser[require_internal_dependency.dependencyIds] != null) Object.defineProperty(transformed, require_internal_dependency.dependencyIds, {
+		value: parser[require_internal_dependency.dependencyIds],
+		enumerable: true
+	});
+	if (require_internal_dependency.defaultValues in parser && parser[require_internal_dependency.defaultValues] != null) Object.defineProperty(transformed, require_internal_dependency.defaultValues, {
+		value: parser[require_internal_dependency.defaultValues],
+		enumerable: true
+	});
+	if (require_internal_dependency.singleDefaultValue in parser && parser[require_internal_dependency.singleDefaultValue] != null) Object.defineProperty(transformed, require_internal_dependency.singleDefaultValue, {
+		value: parser[require_internal_dependency.singleDefaultValue],
+		enumerable: true
+	});
+	if (require_internal_dependency.suggestWithDependency in parser && parser[require_internal_dependency.suggestWithDependency] != null) {
+		const suggest = parser[require_internal_dependency.suggestWithDependency];
+		Object.defineProperty(transformed, require_internal_dependency.suggestWithDependency, {
+			value(prefix, dependencyValue) {
+				return require_mode_dispatch.wrapIterableForMode(parser.mode, suggest(prefix, dependencyValue));
+			},
+			enumerable: true
+		});
+	}
+}
 /**
 * Validates that an option value, if present, is a boolean.
 * Throws a {@link TypeError} if the value is defined but not a boolean.
@@ -6336,6 +6542,7 @@ function plainObjectsEqual(a, b) {
 }
 
 //#endregion
+exports.biject = biject;
 exports.checkBooleanOption = checkBooleanOption;
 exports.checkEnumOption = checkEnumOption;
 exports.choice = choice;
@@ -6364,5 +6571,6 @@ exports.portRange = portRange;
 exports.semVer = semVer;
 exports.socketAddress = socketAddress;
 exports.string = string;
+exports.transform = transform;
 exports.url = url;
 exports.uuid = uuid;

package/dist/valueparser.d.cts

@@ -327,6 +327,36 @@ interface ChoiceOptionsNumber extends ChoiceOptionsBase {
  *             {@link ChoiceOptionsNumber} for number choices.
  */
 type ChoiceOptions = ChoiceOptionsString;
+/**
+ * Mapping functions for the {@link transform} value parser combinator.
+ *
+ * `map` converts values produced by the wrapped parser into the public result
+ * type.  `unmap` converts public values back to the wrapped parser's type so
+ * `format()`, `validate()`, and default-value handling can keep using the
+ * wrapped parser's own validation and formatting rules.
+ *
+ * The two functions should be inverses for the values your CLI accepts:
+ * `unmap(map(input))` should return a value accepted by the wrapped parser,
+ * and `map(unmap(output))` should preserve valid public values.
+ *
+ * @template T The value type produced by the wrapped parser.
+ * @template U The value type produced by the transformed parser.
+ * @since 1.2.0
+ */
+interface TransformMapping<T, U> {
+  /**
+   * Converts a value produced by the wrapped parser into the transformed
+   * parser's public value type.
+   */
+  map(value: T): U;
+  /**
+   * Converts a public transformed value back into the wrapped parser's value
+   * type for formatting and fallback validation.
+   */
+  unmap(value: U): T;
+}
+type BijectKey<T> = Extract<keyof T, string | number>;
+type BijectValue<T> = T[BijectKey<T>];
 /**
  * A predicate function that checks if an object is a {@link ValueParser}.
  * @param object The object to check.
@@ -374,6 +404,58 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  * @since 0.9.0
  */
 declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<"sync", T>;
+/**
+ * Creates a value parser from a one-to-one mapping of CLI spellings to values.
+ *
+ * The mapping's string keys are accepted as command-line input, and each key
+ * is parsed into its corresponding value.  Values must also be unique using
+ * the same equality semantics as `Map` keys, so the parser can format a value
+ * back to the original key.
+ *
+ * This is a convenience wrapper around `choice(Object.keys(mapping))` and
+ * {@link transform}.  It keeps the input-side metadata from `choice()` while
+ * exposing the mapped values as the parser result type.
+ *
+ * @template T The one-to-one mapping from input strings to parsed values.
+ * @param mapping A mapping whose own enumerable string keys are valid inputs.
+ * @returns A value parser that accepts one of the mapping keys and returns the
+ *          corresponding value.
+ * @throws {TypeError} If `mapping` is an array, or if any key is the empty
+ *         string.
+ * @throws {RangeError} If the mapping has no own enumerable string keys, or if
+ *         two keys map to the same value according to `Map` key equality.
+ * @since 1.2.0
+ */
+declare function biject<const T extends readonly unknown[]>(mapping: T): never;
+declare function biject<const T extends object>(mapping: T): ValueParser<"sync", BijectValue<T>>;
+/**
+ * Creates a value parser that transforms the result of another value parser.
+ *
+ * This is useful when an existing value parser already describes the accepted
+ * CLI spelling, suggestions, and error messages, but your application wants a
+ * different result type.  For example, a string `choice()` can be transformed
+ * into an internal enum, tagged object, or other domain type.
+ *
+ * Unlike parser-level `map()`, value parser transformation needs an inverse
+ * mapping.  The `unmap` function lets the transformed parser format values,
+ * validate fallback/default values, and reuse the wrapped parser's metadata
+ * without guessing how to serialize the transformed type.
+ *
+ * Transform functions are synchronous.  If the wrapped parser is async, the
+ * returned parser is async too, but `map` and `unmap` still run synchronously
+ * after the wrapped parser resolves.
+ *
+ * @template M The execution mode of the wrapped parser.
+ * @template T The value type produced by the wrapped parser.
+ * @template U The value type produced by the transformed parser.
+ * @param parser The value parser to transform.
+ * @param mapping Mapping functions between the wrapped and transformed value
+ *                types.
+ * @returns A value parser that accepts the same input as `parser` and produces
+ *          transformed values.
+ * @since 1.2.0
+ */
+declare function transform<M extends Mode, T, U>(parser: ValueParser<M, T>, mapping: TransformMapping<T, U>): ValueParser<M, U>;
 /**
  * Validates that an option value, if present, is a boolean.
  * Throws a {@link TypeError} if the value is defined but not a boolean.
@@ -3197,4 +3279,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, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, 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, semVer, socketAddress, string, 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, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, 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, semVer, socketAddress, string, transform, url, uuid };

package/dist/valueparser.d.ts

@@ -327,6 +327,36 @@ interface ChoiceOptionsNumber extends ChoiceOptionsBase {
  *             {@link ChoiceOptionsNumber} for number choices.
  */
 type ChoiceOptions = ChoiceOptionsString;
+/**
+ * Mapping functions for the {@link transform} value parser combinator.
+ *
+ * `map` converts values produced by the wrapped parser into the public result
+ * type.  `unmap` converts public values back to the wrapped parser's type so
+ * `format()`, `validate()`, and default-value handling can keep using the
+ * wrapped parser's own validation and formatting rules.
+ *
+ * The two functions should be inverses for the values your CLI accepts:
+ * `unmap(map(input))` should return a value accepted by the wrapped parser,
+ * and `map(unmap(output))` should preserve valid public values.
+ *
+ * @template T The value type produced by the wrapped parser.
+ * @template U The value type produced by the transformed parser.
+ * @since 1.2.0
+ */
+interface TransformMapping<T, U> {
+  /**
+   * Converts a value produced by the wrapped parser into the transformed
+   * parser's public value type.
+   */
+  map(value: T): U;
+  /**
+   * Converts a public transformed value back into the wrapped parser's value
+   * type for formatting and fallback validation.
+   */
+  unmap(value: U): T;
+}
+type BijectKey<T> = Extract<keyof T, string | number>;
+type BijectValue<T> = T[BijectKey<T>];
 /**
  * A predicate function that checks if an object is a {@link ValueParser}.
  * @param object The object to check.
@@ -374,6 +404,58 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  * @since 0.9.0
  */
 declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<"sync", T>;
+/**
+ * Creates a value parser from a one-to-one mapping of CLI spellings to values.
+ *
+ * The mapping's string keys are accepted as command-line input, and each key
+ * is parsed into its corresponding value.  Values must also be unique using
+ * the same equality semantics as `Map` keys, so the parser can format a value
+ * back to the original key.
+ *
+ * This is a convenience wrapper around `choice(Object.keys(mapping))` and
+ * {@link transform}.  It keeps the input-side metadata from `choice()` while
+ * exposing the mapped values as the parser result type.
+ *
+ * @template T The one-to-one mapping from input strings to parsed values.
+ * @param mapping A mapping whose own enumerable string keys are valid inputs.
+ * @returns A value parser that accepts one of the mapping keys and returns the
+ *          corresponding value.
+ * @throws {TypeError} If `mapping` is an array, or if any key is the empty
+ *         string.
+ * @throws {RangeError} If the mapping has no own enumerable string keys, or if
+ *         two keys map to the same value according to `Map` key equality.
+ * @since 1.2.0
+ */
+declare function biject<const T extends readonly unknown[]>(mapping: T): never;
+declare function biject<const T extends object>(mapping: T): ValueParser<"sync", BijectValue<T>>;
+/**
+ * Creates a value parser that transforms the result of another value parser.
+ *
+ * This is useful when an existing value parser already describes the accepted
+ * CLI spelling, suggestions, and error messages, but your application wants a
+ * different result type.  For example, a string `choice()` can be transformed
+ * into an internal enum, tagged object, or other domain type.
+ *
+ * Unlike parser-level `map()`, value parser transformation needs an inverse
+ * mapping.  The `unmap` function lets the transformed parser format values,
+ * validate fallback/default values, and reuse the wrapped parser's metadata
+ * without guessing how to serialize the transformed type.
+ *
+ * Transform functions are synchronous.  If the wrapped parser is async, the
+ * returned parser is async too, but `map` and `unmap` still run synchronously
+ * after the wrapped parser resolves.
+ *
+ * @template M The execution mode of the wrapped parser.
+ * @template T The value type produced by the wrapped parser.
+ * @template U The value type produced by the transformed parser.
+ * @param parser The value parser to transform.
+ * @param mapping Mapping functions between the wrapped and transformed value
+ *                types.
+ * @returns A value parser that accepts the same input as `parser` and produces
+ *          transformed values.
+ * @since 1.2.0
+ */
+declare function transform<M extends Mode, T, U>(parser: ValueParser<M, T>, mapping: TransformMapping<T, U>): ValueParser<M, U>;
 /**
  * Validates that an option value, if present, is a boolean.
  * Throws a {@link TypeError} if the value is defined but not a boolean.
@@ -3197,4 +3279,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, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, 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, semVer, socketAddress, string, 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, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, 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, semVer, socketAddress, string, transform, url, uuid };

package/dist/valueparser.js

@@ -1,9 +1,34 @@
 import { cloneMessage, lineBreak, message, metavar, text, valueSet } from "./message.js";
-import { isDerivedValueParser } from "./internal/dependency.js";
+import { mapMaybePromiseByMode, mapModeValue, wrapIterableForMode } from "./internal/mode-dispatch.js";
+import { defaultValues, dependencyId, dependencyIds, derivedValueParserMarker, getSnapshottedDefaultDependencyValues, isDerivedValueParser, parseWithDependency, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency } from "./internal/dependency.js";
 import { appendValueHint, appendValueSuggestions, deduplicateSuggestions } from "./suggestion.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 
 //#region src/valueparser.ts
+function transformValueParserResult(result, mapping) {
+	if (!result.success) return result;
+	const preserveSnapshot = (mapped) => {
+		const snapshot = getSnapshottedDefaultDependencyValues(result);
+		return snapshot == null ? mapped : snapshotDefaultDependencyValues(mapped, snapshot);
+	};
+	if (result.deferred) try {
+		return preserveSnapshot({
+			success: true,
+			value: mapping.map(result.value),
+			deferred: true
+		});
+	} catch {
+		return preserveSnapshot({
+			success: true,
+			value: void 0,
+			deferred: true
+		});
+	}
+	return preserveSnapshot({
+		success: true,
+		value: mapping.map(result.value)
+	});
+}
 /**
 * A predicate function that checks if an object is a {@link ValueParser}.
 * @param object The object to check.
@@ -191,6 +216,187 @@ function choice(choices, options = {}) {
 		}
 	};
 }
+function biject(mapping) {
+	if (Array.isArray(mapping)) throw new TypeError("Expected biject mapping to be a non-array object.");
+	const keys = [];
+	for (const key in mapping) if (Object.prototype.hasOwnProperty.call(mapping, key)) keys.push(key);
+	if (keys.length < 1) throw new RangeError("Expected at least one biject entry.");
+	const source = choice(keys);
+	const forward = /* @__PURE__ */ new Map();
+	const reverse = /* @__PURE__ */ new Map();
+	for (const key of keys) {
+		const value = mapping[key];
+		if (reverse.has(value)) throw new RangeError(`Duplicate biject value for key ${JSON.stringify(key)}.`);
+		forward.set(key, value);
+		reverse.set(value, key);
+	}
+	const parser = transform(source, {
+		map(value) {
+			return forward.get(value);
+		},
+		unmap(value) {
+			const key = reverse.get(value);
+			if (key !== void 0) return key;
+			try {
+				return String(value);
+			} catch {
+				return "";
+			}
+		}
+	});
+	Object.defineProperty(parser, "validate", {
+		value(value) {
+			if (reverse.has(value)) return {
+				success: true,
+				value
+			};
+			let input;
+			try {
+				input = String(value);
+			} catch {
+				input = "";
+			}
+			const result = source.parse(input);
+			if (!result.success) return result;
+			return {
+				success: false,
+				error: formatDefaultChoiceError(input, keys)
+			};
+		},
+		configurable: true,
+		enumerable: true
+	});
+	return parser;
+}
+/**
+* Creates a value parser that transforms the result of another value parser.
+*
+* This is useful when an existing value parser already describes the accepted
+* CLI spelling, suggestions, and error messages, but your application wants a
+* different result type.  For example, a string `choice()` can be transformed
+* into an internal enum, tagged object, or other domain type.
+*
+* Unlike parser-level `map()`, value parser transformation needs an inverse
+* mapping.  The `unmap` function lets the transformed parser format values,
+* validate fallback/default values, and reuse the wrapped parser's metadata
+* without guessing how to serialize the transformed type.
+*
+* Transform functions are synchronous.  If the wrapped parser is async, the
+* returned parser is async too, but `map` and `unmap` still run synchronously
+* after the wrapped parser resolves.
+*
+* @template M The execution mode of the wrapped parser.
+* @template T The value type produced by the wrapped parser.
+* @template U The value type produced by the transformed parser.
+* @param parser The value parser to transform.
+* @param mapping Mapping functions between the wrapped and transformed value
+*                types.
+* @returns A value parser that accepts the same input as `parser` and produces
+*          transformed values.
+* @since 1.2.0
+*/
+function transform(parser, mapping) {
+	const normalize = parser.normalize?.bind(parser);
+	const suggest = parser.suggest?.bind(parser);
+	const transformedChoices = parser.choices == null ? void 0 : Object.freeze(parser.choices.map((choice$1) => mapping.map(choice$1)));
+	const transformed = {
+		mode: parser.mode,
+		metavar: parser.metavar,
+		placeholder: void 0,
+		...transformedChoices == null ? {} : { choices: transformedChoices },
+		parse(input) {
+			return mapModeValue(parser.mode, parser.parse(input), (result) => transformValueParserResult(result, mapping));
+		},
+		format(value) {
+			return parser.format(mapping.unmap(value));
+		},
+		...normalize == null ? {} : { normalize(value) {
+			return mapping.map(normalize(mapping.unmap(value)));
+		} },
+		...suggest == null ? {} : { suggest(prefix) {
+			return suggest(prefix);
+		} }
+	};
+	Object.defineProperty(transformed, "placeholder", {
+		get() {
+			try {
+				return mapping.map(parser.placeholder);
+			} catch {
+				return void 0;
+			}
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validate === "function") {
+		const validate = parser.validate.bind(parser);
+		Object.defineProperty(transformed, "validate", {
+			value(value) {
+				const result = validate(mapping.unmap(value));
+				return result.success ? {
+					success: true,
+					value: mapping.map(result.value)
+				} : result;
+			},
+			configurable: true,
+			enumerable: true
+		});
+	} else if (parser.mode === "sync") {
+		const syncParser = parser;
+		Object.defineProperty(transformed, "validate", {
+			value(value) {
+				const result = syncParser.parse(syncParser.format(mapping.unmap(value)));
+				return result.success ? {
+					success: true,
+					value: mapping.map(result.value)
+				} : result;
+			},
+			configurable: true,
+			enumerable: true
+		});
+	}
+	if (isDerivedValueParser(parser)) preserveTransformedDerivedMetadata(transformed, parser, mapping);
+	return transformed;
+}
+function preserveTransformedDerivedMetadata(transformed, parser, mapping) {
+	Object.defineProperties(transformed, {
+		[derivedValueParserMarker]: {
+			value: true,
+			enumerable: true
+		},
+		[dependencyId]: {
+			value: parser[dependencyId],
+			enumerable: true
+		},
+		[parseWithDependency]: {
+			value(input, dependencyValue) {
+				return mapMaybePromiseByMode(parser.mode, parser[parseWithDependency](input, dependencyValue), (result) => transformValueParserResult(result, mapping));
+			},
+			enumerable: true
+		}
+	});
+	if (dependencyIds in parser && parser[dependencyIds] != null) Object.defineProperty(transformed, dependencyIds, {
+		value: parser[dependencyIds],
+		enumerable: true
+	});
+	if (defaultValues in parser && parser[defaultValues] != null) Object.defineProperty(transformed, defaultValues, {
+		value: parser[defaultValues],
+		enumerable: true
+	});
+	if (singleDefaultValue in parser && parser[singleDefaultValue] != null) Object.defineProperty(transformed, singleDefaultValue, {
+		value: parser[singleDefaultValue],
+		enumerable: true
+	});
+	if (suggestWithDependency in parser && parser[suggestWithDependency] != null) {
+		const suggest = parser[suggestWithDependency];
+		Object.defineProperty(transformed, suggestWithDependency, {
+			value(prefix, dependencyValue) {
+				return wrapIterableForMode(parser.mode, suggest(prefix, dependencyValue));
+			},
+			enumerable: true
+		});
+	}
+}
 /**
 * Validates that an option value, if present, is a boolean.
 * Throws a {@link TypeError} if the value is defined but not a boolean.
@@ -6336,4 +6542,4 @@ function plainObjectsEqual(a, b) {
 }
 
 //#endregion
-export { 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, semVer, socketAddress, string, url, uuid };
+export { 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, semVer, socketAddress, string, transform, url, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2301",
+  "version": "1.2.0-dev.2302",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -225,7 +225,7 @@
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.2.0-dev.2301+7cd22796"
+    "@optique/env": "1.2.0-dev.2302+77665cb5"
   },
   "scripts": {
     "build": "tsdown",

package/skills/optique/SKILL.md

@@ -40,8 +40,11 @@ Core rules
  -  Use `message` from *@optique/core/message* for descriptions, help text, and
     custom errors. Prefer semantic message helpers such as `optionName()` and
     `metavar()` over string concatenation when naming CLI elements.
- -  Use value parsers such as `integer()`, `choice()`, `url()`, and `uuid()`
-    instead of validating raw strings after parsing. Use `path()` from
+ -  Use value parsers such as `integer()`, `choice()`, `biject()`, `url()`,
+    and `uuid()` instead of validating raw strings after parsing. Use
+    `biject()` for one-to-one string-to-value choices, and use `transform()`
+    when an existing value parser describes the accepted CLI spelling but your
+    app needs a different result type. Use `path()` from
     `@optique/run/valueparser` for file-system paths. Write a custom
     `{ mode, metavar, parse, format }` value parser only when the catalog does
     not cover the domain.
@@ -138,9 +141,32 @@ if (result.success) {
 Custom value parsers
 --------------------
 
-Prefer the built-in catalog first. When a custom domain is needed, keep the
-validation in a value parser so help, errors, defaults, prompts, and completion
-all see the same typed value.
+Prefer the built-in catalog first. If a one-to-one dictionary can describe the
+input tokens and domain values, use `biject()`. If an existing parser already
+accepts the right input syntax, wrap it with `transform()` before writing a
+custom parser:
+
+~~~~ typescript
+import { biject, choice, transform } from "@optique/core/valueparser";
+
+const exitCode = biject({
+  ok: 0,
+  warning: 1,
+  error: 2,
+});
+
+const logLevel = transform(choice(["debug", "info", "warn", "error"] as const), {
+  map(value) {
+    return value.toUpperCase() as "DEBUG" | "INFO" | "WARN" | "ERROR";
+  },
+  unmap(value) {
+    return value.toLowerCase() as "debug" | "info" | "warn" | "error";
+  },
+});
+~~~~
+
+When a custom domain is needed, keep the validation in a value parser so help,
+errors, defaults, prompts, and completion all see the same typed value.
 
 ~~~~ typescript
 import { message } from "@optique/core/message";