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

package/dist/primitives.d.cts

@@ -2,6 +2,7 @@ import { Message } from "./message.cjs";
 import { HiddenVisibility, OptionName, Usage } from "./usage.cjs";
 import { ValueParser, ValueParserResult } from "./valueparser.cjs";
 import { Mode, Parser } from "./internal/parser.cjs";
+import { FluentParser } from "./modifiers.cjs";
 
 //#region src/primitives.d.ts
 /** @internal */
@@ -11,7 +12,7 @@ type OptionState<T> = ValueParserResult<T> | undefined;
  * produces a constant value of the type {@link T}.
  * @template T The type of the constant value produced by the parser.
  */
-declare function constant<const T>(value: T): Parser<"sync", T, T>;
+declare function constant<const T>(value: T): FluentParser<"sync", T, T>;
 /**
  * Creates a parser that always fails without consuming any input.
  *
@@ -31,7 +32,7 @@ declare function constant<const T>(value: T): Parser<"sync", T, T>;
  *          complete time.
  * @since 1.0.0
  */
-declare function fail<T>(): Parser<"sync", T, undefined>;
+declare function fail<T>(): FluentParser<"sync", T, undefined>;
 /**
  * Options for the {@link option} parser.
  */
@@ -113,7 +114,7 @@ interface OptionErrorOptions {
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>]): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>]): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
@@ -127,7 +128,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>, OptionOptions]): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>, OptionOptions]): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that do not
  * take an argument value, such as `--option`, `-o`, or `/option`.
@@ -135,7 +136,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
  * @return A {@link Parser} that can parse the specified options as Boolean
  *         flags, producing `true` if the option is present.
  */
-declare function option(...optionNames: readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
+declare function option(...optionNames: readonly [OptionName, ...readonly OptionName[]]): FluentParser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
@@ -146,7 +147,7 @@ declare function option(...optionNames: readonly [OptionName, ...readonly Option
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option(...args: readonly [OptionName, ...readonly OptionName[], OptionOptions]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
+declare function option(...args: readonly [OptionName, ...readonly OptionName[], OptionOptions]): FluentParser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Options for the {@link flag} parser.
  */
@@ -236,7 +237,7 @@ interface FlagErrorOptions {
  * });
  * ```
  */
-declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", true, ValueParserResult<true> | undefined>;
+declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): FluentParser<"sync", true, ValueParserResult<true> | undefined>;
 /**
  * A non-empty list of option names, or a single option name.
  * @since 1.1.0
@@ -340,7 +341,7 @@ interface NegatableFlagState {
  *         side, or shared by the positive and negative sides.
  * @since 1.1.0
  */
-declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): Parser<"sync", boolean, NegatableFlagState | undefined>;
+declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): FluentParser<"sync", boolean, NegatableFlagState | undefined>;
 /**
  * Options for the {@link argument} parser.
  */
@@ -399,7 +400,7 @@ interface ArgumentErrorOptions {
  * @returns A {@link Parser} that expects a single argument value and produces
  *          the parsed value of type {@link T}.
  */
-declare function argument<M extends Mode, T>(valueParser: ValueParser<M, T>, options?: ArgumentOptions): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function argument<M extends Mode, T>(valueParser: ValueParser<M, T>, options?: ArgumentOptions): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Options for the {@link command} parser.
  * @since 0.5.0
@@ -507,7 +508,7 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  * @throws {TypeError} If `name` is empty, whitespace-only, contains
  *         embedded whitespace, or contains control characters.
  */
-declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): Parser<M, T, CommandState<TState>>;
+declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): FluentParser<M, T, CommandState<TState>>;
 /**
  * Format options for how {@link passThrough} captures options.
  * @since 0.8.0
@@ -595,6 +596,6 @@ interface PassThroughOptions {
  *
  * @since 0.8.0
  */
-declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
+declare function passThrough(options?: PassThroughOptions): FluentParser<"sync", readonly string[], readonly string[]>;
 //#endregion
 export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough };

package/dist/primitives.d.ts

@@ -2,6 +2,7 @@ import { Message } from "./message.js";
 import { HiddenVisibility, OptionName, Usage } from "./usage.js";
 import { ValueParser, ValueParserResult } from "./valueparser.js";
 import { Mode, Parser } from "./internal/parser.js";
+import { FluentParser } from "./modifiers.js";
 
 //#region src/primitives.d.ts
 /** @internal */
@@ -11,7 +12,7 @@ type OptionState<T> = ValueParserResult<T> | undefined;
  * produces a constant value of the type {@link T}.
  * @template T The type of the constant value produced by the parser.
  */
-declare function constant<const T>(value: T): Parser<"sync", T, T>;
+declare function constant<const T>(value: T): FluentParser<"sync", T, T>;
 /**
  * Creates a parser that always fails without consuming any input.
  *
@@ -31,7 +32,7 @@ declare function constant<const T>(value: T): Parser<"sync", T, T>;
  *          complete time.
  * @since 1.0.0
  */
-declare function fail<T>(): Parser<"sync", T, undefined>;
+declare function fail<T>(): FluentParser<"sync", T, undefined>;
 /**
  * Options for the {@link option} parser.
  */
@@ -113,7 +114,7 @@ interface OptionErrorOptions {
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>]): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>]): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
@@ -127,7 +128,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>, OptionOptions]): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>, OptionOptions]): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that do not
  * take an argument value, such as `--option`, `-o`, or `/option`.
@@ -135,7 +136,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
  * @return A {@link Parser} that can parse the specified options as Boolean
  *         flags, producing `true` if the option is present.
  */
-declare function option(...optionNames: readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
+declare function option(...optionNames: readonly [OptionName, ...readonly OptionName[]]): FluentParser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
@@ -146,7 +147,7 @@ declare function option(...optionNames: readonly [OptionName, ...readonly Option
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option(...args: readonly [OptionName, ...readonly OptionName[], OptionOptions]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
+declare function option(...args: readonly [OptionName, ...readonly OptionName[], OptionOptions]): FluentParser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Options for the {@link flag} parser.
  */
@@ -236,7 +237,7 @@ interface FlagErrorOptions {
  * });
  * ```
  */
-declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", true, ValueParserResult<true> | undefined>;
+declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): FluentParser<"sync", true, ValueParserResult<true> | undefined>;
 /**
  * A non-empty list of option names, or a single option name.
  * @since 1.1.0
@@ -340,7 +341,7 @@ interface NegatableFlagState {
  *         side, or shared by the positive and negative sides.
  * @since 1.1.0
  */
-declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): Parser<"sync", boolean, NegatableFlagState | undefined>;
+declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): FluentParser<"sync", boolean, NegatableFlagState | undefined>;
 /**
  * Options for the {@link argument} parser.
  */
@@ -399,7 +400,7 @@ interface ArgumentErrorOptions {
  * @returns A {@link Parser} that expects a single argument value and produces
  *          the parsed value of type {@link T}.
  */
-declare function argument<M extends Mode, T>(valueParser: ValueParser<M, T>, options?: ArgumentOptions): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function argument<M extends Mode, T>(valueParser: ValueParser<M, T>, options?: ArgumentOptions): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Options for the {@link command} parser.
  * @since 0.5.0
@@ -507,7 +508,7 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  * @throws {TypeError} If `name` is empty, whitespace-only, contains
  *         embedded whitespace, or contains control characters.
  */
-declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): Parser<M, T, CommandState<TState>>;
+declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): FluentParser<M, T, CommandState<TState>>;
 /**
  * Format options for how {@link passThrough} captures options.
  * @since 0.8.0
@@ -595,6 +596,6 @@ interface PassThroughOptions {
  *
  * @since 0.8.0
  */
-declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
+declare function passThrough(options?: PassThroughOptions): FluentParser<"sync", readonly string[], readonly string[]>;
 //#endregion
 export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough };

package/dist/primitives.js

@@ -9,9 +9,10 @@ import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedIni
 import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
+import { extractDependencyMetadata } from "./dependency-metadata.js";
+import { fluent } from "./modifiers.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, expandCommandAliasSuggestions, findSimilar } from "./suggestion.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
-import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { isValueParser } from "./valueparser.js";
 
 //#region src/primitives.ts
@@ -150,7 +151,7 @@ function constant(value) {
 		enumerable: false,
 		writable: false
 	});
-	return result;
+	return fluent(result);
 }
 /**
 * Creates a parser that always fails without consuming any input.
@@ -172,7 +173,7 @@ function constant(value) {
 * @since 1.0.0
 */
 function fail() {
-	return {
+	return fluent({
 		$valueType: [],
 		$stateType: [],
 		mode: "sync",
@@ -203,7 +204,7 @@ function fail() {
 		getDocFragments(_state, _defaultValue) {
 			return { fragments: [] };
 		}
-	};
+	});
 }
 /**
 * Internal helper to get suggestions from a value parser, using dependency values
@@ -741,7 +742,7 @@ function option(...args) {
 		configurable: true,
 		enumerable: false
 	});
-	return result;
+	return fluent(result);
 }
 /**
 * Creates a parser for command-line flags that must be explicitly provided.
@@ -944,7 +945,7 @@ function flag(...args) {
 		enumerable: false,
 		writable: false
 	});
-	return result;
+	return fluent(result);
 }
 function normalizeNegatableFlagNameList(names) {
 	return typeof names === "string" ? [names] : names;
@@ -1162,7 +1163,7 @@ function negatableFlag(names, options = {}) {
 		enumerable: false,
 		writable: false
 	});
-	return result;
+	return fluent(result);
 }
 /**
 * Creates a parser that expects a single argument value.
@@ -1371,7 +1372,7 @@ function argument(valueParser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	return result;
+	return fluent(result);
 }
 function normalizeCommandState(state) {
 	return normalizeInjectedAnnotationState(state);
@@ -1700,7 +1701,7 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	return result;
+	return fluent(result);
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.
@@ -1752,7 +1753,7 @@ function passThrough(options = {}) {
 	const format = options.format ?? "equalsOnly";
 	const optionPattern = /^-[a-z0-9-]|^--[a-z0-9-]+/i;
 	const equalsOptionPattern = /^--[a-z0-9-]+=/i;
-	return {
+	const result = {
 		$valueType: [],
 		$stateType: [],
 		mode: "sync",
@@ -1884,6 +1885,7 @@ function passThrough(options = {}) {
 			return `passThrough(${format})`;
 		}
 	};
+	return fluent(result);
 }
 
 //#endregion

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 };