@optique/core 1.1.0-dev.2069 → 1.1.0-dev.2077

package/dist/completion.cjs

@@ -162,7 +162,7 @@ function _${programName} () {
 
       # Pre-expand file candidates.  When the glob base came from the
       # program's pattern and contains wildcard characters (* or ?),
-      # use it as-is via compgen -G (safe — no command substitution).
+      # use it as-is via compgen -G (safe—no command substitution).
       # Otherwise append * to treat it as a prefix.
       # Note: [ is NOT treated as a glob indicator because it commonly
       # appears in literal filenames like [draft] or foo[1].txt.
@@ -375,7 +375,7 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
             [[ "\$__compare_pattern" == */* ]] && __compare_pattern="\${__compare_pattern%/*}/" || __compare_pattern=""
           fi
           if [[ ( -n "\$__compare_pattern" || -n "\$__norm_prefix" ) && \${#__norm_prefix} -ge \${#__compare_pattern} && "\${__norm_prefix[1,\${#__compare_pattern}]}" == "\$__compare_pattern" && "\$PREFIX" != "\$pattern" ]]; then
-            # User typed an equivalent or extended form — keep PREFIX
+            # User typed an equivalent or extended form—keep PREFIX
             true
           else
             PREFIX="\$pattern"
@@ -536,7 +536,7 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
                 end
             end
 
-            # Expand tilde prefix for globbing — fish does not expand ~
+            # Expand tilde prefix for globbing—fish does not expand ~
             # inside variable substitutions, so replace it with $HOME
             if string match -q '~/*' -- "$glob_base"
                 set __tilde_prefix "~"
@@ -1186,7 +1186,7 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
                     \$prefix = \$prefix + '/'
                 }
 
-                # Build the glob path — when the prefix contains wildcard
+                # Build the glob path—when the prefix contains wildcard
                 # characters, use it as-is; otherwise append *
                 \$globPath = if (\$prefix -match '[\*\?]') { \$prefix } else { "\${prefix}*" }
 

package/dist/completion.js

@@ -162,7 +162,7 @@ function _${programName} () {
 
       # Pre-expand file candidates.  When the glob base came from the
       # program's pattern and contains wildcard characters (* or ?),
-      # use it as-is via compgen -G (safe — no command substitution).
+      # use it as-is via compgen -G (safe—no command substitution).
       # Otherwise append * to treat it as a prefix.
       # Note: [ is NOT treated as a glob indicator because it commonly
       # appears in literal filenames like [draft] or foo[1].txt.
@@ -375,7 +375,7 @@ function _${programName.replace(/[^a-zA-Z0-9]/g, "_")} () {
             [[ "\$__compare_pattern" == */* ]] && __compare_pattern="\${__compare_pattern%/*}/" || __compare_pattern=""
           fi
           if [[ ( -n "\$__compare_pattern" || -n "\$__norm_prefix" ) && \${#__norm_prefix} -ge \${#__compare_pattern} && "\${__norm_prefix[1,\${#__compare_pattern}]}" == "\$__compare_pattern" && "\$PREFIX" != "\$pattern" ]]; then
-            # User typed an equivalent or extended form — keep PREFIX
+            # User typed an equivalent or extended form—keep PREFIX
             true
           else
             PREFIX="\$pattern"
@@ -536,7 +536,7 @@ ${escapedArgs ? `    set -l output (${programName} ${escapedArgs} $prev $current
                 end
             end
 
-            # Expand tilde prefix for globbing — fish does not expand ~
+            # Expand tilde prefix for globbing—fish does not expand ~
             # inside variable substitutions, so replace it with $HOME
             if string match -q '~/*' -- "$glob_base"
                 set __tilde_prefix "~"
@@ -1186,7 +1186,7 @@ ${escapedArgs ? `    \$completionArgs += @(${escapedArgs})
                     \$prefix = \$prefix + '/'
                 }
 
-                # Build the glob path — when the prefix contains wildcard
+                # Build the glob path—when the prefix contains wildcard
                 # characters, use it as-is; otherwise append *
                 \$globPath = if (\$prefix -match '[\*\?]') { \$prefix } else { "\${prefix}*" }
 

package/dist/constructs.cjs

@@ -1597,7 +1597,7 @@ function filterExcludedFieldParsers(pairs, excludedFields) {
 /**
 * Pre-completes dependency source fields and registers their values in
 * the given registry.  Unlike `completeDependencySourceDefaults()` (used
-* by suggest), this function handles all four Phase 1 cases — including
+* by suggest), this function handles all four Phase 1 cases—including
 * PendingDependencySourceState in arrays and wrappedDependencySourceMarker.
 *
 * The original state is NOT modified; only the registry is populated.

package/dist/constructs.js

@@ -1597,7 +1597,7 @@ function filterExcludedFieldParsers(pairs, excludedFields) {
 /**
 * Pre-completes dependency source fields and registers their values in
 * the given registry.  Unlike `completeDependencySourceDefaults()` (used
-* by suggest), this function handles all four Phase 1 cases — including
+* by suggest), this function handles all four Phase 1 cases—including
 * PendingDependencySourceState in arrays and wrappedDependencySourceMarker.
 *
 * The original state is NOT modified; only the registry is populated.

package/dist/dependency-metadata.d.cts

@@ -20,13 +20,13 @@ interface DependencySourceCapability {
    * The `state` argument is the current parser state for the source-owning
    * parser.  Each wrapper composes this method to handle its own state shape:
    * - plain source: reads from `DependencySourceState`
-   * - `optional()` / `withDefault()`: unwraps `[innerState]` first
+   * - `optional()`/`withDefault()`: unwraps `[innerState]` first
    * - `map()`: reads the pre-transform value from inner state
    *
    * Returns the `ValueParserResult` (which may be successful with any
    * value including `undefined`, or failed), a promise that resolves to the
    * same shape when extraction needs async work, or `undefined` if the state
-   * does not contain a source result at all (unpopulated / wrong shape).
+   * does not contain a source result at all (unpopulated/wrong shape).
    * Callers and wrapper authors must handle both direct and promise-wrapped
    * results when composing `extractSourceValue`.
    */

package/dist/dependency-metadata.d.ts

@@ -20,13 +20,13 @@ interface DependencySourceCapability {
    * The `state` argument is the current parser state for the source-owning
    * parser.  Each wrapper composes this method to handle its own state shape:
    * - plain source: reads from `DependencySourceState`
-   * - `optional()` / `withDefault()`: unwraps `[innerState]` first
+   * - `optional()`/`withDefault()`: unwraps `[innerState]` first
    * - `map()`: reads the pre-transform value from inner state
    *
    * Returns the `ValueParserResult` (which may be successful with any
    * value including `undefined`, or failed), a promise that resolves to the
    * same shape when extraction needs async work, or `undefined` if the state
-   * does not contain a source result at all (unpopulated / wrong shape).
+   * does not contain a source result at all (unpopulated/wrong shape).
    * Callers and wrapper authors must handle both direct and promise-wrapped
    * results when composing `extractSourceValue`.
    */

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/internal/parser.d.cts

@@ -112,7 +112,7 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    *
    * Each built-in combinator computes this from its structural semantics.
    * Custom parser implementations must include every fixed token that
-   * the parser accepts at `argv[0]` — command names, option names, and
+   * the parser accepts at `argv[0]`—command names, option names, and
    * literal values alike.  For example, a parser whose usage declares
    * `{ type: "literal", value: "serve" }` should include `"serve"` in
    * this set.  Parsers that accept *any* token (like `argument()`) should
@@ -265,8 +265,8 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * parser (e.g., regex patterns, numeric bounds, `choice()` values).
    *
    * Wrappers like `bindEnv()` and `bindConfig()` call this on fallback
-   * values — environment variables parsed by a looser env parser,
-   * configured defaults, and values loaded from config files — so that
+   * values—environment variables parsed by a looser env parser,
+   * configured defaults, and values loaded from config files—so that
    * those values obey the same validation semantics as CLI input.
    * Without it, parser constraints can be silently bypassed through
    * fallback paths.
@@ -292,7 +292,7 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * current dependency value, and custom value parsers whose `format()`
    * intentionally throws for unsupported inputs.  Values that
    * `format()` successfully serializes to a string are always re-parsed,
-   * and any resulting parse failure is propagated — they represent the
+   * and any resulting parse failure is propagated—they represent the
    * bug class this method exists to surface.
    *
    * @param value The candidate value to validate.
@@ -413,7 +413,7 @@ interface ExecutionContext {
    * `preCompleteAndRegisterDependencies` results directly to children
    * in Phase 3.  Children read it in their own Phase 1 to avoid
    * re-evaluating non-idempotent default thunks, but never write to
-   * it — this prevents sibling completions from leaking into each
+   * it—this prevents sibling completions from leaking into each
    * other.
    *
    * Field-name keying naturally handles parser reuse across different

package/dist/internal/parser.d.ts

@@ -112,7 +112,7 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    *
    * Each built-in combinator computes this from its structural semantics.
    * Custom parser implementations must include every fixed token that
-   * the parser accepts at `argv[0]` — command names, option names, and
+   * the parser accepts at `argv[0]`—command names, option names, and
    * literal values alike.  For example, a parser whose usage declares
    * `{ type: "literal", value: "serve" }` should include `"serve"` in
    * this set.  Parsers that accept *any* token (like `argument()`) should
@@ -265,8 +265,8 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * parser (e.g., regex patterns, numeric bounds, `choice()` values).
    *
    * Wrappers like `bindEnv()` and `bindConfig()` call this on fallback
-   * values — environment variables parsed by a looser env parser,
-   * configured defaults, and values loaded from config files — so that
+   * values—environment variables parsed by a looser env parser,
+   * configured defaults, and values loaded from config files—so that
    * those values obey the same validation semantics as CLI input.
    * Without it, parser constraints can be silently bypassed through
    * fallback paths.
@@ -292,7 +292,7 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * current dependency value, and custom value parsers whose `format()`
    * intentionally throws for unsupported inputs.  Values that
    * `format()` successfully serializes to a string are always re-parsed,
-   * and any resulting parse failure is propagated — they represent the
+   * and any resulting parse failure is propagated—they represent the
    * bug class this method exists to surface.
    *
    * @param value The candidate value to validate.
@@ -413,7 +413,7 @@ interface ExecutionContext {
    * `preCompleteAndRegisterDependencies` results directly to children
    * in Phase 3.  Children read it in their own Phase 1 to avoid
    * re-evaluating non-idempotent default thunks, but never write to
-   * it — this prevents sibling completions from leaking into each
+   * it—this prevents sibling completions from leaking into each
    * other.
    *
    * Field-name keying naturally handles parser reuse across different

package/dist/modifiers.cjs

@@ -142,14 +142,14 @@ function extractOptionalLikePhase2Seed(parser, state, exec) {
 }
 /**
 * Computes the inner state to pass through to the wrapped parser inside
-* {@link optional} / {@link withDefault}.  When the outer state is an
+* {@link optional}/{@link withDefault}.  When the outer state is an
 * array, the inner state is `state[0]`.  Otherwise, including the
 * common case where `optional()` sits at top level and the outer state
-* is either `undefined` or an annotation wrapper from `parseOptionalLike`
-* / `parse({ annotations })`, we use the wrapped parser's
+* is either `undefined` or an annotation wrapper from `parseOptionalLike`/
+* `parse({ annotations })`, we use the wrapped parser's
 * `initialState`, propagating annotations from the outer state so that
-* source-binding wrappers under `optional()` / `withDefault()` (e.g.,
-* `bindEnv()` / `bindConfig()`) can resolve their fallbacks.
+* source-binding wrappers under `optional()`/`withDefault()` (e.g.,
+* `bindEnv()`/`bindConfig()`) can resolve their fallbacks.
 *
 * @internal
 */
@@ -677,7 +677,7 @@ function withDefault(parser, defaultValue, options) {
 *
 * Because the `deferred` flag is propagated conservatively, mapped scalar
 * results are treated as missing (`undefined`) during phase-two context
-* collection — even when `transform` only used non-deferred fields.
+* collection—even when `transform` only used non-deferred fields.
 * For example, `map(object({ apiKey: prompt(...), mode: option(...) }),
 * v => v.mode)` makes phase-two contexts see `undefined` instead of the
 * real `mode` value.  This is the intentional trade-off: the alternative

package/dist/modifiers.d.cts

@@ -138,7 +138,7 @@ declare function withDefault<M extends Mode, TValue, TState, const TDefault = TV
  *
  * Because the `deferred` flag is propagated conservatively, mapped scalar
  * results are treated as missing (`undefined`) during phase-two context
- * collection — even when `transform` only used non-deferred fields.
+ * collection—even when `transform` only used non-deferred fields.
  * For example, `map(object({ apiKey: prompt(...), mode: option(...) }),
  * v => v.mode)` makes phase-two contexts see `undefined` instead of the
  * real `mode` value.  This is the intentional trade-off: the alternative

package/dist/modifiers.d.ts

@@ -138,7 +138,7 @@ declare function withDefault<M extends Mode, TValue, TState, const TDefault = TV
  *
  * Because the `deferred` flag is propagated conservatively, mapped scalar
  * results are treated as missing (`undefined`) during phase-two context
- * collection — even when `transform` only used non-deferred fields.
+ * collection—even when `transform` only used non-deferred fields.
  * For example, `map(object({ apiKey: prompt(...), mode: option(...) }),
  * v => v.mode)` makes phase-two contexts see `undefined` instead of the
  * real `mode` value.  This is the intentional trade-off: the alternative

package/dist/modifiers.js

@@ -142,14 +142,14 @@ function extractOptionalLikePhase2Seed(parser, state, exec) {
 }
 /**
 * Computes the inner state to pass through to the wrapped parser inside
-* {@link optional} / {@link withDefault}.  When the outer state is an
+* {@link optional}/{@link withDefault}.  When the outer state is an
 * array, the inner state is `state[0]`.  Otherwise, including the
 * common case where `optional()` sits at top level and the outer state
-* is either `undefined` or an annotation wrapper from `parseOptionalLike`
-* / `parse({ annotations })`, we use the wrapped parser's
+* is either `undefined` or an annotation wrapper from `parseOptionalLike`/
+* `parse({ annotations })`, we use the wrapped parser's
 * `initialState`, propagating annotations from the outer state so that
-* source-binding wrappers under `optional()` / `withDefault()` (e.g.,
-* `bindEnv()` / `bindConfig()`) can resolve their fallbacks.
+* source-binding wrappers under `optional()`/`withDefault()` (e.g.,
+* `bindEnv()`/`bindConfig()`) can resolve their fallbacks.
 *
 * @internal
 */
@@ -677,7 +677,7 @@ function withDefault(parser, defaultValue, options) {
 *
 * Because the `deferred` flag is propagated conservatively, mapped scalar
 * results are treated as missing (`undefined`) during phase-two context
-* collection — even when `transform` only used non-deferred fields.
+* collection—even when `transform` only used non-deferred fields.
 * For example, `map(object({ apiKey: prompt(...), mode: option(...) }),
 * v => v.mode)` makes phase-two contexts see `undefined` instead of the
 * real `mode` value.  This is the intentional trade-off: the alternative

package/dist/usage-internals.cjs

@@ -55,7 +55,7 @@ function collectLeadingCandidates(terms, optionNames, commandNames) {
 *
 * This is the command-only projection of {@link collectLeadingCandidates}
 * and is used to generate accurate "Did you mean?" suggestions in
-* `command()` error messages — suggestions are scoped to commands actually
+* `command()` error messages—suggestions are scoped to commands actually
 * reachable at the current parse position rather than all commands anywhere
 * in the usage tree.
 *

package/dist/usage-internals.js

@@ -55,7 +55,7 @@ function collectLeadingCandidates(terms, optionNames, commandNames) {
 *
 * This is the command-only projection of {@link collectLeadingCandidates}
 * and is used to generate accurate "Did you mean?" suggestions in
-* `command()` error messages — suggestions are scoped to commands actually
+* `command()` error messages—suggestions are scoped to commands actually
 * reachable at the current parse position rather than all commands anywhere
 * in the usage tree.
 *

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

@@ -161,7 +161,7 @@ type ValueParserResult<T> = {
  * A recursive map that tracks which fields in a parsed object hold deferred
  * placeholder values.  Each entry maps a property key to either `null`
  * (the field is fully deferred and should be replaced with `undefined`)
- * or another `DeferredMap` (the field is partially deferred — recurse into
+ * or another `DeferredMap` (the field is partially deferred—recurse into
  * its sub-fields).
  *
  * @since 1.0.0
@@ -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

@@ -161,7 +161,7 @@ type ValueParserResult<T> = {
  * A recursive map that tracks which fields in a parsed object hold deferred
  * placeholder values.  Each entry maps a property key to either `null`
  * (the field is fully deferred and should be replaced with `undefined`)
- * or another `DeferredMap` (the field is partially deferred — recurse into
+ * or another `DeferredMap` (the field is partially deferred—recurse into
  * its sub-fields).
  *
  * @since 1.0.0
@@ -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.2069",
+  "version": "1.1.0-dev.2077",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",