@optique/core 0.5.0-dev.79 → 0.5.0-dev.80

package/dist/valueparser.cjs

@@ -30,7 +30,7 @@ function choice(values, options = {}) {
 			const index = normalizedValues.indexOf(normalizedInput);
 			if (index < 0) return {
 				success: false,
-				error: require_message.message`Expected one of ${values.join(", ")}, but got ${input}.`
+				error: options.errors?.invalidChoice ? typeof options.errors.invalidChoice === "function" ? options.errors.invalidChoice(input, values) : options.errors.invalidChoice : require_message.message`Expected one of ${values.join(", ")}, but got ${input}.`
 			};
 			return {
 				success: true,
@@ -57,7 +57,7 @@ function string(options = {}) {
 		parse(input) {
 			if (options.pattern != null && !options.pattern.test(input)) return {
 				success: false,
-				error: require_message.message`Expected a string matching pattern ${require_message.text(options.pattern.source)}, but got ${input}.`
+				error: options.errors?.patternMismatch ? typeof options.errors.patternMismatch === "function" ? options.errors.patternMismatch(input, options.pattern) : options.errors.patternMismatch : require_message.message`Expected a string matching pattern ${require_message.text(options.pattern.source)}, but got ${input}.`
 			};
 			return {
 				success: true,
@@ -112,17 +112,17 @@ function integer(options) {
 			} catch (e) {
 				if (e instanceof SyntaxError) return {
 					success: false,
-					error: require_message.message`Expected a valid integer, but got ${input}.`
+					error: options.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : require_message.message`Expected a valid integer, but got ${input}.`
 				};
 				throw e;
 			}
 			if (options.min != null && value < options.min) return {
 				success: false,
-				error: require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
+				error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, options.min) : options.errors.belowMinimum : require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
 			};
 			else if (options.max != null && value > options.max) return {
 				success: false,
-				error: require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
+				error: options.errors?.aboveMaximum ? typeof options.errors.aboveMaximum === "function" ? options.errors.aboveMaximum(value, options.max) : options.errors.aboveMaximum : require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
 			};
 			return {
 				success: true,
@@ -138,16 +138,16 @@ function integer(options) {
 		parse(input) {
 			if (!input.match(/^\d+$/)) return {
 				success: false,
-				error: require_message.message`Expected a valid integer, but got ${input}.`
+				error: options?.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : require_message.message`Expected a valid integer, but got ${input}.`
 			};
 			const value = Number.parseInt(input);
 			if (options?.min != null && value < options.min) return {
 				success: false,
-				error: require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
+				error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, options.min) : options.errors.belowMinimum : require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
 			};
 			else if (options?.max != null && value > options.max) return {
 				success: false,
-				error: require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
+				error: options.errors?.aboveMaximum ? typeof options.errors.aboveMaximum === "function" ? options.errors.aboveMaximum(value, options.max) : options.errors.aboveMaximum : require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
 			};
 			return {
 				success: true,
@@ -182,19 +182,19 @@ function float(options = {}) {
 				value = Number(input);
 				if (Number.isNaN(value)) return {
 					success: false,
-					error: require_message.message`Expected a valid number, but got ${input}.`
+					error: options.errors?.invalidNumber ? typeof options.errors.invalidNumber === "function" ? options.errors.invalidNumber(input) : options.errors.invalidNumber : require_message.message`Expected a valid number, but got ${input}.`
 				};
 			} else return {
 				success: false,
-				error: require_message.message`Expected a valid number, but got ${input}.`
+				error: options.errors?.invalidNumber ? typeof options.errors.invalidNumber === "function" ? options.errors.invalidNumber(input) : options.errors.invalidNumber : require_message.message`Expected a valid number, but got ${input}.`
 			};
 			if (options.min != null && value < options.min) return {
 				success: false,
-				error: require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
+				error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, options.min) : options.errors.belowMinimum : require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
 			};
 			else if (options.max != null && value > options.max) return {
 				success: false,
-				error: require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
+				error: options.errors?.aboveMaximum ? typeof options.errors.aboveMaximum === "function" ? options.errors.aboveMaximum(value, options.max) : options.errors.aboveMaximum : require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
 			};
 			return {
 				success: true,
@@ -222,12 +222,12 @@ function url(options = {}) {
 		parse(input) {
 			if (!URL.canParse(input)) return {
 				success: false,
-				error: require_message.message`Invalid URL: ${input}.`
+				error: options.errors?.invalidUrl ? typeof options.errors.invalidUrl === "function" ? options.errors.invalidUrl(input) : options.errors.invalidUrl : require_message.message`Invalid URL: ${input}.`
 			};
 			const url$1 = new URL(input);
 			if (allowedProtocols != null && !allowedProtocols.includes(url$1.protocol)) return {
 				success: false,
-				error: require_message.message`URL protocol ${url$1.protocol} is not allowed. Allowed protocols: ${allowedProtocols.join(", ")}.`
+				error: options.errors?.disallowedProtocol ? typeof options.errors.disallowedProtocol === "function" ? options.errors.disallowedProtocol(url$1.protocol, options.allowedProtocols) : options.errors.disallowedProtocol : require_message.message`URL protocol ${url$1.protocol} is not allowed. Allowed protocols: ${allowedProtocols.join(", ")}.`
 			};
 			return {
 				success: true,
@@ -259,7 +259,7 @@ function locale(options = {}) {
 			} catch (e) {
 				if (e instanceof RangeError) return {
 					success: false,
-					error: require_message.message`Invalid locale: ${input}.`
+					error: options.errors?.invalidLocale ? typeof options.errors.invalidLocale === "function" ? options.errors.invalidLocale(input) : options.errors.invalidLocale : require_message.message`Invalid locale: ${input}.`
 				};
 				throw e;
 			}
@@ -292,23 +292,23 @@ function uuid(options = {}) {
 		parse(input) {
 			if (!uuidRegex.test(input)) return {
 				success: false,
-				error: require_message.message`Expected a valid UUID in format ${"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}, but got ${input}.`
+				error: options.errors?.invalidUuid ? typeof options.errors.invalidUuid === "function" ? options.errors.invalidUuid(input) : options.errors.invalidUuid : require_message.message`Expected a valid UUID in format ${"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}, but got ${input}.`
 			};
 			if (options.allowedVersions != null && options.allowedVersions.length > 0) {
 				const versionChar = input.charAt(14);
 				const version = parseInt(versionChar, 16);
-				if (!options.allowedVersions.includes(version)) {
-					let expectedVersions = require_message.message``;
-					let i = 0;
-					for (const v of options.allowedVersions) {
-						expectedVersions = i < 1 ? require_message.message`${expectedVersions}${v.toLocaleString("en")}` : i + 1 >= options.allowedVersions.length ? require_message.message`${expectedVersions}, or ${v.toLocaleString("en")}` : require_message.message`${expectedVersions}, ${v.toLocaleString("en")}`;
-						i++;
-					}
-					return {
-						success: false,
-						error: require_message.message`Expected UUID version ${expectedVersions}, but got version ${version.toLocaleString("en")}.`
-					};
-				}
+				if (!options.allowedVersions.includes(version)) return {
+					success: false,
+					error: options.errors?.disallowedVersion ? typeof options.errors.disallowedVersion === "function" ? options.errors.disallowedVersion(version, options.allowedVersions) : options.errors.disallowedVersion : (() => {
+						let expectedVersions = require_message.message``;
+						let i = 0;
+						for (const v of options.allowedVersions) {
+							expectedVersions = i < 1 ? require_message.message`${expectedVersions}${v.toLocaleString("en")}` : i + 1 >= options.allowedVersions.length ? require_message.message`${expectedVersions}, or ${v.toLocaleString("en")}` : require_message.message`${expectedVersions}, ${v.toLocaleString("en")}`;
+							i++;
+						}
+						return require_message.message`Expected UUID version ${expectedVersions}, but got version ${version.toLocaleString("en")}.`;
+					})()
+				};
 			}
 			return {
 				success: true,

package/dist/valueparser.d.cts

@@ -70,6 +70,18 @@ interface StringOptions {
    * Optional regular expression pattern that the string must match.
    */
   readonly pattern?: RegExp;
+  /**
+   * Custom error messages for various string parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input doesn't match the pattern.
+     * Can be a static message or a function that receives the input and pattern.
+     * @since 0.5.0
+     */
+    patternMismatch?: Message | ((input: string, pattern: RegExp) => Message);
+  };
 }
 /**
  * Options for creating a {@link choice} parser.
@@ -90,6 +102,18 @@ interface ChoiceOptions {
    * @default `false`
    */
   readonly caseInsensitive?: boolean;
+  /**
+   * Custom error messages for choice parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input doesn't match any of the valid choices.
+     * Can be a static message or a function that receives the input and valid choices.
+     * @since 0.5.0
+     */
+    invalidChoice?: Message | ((input: string, choices: readonly string[]) => Message);
+  };
 }
 /**
  * A predicate function that checks if an object is a {@link ValueParser}.
@@ -149,6 +173,30 @@ interface IntegerOptionsNumber {
    * no maximum is enforced.
    */
   readonly max?: number;
+  /**
+   * Custom error messages for integer parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid integer.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidInteger?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when integer is below minimum value.
+     * Can be a static message or a function that receives the value and minimum.
+     * @since 0.5.0
+     */
+    belowMinimum?: Message | ((value: number, min: number) => Message);
+    /**
+     * Custom error message when integer is above maximum value.
+     * Can be a static message or a function that receives the value and maximum.
+     * @since 0.5.0
+     */
+    aboveMaximum?: Message | ((value: number, max: number) => Message);
+  };
 }
 /**
  * Options for creating an integer parser that returns a `bigint`.
@@ -176,6 +224,30 @@ interface IntegerOptionsBigInt {
    * no maximum is enforced.
    */
   readonly max?: bigint;
+  /**
+   * Custom error messages for bigint integer parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid integer.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidInteger?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when integer is below minimum value.
+     * Can be a static message or a function that receives the value and minimum.
+     * @since 0.5.0
+     */
+    belowMinimum?: Message | ((value: bigint, min: bigint) => Message);
+    /**
+     * Custom error message when integer is above maximum value.
+     * Can be a static message or a function that receives the value and maximum.
+     * @since 0.5.0
+     */
+    aboveMaximum?: Message | ((value: bigint, max: bigint) => Message);
+  };
 }
 /**
  * Creates a ValueParser for integers that returns JavaScript numbers.
@@ -226,6 +298,30 @@ interface FloatOptions {
    * @default `false`
    */
   readonly allowInfinity?: boolean;
+  /**
+   * Custom error messages for float parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid number.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidNumber?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when number is below minimum value.
+     * Can be a static message or a function that receives the value and minimum.
+     * @since 0.5.0
+     */
+    belowMinimum?: Message | ((value: number, min: number) => Message);
+    /**
+     * Custom error message when number is above maximum value.
+     * Can be a static message or a function that receives the value and maximum.
+     * @since 0.5.0
+     */
+    aboveMaximum?: Message | ((value: number, max: number) => Message);
+  };
 }
 /**
  * Creates a {@link ValueParser} for floating-point numbers.
@@ -255,6 +351,24 @@ interface UrlOptions {
    * If not specified, any protocol is allowed.
    */
   readonly allowedProtocols?: readonly string[];
+  /**
+   * Custom error messages for URL parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid URL.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidUrl?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when URL protocol is not allowed.
+     * Can be a static message or a function that receives the protocol and allowed protocols.
+     * @since 0.5.0
+     */
+    disallowedProtocol?: Message | ((protocol: string, allowedProtocols: readonly string[]) => Message);
+  };
 }
 /**
  * Creates a {@link ValueParser} for URL values.
@@ -277,6 +391,18 @@ interface LocaleOptions {
    * @default `"LOCALE"`
    */
   readonly metavar?: string;
+  /**
+   * Custom error messages for locale parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid locale identifier.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidLocale?: Message | ((input: string) => Message);
+  };
 }
 /**
  * Creates a {@link ValueParser} for locale values.
@@ -314,6 +440,24 @@ interface UuidOptions {
    * allowed versions. If not specified, any valid UUID format is accepted.
    */
   readonly allowedVersions?: readonly number[];
+  /**
+   * Custom error messages for UUID parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid UUID format.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidUuid?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when UUID version is not allowed.
+     * Can be a static message or a function that receives the version and allowed versions.
+     * @since 0.5.0
+     */
+    disallowedVersion?: Message | ((version: number, allowedVersions: readonly number[]) => Message);
+  };
 }
 /**
  * Creates a {@link ValueParser} for UUID values.

package/dist/valueparser.d.ts

@@ -70,6 +70,18 @@ interface StringOptions {
    * Optional regular expression pattern that the string must match.
    */
   readonly pattern?: RegExp;
+  /**
+   * Custom error messages for various string parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input doesn't match the pattern.
+     * Can be a static message or a function that receives the input and pattern.
+     * @since 0.5.0
+     */
+    patternMismatch?: Message | ((input: string, pattern: RegExp) => Message);
+  };
 }
 /**
  * Options for creating a {@link choice} parser.
@@ -90,6 +102,18 @@ interface ChoiceOptions {
    * @default `false`
    */
   readonly caseInsensitive?: boolean;
+  /**
+   * Custom error messages for choice parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input doesn't match any of the valid choices.
+     * Can be a static message or a function that receives the input and valid choices.
+     * @since 0.5.0
+     */
+    invalidChoice?: Message | ((input: string, choices: readonly string[]) => Message);
+  };
 }
 /**
  * A predicate function that checks if an object is a {@link ValueParser}.
@@ -149,6 +173,30 @@ interface IntegerOptionsNumber {
    * no maximum is enforced.
    */
   readonly max?: number;
+  /**
+   * Custom error messages for integer parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid integer.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidInteger?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when integer is below minimum value.
+     * Can be a static message or a function that receives the value and minimum.
+     * @since 0.5.0
+     */
+    belowMinimum?: Message | ((value: number, min: number) => Message);
+    /**
+     * Custom error message when integer is above maximum value.
+     * Can be a static message or a function that receives the value and maximum.
+     * @since 0.5.0
+     */
+    aboveMaximum?: Message | ((value: number, max: number) => Message);
+  };
 }
 /**
  * Options for creating an integer parser that returns a `bigint`.
@@ -176,6 +224,30 @@ interface IntegerOptionsBigInt {
    * no maximum is enforced.
    */
   readonly max?: bigint;
+  /**
+   * Custom error messages for bigint integer parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid integer.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidInteger?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when integer is below minimum value.
+     * Can be a static message or a function that receives the value and minimum.
+     * @since 0.5.0
+     */
+    belowMinimum?: Message | ((value: bigint, min: bigint) => Message);
+    /**
+     * Custom error message when integer is above maximum value.
+     * Can be a static message or a function that receives the value and maximum.
+     * @since 0.5.0
+     */
+    aboveMaximum?: Message | ((value: bigint, max: bigint) => Message);
+  };
 }
 /**
  * Creates a ValueParser for integers that returns JavaScript numbers.
@@ -226,6 +298,30 @@ interface FloatOptions {
    * @default `false`
    */
   readonly allowInfinity?: boolean;
+  /**
+   * Custom error messages for float parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid number.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidNumber?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when number is below minimum value.
+     * Can be a static message or a function that receives the value and minimum.
+     * @since 0.5.0
+     */
+    belowMinimum?: Message | ((value: number, min: number) => Message);
+    /**
+     * Custom error message when number is above maximum value.
+     * Can be a static message or a function that receives the value and maximum.
+     * @since 0.5.0
+     */
+    aboveMaximum?: Message | ((value: number, max: number) => Message);
+  };
 }
 /**
  * Creates a {@link ValueParser} for floating-point numbers.
@@ -255,6 +351,24 @@ interface UrlOptions {
    * If not specified, any protocol is allowed.
    */
   readonly allowedProtocols?: readonly string[];
+  /**
+   * Custom error messages for URL parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid URL.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidUrl?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when URL protocol is not allowed.
+     * Can be a static message or a function that receives the protocol and allowed protocols.
+     * @since 0.5.0
+     */
+    disallowedProtocol?: Message | ((protocol: string, allowedProtocols: readonly string[]) => Message);
+  };
 }
 /**
  * Creates a {@link ValueParser} for URL values.
@@ -277,6 +391,18 @@ interface LocaleOptions {
    * @default `"LOCALE"`
    */
   readonly metavar?: string;
+  /**
+   * Custom error messages for locale parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid locale identifier.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidLocale?: Message | ((input: string) => Message);
+  };
 }
 /**
  * Creates a {@link ValueParser} for locale values.
@@ -314,6 +440,24 @@ interface UuidOptions {
    * allowed versions. If not specified, any valid UUID format is accepted.
    */
   readonly allowedVersions?: readonly number[];
+  /**
+   * Custom error messages for UUID parsing failures.
+   * @since 0.5.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid UUID format.
+     * Can be a static message or a function that receives the input.
+     * @since 0.5.0
+     */
+    invalidUuid?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when UUID version is not allowed.
+     * Can be a static message or a function that receives the version and allowed versions.
+     * @since 0.5.0
+     */
+    disallowedVersion?: Message | ((version: number, allowedVersions: readonly number[]) => Message);
+  };
 }
 /**
  * Creates a {@link ValueParser} for UUID values.