@optique/core 1.1.0-dev.2054 → 1.1.0-dev.2065

package/dist/valueparser.d.cts

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

package/dist/valueparser.d.ts

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