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

package/dist/valueparser.d.cts

@@ -747,6 +747,83 @@ declare function fileSize(options?: FileSizeOptionsNumber): ValueParser<"sync",
  * @since 1.1.0
  */
 declare function fileSize(options: FileSizeOptionsBigInt): ValueParser<"sync", bigint>;
+/**
+ * A structured CSS color value with normalized RGBA components.
+ * @since 1.1.0
+ */
+interface Color {
+  /** Red channel, 0–255. */
+  readonly r: number;
+  /** Green channel, 0–255. */
+  readonly g: number;
+  /** Blue channel, 0–255. */
+  readonly b: number;
+  /** Alpha channel, 0–1 (1 = fully opaque). */
+  readonly a: number;
+}
+/**
+ * The CSS color notation a {@link color} parser accepts.
+ * @since 1.1.0
+ */
+type ColorFormat = "hex" | "rgb" | "hsl" | "named";
+/**
+ * Options for creating a {@link color} value parser.
+ * @since 1.1.0
+ */
+interface ColorOptions {
+  /**
+   * The metavariable name for this parser.  Used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"COLOR"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Restricts which CSS color notations are accepted.  Defaults to all
+   * four notations: `"hex"`, `"rgb"`, `"hsl"`, and `"named"`.
+   * @default all formats
+   */
+  readonly formats?: readonly ColorFormat[];
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * @default `{ r: 0, g: 0, b: 0, a: 1 }`
+   * @since 1.1.0
+   */
+  readonly placeholder?: Color;
+  /**
+   * Custom error messages for color parsing failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid CSS color string.
+     * Can be a static message or a function that receives the raw input.
+     */
+    readonly invalidFormat?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a value parser that accepts CSS color strings and returns a
+ * structured {@link Color} object with normalized RGBA components.
+ *
+ * Supported input notations by default:
+ * - Hex: `#rgb`, `#rrggbb`, `#rgba`, `#rrggbbaa`
+ * - RGB: `rgb(r, g, b)`, `rgba(r, g, b, a)`
+ * - HSL: `hsl(h, s%, l%)`, `hsla(h, s%, l%, a)`
+ * - Named: all 148 CSS Level 4 named colors (e.g., `red`, `rebeccapurple`)
+ *
+ * The `format()` method always outputs canonical lowercase hex
+ * (`#rrggbb` when fully opaque, `#rrggbbaa` otherwise).
+ *
+ * @param options Configuration options for the parser.
+ * @returns A sync value parser producing {@link Color} objects.
+ * @throws {TypeError} If {@link ColorOptions.metavar} is an empty string, or
+ *   if {@link ColorOptions.formats} contains an invalid format name.
+ * @throws {RangeError} If {@link ValueParser.format} is called with a
+ *   {@link Color} whose `r`, `g`, or `b` channel is not an integer in
+ *   0–255, or whose `a` channel is not a finite number in 0–1.
+ * @since 1.1.0
+ */
+declare function color(options?: ColorOptions): ValueParser<"sync", Color>;
 /**
  * Options for creating a {@link url} parser.
  */
@@ -2328,5 +2405,159 @@ interface CidrOptions {
  * @since 0.10.0
  */
 declare function cidr(options?: CidrOptions): ValueParser<"sync", CidrValue>;
+/**
+ * A normalized Semantic Versioning 2.0.0 string.
+ *
+ * Covers all four valid forms:
+ *  - `MAJOR.MINOR.PATCH`
+ *  - `MAJOR.MINOR.PATCH-preRelease`
+ *  - `MAJOR.MINOR.PATCH+metadata`
+ *  - `MAJOR.MINOR.PATCH-preRelease+metadata`
+ *
+ * Note: this type uses TypeScript template literals as a coarse structural
+ * hint.  The `${number}` slots accept any JavaScript number serialization
+ * (including negative numbers, decimals, and `Infinity`), so the type alone
+ * does not guarantee full SemVer 2.0.0 validity.  Full validation is
+ * enforced at parse time by {@link semVer}.  Only values returned by
+ * `semVer().parse()` are guaranteed to conform to the specification.
+ *
+ * @since 1.1.0
+ */
+type SemVerString = `${number}.${number}.${number}` | `${number}.${number}.${number}-${string}` | `${number}.${number}.${number}+${string}` | `${number}.${number}.${number}-${string}+${string}`;
+/**
+ * A parsed Semantic Versioning 2.0.0 value as a structured object.
+ *
+ * @since 1.1.0
+ */
+interface SemVer {
+  /**
+   * The major version number.
+   *
+   * This field is a JavaScript `number`, so it is limited to
+   * {@link Number.MAX_SAFE_INTEGER} (2⁵³ − 1).  Inputs whose major
+   * component exceeds this value are rejected by {@link semVer} in object
+   * mode; use string mode to handle arbitrarily large version numbers.
+   */
+  readonly major: number;
+  /**
+   * The minor version number.
+   *
+   * Same safe-integer constraint as {@link major}.
+   */
+  readonly minor: number;
+  /**
+   * The patch version number.
+   *
+   * Same safe-integer constraint as {@link major}.
+   */
+  readonly patch: number;
+  /**
+   * The pre-release identifier (the part after `-`, before `+`), if present.
+   * Example: `"alpha.1"` for `1.0.0-alpha.1`.
+   */
+  readonly preRelease?: string;
+  /**
+   * The build metadata (the part after `+`), if present.
+   * Example: `"build.42"` for `1.0.0+build.42`.
+   */
+  readonly metadata?: string;
+}
+/** @internal */
+interface SemVerOptionsBase {
+  /**
+   * The metavariable name for this parser.  Used in help messages.
+   * @default `"SEMVER"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Whether to accept an optional leading `v` character (e.g. `v1.2.3`).
+   * The `v` prefix is stripped; output is always the canonical unprefixed form.
+   * @default false
+   */
+  readonly allowPrefix?: boolean;
+  /**
+   * Custom error messages for parse failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Message when input is not a valid SemVer string.
+     * Can be a static message or a function receiving the rejected input.
+     */
+    readonly invalidSemVer?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Options for {@link semVer} in string mode (the default).
+ *
+ * @since 1.1.0
+ */
+interface SemVerOptionsString extends SemVerOptionsBase {
+  /** Return a {@link SemVerString} template-literal type. */
+  readonly type?: "string";
+}
+/**
+ * Options for {@link semVer} in object mode.
+ *
+ * In object mode, version components are stored as JavaScript `number`
+ * values.  Components exceeding {@link Number.MAX_SAFE_INTEGER} (2⁵³ − 1)
+ * cannot be represented exactly and are therefore rejected with a parse
+ * error.  Use string mode (the default) if you need to handle version
+ * numbers of arbitrary magnitude.
+ *
+ * @since 1.1.0
+ */
+interface SemVerOptionsObject extends SemVerOptionsBase {
+  /** Return a structured {@link SemVer} object. */
+  readonly type: "object";
+}
+/**
+ * Creates a {@link ValueParser} for [Semantic Versioning 2.0.0] strings.
+ *
+ * In string mode (the default), the parser returns a {@link SemVerString}
+ * template-literal type.  String mode accepts any spec-valid SemVer input,
+ * including version components of arbitrary magnitude.
+ *
+ * In object mode (`type: "object"`), the parser returns a structured
+ * {@link SemVer} value with `major`, `minor`, `patch`, and optional
+ * `preRelease` and `metadata` fields.  Because the numeric components are
+ * stored as JavaScript `number`, object mode additionally rejects inputs
+ * whose major, minor, or patch value exceeds
+ * {@link Number.MAX_SAFE_INTEGER} (2⁵³ − 1).  Use string mode if you need
+ * to handle arbitrarily large version numbers.
+ *
+ * Both modes strictly enforce the SemVer 2.0.0 specification: no leading
+ * zeros in numeric components, no empty pre-release or build identifiers,
+ * and no invalid characters.
+ *
+ * [Semantic Versioning 2.0.0]: https://semver.org/
+ *
+ * @param options Configuration options.
+ * @returns A {@link ValueParser} that validates SemVer strings.
+ * @throws {TypeError} If {@link SemVerOptionsBase.metavar} is an empty string.
+ * @throws {TypeError} If {@link SemVerOptionsBase.allowPrefix} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link SemVerOptionsString.type} is not `"string"`,
+ *   `"object"`, or `undefined`.
+ * @since 1.1.0
+ */
+declare function semVer(options?: SemVerOptionsString): ValueParser<"sync", SemVerString>;
+/**
+ * Creates a {@link ValueParser} for [Semantic Versioning 2.0.0] strings,
+ * returning a structured {@link SemVer} object.
+ *
+ * [Semantic Versioning 2.0.0]: https://semver.org/
+ *
+ * @param options Configuration options with `type: "object"`.
+ * @returns A {@link ValueParser} that converts SemVer strings to {@link SemVer}
+ *   objects.
+ * @throws {TypeError} If {@link SemVerOptionsBase.metavar} is an empty string.
+ * @throws {TypeError} If {@link SemVerOptionsBase.allowPrefix} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link SemVerOptionsObject.type} is not `"string"`,
+ *   `"object"`, or `undefined`.
+ * @since 1.1.0
+ */
+declare function semVer(options: SemVerOptionsObject): ValueParser<"sync", SemVer>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };

package/dist/valueparser.d.ts

@@ -747,6 +747,83 @@ declare function fileSize(options?: FileSizeOptionsNumber): ValueParser<"sync",
  * @since 1.1.0
  */
 declare function fileSize(options: FileSizeOptionsBigInt): ValueParser<"sync", bigint>;
+/**
+ * A structured CSS color value with normalized RGBA components.
+ * @since 1.1.0
+ */
+interface Color {
+  /** Red channel, 0–255. */
+  readonly r: number;
+  /** Green channel, 0–255. */
+  readonly g: number;
+  /** Blue channel, 0–255. */
+  readonly b: number;
+  /** Alpha channel, 0–1 (1 = fully opaque). */
+  readonly a: number;
+}
+/**
+ * The CSS color notation a {@link color} parser accepts.
+ * @since 1.1.0
+ */
+type ColorFormat = "hex" | "rgb" | "hsl" | "named";
+/**
+ * Options for creating a {@link color} value parser.
+ * @since 1.1.0
+ */
+interface ColorOptions {
+  /**
+   * The metavariable name for this parser.  Used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"COLOR"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Restricts which CSS color notations are accepted.  Defaults to all
+   * four notations: `"hex"`, `"rgb"`, `"hsl"`, and `"named"`.
+   * @default all formats
+   */
+  readonly formats?: readonly ColorFormat[];
+  /**
+   * A custom placeholder value used during deferred prompt resolution.
+   * @default `{ r: 0, g: 0, b: 0, a: 1 }`
+   * @since 1.1.0
+   */
+  readonly placeholder?: Color;
+  /**
+   * Custom error messages for color parsing failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid CSS color string.
+     * Can be a static message or a function that receives the raw input.
+     */
+    readonly invalidFormat?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a value parser that accepts CSS color strings and returns a
+ * structured {@link Color} object with normalized RGBA components.
+ *
+ * Supported input notations by default:
+ * - Hex: `#rgb`, `#rrggbb`, `#rgba`, `#rrggbbaa`
+ * - RGB: `rgb(r, g, b)`, `rgba(r, g, b, a)`
+ * - HSL: `hsl(h, s%, l%)`, `hsla(h, s%, l%, a)`
+ * - Named: all 148 CSS Level 4 named colors (e.g., `red`, `rebeccapurple`)
+ *
+ * The `format()` method always outputs canonical lowercase hex
+ * (`#rrggbb` when fully opaque, `#rrggbbaa` otherwise).
+ *
+ * @param options Configuration options for the parser.
+ * @returns A sync value parser producing {@link Color} objects.
+ * @throws {TypeError} If {@link ColorOptions.metavar} is an empty string, or
+ *   if {@link ColorOptions.formats} contains an invalid format name.
+ * @throws {RangeError} If {@link ValueParser.format} is called with a
+ *   {@link Color} whose `r`, `g`, or `b` channel is not an integer in
+ *   0–255, or whose `a` channel is not a finite number in 0–1.
+ * @since 1.1.0
+ */
+declare function color(options?: ColorOptions): ValueParser<"sync", Color>;
 /**
  * Options for creating a {@link url} parser.
  */
@@ -2328,5 +2405,159 @@ interface CidrOptions {
  * @since 0.10.0
  */
 declare function cidr(options?: CidrOptions): ValueParser<"sync", CidrValue>;
+/**
+ * A normalized Semantic Versioning 2.0.0 string.
+ *
+ * Covers all four valid forms:
+ *  - `MAJOR.MINOR.PATCH`
+ *  - `MAJOR.MINOR.PATCH-preRelease`
+ *  - `MAJOR.MINOR.PATCH+metadata`
+ *  - `MAJOR.MINOR.PATCH-preRelease+metadata`
+ *
+ * Note: this type uses TypeScript template literals as a coarse structural
+ * hint.  The `${number}` slots accept any JavaScript number serialization
+ * (including negative numbers, decimals, and `Infinity`), so the type alone
+ * does not guarantee full SemVer 2.0.0 validity.  Full validation is
+ * enforced at parse time by {@link semVer}.  Only values returned by
+ * `semVer().parse()` are guaranteed to conform to the specification.
+ *
+ * @since 1.1.0
+ */
+type SemVerString = `${number}.${number}.${number}` | `${number}.${number}.${number}-${string}` | `${number}.${number}.${number}+${string}` | `${number}.${number}.${number}-${string}+${string}`;
+/**
+ * A parsed Semantic Versioning 2.0.0 value as a structured object.
+ *
+ * @since 1.1.0
+ */
+interface SemVer {
+  /**
+   * The major version number.
+   *
+   * This field is a JavaScript `number`, so it is limited to
+   * {@link Number.MAX_SAFE_INTEGER} (2⁵³ − 1).  Inputs whose major
+   * component exceeds this value are rejected by {@link semVer} in object
+   * mode; use string mode to handle arbitrarily large version numbers.
+   */
+  readonly major: number;
+  /**
+   * The minor version number.
+   *
+   * Same safe-integer constraint as {@link major}.
+   */
+  readonly minor: number;
+  /**
+   * The patch version number.
+   *
+   * Same safe-integer constraint as {@link major}.
+   */
+  readonly patch: number;
+  /**
+   * The pre-release identifier (the part after `-`, before `+`), if present.
+   * Example: `"alpha.1"` for `1.0.0-alpha.1`.
+   */
+  readonly preRelease?: string;
+  /**
+   * The build metadata (the part after `+`), if present.
+   * Example: `"build.42"` for `1.0.0+build.42`.
+   */
+  readonly metadata?: string;
+}
+/** @internal */
+interface SemVerOptionsBase {
+  /**
+   * The metavariable name for this parser.  Used in help messages.
+   * @default `"SEMVER"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Whether to accept an optional leading `v` character (e.g. `v1.2.3`).
+   * The `v` prefix is stripped; output is always the canonical unprefixed form.
+   * @default false
+   */
+  readonly allowPrefix?: boolean;
+  /**
+   * Custom error messages for parse failures.
+   * @since 1.1.0
+   */
+  readonly errors?: {
+    /**
+     * Message when input is not a valid SemVer string.
+     * Can be a static message or a function receiving the rejected input.
+     */
+    readonly invalidSemVer?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Options for {@link semVer} in string mode (the default).
+ *
+ * @since 1.1.0
+ */
+interface SemVerOptionsString extends SemVerOptionsBase {
+  /** Return a {@link SemVerString} template-literal type. */
+  readonly type?: "string";
+}
+/**
+ * Options for {@link semVer} in object mode.
+ *
+ * In object mode, version components are stored as JavaScript `number`
+ * values.  Components exceeding {@link Number.MAX_SAFE_INTEGER} (2⁵³ − 1)
+ * cannot be represented exactly and are therefore rejected with a parse
+ * error.  Use string mode (the default) if you need to handle version
+ * numbers of arbitrary magnitude.
+ *
+ * @since 1.1.0
+ */
+interface SemVerOptionsObject extends SemVerOptionsBase {
+  /** Return a structured {@link SemVer} object. */
+  readonly type: "object";
+}
+/**
+ * Creates a {@link ValueParser} for [Semantic Versioning 2.0.0] strings.
+ *
+ * In string mode (the default), the parser returns a {@link SemVerString}
+ * template-literal type.  String mode accepts any spec-valid SemVer input,
+ * including version components of arbitrary magnitude.
+ *
+ * In object mode (`type: "object"`), the parser returns a structured
+ * {@link SemVer} value with `major`, `minor`, `patch`, and optional
+ * `preRelease` and `metadata` fields.  Because the numeric components are
+ * stored as JavaScript `number`, object mode additionally rejects inputs
+ * whose major, minor, or patch value exceeds
+ * {@link Number.MAX_SAFE_INTEGER} (2⁵³ − 1).  Use string mode if you need
+ * to handle arbitrarily large version numbers.
+ *
+ * Both modes strictly enforce the SemVer 2.0.0 specification: no leading
+ * zeros in numeric components, no empty pre-release or build identifiers,
+ * and no invalid characters.
+ *
+ * [Semantic Versioning 2.0.0]: https://semver.org/
+ *
+ * @param options Configuration options.
+ * @returns A {@link ValueParser} that validates SemVer strings.
+ * @throws {TypeError} If {@link SemVerOptionsBase.metavar} is an empty string.
+ * @throws {TypeError} If {@link SemVerOptionsBase.allowPrefix} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link SemVerOptionsString.type} is not `"string"`,
+ *   `"object"`, or `undefined`.
+ * @since 1.1.0
+ */
+declare function semVer(options?: SemVerOptionsString): ValueParser<"sync", SemVerString>;
+/**
+ * Creates a {@link ValueParser} for [Semantic Versioning 2.0.0] strings,
+ * returning a structured {@link SemVer} object.
+ *
+ * [Semantic Versioning 2.0.0]: https://semver.org/
+ *
+ * @param options Configuration options with `type: "object"`.
+ * @returns A {@link ValueParser} that converts SemVer strings to {@link SemVer}
+ *   objects.
+ * @throws {TypeError} If {@link SemVerOptionsBase.metavar} is an empty string.
+ * @throws {TypeError} If {@link SemVerOptionsBase.allowPrefix} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link SemVerOptionsObject.type} is not `"string"`,
+ *   `"object"`, or `undefined`.
+ * @since 1.1.0
+ */
+declare function semVer(options: SemVerOptionsObject): ValueParser<"sync", SemVer>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };