@optique/core 1.2.0-dev.2187 → 1.2.0-dev.2188

package/dist/index.cjs

@@ -31,6 +31,7 @@ exports.concat = require_constructs.concat;
 exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
 exports.createParserContext = require_internal_parser.createParserContext;
+exports.cron = require_valueparser.cron;
 exports.deduplicateDocEntries = require_doc.deduplicateDocEntries;
 exports.deduplicateDocFragments = require_doc.deduplicateDocFragments;
 exports.dependency = require_internal_dependency.dependency;

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

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

package/dist/index.js

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

package/dist/valueparser.cjs

@@ -5844,6 +5844,218 @@ function findNonFiniteNumber(root) {
 	}
 	return void 0;
 }
+const CRON_MONTH_NAMES = new Map([
+	["JAN", 1],
+	["FEB", 2],
+	["MAR", 3],
+	["APR", 4],
+	["MAY", 5],
+	["JUN", 6],
+	["JUL", 7],
+	["AUG", 8],
+	["SEP", 9],
+	["OCT", 10],
+	["NOV", 11],
+	["DEC", 12]
+]);
+const CRON_DAY_NAMES = new Map([
+	["SUN", 0],
+	["MON", 1],
+	["TUE", 2],
+	["WED", 3],
+	["THU", 4],
+	["FRI", 5],
+	["SAT", 6]
+]);
+const CRON_FIELD_SPECS = {
+	second: {
+		kind: "second",
+		min: 0,
+		max: 59
+	},
+	minute: {
+		kind: "minute",
+		min: 0,
+		max: 59
+	},
+	hour: {
+		kind: "hour",
+		min: 0,
+		max: 23
+	},
+	dayOfMonth: {
+		kind: "dayOfMonth",
+		min: 1,
+		max: 31
+	},
+	month: {
+		kind: "month",
+		min: 1,
+		max: 12,
+		names: CRON_MONTH_NAMES
+	},
+	dayOfWeek: {
+		kind: "dayOfWeek",
+		min: 0,
+		max: 7,
+		names: CRON_DAY_NAMES
+	},
+	year: {
+		kind: "year",
+		min: 1970,
+		max: 2099
+	}
+};
+function cron(options = {}) {
+	const metavar$1 = options.metavar ?? "CRON";
+	require_nonempty.ensureNonEmptyString(metavar$1);
+	checkBooleanOption(options, "seconds");
+	checkBooleanOption(options, "years");
+	checkBooleanOption(options, "quartz");
+	const seconds = options.seconds ?? false;
+	const years = options.years ?? false;
+	const quartz = options.quartz ?? false;
+	const invalidCronError = options.errors?.invalidCron;
+	const expectedFieldCount = 5 + (seconds ? 1 : 0) + (years ? 1 : 0);
+	function makeError(input) {
+		const error = invalidCronError instanceof Function ? invalidCronError(input) : invalidCronError ?? require_message.message`Expected a valid cron expression, but got ${input}.`;
+		return {
+			success: false,
+			error
+		};
+	}
+	function parseCron(input) {
+		const fields = input.trim() === "" ? [] : input.trim().split(/\s+/u);
+		if (fields.length !== expectedFieldCount) return makeError(input);
+		let index = 0;
+		const second = seconds ? fields[index++] : void 0;
+		const minute = fields[index++];
+		const hour = fields[index++];
+		const dayOfMonth = fields[index++];
+		const month = fields[index++];
+		const dayOfWeek = fields[index++];
+		const year = years ? fields[index++] : void 0;
+		const fieldChecks = [
+			[second, CRON_FIELD_SPECS.second],
+			[minute, CRON_FIELD_SPECS.minute],
+			[hour, CRON_FIELD_SPECS.hour],
+			[dayOfMonth, CRON_FIELD_SPECS.dayOfMonth],
+			[month, CRON_FIELD_SPECS.month],
+			[dayOfWeek, CRON_FIELD_SPECS.dayOfWeek],
+			[year, CRON_FIELD_SPECS.year]
+		];
+		for (const [field, spec] of fieldChecks) if (field !== void 0 && !isValidCronField(field, spec, { quartz })) return makeError(input);
+		if (quartz && dayOfMonth === "?" && dayOfWeek === "?") return makeError(input);
+		return {
+			success: true,
+			value: {
+				...second !== void 0 ? { second } : {},
+				minute,
+				hour,
+				dayOfMonth,
+				month,
+				dayOfWeek,
+				...year !== void 0 ? { year } : {}
+			}
+		};
+	}
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		placeholder: {
+			...seconds ? { second: "0" } : {},
+			minute: "0",
+			hour: "0",
+			dayOfMonth: "*",
+			month: "*",
+			dayOfWeek: "*",
+			...years ? { year: "1970" } : {}
+		},
+		parse: parseCron,
+		format(value) {
+			return [
+				...seconds ? [value.second ?? "0"] : [],
+				value.minute,
+				value.hour,
+				value.dayOfMonth,
+				value.month,
+				value.dayOfWeek,
+				...years ? [value.year ?? "1970"] : []
+			].join(" ");
+		},
+		validate(value) {
+			if (seconds && value.second == null || years && value.year == null) return makeError(this.format(value));
+			if (!seconds && value.second != null || !years && value.year != null) return makeError(this.format(value));
+			const result = parseCron(this.format(value));
+			return result.success ? {
+				success: true,
+				value: result.value
+			} : result;
+		}
+	};
+}
+function isValidCronField(field, spec, options) {
+	if (field === "") return false;
+	const parts = field.split(",");
+	const standard = !parts.some((part) => part === "") && parts.every((part) => isValidCronFieldPart(part, spec));
+	return standard || isQuartzCronField(field, spec, options.quartz);
+}
+function isQuartzCronField(field, spec, quartz) {
+	if (!quartz) return false;
+	const upper = field.toUpperCase();
+	if (upper === "?") return spec.kind === "dayOfMonth" || spec.kind === "dayOfWeek";
+	if (spec.kind === "dayOfMonth") {
+		if (upper === "L" || upper === "LW") return true;
+		const match = /^(?<day>\d{1,2})W$/u.exec(upper);
+		return match != null && isCronValueInRange(match.groups.day, spec);
+	}
+	if (spec.kind === "dayOfWeek") {
+		if (upper === "L") return true;
+		const lastMatch = /^(?<day>[A-Z]{3}|\d)L$/u.exec(upper);
+		if (lastMatch != null) return parseQuartzDayOfWeekSuffixValue(lastMatch.groups.day);
+		const nthMatch = /^(?<day>[A-Z]{3}|\d)#(?<nth>[1-5])$/u.exec(upper);
+		if (nthMatch != null) return parseQuartzDayOfWeekSuffixValue(nthMatch.groups.day);
+	}
+	return false;
+}
+function parseQuartzDayOfWeekSuffixValue(value) {
+	if (/^[1-7]$/u.test(value)) return true;
+	if (!/^[A-Z]{3}$/u.test(value)) return false;
+	return CRON_DAY_NAMES.has(value);
+}
+function isValidCronFieldPart(part, spec) {
+	const stepParts = part.split("/");
+	if (stepParts.length > 2) return false;
+	const [base, step] = stepParts;
+	if (base === "") return false;
+	if (step !== void 0 && !isPositiveCronStep(step)) return false;
+	if (base === "*") return true;
+	const rangeParts = base.split("-");
+	if (rangeParts.length === 1) return parseCronValue(base, spec) !== void 0;
+	if (rangeParts.length !== 2) return false;
+	const [rawStart, rawEnd] = rangeParts;
+	if (rawStart === "" || rawEnd === "") return false;
+	const start = parseCronValue(rawStart, spec);
+	const end = parseCronRangeEnd(rawStart, rawEnd, spec);
+	return start !== void 0 && end !== void 0 && start <= end;
+}
+function isPositiveCronStep(step) {
+	return /^\d+$/u.test(step) && Number.parseInt(step, 10) > 0;
+}
+function isCronValueInRange(value, spec) {
+	return parseCronValue(value, spec) !== void 0;
+}
+function parseCronRangeEnd(start, end, spec) {
+	if (spec.kind === "dayOfWeek" && start.toUpperCase() !== "SUN" && (end.toUpperCase() === "SUN" || end === "0")) return 7;
+	return parseCronValue(end, spec);
+}
+function parseCronValue(value, spec) {
+	const named = spec.names?.get(value.toUpperCase());
+	if (named !== void 0) return named;
+	if (!/^\d+$/u.test(value)) return void 0;
+	const number = Number.parseInt(value, 10);
+	return number >= spec.min && number <= spec.max ? number : void 0;
+}
 /**
 * Implementation of the {@link firstOf} combinator.
 */
@@ -6102,6 +6314,7 @@ exports.checkEnumOption = checkEnumOption;
 exports.choice = choice;
 exports.cidr = cidr;
 exports.color = color;
+exports.cron = cron;
 exports.domain = domain;
 exports.email = email;
 exports.ensureNonEmptyString = require_nonempty.ensureNonEmptyString;

package/dist/valueparser.d.cts

@@ -2882,6 +2882,114 @@ declare function json(options: JsonOptions & {
  * @since 1.1.0
  */
 declare function json(options?: JsonOptions): ValueParser<"sync", Json>;
+/**
+ * A validated cron schedule expression split into cron fields.
+ *
+ * The `second` field is present when {@link cron} is configured with
+ * `seconds: true`, and the `year` field is present when it is configured
+ * with `years: true`.
+ *
+ * @since 1.2.0
+ */
+interface CronExpression {
+  /** Seconds field, when enabled via `seconds: true`. */
+  readonly second?: string;
+  /** Minutes field. */
+  readonly minute: string;
+  /** Hours field. */
+  readonly hour: string;
+  /** Day-of-month field. */
+  readonly dayOfMonth: string;
+  /** Month field. */
+  readonly month: string;
+  /** Day-of-week field. */
+  readonly dayOfWeek: string;
+  /** Year field, when enabled via `years: true`. */
+  readonly year?: string;
+}
+/**
+ * Options for creating a {@link cron} value parser.
+ *
+ * @since 1.2.0
+ */
+interface CronOptions {
+  /**
+   * The metavariable name for this parser.
+   * @default `"CRON"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Whether to require a leading seconds field.
+   * @default `false`
+   */
+  readonly seconds?: boolean;
+  /**
+   * Whether to require a trailing year field.
+   * @default `false`
+   */
+  readonly years?: boolean;
+  /**
+   * Whether to allow common Quartz day-field extensions such as `?`, `L`,
+   * `W`, and `#`.
+   * @default `false`
+   */
+  readonly quartz?: boolean;
+  /**
+   * Custom error messages for cron parsing failures.
+   *
+   * @since 1.2.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid cron expression.
+     * Can be a static message or a function that receives the raw input.
+     */
+    readonly invalidCron?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Cron expression result type for a specific {@link cron} option set.
+ *
+ * When `seconds: true` is configured, the `second` field is required in the
+ * parser result.  When `years: true` is configured, the `year` field is
+ * required in the parser result.
+ *
+ * @since 1.2.0
+ */
+type CronExpressionForOptions<O extends CronOptions> = Omit<CronExpression, "second" | "year"> & (O["seconds"] extends true ? {
+  readonly second: string;
+} : {
+  readonly second?: string;
+}) & (O["years"] extends true ? {
+  readonly year: string;
+} : {
+  readonly year?: string;
+});
+/**
+ * Creates a {@link ValueParser} for cron schedule expressions.
+ *
+ * By default, the parser accepts standard five-field cron expressions:
+ * minute, hour, day of month, month, and day of week.  Enable
+ * {@link CronOptions.seconds} to require a leading seconds field, and
+ * {@link CronOptions.years} to require a trailing year field.  Successful
+ * parses return a {@link CronExpression} object whose fields preserve the
+ * validated cron field expressions.
+ *
+ * The standard syntax supports `*`, numeric values, ranges (`1-5`), lists
+ * (`1,2,3`), intervals (for example every five units or `1-10/2`), and
+ * month/day names such as
+ * `JAN` and `MON`.  Enable {@link CronOptions.quartz} to allow common Quartz
+ * day-field tokens: `?`, `L`, `LW`, `nW`, `nL`, and `n#k`.
+ *
+ * @param options Configuration options.
+ * @returns A sync value parser producing {@link CronExpressionForOptions}
+ * objects for the configured options.
+ * @throws {TypeError} If `options.metavar` is an empty string.
+ * @throws {TypeError} If `seconds`, `years`, or `quartz` is not a boolean.
+ * @since 1.2.0
+ */
+declare function cron(): ValueParser<"sync", CronExpression>;
+declare function cron<const O extends CronOptions>(options: O): ValueParser<"sync", CronExpressionForOptions<O>>;
 /**
  * Options for the {@link firstOf} combinator.
  * @since 1.1.0
@@ -3058,4 +3166,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };

package/dist/valueparser.d.ts

@@ -2882,6 +2882,114 @@ declare function json(options: JsonOptions & {
  * @since 1.1.0
  */
 declare function json(options?: JsonOptions): ValueParser<"sync", Json>;
+/**
+ * A validated cron schedule expression split into cron fields.
+ *
+ * The `second` field is present when {@link cron} is configured with
+ * `seconds: true`, and the `year` field is present when it is configured
+ * with `years: true`.
+ *
+ * @since 1.2.0
+ */
+interface CronExpression {
+  /** Seconds field, when enabled via `seconds: true`. */
+  readonly second?: string;
+  /** Minutes field. */
+  readonly minute: string;
+  /** Hours field. */
+  readonly hour: string;
+  /** Day-of-month field. */
+  readonly dayOfMonth: string;
+  /** Month field. */
+  readonly month: string;
+  /** Day-of-week field. */
+  readonly dayOfWeek: string;
+  /** Year field, when enabled via `years: true`. */
+  readonly year?: string;
+}
+/**
+ * Options for creating a {@link cron} value parser.
+ *
+ * @since 1.2.0
+ */
+interface CronOptions {
+  /**
+   * The metavariable name for this parser.
+   * @default `"CRON"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Whether to require a leading seconds field.
+   * @default `false`
+   */
+  readonly seconds?: boolean;
+  /**
+   * Whether to require a trailing year field.
+   * @default `false`
+   */
+  readonly years?: boolean;
+  /**
+   * Whether to allow common Quartz day-field extensions such as `?`, `L`,
+   * `W`, and `#`.
+   * @default `false`
+   */
+  readonly quartz?: boolean;
+  /**
+   * Custom error messages for cron parsing failures.
+   *
+   * @since 1.2.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid cron expression.
+     * Can be a static message or a function that receives the raw input.
+     */
+    readonly invalidCron?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Cron expression result type for a specific {@link cron} option set.
+ *
+ * When `seconds: true` is configured, the `second` field is required in the
+ * parser result.  When `years: true` is configured, the `year` field is
+ * required in the parser result.
+ *
+ * @since 1.2.0
+ */
+type CronExpressionForOptions<O extends CronOptions> = Omit<CronExpression, "second" | "year"> & (O["seconds"] extends true ? {
+  readonly second: string;
+} : {
+  readonly second?: string;
+}) & (O["years"] extends true ? {
+  readonly year: string;
+} : {
+  readonly year?: string;
+});
+/**
+ * Creates a {@link ValueParser} for cron schedule expressions.
+ *
+ * By default, the parser accepts standard five-field cron expressions:
+ * minute, hour, day of month, month, and day of week.  Enable
+ * {@link CronOptions.seconds} to require a leading seconds field, and
+ * {@link CronOptions.years} to require a trailing year field.  Successful
+ * parses return a {@link CronExpression} object whose fields preserve the
+ * validated cron field expressions.
+ *
+ * The standard syntax supports `*`, numeric values, ranges (`1-5`), lists
+ * (`1,2,3`), intervals (for example every five units or `1-10/2`), and
+ * month/day names such as
+ * `JAN` and `MON`.  Enable {@link CronOptions.quartz} to allow common Quartz
+ * day-field tokens: `?`, `L`, `LW`, `nW`, `nL`, and `n#k`.
+ *
+ * @param options Configuration options.
+ * @returns A sync value parser producing {@link CronExpressionForOptions}
+ * objects for the configured options.
+ * @throws {TypeError} If `options.metavar` is an empty string.
+ * @throws {TypeError} If `seconds`, `years`, or `quartz` is not a boolean.
+ * @since 1.2.0
+ */
+declare function cron(): ValueParser<"sync", CronExpression>;
+declare function cron<const O extends CronOptions>(options: O): ValueParser<"sync", CronExpressionForOptions<O>>;
 /**
  * Options for the {@link firstOf} combinator.
  * @since 1.1.0
@@ -3058,4 +3166,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };

package/dist/valueparser.js

@@ -5844,6 +5844,218 @@ function findNonFiniteNumber(root) {
 	}
 	return void 0;
 }
+const CRON_MONTH_NAMES = new Map([
+	["JAN", 1],
+	["FEB", 2],
+	["MAR", 3],
+	["APR", 4],
+	["MAY", 5],
+	["JUN", 6],
+	["JUL", 7],
+	["AUG", 8],
+	["SEP", 9],
+	["OCT", 10],
+	["NOV", 11],
+	["DEC", 12]
+]);
+const CRON_DAY_NAMES = new Map([
+	["SUN", 0],
+	["MON", 1],
+	["TUE", 2],
+	["WED", 3],
+	["THU", 4],
+	["FRI", 5],
+	["SAT", 6]
+]);
+const CRON_FIELD_SPECS = {
+	second: {
+		kind: "second",
+		min: 0,
+		max: 59
+	},
+	minute: {
+		kind: "minute",
+		min: 0,
+		max: 59
+	},
+	hour: {
+		kind: "hour",
+		min: 0,
+		max: 23
+	},
+	dayOfMonth: {
+		kind: "dayOfMonth",
+		min: 1,
+		max: 31
+	},
+	month: {
+		kind: "month",
+		min: 1,
+		max: 12,
+		names: CRON_MONTH_NAMES
+	},
+	dayOfWeek: {
+		kind: "dayOfWeek",
+		min: 0,
+		max: 7,
+		names: CRON_DAY_NAMES
+	},
+	year: {
+		kind: "year",
+		min: 1970,
+		max: 2099
+	}
+};
+function cron(options = {}) {
+	const metavar$1 = options.metavar ?? "CRON";
+	ensureNonEmptyString(metavar$1);
+	checkBooleanOption(options, "seconds");
+	checkBooleanOption(options, "years");
+	checkBooleanOption(options, "quartz");
+	const seconds = options.seconds ?? false;
+	const years = options.years ?? false;
+	const quartz = options.quartz ?? false;
+	const invalidCronError = options.errors?.invalidCron;
+	const expectedFieldCount = 5 + (seconds ? 1 : 0) + (years ? 1 : 0);
+	function makeError(input) {
+		const error = invalidCronError instanceof Function ? invalidCronError(input) : invalidCronError ?? message`Expected a valid cron expression, but got ${input}.`;
+		return {
+			success: false,
+			error
+		};
+	}
+	function parseCron(input) {
+		const fields = input.trim() === "" ? [] : input.trim().split(/\s+/u);
+		if (fields.length !== expectedFieldCount) return makeError(input);
+		let index = 0;
+		const second = seconds ? fields[index++] : void 0;
+		const minute = fields[index++];
+		const hour = fields[index++];
+		const dayOfMonth = fields[index++];
+		const month = fields[index++];
+		const dayOfWeek = fields[index++];
+		const year = years ? fields[index++] : void 0;
+		const fieldChecks = [
+			[second, CRON_FIELD_SPECS.second],
+			[minute, CRON_FIELD_SPECS.minute],
+			[hour, CRON_FIELD_SPECS.hour],
+			[dayOfMonth, CRON_FIELD_SPECS.dayOfMonth],
+			[month, CRON_FIELD_SPECS.month],
+			[dayOfWeek, CRON_FIELD_SPECS.dayOfWeek],
+			[year, CRON_FIELD_SPECS.year]
+		];
+		for (const [field, spec] of fieldChecks) if (field !== void 0 && !isValidCronField(field, spec, { quartz })) return makeError(input);
+		if (quartz && dayOfMonth === "?" && dayOfWeek === "?") return makeError(input);
+		return {
+			success: true,
+			value: {
+				...second !== void 0 ? { second } : {},
+				minute,
+				hour,
+				dayOfMonth,
+				month,
+				dayOfWeek,
+				...year !== void 0 ? { year } : {}
+			}
+		};
+	}
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		placeholder: {
+			...seconds ? { second: "0" } : {},
+			minute: "0",
+			hour: "0",
+			dayOfMonth: "*",
+			month: "*",
+			dayOfWeek: "*",
+			...years ? { year: "1970" } : {}
+		},
+		parse: parseCron,
+		format(value) {
+			return [
+				...seconds ? [value.second ?? "0"] : [],
+				value.minute,
+				value.hour,
+				value.dayOfMonth,
+				value.month,
+				value.dayOfWeek,
+				...years ? [value.year ?? "1970"] : []
+			].join(" ");
+		},
+		validate(value) {
+			if (seconds && value.second == null || years && value.year == null) return makeError(this.format(value));
+			if (!seconds && value.second != null || !years && value.year != null) return makeError(this.format(value));
+			const result = parseCron(this.format(value));
+			return result.success ? {
+				success: true,
+				value: result.value
+			} : result;
+		}
+	};
+}
+function isValidCronField(field, spec, options) {
+	if (field === "") return false;
+	const parts = field.split(",");
+	const standard = !parts.some((part) => part === "") && parts.every((part) => isValidCronFieldPart(part, spec));
+	return standard || isQuartzCronField(field, spec, options.quartz);
+}
+function isQuartzCronField(field, spec, quartz) {
+	if (!quartz) return false;
+	const upper = field.toUpperCase();
+	if (upper === "?") return spec.kind === "dayOfMonth" || spec.kind === "dayOfWeek";
+	if (spec.kind === "dayOfMonth") {
+		if (upper === "L" || upper === "LW") return true;
+		const match = /^(?<day>\d{1,2})W$/u.exec(upper);
+		return match != null && isCronValueInRange(match.groups.day, spec);
+	}
+	if (spec.kind === "dayOfWeek") {
+		if (upper === "L") return true;
+		const lastMatch = /^(?<day>[A-Z]{3}|\d)L$/u.exec(upper);
+		if (lastMatch != null) return parseQuartzDayOfWeekSuffixValue(lastMatch.groups.day);
+		const nthMatch = /^(?<day>[A-Z]{3}|\d)#(?<nth>[1-5])$/u.exec(upper);
+		if (nthMatch != null) return parseQuartzDayOfWeekSuffixValue(nthMatch.groups.day);
+	}
+	return false;
+}
+function parseQuartzDayOfWeekSuffixValue(value) {
+	if (/^[1-7]$/u.test(value)) return true;
+	if (!/^[A-Z]{3}$/u.test(value)) return false;
+	return CRON_DAY_NAMES.has(value);
+}
+function isValidCronFieldPart(part, spec) {
+	const stepParts = part.split("/");
+	if (stepParts.length > 2) return false;
+	const [base, step] = stepParts;
+	if (base === "") return false;
+	if (step !== void 0 && !isPositiveCronStep(step)) return false;
+	if (base === "*") return true;
+	const rangeParts = base.split("-");
+	if (rangeParts.length === 1) return parseCronValue(base, spec) !== void 0;
+	if (rangeParts.length !== 2) return false;
+	const [rawStart, rawEnd] = rangeParts;
+	if (rawStart === "" || rawEnd === "") return false;
+	const start = parseCronValue(rawStart, spec);
+	const end = parseCronRangeEnd(rawStart, rawEnd, spec);
+	return start !== void 0 && end !== void 0 && start <= end;
+}
+function isPositiveCronStep(step) {
+	return /^\d+$/u.test(step) && Number.parseInt(step, 10) > 0;
+}
+function isCronValueInRange(value, spec) {
+	return parseCronValue(value, spec) !== void 0;
+}
+function parseCronRangeEnd(start, end, spec) {
+	if (spec.kind === "dayOfWeek" && start.toUpperCase() !== "SUN" && (end.toUpperCase() === "SUN" || end === "0")) return 7;
+	return parseCronValue(end, spec);
+}
+function parseCronValue(value, spec) {
+	const named = spec.names?.get(value.toUpperCase());
+	if (named !== void 0) return named;
+	if (!/^\d+$/u.test(value)) return void 0;
+	const number = Number.parseInt(value, 10);
+	return number >= spec.min && number <= spec.max ? number : void 0;
+}
 /**
 * Implementation of the {@link firstOf} combinator.
 */
@@ -6097,4 +6309,4 @@ function plainObjectsEqual(a, b) {
 }
 
 //#endregion
-export { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2187",
+  "version": "1.2.0-dev.2188",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -208,7 +208,7 @@
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.2.0-dev.2187+6112b083"
+    "@optique/env": "1.2.0-dev.2188+dd035768"
   },
   "scripts": {
     "build": "tsdown",