@optique/core 1.1.0-dev.2053 → 1.1.0-dev.2057

package/dist/index.cjs

@@ -45,6 +45,7 @@ exports.extractCommandNames = require_usage.extractCommandNames;
 exports.extractLiteralValues = require_usage.extractLiteralValues;
 exports.extractOptionNames = require_usage.extractOptionNames;
 exports.fail = require_primitives.fail;
+exports.fileSize = require_valueparser.fileSize;
 exports.fish = require_completion.fish;
 exports.flag = require_primitives.flag;
 exports.float = require_valueparser.float;

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, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, 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, 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, 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, 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, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, 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, 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, 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, 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, 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, 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, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, 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, 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, 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, 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, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, 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, 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, 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, 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, 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, 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, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
+import { checkBooleanOption, checkEnumOption, choice, cidr, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, 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, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, 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, 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, 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, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/valueparser.cjs

@@ -504,6 +504,337 @@ function float(options = {}) {
 		}
 	};
 }
+const SI_MULTIPLIERS = {
+	b: 1,
+	kb: 1e3,
+	mb: 1e6,
+	gb: 1e9,
+	tb: 1e12,
+	pb: 1e15,
+	eb: 1e18
+};
+const IEC_MULTIPLIERS = {
+	b: 1,
+	kb: 1024,
+	mb: 1024 ** 2,
+	gb: 1024 ** 3,
+	tb: 1024 ** 4,
+	pb: 1024 ** 5,
+	eb: 1024 ** 6,
+	kib: 1024,
+	mib: 1024 ** 2,
+	gib: 1024 ** 3,
+	tib: 1024 ** 4,
+	pib: 1024 ** 5,
+	eib: 1024 ** 6
+};
+const IEC_ONLY_MULTIPLIERS = {
+	kib: 1024,
+	mib: 1024 ** 2,
+	gib: 1024 ** 3,
+	tib: 1024 ** 4,
+	pib: 1024 ** 5,
+	eib: 1024 ** 6
+};
+const FILE_SIZE_REGEX = /^([+-]?(?:\d+\.?\d*|\d*\.\d+))\s*([a-zA-Z]*)$/;
+/**
+* Formats `bytes` using the most readable unit from the given ordered list.
+* Falls back to `"${bytes}B"`.
+*
+* A unit is chosen only when the formatted value round-trips exactly: the
+* rounded quotient must lie in [1, 1000) and `rounded * size === bytes` must
+* hold in float64 arithmetic.  This guarantees `parse(format(x)) === x`.
+*/
+function formatWithUnits(bytes, units) {
+	if (bytes === 0) return "0B";
+	const absBytes = Math.abs(bytes);
+	for (const [unit, size] of units) {
+		if (absBytes < size) continue;
+		const v = bytes / size;
+		const rounded = Math.round(v * 100) / 100;
+		const absRounded = Math.abs(rounded);
+		if (absRounded >= 1 && absRounded < 1e3 && rounded * size === bytes) return `${rounded}${unit}`;
+	}
+	return `${bytes}B`;
+}
+const FORMAT_UNITS_DEFAULT = [
+	["EiB", 1024 ** 6],
+	["PiB", 1024 ** 5],
+	["TiB", 1024 ** 4],
+	["GiB", 1024 ** 3],
+	["MiB", 1024 ** 2],
+	["KiB", 1024],
+	["EB", 1e18],
+	["PB", 1e15],
+	["TB", 1e12],
+	["GB", 1e9],
+	["MB", 1e6],
+	["KB", 1e3]
+];
+const FORMAT_UNITS_SI_AS_BINARY = [
+	["EB", 1024 ** 6],
+	["PB", 1024 ** 5],
+	["TB", 1024 ** 4],
+	["GB", 1024 ** 3],
+	["MB", 1024 ** 2],
+	["KB", 1024]
+];
+const BIGINT_SI_MULTIPLIERS = {
+	b: 1n,
+	kb: 1000n,
+	mb: 1000000n,
+	gb: 1000000000n,
+	tb: 1000000000000n,
+	pb: 1000000000000000n,
+	eb: 1000000000000000000n
+};
+const BIGINT_IEC_MULTIPLIERS = {
+	b: 1n,
+	kb: 1024n,
+	mb: 1024n ** 2n,
+	gb: 1024n ** 3n,
+	tb: 1024n ** 4n,
+	pb: 1024n ** 5n,
+	eb: 1024n ** 6n,
+	kib: 1024n,
+	mib: 1024n ** 2n,
+	gib: 1024n ** 3n,
+	tib: 1024n ** 4n,
+	pib: 1024n ** 5n,
+	eib: 1024n ** 6n
+};
+const BIGINT_IEC_ONLY_MULTIPLIERS = {
+	kib: 1024n,
+	mib: 1024n ** 2n,
+	gib: 1024n ** 3n,
+	tib: 1024n ** 4n,
+	pib: 1024n ** 5n,
+	eib: 1024n ** 6n
+};
+const BIGINT_FORMAT_UNITS_DEFAULT = [
+	["EiB", 1024n ** 6n],
+	["PiB", 1024n ** 5n],
+	["TiB", 1024n ** 4n],
+	["GiB", 1024n ** 3n],
+	["MiB", 1024n ** 2n],
+	["KiB", 1024n],
+	["EB", 1000000000000000000n],
+	["PB", 1000000000000000n],
+	["TB", 1000000000000n],
+	["GB", 1000000000n],
+	["MB", 1000000n],
+	["KB", 1000n]
+];
+const BIGINT_FORMAT_UNITS_SI_AS_BINARY = [
+	["EB", 1024n ** 6n],
+	["PB", 1024n ** 5n],
+	["TB", 1024n ** 4n],
+	["GB", 1024n ** 3n],
+	["MB", 1024n ** 2n],
+	["KB", 1024n]
+];
+/**
+* Formats a bigint byte count using the most readable unit.  Falls back to
+* `"${value}B"`.  Tries exact integers, then 1 and 2 decimal places.
+*/
+function formatBigIntBytes(value, units) {
+	if (value === 0n) return "0B";
+	const absValue = value < 0n ? -value : value;
+	for (const [unit, size] of units) {
+		if (absValue < size) continue;
+		if (value % size === 0n) {
+			const v = value / size;
+			const absV = v < 0n ? -v : v;
+			if (absV >= 1n && absV < 1000n) return `${v}${unit}`;
+		}
+		const v100 = value * 100n;
+		if (v100 % size === 0n) {
+			const q = v100 / size;
+			const absQ = q < 0n ? -q : q;
+			if (absQ >= 100n && absQ < 100000n) {
+				const intPart = q / 100n;
+				const decPart = absQ % 100n;
+				if (decPart % 10n === 0n) return `${intPart}.${decPart / 10n}${unit}`;
+				return `${intPart}.${String(decPart).padStart(2, "0")}${unit}`;
+			}
+		}
+	}
+	return `${value}B`;
+}
+/**
+* Core computation: parses `numStr` as a decimal rational, multiplies by
+* `mBig`, and returns the exact integer result as a `bigint`, or `null` when
+* the result would be fractional.  The safe-integer range check is NOT applied
+* here; callers add it as needed.
+*/
+function parseExactBytesRaw(numStr, mBig) {
+	const negative = numStr.startsWith("-");
+	const absStr = numStr.startsWith("+") || numStr.startsWith("-") ? numStr.slice(1) : numStr;
+	const dotIdx = absStr.indexOf(".");
+	const intPart = dotIdx < 0 ? absStr : absStr.slice(0, dotIdx);
+	const fracPart = dotIdx < 0 ? "" : absStr.slice(dotIdx + 1);
+	const numeratorStr = ((intPart || "0") + fracPart).replace(/^0+/, "") || "0";
+	const numerator = BigInt(numeratorStr) * (negative ? -1n : 1n);
+	const denominator = 10n ** BigInt(fracPart.length);
+	const bytesNumerator = numerator * mBig;
+	if (bytesNumerator % denominator !== 0n) return null;
+	return bytesNumerator / denominator;
+}
+/**
+* Parses `numStr` as a decimal rational and multiplies by `multiplier`,
+* returning the exact integer result as a safe `number`, or `null` when the
+* result would be fractional or outside `Number.MAX_SAFE_INTEGER`.
+*
+* All arithmetic is performed with `bigint` to avoid float64 precision loss
+* (e.g. `"1.0000000000000001"` must not silently round to `1`).
+*/
+function parseExactBytes(numStr, multiplier) {
+	const bytes = parseExactBytesRaw(numStr, BigInt(multiplier));
+	if (bytes == null) return null;
+	const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+	if (bytes < -maxSafe || bytes > maxSafe) return null;
+	return Number(bytes);
+}
+const FILE_SIZE_UNITS = [
+	"B",
+	"KB",
+	"MB",
+	"GB",
+	"TB",
+	"PB",
+	"EB",
+	"KiB",
+	"MiB",
+	"GiB",
+	"TiB",
+	"PiB",
+	"EiB"
+];
+/**
+* Creates a {@link ValueParser} for human-readable file/data size strings such
+* as `"10MB"`, `"1.5GiB"`, or `"512B"`.  The parsed value is a `number` or
+* `bigint` representing the equivalent byte count.
+*
+* Supported units:
+*
+* | Unit | Bytes (default) |
+* |------|----------------|
+* | B    | 1              |
+* | KB   | 1 000          |
+* | MB   | 1 000 000      |
+* | GB   | 1 000 000 000  |
+* | KiB  | 1 024          |
+* | MiB  | 1 048 576      |
+* | GiB  | 1 073 741 824  |
+* | …    | …              |
+*
+* Unit suffixes are matched case-insensitively, so `"1kb"`, `"1KB"`, and
+* `"1Kb"` are all equivalent.
+*
+* @param options Configuration options for the file size parser.
+* @returns A {@link ValueParser} that parses file size strings into byte
+*          counts.
+* @throws {TypeError} If `type` is neither `"number"` nor `"bigint"`, if
+*   `metavar` is an empty string, if `allowNegative` or `siAsBinary` is not
+*   a boolean, or if `defaultUnit` is not a valid {@link FileSizeUnit}.
+* @since 1.1.0
+*/
+function fileSize(options = {}) {
+	if (options.type !== void 0 && options.type !== "number" && options.type !== "bigint") throw new TypeError(`Expected type to be "number" or "bigint", but got: ${String(options.type)}.`);
+	const metavar = options.metavar ?? "SIZE";
+	require_nonempty.ensureNonEmptyString(metavar);
+	checkBooleanOption(options, "allowNegative");
+	checkBooleanOption(options, "siAsBinary");
+	checkEnumOption(options, "defaultUnit", FILE_SIZE_UNITS);
+	const siAsBinary = options.siAsBinary ?? false;
+	function invalidFormatError(input) {
+		return {
+			success: false,
+			error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : require_message.message`Expected a file size like ${"10MB"} or ${"1.5GiB"}, but got ${input}.`
+		};
+	}
+	if (options.type === "bigint") {
+		const bigintMultiplierMap = siAsBinary ? BIGINT_IEC_MULTIPLIERS : {
+			...BIGINT_SI_MULTIPLIERS,
+			...BIGINT_IEC_ONLY_MULTIPLIERS
+		};
+		const bigintFormatUnits = siAsBinary ? BIGINT_FORMAT_UNITS_SI_AS_BINARY : BIGINT_FORMAT_UNITS_DEFAULT;
+		const numberFormatUnits = siAsBinary ? FORMAT_UNITS_SI_AS_BINARY : FORMAT_UNITS_DEFAULT;
+		return {
+			mode: "sync",
+			metavar,
+			placeholder: options.placeholder ?? 0n,
+			parse(input) {
+				const match = FILE_SIZE_REGEX.exec(input.trim());
+				if (match == null) return invalidFormatError(input);
+				const numStr = match[1];
+				const unitStr = match[2].toLowerCase();
+				let mBig;
+				if (unitStr === "") {
+					if (options.defaultUnit == null) return invalidFormatError(input);
+					mBig = bigintMultiplierMap[options.defaultUnit.toLowerCase()];
+				} else {
+					const m = bigintMultiplierMap[unitStr];
+					if (m == null) return invalidFormatError(input);
+					mBig = m;
+				}
+				const bytes = parseExactBytesRaw(numStr, mBig);
+				if (bytes == null) return invalidFormatError(input);
+				if (!(options.allowNegative ?? false) && bytes < 0n) return {
+					success: false,
+					error: options.errors?.negativeNotAllowed ? typeof options.errors.negativeNotAllowed === "function" ? options.errors.negativeNotAllowed(bytes) : options.errors.negativeNotAllowed : require_message.message`Expected a non-negative file size, but got ${input}.`
+				};
+				return {
+					success: true,
+					value: bytes
+				};
+			},
+			format(value) {
+				const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+				if (value >= -maxSafe && value <= maxSafe) return formatWithUnits(Number(value), numberFormatUnits);
+				return formatBigIntBytes(value, bigintFormatUnits);
+			}
+		};
+	}
+	const multiplierMap = siAsBinary ? IEC_MULTIPLIERS : {
+		...SI_MULTIPLIERS,
+		...IEC_ONLY_MULTIPLIERS
+	};
+	const formatUnits = siAsBinary ? FORMAT_UNITS_SI_AS_BINARY : FORMAT_UNITS_DEFAULT;
+	return {
+		mode: "sync",
+		metavar,
+		placeholder: options.placeholder ?? 0,
+		parse(input) {
+			const match = FILE_SIZE_REGEX.exec(input.trim());
+			if (match == null) return invalidFormatError(input);
+			const numStr = match[1];
+			const unitStr = match[2].toLowerCase();
+			let multiplier;
+			if (unitStr === "") {
+				if (options.defaultUnit == null) return invalidFormatError(input);
+				multiplier = multiplierMap[options.defaultUnit.toLowerCase()];
+			} else {
+				const m = multiplierMap[unitStr];
+				if (m == null) return invalidFormatError(input);
+				multiplier = m;
+			}
+			const bytes = parseExactBytes(numStr, multiplier);
+			if (bytes == null) return invalidFormatError(input);
+			if (!(options.allowNegative ?? false) && bytes < 0) return {
+				success: false,
+				error: options.errors?.negativeNotAllowed ? typeof options.errors.negativeNotAllowed === "function" ? options.errors.negativeNotAllowed(bytes) : options.errors.negativeNotAllowed : require_message.message`Expected a non-negative file size, but got ${input}.`
+			};
+			return {
+				success: true,
+				value: bytes
+			};
+		},
+		format(value) {
+			return formatWithUnits(value, formatUnits);
+		}
+	};
+}
 /**
 * The set of URL schemes that are considered "special" by the WHATWG URL
 * Standard.  These schemes always use the `://` authority syntax.
@@ -3692,6 +4023,7 @@ exports.cidr = cidr;
 exports.domain = domain;
 exports.email = email;
 exports.ensureNonEmptyString = require_nonempty.ensureNonEmptyString;
+exports.fileSize = fileSize;
 exports.float = float;
 exports.hostname = hostname;
 exports.integer = integer;

package/dist/valueparser.d.cts

@@ -584,6 +584,169 @@ interface FloatOptions {
  *          numbers.
  */
 declare function float(options?: FloatOptions): ValueParser<"sync", number>;
+/**
+ * A canonical file size unit string.  SI units use powers of 1 000 by
+ * default; IEC units always use powers of 1 024.
+ * @since 1.1.0
+ */
+type FileSizeUnit = "B" | "KB" | "MB" | "GB" | "TB" | "PB" | "EB" | "KiB" | "MiB" | "GiB" | "TiB" | "PiB" | "EiB";
+/**
+ * Options for creating a {@link fileSize} parser that returns `number`.
+ * @since 1.1.0
+ */
+interface FileSizeOptionsNumber {
+  /**
+   * The return type.  Defaults to `"number"`.
+   * @default `"number"`
+   */
+  readonly type?: "number";
+  /**
+   * The metavariable name for this parser.  Used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"SIZE"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * If `true`, negative byte values are accepted.  Most size-related CLI
+   * options do not accept negative values, so this defaults to `false`.
+   * @default `false`
+   */
+  readonly allowNegative?: boolean;
+  /**
+   * The unit to assume when the input contains only a number with no unit
+   * suffix (e.g., `"100"` with `defaultUnit: "MB"` → 100 000 000 bytes).
+   * When this option is absent, a bare number without a unit is rejected.
+   */
+  readonly defaultUnit?: FileSizeUnit;
+  /**
+   * When `true`, SI suffixes (`KB`, `MB`, `GB`, …) are interpreted as
+   * binary powers of 1 024 rather than decimal powers of 1 000.  This
+   * matches a widespread but technically incorrect convention where
+   * "1 KB" means 1 024 bytes.  IEC suffixes (`KiB`, `MiB`, …) are
+   * unaffected by this option.
+   *
+   * @default `false`
+   * @since 1.1.0
+   */
+  readonly siAsBinary?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * @default `0`
+   * @since 1.1.0
+   */
+  readonly placeholder?: number;
+  /**
+   * Custom error messages for file size parsing failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid file size string.
+     * Can be a static message or a function that receives the raw input.
+     */
+    readonly invalidFormat?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when a negative value is provided but
+     * {@link FileSizeOptionsNumber.allowNegative} is `false`.
+     * Can be a static message or a function that receives the byte value.
+     */
+    readonly negativeNotAllowed?: Message | ((value: number) => Message);
+  };
+}
+/**
+ * Options for creating a {@link fileSize} parser that returns `bigint`.
+ * Use this when byte counts may exceed `Number.MAX_SAFE_INTEGER` (roughly
+ * 9 PB), for example when working with EB/EiB-range values.
+ * @since 1.1.0
+ */
+interface FileSizeOptionsBigInt {
+  /**
+   * Must be set to `"bigint"` to select bigint output.
+   */
+  readonly type: "bigint";
+  /**
+   * The metavariable name for this parser.  Used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"SIZE"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * If `true`, negative byte values are accepted.
+   * @default `false`
+   */
+  readonly allowNegative?: boolean;
+  /**
+   * The unit to assume when the input contains only a number with no unit
+   * suffix.  When absent, a bare number is rejected.
+   */
+  readonly defaultUnit?: FileSizeUnit;
+  /**
+   * When `true`, SI suffixes (`KB`, `MB`, `GB`, …) are interpreted as
+   * binary powers of 1 024 rather than decimal powers of 1 000.
+   * @default `false`
+   * @since 1.1.0
+   */
+  readonly siAsBinary?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * @default `0n`
+   * @since 1.1.0
+   */
+  readonly placeholder?: bigint;
+  /**
+   * Custom error messages for file size parsing failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid file size string.
+     * Can be a static message or a function that receives the raw input.
+     */
+    readonly invalidFormat?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when a negative value is provided but
+     * {@link FileSizeOptionsBigInt.allowNegative} is `false`.
+     * Can be a static message or a function that receives the byte value.
+     */
+    readonly negativeNotAllowed?: Message | ((value: bigint) => Message);
+  };
+}
+/**
+ * Options for creating a {@link fileSize} parser.
+ * @since 1.1.0
+ */
+type FileSizeOptions = FileSizeOptionsNumber | FileSizeOptionsBigInt;
+/**
+ * Creates a {@link ValueParser} for human-readable file/data size strings
+ * that returns a `number` byte count.
+ *
+ * @param options Configuration options for the file size parser.
+ * @returns A {@link ValueParser} that parses file size strings into `number`
+ *          byte counts.
+ * @throws {TypeError} If {@link FileSizeOptionsNumber.metavar} is an empty
+ *   string, if {@link FileSizeOptionsNumber.allowNegative} or
+ *   {@link FileSizeOptionsNumber.siAsBinary} is not a boolean, or if
+ *   {@link FileSizeOptionsNumber.defaultUnit} is not a valid
+ *   {@link FileSizeUnit}.
+ * @since 1.1.0
+ */
+declare function fileSize(options?: FileSizeOptionsNumber): ValueParser<"sync", number>;
+/**
+ * Creates a {@link ValueParser} for human-readable file/data size strings
+ * that returns a `bigint` byte count.  Use this when byte counts may exceed
+ * `Number.MAX_SAFE_INTEGER` (~9 PB), for example with EB/EiB-range values.
+ *
+ * @param options Configuration options for the file size parser.
+ * @returns A {@link ValueParser} that parses file size strings into `bigint`
+ *          byte counts.
+ * @throws {TypeError} If {@link FileSizeOptionsBigInt.metavar} is an empty
+ *   string, if {@link FileSizeOptionsBigInt.allowNegative} or
+ *   {@link FileSizeOptionsBigInt.siAsBinary} is not a boolean, or if
+ *   {@link FileSizeOptionsBigInt.defaultUnit} is not a valid
+ *   {@link FileSizeUnit}.
+ * @since 1.1.0
+ */
+declare function fileSize(options: FileSizeOptionsBigInt): ValueParser<"sync", bigint>;
 /**
  * Options for creating a {@link url} parser.
  */
@@ -2166,4 +2329,4 @@ interface CidrOptions {
  */
 declare function cidr(options?: CidrOptions): ValueParser<"sync", CidrValue>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, 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, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };

package/dist/valueparser.d.ts

@@ -584,6 +584,169 @@ interface FloatOptions {
  *          numbers.
  */
 declare function float(options?: FloatOptions): ValueParser<"sync", number>;
+/**
+ * A canonical file size unit string.  SI units use powers of 1 000 by
+ * default; IEC units always use powers of 1 024.
+ * @since 1.1.0
+ */
+type FileSizeUnit = "B" | "KB" | "MB" | "GB" | "TB" | "PB" | "EB" | "KiB" | "MiB" | "GiB" | "TiB" | "PiB" | "EiB";
+/**
+ * Options for creating a {@link fileSize} parser that returns `number`.
+ * @since 1.1.0
+ */
+interface FileSizeOptionsNumber {
+  /**
+   * The return type.  Defaults to `"number"`.
+   * @default `"number"`
+   */
+  readonly type?: "number";
+  /**
+   * The metavariable name for this parser.  Used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"SIZE"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * If `true`, negative byte values are accepted.  Most size-related CLI
+   * options do not accept negative values, so this defaults to `false`.
+   * @default `false`
+   */
+  readonly allowNegative?: boolean;
+  /**
+   * The unit to assume when the input contains only a number with no unit
+   * suffix (e.g., `"100"` with `defaultUnit: "MB"` → 100 000 000 bytes).
+   * When this option is absent, a bare number without a unit is rejected.
+   */
+  readonly defaultUnit?: FileSizeUnit;
+  /**
+   * When `true`, SI suffixes (`KB`, `MB`, `GB`, …) are interpreted as
+   * binary powers of 1 024 rather than decimal powers of 1 000.  This
+   * matches a widespread but technically incorrect convention where
+   * "1 KB" means 1 024 bytes.  IEC suffixes (`KiB`, `MiB`, …) are
+   * unaffected by this option.
+   *
+   * @default `false`
+   * @since 1.1.0
+   */
+  readonly siAsBinary?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * @default `0`
+   * @since 1.1.0
+   */
+  readonly placeholder?: number;
+  /**
+   * Custom error messages for file size parsing failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid file size string.
+     * Can be a static message or a function that receives the raw input.
+     */
+    readonly invalidFormat?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when a negative value is provided but
+     * {@link FileSizeOptionsNumber.allowNegative} is `false`.
+     * Can be a static message or a function that receives the byte value.
+     */
+    readonly negativeNotAllowed?: Message | ((value: number) => Message);
+  };
+}
+/**
+ * Options for creating a {@link fileSize} parser that returns `bigint`.
+ * Use this when byte counts may exceed `Number.MAX_SAFE_INTEGER` (roughly
+ * 9 PB), for example when working with EB/EiB-range values.
+ * @since 1.1.0
+ */
+interface FileSizeOptionsBigInt {
+  /**
+   * Must be set to `"bigint"` to select bigint output.
+   */
+  readonly type: "bigint";
+  /**
+   * The metavariable name for this parser.  Used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"SIZE"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * If `true`, negative byte values are accepted.
+   * @default `false`
+   */
+  readonly allowNegative?: boolean;
+  /**
+   * The unit to assume when the input contains only a number with no unit
+   * suffix.  When absent, a bare number is rejected.
+   */
+  readonly defaultUnit?: FileSizeUnit;
+  /**
+   * When `true`, SI suffixes (`KB`, `MB`, `GB`, …) are interpreted as
+   * binary powers of 1 024 rather than decimal powers of 1 000.
+   * @default `false`
+   * @since 1.1.0
+   */
+  readonly siAsBinary?: boolean;
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * @default `0n`
+   * @since 1.1.0
+   */
+  readonly placeholder?: bigint;
+  /**
+   * Custom error messages for file size parsing failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid file size string.
+     * Can be a static message or a function that receives the raw input.
+     */
+    readonly invalidFormat?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when a negative value is provided but
+     * {@link FileSizeOptionsBigInt.allowNegative} is `false`.
+     * Can be a static message or a function that receives the byte value.
+     */
+    readonly negativeNotAllowed?: Message | ((value: bigint) => Message);
+  };
+}
+/**
+ * Options for creating a {@link fileSize} parser.
+ * @since 1.1.0
+ */
+type FileSizeOptions = FileSizeOptionsNumber | FileSizeOptionsBigInt;
+/**
+ * Creates a {@link ValueParser} for human-readable file/data size strings
+ * that returns a `number` byte count.
+ *
+ * @param options Configuration options for the file size parser.
+ * @returns A {@link ValueParser} that parses file size strings into `number`
+ *          byte counts.
+ * @throws {TypeError} If {@link FileSizeOptionsNumber.metavar} is an empty
+ *   string, if {@link FileSizeOptionsNumber.allowNegative} or
+ *   {@link FileSizeOptionsNumber.siAsBinary} is not a boolean, or if
+ *   {@link FileSizeOptionsNumber.defaultUnit} is not a valid
+ *   {@link FileSizeUnit}.
+ * @since 1.1.0
+ */
+declare function fileSize(options?: FileSizeOptionsNumber): ValueParser<"sync", number>;
+/**
+ * Creates a {@link ValueParser} for human-readable file/data size strings
+ * that returns a `bigint` byte count.  Use this when byte counts may exceed
+ * `Number.MAX_SAFE_INTEGER` (~9 PB), for example with EB/EiB-range values.
+ *
+ * @param options Configuration options for the file size parser.
+ * @returns A {@link ValueParser} that parses file size strings into `bigint`
+ *          byte counts.
+ * @throws {TypeError} If {@link FileSizeOptionsBigInt.metavar} is an empty
+ *   string, if {@link FileSizeOptionsBigInt.allowNegative} or
+ *   {@link FileSizeOptionsBigInt.siAsBinary} is not a boolean, or if
+ *   {@link FileSizeOptionsBigInt.defaultUnit} is not a valid
+ *   {@link FileSizeUnit}.
+ * @since 1.1.0
+ */
+declare function fileSize(options: FileSizeOptionsBigInt): ValueParser<"sync", bigint>;
 /**
  * Options for creating a {@link url} parser.
  */
@@ -2166,4 +2329,4 @@ interface CidrOptions {
  */
 declare function cidr(options?: CidrOptions): ValueParser<"sync", CidrValue>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, 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, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };

package/dist/valueparser.js

@@ -504,6 +504,337 @@ function float(options = {}) {
 		}
 	};
 }
+const SI_MULTIPLIERS = {
+	b: 1,
+	kb: 1e3,
+	mb: 1e6,
+	gb: 1e9,
+	tb: 1e12,
+	pb: 1e15,
+	eb: 1e18
+};
+const IEC_MULTIPLIERS = {
+	b: 1,
+	kb: 1024,
+	mb: 1024 ** 2,
+	gb: 1024 ** 3,
+	tb: 1024 ** 4,
+	pb: 1024 ** 5,
+	eb: 1024 ** 6,
+	kib: 1024,
+	mib: 1024 ** 2,
+	gib: 1024 ** 3,
+	tib: 1024 ** 4,
+	pib: 1024 ** 5,
+	eib: 1024 ** 6
+};
+const IEC_ONLY_MULTIPLIERS = {
+	kib: 1024,
+	mib: 1024 ** 2,
+	gib: 1024 ** 3,
+	tib: 1024 ** 4,
+	pib: 1024 ** 5,
+	eib: 1024 ** 6
+};
+const FILE_SIZE_REGEX = /^([+-]?(?:\d+\.?\d*|\d*\.\d+))\s*([a-zA-Z]*)$/;
+/**
+* Formats `bytes` using the most readable unit from the given ordered list.
+* Falls back to `"${bytes}B"`.
+*
+* A unit is chosen only when the formatted value round-trips exactly: the
+* rounded quotient must lie in [1, 1000) and `rounded * size === bytes` must
+* hold in float64 arithmetic.  This guarantees `parse(format(x)) === x`.
+*/
+function formatWithUnits(bytes, units) {
+	if (bytes === 0) return "0B";
+	const absBytes = Math.abs(bytes);
+	for (const [unit, size] of units) {
+		if (absBytes < size) continue;
+		const v = bytes / size;
+		const rounded = Math.round(v * 100) / 100;
+		const absRounded = Math.abs(rounded);
+		if (absRounded >= 1 && absRounded < 1e3 && rounded * size === bytes) return `${rounded}${unit}`;
+	}
+	return `${bytes}B`;
+}
+const FORMAT_UNITS_DEFAULT = [
+	["EiB", 1024 ** 6],
+	["PiB", 1024 ** 5],
+	["TiB", 1024 ** 4],
+	["GiB", 1024 ** 3],
+	["MiB", 1024 ** 2],
+	["KiB", 1024],
+	["EB", 1e18],
+	["PB", 1e15],
+	["TB", 1e12],
+	["GB", 1e9],
+	["MB", 1e6],
+	["KB", 1e3]
+];
+const FORMAT_UNITS_SI_AS_BINARY = [
+	["EB", 1024 ** 6],
+	["PB", 1024 ** 5],
+	["TB", 1024 ** 4],
+	["GB", 1024 ** 3],
+	["MB", 1024 ** 2],
+	["KB", 1024]
+];
+const BIGINT_SI_MULTIPLIERS = {
+	b: 1n,
+	kb: 1000n,
+	mb: 1000000n,
+	gb: 1000000000n,
+	tb: 1000000000000n,
+	pb: 1000000000000000n,
+	eb: 1000000000000000000n
+};
+const BIGINT_IEC_MULTIPLIERS = {
+	b: 1n,
+	kb: 1024n,
+	mb: 1024n ** 2n,
+	gb: 1024n ** 3n,
+	tb: 1024n ** 4n,
+	pb: 1024n ** 5n,
+	eb: 1024n ** 6n,
+	kib: 1024n,
+	mib: 1024n ** 2n,
+	gib: 1024n ** 3n,
+	tib: 1024n ** 4n,
+	pib: 1024n ** 5n,
+	eib: 1024n ** 6n
+};
+const BIGINT_IEC_ONLY_MULTIPLIERS = {
+	kib: 1024n,
+	mib: 1024n ** 2n,
+	gib: 1024n ** 3n,
+	tib: 1024n ** 4n,
+	pib: 1024n ** 5n,
+	eib: 1024n ** 6n
+};
+const BIGINT_FORMAT_UNITS_DEFAULT = [
+	["EiB", 1024n ** 6n],
+	["PiB", 1024n ** 5n],
+	["TiB", 1024n ** 4n],
+	["GiB", 1024n ** 3n],
+	["MiB", 1024n ** 2n],
+	["KiB", 1024n],
+	["EB", 1000000000000000000n],
+	["PB", 1000000000000000n],
+	["TB", 1000000000000n],
+	["GB", 1000000000n],
+	["MB", 1000000n],
+	["KB", 1000n]
+];
+const BIGINT_FORMAT_UNITS_SI_AS_BINARY = [
+	["EB", 1024n ** 6n],
+	["PB", 1024n ** 5n],
+	["TB", 1024n ** 4n],
+	["GB", 1024n ** 3n],
+	["MB", 1024n ** 2n],
+	["KB", 1024n]
+];
+/**
+* Formats a bigint byte count using the most readable unit.  Falls back to
+* `"${value}B"`.  Tries exact integers, then 1 and 2 decimal places.
+*/
+function formatBigIntBytes(value, units) {
+	if (value === 0n) return "0B";
+	const absValue = value < 0n ? -value : value;
+	for (const [unit, size] of units) {
+		if (absValue < size) continue;
+		if (value % size === 0n) {
+			const v = value / size;
+			const absV = v < 0n ? -v : v;
+			if (absV >= 1n && absV < 1000n) return `${v}${unit}`;
+		}
+		const v100 = value * 100n;
+		if (v100 % size === 0n) {
+			const q = v100 / size;
+			const absQ = q < 0n ? -q : q;
+			if (absQ >= 100n && absQ < 100000n) {
+				const intPart = q / 100n;
+				const decPart = absQ % 100n;
+				if (decPart % 10n === 0n) return `${intPart}.${decPart / 10n}${unit}`;
+				return `${intPart}.${String(decPart).padStart(2, "0")}${unit}`;
+			}
+		}
+	}
+	return `${value}B`;
+}
+/**
+* Core computation: parses `numStr` as a decimal rational, multiplies by
+* `mBig`, and returns the exact integer result as a `bigint`, or `null` when
+* the result would be fractional.  The safe-integer range check is NOT applied
+* here; callers add it as needed.
+*/
+function parseExactBytesRaw(numStr, mBig) {
+	const negative = numStr.startsWith("-");
+	const absStr = numStr.startsWith("+") || numStr.startsWith("-") ? numStr.slice(1) : numStr;
+	const dotIdx = absStr.indexOf(".");
+	const intPart = dotIdx < 0 ? absStr : absStr.slice(0, dotIdx);
+	const fracPart = dotIdx < 0 ? "" : absStr.slice(dotIdx + 1);
+	const numeratorStr = ((intPart || "0") + fracPart).replace(/^0+/, "") || "0";
+	const numerator = BigInt(numeratorStr) * (negative ? -1n : 1n);
+	const denominator = 10n ** BigInt(fracPart.length);
+	const bytesNumerator = numerator * mBig;
+	if (bytesNumerator % denominator !== 0n) return null;
+	return bytesNumerator / denominator;
+}
+/**
+* Parses `numStr` as a decimal rational and multiplies by `multiplier`,
+* returning the exact integer result as a safe `number`, or `null` when the
+* result would be fractional or outside `Number.MAX_SAFE_INTEGER`.
+*
+* All arithmetic is performed with `bigint` to avoid float64 precision loss
+* (e.g. `"1.0000000000000001"` must not silently round to `1`).
+*/
+function parseExactBytes(numStr, multiplier) {
+	const bytes = parseExactBytesRaw(numStr, BigInt(multiplier));
+	if (bytes == null) return null;
+	const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+	if (bytes < -maxSafe || bytes > maxSafe) return null;
+	return Number(bytes);
+}
+const FILE_SIZE_UNITS = [
+	"B",
+	"KB",
+	"MB",
+	"GB",
+	"TB",
+	"PB",
+	"EB",
+	"KiB",
+	"MiB",
+	"GiB",
+	"TiB",
+	"PiB",
+	"EiB"
+];
+/**
+* Creates a {@link ValueParser} for human-readable file/data size strings such
+* as `"10MB"`, `"1.5GiB"`, or `"512B"`.  The parsed value is a `number` or
+* `bigint` representing the equivalent byte count.
+*
+* Supported units:
+*
+* | Unit | Bytes (default) |
+* |------|----------------|
+* | B    | 1              |
+* | KB   | 1 000          |
+* | MB   | 1 000 000      |
+* | GB   | 1 000 000 000  |
+* | KiB  | 1 024          |
+* | MiB  | 1 048 576      |
+* | GiB  | 1 073 741 824  |
+* | …    | …              |
+*
+* Unit suffixes are matched case-insensitively, so `"1kb"`, `"1KB"`, and
+* `"1Kb"` are all equivalent.
+*
+* @param options Configuration options for the file size parser.
+* @returns A {@link ValueParser} that parses file size strings into byte
+*          counts.
+* @throws {TypeError} If `type` is neither `"number"` nor `"bigint"`, if
+*   `metavar` is an empty string, if `allowNegative` or `siAsBinary` is not
+*   a boolean, or if `defaultUnit` is not a valid {@link FileSizeUnit}.
+* @since 1.1.0
+*/
+function fileSize(options = {}) {
+	if (options.type !== void 0 && options.type !== "number" && options.type !== "bigint") throw new TypeError(`Expected type to be "number" or "bigint", but got: ${String(options.type)}.`);
+	const metavar = options.metavar ?? "SIZE";
+	ensureNonEmptyString(metavar);
+	checkBooleanOption(options, "allowNegative");
+	checkBooleanOption(options, "siAsBinary");
+	checkEnumOption(options, "defaultUnit", FILE_SIZE_UNITS);
+	const siAsBinary = options.siAsBinary ?? false;
+	function invalidFormatError(input) {
+		return {
+			success: false,
+			error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : message`Expected a file size like ${"10MB"} or ${"1.5GiB"}, but got ${input}.`
+		};
+	}
+	if (options.type === "bigint") {
+		const bigintMultiplierMap = siAsBinary ? BIGINT_IEC_MULTIPLIERS : {
+			...BIGINT_SI_MULTIPLIERS,
+			...BIGINT_IEC_ONLY_MULTIPLIERS
+		};
+		const bigintFormatUnits = siAsBinary ? BIGINT_FORMAT_UNITS_SI_AS_BINARY : BIGINT_FORMAT_UNITS_DEFAULT;
+		const numberFormatUnits = siAsBinary ? FORMAT_UNITS_SI_AS_BINARY : FORMAT_UNITS_DEFAULT;
+		return {
+			mode: "sync",
+			metavar,
+			placeholder: options.placeholder ?? 0n,
+			parse(input) {
+				const match = FILE_SIZE_REGEX.exec(input.trim());
+				if (match == null) return invalidFormatError(input);
+				const numStr = match[1];
+				const unitStr = match[2].toLowerCase();
+				let mBig;
+				if (unitStr === "") {
+					if (options.defaultUnit == null) return invalidFormatError(input);
+					mBig = bigintMultiplierMap[options.defaultUnit.toLowerCase()];
+				} else {
+					const m = bigintMultiplierMap[unitStr];
+					if (m == null) return invalidFormatError(input);
+					mBig = m;
+				}
+				const bytes = parseExactBytesRaw(numStr, mBig);
+				if (bytes == null) return invalidFormatError(input);
+				if (!(options.allowNegative ?? false) && bytes < 0n) return {
+					success: false,
+					error: options.errors?.negativeNotAllowed ? typeof options.errors.negativeNotAllowed === "function" ? options.errors.negativeNotAllowed(bytes) : options.errors.negativeNotAllowed : message`Expected a non-negative file size, but got ${input}.`
+				};
+				return {
+					success: true,
+					value: bytes
+				};
+			},
+			format(value) {
+				const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+				if (value >= -maxSafe && value <= maxSafe) return formatWithUnits(Number(value), numberFormatUnits);
+				return formatBigIntBytes(value, bigintFormatUnits);
+			}
+		};
+	}
+	const multiplierMap = siAsBinary ? IEC_MULTIPLIERS : {
+		...SI_MULTIPLIERS,
+		...IEC_ONLY_MULTIPLIERS
+	};
+	const formatUnits = siAsBinary ? FORMAT_UNITS_SI_AS_BINARY : FORMAT_UNITS_DEFAULT;
+	return {
+		mode: "sync",
+		metavar,
+		placeholder: options.placeholder ?? 0,
+		parse(input) {
+			const match = FILE_SIZE_REGEX.exec(input.trim());
+			if (match == null) return invalidFormatError(input);
+			const numStr = match[1];
+			const unitStr = match[2].toLowerCase();
+			let multiplier;
+			if (unitStr === "") {
+				if (options.defaultUnit == null) return invalidFormatError(input);
+				multiplier = multiplierMap[options.defaultUnit.toLowerCase()];
+			} else {
+				const m = multiplierMap[unitStr];
+				if (m == null) return invalidFormatError(input);
+				multiplier = m;
+			}
+			const bytes = parseExactBytes(numStr, multiplier);
+			if (bytes == null) return invalidFormatError(input);
+			if (!(options.allowNegative ?? false) && bytes < 0) return {
+				success: false,
+				error: options.errors?.negativeNotAllowed ? typeof options.errors.negativeNotAllowed === "function" ? options.errors.negativeNotAllowed(bytes) : options.errors.negativeNotAllowed : message`Expected a non-negative file size, but got ${input}.`
+			};
+			return {
+				success: true,
+				value: bytes
+			};
+		},
+		format(value) {
+			return formatWithUnits(value, formatUnits);
+		}
+	};
+}
 /**
 * The set of URL schemes that are considered "special" by the WHATWG URL
 * Standard.  These schemes always use the `://` authority syntax.
@@ -3685,4 +4016,4 @@ function cidr(options) {
 }
 
 //#endregion
-export { checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };
+export { checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };

package/package.json

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