@optique/core 1.1.0-dev.2070 → 1.1.0-dev.2083

package/dist/index.cjs

@@ -72,6 +72,7 @@ exports.isNonEmptyString = require_nonempty.isNonEmptyString;
 exports.isSuggestionHidden = require_usage.isSuggestionHidden;
 exports.isUsageHidden = require_usage.isUsageHidden;
 exports.isValueParser = require_valueparser.isValueParser;
+exports.json = require_valueparser.json;
 exports.lineBreak = require_message.lineBreak;
 exports.link = require_message.link;
 exports.locale = require_valueparser.locale;

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, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, 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, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.cjs";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, 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, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, 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 { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
@@ -12,4 +12,4 @@ import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMod
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.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, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, 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, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, 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, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, 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, 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, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, 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, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, 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, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, 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, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, 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, socketAddress, string, suggest, suggestAsync, suggestSync, text, 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, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, 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, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, 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, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, 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 { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
@@ -12,4 +12,4 @@ import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMod
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.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, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, 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, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, 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, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, 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, 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, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, 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, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, 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, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, 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, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, 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, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

@@ -8,8 +8,8 @@ import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
-import { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
+import { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, 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, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, 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, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, 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, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/valueparser.cjs

@@ -5235,6 +5235,140 @@ function semVer(options = {}) {
 		}
 	};
 }
+/**
+* Creates a {@link ValueParser} for parsing JSON-encoded strings from the
+* command line.
+*
+* The parser accepts any well-formed JSON string by default.  Use the
+* `rootType` option to restrict which JSON root type is accepted and to
+* narrow the TypeScript return type accordingly.
+*
+* @example
+* ```typescript
+* // Accept any JSON value
+* const anyJson = json();
+*
+* // Accept only JSON objects (return type narrowed)
+* const objJson = json({ rootType: "object" });
+* ```
+*
+* @param options Optional configuration for the parser.
+* @returns A {@link ValueParser} that converts JSON-encoded strings to the
+*   appropriate JavaScript type.
+* @throws {TypeError} If `options.metavar` is provided but is an empty string.
+* @throws {TypeError} If `options.rootType` is provided but is not one of the
+*   six allowed values.
+* @throws {TypeError} If `options.placeholder` or any value nested within
+*   it is a non-finite number (`Infinity`, `-Infinity`, or `NaN`).
+* @throws {TypeError} If `options.placeholder` is provided with a `rootType`
+*   but its JSON type does not match the `rootType`.
+* @throws {TypeError} If the returned parser's `format()` method is called
+*   with a value that contains a non-finite number anywhere in its structure.
+* @since 1.1.0
+*/
+function json(options) {
+	const metavar = options?.metavar ?? "JSON";
+	require_nonempty.ensureNonEmptyString(metavar);
+	checkEnumOption(options, "rootType", [
+		"string",
+		"number",
+		"boolean",
+		"null",
+		"object",
+		"array"
+	]);
+	const rootType = options?.rootType;
+	const invalidJsonError = options?.errors?.invalidJson;
+	const invalidRootTypeError = options?.errors?.invalidRootType;
+	if (options?.placeholder !== void 0) {
+		const p = options.placeholder;
+		const nonFinitePlaceholder = findNonFiniteNumber(p);
+		if (nonFinitePlaceholder !== void 0) throw new TypeError(`Expected placeholder to contain only finite numbers, but found ${String(nonFinitePlaceholder)}.`);
+		if (rootType != null && jsonTypeOf(p) !== rootType) throw new TypeError(`Expected placeholder to be a JSON ${rootType}, but got ${jsonTypeOf(p)}.`);
+	}
+	const defaultPlaceholder = rootType === "string" ? "" : rootType === "number" ? 0 : rootType === "boolean" ? false : rootType === "object" ? {} : rootType === "array" ? [] : null;
+	const placeholder = options?.placeholder ?? defaultPlaceholder;
+	return {
+		mode: "sync",
+		metavar,
+		placeholder,
+		parse(input) {
+			let value;
+			try {
+				value = JSON.parse(input);
+			} catch (e) {
+				const err = e instanceof Error ? e : new Error(String(e));
+				const error = invalidJsonError instanceof Function ? invalidJsonError(input) : invalidJsonError ?? [require_message.text(`Not a valid JSON: ${err.message}`)];
+				return {
+					success: false,
+					error
+				};
+			}
+			const nonFinite = findNonFiniteNumber(value);
+			if (nonFinite !== void 0) {
+				const error = invalidJsonError instanceof Function ? invalidJsonError(input) : invalidJsonError ?? [require_message.text(`Not a valid JSON: number out of range.`)];
+				return {
+					success: false,
+					error
+				};
+			}
+			if (rootType != null) {
+				const actual = jsonTypeOf(value);
+				if (actual !== rootType) {
+					const error = invalidRootTypeError instanceof Function ? invalidRootTypeError(value, rootType) : invalidRootTypeError ?? [require_message.text(`Expected JSON ${rootType}, but got ${actual}.`)];
+					return {
+						success: false,
+						error
+					};
+				}
+			}
+			return {
+				success: true,
+				value
+			};
+		},
+		format(value) {
+			const nonFinite = findNonFiniteNumber(value);
+			if (nonFinite !== void 0) throw new TypeError(`Expected a finite JSON number, but got ${String(nonFinite)}.`);
+			return JSON.stringify(value);
+		}
+	};
+}
+function jsonTypeOf(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+/**
+* Finds the first non-finite number (`NaN`, `Infinity`, or `-Infinity`)
+* anywhere in a JSON structure.
+*
+* Uses an explicit stack rather than recursion to avoid call-stack overflows
+* on deeply nested inputs.  Tracks visited objects to handle circular
+* references without looping forever.
+*
+* @returns The first non-finite number found, or `undefined` if all numbers
+*   in the structure are finite.
+*/
+function findNonFiniteNumber(root) {
+	const stack = [root];
+	const seen = /* @__PURE__ */ new Set();
+	while (stack.length > 0) {
+		const value = stack.pop();
+		if (typeof value === "number") {
+			if (!Number.isFinite(value)) return value;
+		} else if (Array.isArray(value)) {
+			if (seen.has(value)) continue;
+			seen.add(value);
+			for (const item of value) stack.push(item);
+		} else if (value !== null && typeof value === "object") {
+			if (seen.has(value)) continue;
+			seen.add(value);
+			for (const item of Object.values(value)) stack.push(item);
+		}
+	}
+	return void 0;
+}
 
 //#endregion
 exports.checkBooleanOption = checkBooleanOption;
@@ -5254,6 +5388,7 @@ exports.ipv4 = ipv4;
 exports.ipv6 = ipv6;
 exports.isNonEmptyString = require_nonempty.isNonEmptyString;
 exports.isValueParser = isValueParser;
+exports.json = json;
 exports.locale = locale;
 exports.macAddress = macAddress;
 exports.port = port;

package/dist/valueparser.d.cts

@@ -2559,5 +2559,157 @@ declare function semVer(options?: SemVerOptionsString): ValueParser<"sync", SemV
  * @since 1.1.0
  */
 declare function semVer(options: SemVerOptionsObject): ValueParser<"sync", SemVer>;
+/**
+ * Any JSON-serializable value.
+ *
+ * This type is a TypeScript approximation of JSON data values.  Note that
+ * certain JavaScript distinctions are not preserved through serialization:
+ * for example, `-0` serializes as `"0"`, so a round-trip through
+ * `format()` and `parse()` may return `0` instead.
+ *
+ * @since 1.1.0
+ */
+type Json = string | number | boolean | null | {
+  readonly [property: string]: Json;
+} | readonly Json[];
+/**
+ * Options for creating a {@link json} value parser.
+ *
+ * @since 1.1.0
+ */
+interface JsonOptions {
+  /**
+   * 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 `DATA` or `CONFIG`.
+   * @default `"JSON"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * @default Depends on `rootType`: `null` when unset, `""` for `"string"`,
+   *   `0` for `"number"`, `false` for `"boolean"`, `null` for `"null"`,
+   *   `{}` for `"object"`, `[]` for `"array"`.
+   * @since 1.1.0
+   */
+  readonly placeholder?: Json;
+  /**
+   * Restricts the expected JSON root type.  When set, the parser rejects
+   * JSON values whose root type does not match and narrows the TypeScript
+   * return type accordingly.
+   *
+   * @since 1.1.0
+   */
+  readonly rootType?: "string" | "number" | "boolean" | "null" | "object" | "array";
+  /**
+   * Custom error messages for JSON parsing failures.
+   *
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not valid JSON.
+     * Can be a static message or a function that receives the raw input.
+     * @since 1.1.0
+     */
+    readonly invalidJson?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when the parsed JSON value does not match the
+     * expected `rootType`.  Can be a static message or a function that
+     * receives the parsed value and the expected root type name.
+     * @since 1.1.0
+     */
+    readonly invalidRootType?: Message | ((value: Json, expected: string) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * a `string`.
+ *
+ * @param options Configuration options including `rootType: "string"`.
+ * @returns A parser whose successful value is typed as `string`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "string";
+  readonly placeholder?: string;
+}): ValueParser<"sync", string>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * a `number`.
+ *
+ * @param options Configuration options including `rootType: "number"`.
+ * @returns A parser whose successful value is typed as `number`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "number";
+  readonly placeholder?: number;
+}): ValueParser<"sync", number>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * a `boolean`.
+ *
+ * @param options Configuration options including `rootType: "boolean"`.
+ * @returns A parser whose successful value is typed as `boolean`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "boolean";
+  readonly placeholder?: boolean;
+}): ValueParser<"sync", boolean>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * `null`.
+ *
+ * @param options Configuration options including `rootType: "null"`.
+ * @returns A parser whose successful value is typed as `null`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "null";
+  readonly placeholder?: null;
+}): ValueParser<"sync", null>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * a plain JSON object.
+ *
+ * @param options Configuration options including `rootType: "object"`.
+ * @returns A parser whose successful value is typed as
+ *   `{ readonly [property: string]: Json }`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "object";
+  readonly placeholder?: {
+    readonly [property: string]: Json;
+  };
+}): ValueParser<"sync", {
+  readonly [property: string]: Json;
+}>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * a JSON array.
+ *
+ * @param options Configuration options including `rootType: "array"`.
+ * @returns A parser whose successful value is typed as `readonly Json[]`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "array";
+  readonly placeholder?: readonly Json[];
+}): ValueParser<"sync", readonly Json[]>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings into any
+ * {@link Json} value (object, array, string, number, boolean, or null).
+ *
+ * Also accepts a pre-typed `JsonOptions` variable when the `rootType` is not
+ * known at compile time; the return type is the widened {@link Json} union.
+ *
+ * @param options Optional configuration for the parser.
+ * @returns A parser whose successful value is typed as {@link Json}.
+ * @since 1.1.0
+ */
+declare function json(options?: JsonOptions): ValueParser<"sync", Json>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, 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, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, 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, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };

package/dist/valueparser.d.ts

@@ -2559,5 +2559,157 @@ declare function semVer(options?: SemVerOptionsString): ValueParser<"sync", SemV
  * @since 1.1.0
  */
 declare function semVer(options: SemVerOptionsObject): ValueParser<"sync", SemVer>;
+/**
+ * Any JSON-serializable value.
+ *
+ * This type is a TypeScript approximation of JSON data values.  Note that
+ * certain JavaScript distinctions are not preserved through serialization:
+ * for example, `-0` serializes as `"0"`, so a round-trip through
+ * `format()` and `parse()` may return `0` instead.
+ *
+ * @since 1.1.0
+ */
+type Json = string | number | boolean | null | {
+  readonly [property: string]: Json;
+} | readonly Json[];
+/**
+ * Options for creating a {@link json} value parser.
+ *
+ * @since 1.1.0
+ */
+interface JsonOptions {
+  /**
+   * 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 `DATA` or `CONFIG`.
+   * @default `"JSON"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * @default Depends on `rootType`: `null` when unset, `""` for `"string"`,
+   *   `0` for `"number"`, `false` for `"boolean"`, `null` for `"null"`,
+   *   `{}` for `"object"`, `[]` for `"array"`.
+   * @since 1.1.0
+   */
+  readonly placeholder?: Json;
+  /**
+   * Restricts the expected JSON root type.  When set, the parser rejects
+   * JSON values whose root type does not match and narrows the TypeScript
+   * return type accordingly.
+   *
+   * @since 1.1.0
+   */
+  readonly rootType?: "string" | "number" | "boolean" | "null" | "object" | "array";
+  /**
+   * Custom error messages for JSON parsing failures.
+   *
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not valid JSON.
+     * Can be a static message or a function that receives the raw input.
+     * @since 1.1.0
+     */
+    readonly invalidJson?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when the parsed JSON value does not match the
+     * expected `rootType`.  Can be a static message or a function that
+     * receives the parsed value and the expected root type name.
+     * @since 1.1.0
+     */
+    readonly invalidRootType?: Message | ((value: Json, expected: string) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * a `string`.
+ *
+ * @param options Configuration options including `rootType: "string"`.
+ * @returns A parser whose successful value is typed as `string`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "string";
+  readonly placeholder?: string;
+}): ValueParser<"sync", string>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * a `number`.
+ *
+ * @param options Configuration options including `rootType: "number"`.
+ * @returns A parser whose successful value is typed as `number`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "number";
+  readonly placeholder?: number;
+}): ValueParser<"sync", number>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * a `boolean`.
+ *
+ * @param options Configuration options including `rootType: "boolean"`.
+ * @returns A parser whose successful value is typed as `boolean`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "boolean";
+  readonly placeholder?: boolean;
+}): ValueParser<"sync", boolean>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * `null`.
+ *
+ * @param options Configuration options including `rootType: "null"`.
+ * @returns A parser whose successful value is typed as `null`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "null";
+  readonly placeholder?: null;
+}): ValueParser<"sync", null>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * a plain JSON object.
+ *
+ * @param options Configuration options including `rootType: "object"`.
+ * @returns A parser whose successful value is typed as
+ *   `{ readonly [property: string]: Json }`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "object";
+  readonly placeholder?: {
+    readonly [property: string]: Json;
+  };
+}): ValueParser<"sync", {
+  readonly [property: string]: Json;
+}>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings and returns
+ * a JSON array.
+ *
+ * @param options Configuration options including `rootType: "array"`.
+ * @returns A parser whose successful value is typed as `readonly Json[]`.
+ * @since 1.1.0
+ */
+declare function json(options: JsonOptions & {
+  readonly rootType: "array";
+  readonly placeholder?: readonly Json[];
+}): ValueParser<"sync", readonly Json[]>;
+/**
+ * Creates a {@link ValueParser} that parses JSON-encoded strings into any
+ * {@link Json} value (object, array, string, number, boolean, or null).
+ *
+ * Also accepts a pre-typed `JsonOptions` variable when the `rootType` is not
+ * known at compile time; the return type is the widened {@link Json} union.
+ *
+ * @param options Optional configuration for the parser.
+ * @returns A parser whose successful value is typed as {@link Json}.
+ * @since 1.1.0
+ */
+declare function json(options?: JsonOptions): ValueParser<"sync", Json>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, 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, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, 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, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };

package/dist/valueparser.js

@@ -5235,6 +5235,140 @@ function semVer(options = {}) {
 		}
 	};
 }
+/**
+* Creates a {@link ValueParser} for parsing JSON-encoded strings from the
+* command line.
+*
+* The parser accepts any well-formed JSON string by default.  Use the
+* `rootType` option to restrict which JSON root type is accepted and to
+* narrow the TypeScript return type accordingly.
+*
+* @example
+* ```typescript
+* // Accept any JSON value
+* const anyJson = json();
+*
+* // Accept only JSON objects (return type narrowed)
+* const objJson = json({ rootType: "object" });
+* ```
+*
+* @param options Optional configuration for the parser.
+* @returns A {@link ValueParser} that converts JSON-encoded strings to the
+*   appropriate JavaScript type.
+* @throws {TypeError} If `options.metavar` is provided but is an empty string.
+* @throws {TypeError} If `options.rootType` is provided but is not one of the
+*   six allowed values.
+* @throws {TypeError} If `options.placeholder` or any value nested within
+*   it is a non-finite number (`Infinity`, `-Infinity`, or `NaN`).
+* @throws {TypeError} If `options.placeholder` is provided with a `rootType`
+*   but its JSON type does not match the `rootType`.
+* @throws {TypeError} If the returned parser's `format()` method is called
+*   with a value that contains a non-finite number anywhere in its structure.
+* @since 1.1.0
+*/
+function json(options) {
+	const metavar = options?.metavar ?? "JSON";
+	ensureNonEmptyString(metavar);
+	checkEnumOption(options, "rootType", [
+		"string",
+		"number",
+		"boolean",
+		"null",
+		"object",
+		"array"
+	]);
+	const rootType = options?.rootType;
+	const invalidJsonError = options?.errors?.invalidJson;
+	const invalidRootTypeError = options?.errors?.invalidRootType;
+	if (options?.placeholder !== void 0) {
+		const p = options.placeholder;
+		const nonFinitePlaceholder = findNonFiniteNumber(p);
+		if (nonFinitePlaceholder !== void 0) throw new TypeError(`Expected placeholder to contain only finite numbers, but found ${String(nonFinitePlaceholder)}.`);
+		if (rootType != null && jsonTypeOf(p) !== rootType) throw new TypeError(`Expected placeholder to be a JSON ${rootType}, but got ${jsonTypeOf(p)}.`);
+	}
+	const defaultPlaceholder = rootType === "string" ? "" : rootType === "number" ? 0 : rootType === "boolean" ? false : rootType === "object" ? {} : rootType === "array" ? [] : null;
+	const placeholder = options?.placeholder ?? defaultPlaceholder;
+	return {
+		mode: "sync",
+		metavar,
+		placeholder,
+		parse(input) {
+			let value;
+			try {
+				value = JSON.parse(input);
+			} catch (e) {
+				const err = e instanceof Error ? e : new Error(String(e));
+				const error = invalidJsonError instanceof Function ? invalidJsonError(input) : invalidJsonError ?? [text(`Not a valid JSON: ${err.message}`)];
+				return {
+					success: false,
+					error
+				};
+			}
+			const nonFinite = findNonFiniteNumber(value);
+			if (nonFinite !== void 0) {
+				const error = invalidJsonError instanceof Function ? invalidJsonError(input) : invalidJsonError ?? [text(`Not a valid JSON: number out of range.`)];
+				return {
+					success: false,
+					error
+				};
+			}
+			if (rootType != null) {
+				const actual = jsonTypeOf(value);
+				if (actual !== rootType) {
+					const error = invalidRootTypeError instanceof Function ? invalidRootTypeError(value, rootType) : invalidRootTypeError ?? [text(`Expected JSON ${rootType}, but got ${actual}.`)];
+					return {
+						success: false,
+						error
+					};
+				}
+			}
+			return {
+				success: true,
+				value
+			};
+		},
+		format(value) {
+			const nonFinite = findNonFiniteNumber(value);
+			if (nonFinite !== void 0) throw new TypeError(`Expected a finite JSON number, but got ${String(nonFinite)}.`);
+			return JSON.stringify(value);
+		}
+	};
+}
+function jsonTypeOf(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+/**
+* Finds the first non-finite number (`NaN`, `Infinity`, or `-Infinity`)
+* anywhere in a JSON structure.
+*
+* Uses an explicit stack rather than recursion to avoid call-stack overflows
+* on deeply nested inputs.  Tracks visited objects to handle circular
+* references without looping forever.
+*
+* @returns The first non-finite number found, or `undefined` if all numbers
+*   in the structure are finite.
+*/
+function findNonFiniteNumber(root) {
+	const stack = [root];
+	const seen = /* @__PURE__ */ new Set();
+	while (stack.length > 0) {
+		const value = stack.pop();
+		if (typeof value === "number") {
+			if (!Number.isFinite(value)) return value;
+		} else if (Array.isArray(value)) {
+			if (seen.has(value)) continue;
+			seen.add(value);
+			for (const item of value) stack.push(item);
+		} else if (value !== null && typeof value === "object") {
+			if (seen.has(value)) continue;
+			seen.add(value);
+			for (const item of Object.values(value)) stack.push(item);
+		}
+	}
+	return void 0;
+}
 
 //#endregion
-export { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.1.0-dev.2070",
+  "version": "1.1.0-dev.2083",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",