@optique/core 0.10.7 → 1.0.0-dev.1116

package/dist/valueparser.d.cts

@@ -206,6 +206,13 @@ declare function isValueParser<M extends Mode, T>(object: unknown): object is Va
  * @param options Configuration options for the choice parser.
  * @returns A {@link ValueParser} that checks if the input matches one of the
  *          specified values.
+ * @throws {TypeError} If the choices array is empty.
+ * @throws {TypeError} If any choice is an empty string.
+ * @throws {TypeError} If any choice is not a string.
+ * @throws {TypeError} If choices contain a mix of strings and numbers.
+ * @throws {TypeError} If `caseInsensitive` is not a boolean.
+ * @throws {TypeError} If `caseInsensitive` is `true` and multiple choices
+ *         normalize to the same lowercase value.
  */
 declare function choice<const T extends string>(choices: readonly T[], options?: ChoiceOptionsString): ValueParser<"sync", T>;
 /**
@@ -219,6 +226,10 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  * @param options Configuration options for the choice parser.
  * @returns A {@link ValueParser} that checks if the input matches one of the
  *          specified values.
+ * @throws {TypeError} If the choices array is empty.
+ * @throws {TypeError} If any choice is not a number.
+ * @throws {TypeError} If any choice is `NaN`.
+ * @throws {TypeError} If choices contain a mix of strings and numbers.
  * @since 0.9.0
  */
 declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<"sync", T>;
@@ -235,6 +246,8 @@ declare function choice<const T extends number>(choices: readonly T[], options?:
  * @param options Configuration options for the string parser.
  * @returns A {@link ValueParser} that parses strings according to the
  *          specified options.
+ * @throws {TypeError} If `options.pattern` is provided but is not a
+ *         `RegExp` instance.
  */
 declare function string(options?: StringOptions): ValueParser<"sync", string>;
 /**
@@ -277,6 +290,13 @@ interface IntegerOptionsNumber {
      * @since 0.5.0
      */
     invalidInteger?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when integer is outside the safe integer range
+     * (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`).
+     * Can be a static message or a function that receives the input string.
+     * @since 1.0.0
+     */
+    unsafeInteger?: 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.
@@ -905,6 +925,7 @@ interface HostnameOptions {
  *
  * @param options - Options for hostname validation.
  * @returns A value parser for hostnames.
+ * @throws {RangeError} If `maxLength` is not a positive integer.
  * @since 0.10.0
  *
  * @example
@@ -946,7 +967,9 @@ interface EmailOptions {
    */
   readonly allowDisplayName?: boolean;
   /**
-   * If `true`, converts email to lowercase.
+   * If `true`, converts the domain part of the email to lowercase.
+   * The local part is preserved as-is, since it is technically
+   * case-sensitive per RFC 5321.
    * @default false
    */
   readonly lowercase?: boolean;
@@ -984,6 +1007,9 @@ interface EmailOptions {
  *
  * @param options - Options for email validation.
  * @returns A value parser for email addresses.
+ * @throws {TypeError} If any `allowedDomains` entry is not a string, has
+ *   leading/trailing whitespace, starts with `"@"`, is empty, lacks a dot,
+ *   has invalid hostname label syntax, or is an IPv4-like dotted-quad.
  * @since 0.10.0
  *
  * @example
@@ -1029,8 +1055,8 @@ interface SocketAddressValue {
  */
 interface SocketAddressOptions {
   /**
-   * The metavariable name for this parser.
-   * @default "HOST:PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"HOST:PORT"` for `":"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1103,6 +1129,8 @@ interface SocketAddressOptions {
  *
  * @param options - Options for socket address validation.
  * @returns A value parser for socket addresses.
+ * @throws {TypeError} If `separator` contains digit characters, since digits
+ *   in the separator would cause ambiguous splitting of port input.
  * @since 0.10.0
  *
  * @example
@@ -1165,8 +1193,8 @@ interface PortRangeOptionsNumber {
    */
   readonly type?: "number";
   /**
-   * The metavariable name for this parser.
-   * @default "PORT-PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"PORT-PORT"` for `"-"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1245,8 +1273,8 @@ interface PortRangeOptionsBigInt {
    */
   readonly type: "bigint";
   /**
-   * The metavariable name for this parser.
-   * @default "PORT-PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"PORT-PORT"` for `"-"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1326,6 +1354,10 @@ interface PortRangeOptionsBigInt {
  *
  * @param options - Options for port range validation.
  * @returns A value parser for port ranges.
+ * @throws {TypeError} If `options.type` is provided but is neither `"number"`
+ *   nor `"bigint"`.
+ * @throws {TypeError} If `separator` contains digit characters, since digits
+ *   in the separator would cause ambiguous splitting of numeric port input.
  * @since 0.10.0
  *
  * @example
@@ -1447,13 +1479,19 @@ interface DomainOptions {
    * List of allowed top-level domains (e.g., ["com", "org", "net"]).
    * If specified, only domains with these TLDs are accepted.
    */
-  readonly allowedTLDs?: readonly string[];
+  readonly allowedTlds?: readonly string[];
   /**
    * Minimum number of domain labels (parts separated by dots).
    *
    * @default 2
    */
   readonly minLabels?: number;
+  /**
+   * Maximum domain length in characters.
+   * @default 253
+   * @since 1.0.0
+   */
+  readonly maxLength?: number;
   /**
    * If `true`, converts domain to lowercase.
    *
@@ -1479,13 +1517,20 @@ interface DomainOptions {
      * Can be a static message or a function that receives the TLD
      * and allowed TLDs.
      */
-    tldNotAllowed?: Message | ((tld: string, allowedTLDs: readonly string[]) => Message);
+    tldNotAllowed?: Message | ((tld: string, allowedTlds: readonly string[]) => Message);
     /**
      * Custom error message when domain has too few labels.
      * Can be a static message or a function that receives the domain
      * and minimum labels.
      */
     tooFewLabels?: Message | ((domain: string, minLabels: number) => Message);
+    /**
+     * Custom error message when domain is too long.
+     * Can be a static message or a function that receives the domain
+     * and max length.
+     * @since 1.0.0
+     */
+    tooLong?: Message | ((domain: string, maxLength: number) => Message);
   };
 }
 /**
@@ -1497,6 +1542,13 @@ interface DomainOptions {
  *
  * @param options Parser options for domain validation.
  * @returns A parser that accepts valid domain names as strings.
+ * @throws {RangeError} If `maxLength` is not a positive integer.
+ * @throws {RangeError} If `minLabels` is not a positive integer.
+ * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
+ *   contains dots, has leading/trailing whitespace, or is not a valid DNS
+ *   label.
+ * @throws {TypeError} If `allowSubdomains` is `false` and `minLabels` is
+ *   greater than 2, since non-subdomain domains have exactly 2 labels.
  *
  * @example
  * ``` typescript
@@ -1510,7 +1562,7 @@ interface DomainOptions {
  * option("--root", domain({ allowSubdomains: false }))
  *
  * // Restrict to specific TLDs
- * option("--domain", domain({ allowedTLDs: ["com", "org", "net"] }))
+ * option("--domain", domain({ allowedTlds: ["com", "org", "net"] }))
  *
  * // Normalize to lowercase
  * option("--domain", domain({ lowercase: true }))

package/dist/valueparser.d.ts

@@ -206,6 +206,13 @@ declare function isValueParser<M extends Mode, T>(object: unknown): object is Va
  * @param options Configuration options for the choice parser.
  * @returns A {@link ValueParser} that checks if the input matches one of the
  *          specified values.
+ * @throws {TypeError} If the choices array is empty.
+ * @throws {TypeError} If any choice is an empty string.
+ * @throws {TypeError} If any choice is not a string.
+ * @throws {TypeError} If choices contain a mix of strings and numbers.
+ * @throws {TypeError} If `caseInsensitive` is not a boolean.
+ * @throws {TypeError} If `caseInsensitive` is `true` and multiple choices
+ *         normalize to the same lowercase value.
  */
 declare function choice<const T extends string>(choices: readonly T[], options?: ChoiceOptionsString): ValueParser<"sync", T>;
 /**
@@ -219,6 +226,10 @@ declare function choice<const T extends string>(choices: readonly T[], options?:
  * @param options Configuration options for the choice parser.
  * @returns A {@link ValueParser} that checks if the input matches one of the
  *          specified values.
+ * @throws {TypeError} If the choices array is empty.
+ * @throws {TypeError} If any choice is not a number.
+ * @throws {TypeError} If any choice is `NaN`.
+ * @throws {TypeError} If choices contain a mix of strings and numbers.
  * @since 0.9.0
  */
 declare function choice<const T extends number>(choices: readonly T[], options?: ChoiceOptionsNumber): ValueParser<"sync", T>;
@@ -235,6 +246,8 @@ declare function choice<const T extends number>(choices: readonly T[], options?:
  * @param options Configuration options for the string parser.
  * @returns A {@link ValueParser} that parses strings according to the
  *          specified options.
+ * @throws {TypeError} If `options.pattern` is provided but is not a
+ *         `RegExp` instance.
  */
 declare function string(options?: StringOptions): ValueParser<"sync", string>;
 /**
@@ -277,6 +290,13 @@ interface IntegerOptionsNumber {
      * @since 0.5.0
      */
     invalidInteger?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when integer is outside the safe integer range
+     * (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`).
+     * Can be a static message or a function that receives the input string.
+     * @since 1.0.0
+     */
+    unsafeInteger?: 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.
@@ -905,6 +925,7 @@ interface HostnameOptions {
  *
  * @param options - Options for hostname validation.
  * @returns A value parser for hostnames.
+ * @throws {RangeError} If `maxLength` is not a positive integer.
  * @since 0.10.0
  *
  * @example
@@ -946,7 +967,9 @@ interface EmailOptions {
    */
   readonly allowDisplayName?: boolean;
   /**
-   * If `true`, converts email to lowercase.
+   * If `true`, converts the domain part of the email to lowercase.
+   * The local part is preserved as-is, since it is technically
+   * case-sensitive per RFC 5321.
    * @default false
    */
   readonly lowercase?: boolean;
@@ -984,6 +1007,9 @@ interface EmailOptions {
  *
  * @param options - Options for email validation.
  * @returns A value parser for email addresses.
+ * @throws {TypeError} If any `allowedDomains` entry is not a string, has
+ *   leading/trailing whitespace, starts with `"@"`, is empty, lacks a dot,
+ *   has invalid hostname label syntax, or is an IPv4-like dotted-quad.
  * @since 0.10.0
  *
  * @example
@@ -1029,8 +1055,8 @@ interface SocketAddressValue {
  */
 interface SocketAddressOptions {
   /**
-   * The metavariable name for this parser.
-   * @default "HOST:PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"HOST:PORT"` for `":"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1103,6 +1129,8 @@ interface SocketAddressOptions {
  *
  * @param options - Options for socket address validation.
  * @returns A value parser for socket addresses.
+ * @throws {TypeError} If `separator` contains digit characters, since digits
+ *   in the separator would cause ambiguous splitting of port input.
  * @since 0.10.0
  *
  * @example
@@ -1165,8 +1193,8 @@ interface PortRangeOptionsNumber {
    */
   readonly type?: "number";
   /**
-   * The metavariable name for this parser.
-   * @default "PORT-PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"PORT-PORT"` for `"-"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1245,8 +1273,8 @@ interface PortRangeOptionsBigInt {
    */
   readonly type: "bigint";
   /**
-   * The metavariable name for this parser.
-   * @default "PORT-PORT"
+   * The metavariable name for this parser.  If not specified, it is derived
+   * from the {@link separator} (e.g., `"PORT-PORT"` for `"-"`).
    */
   readonly metavar?: NonEmptyString;
   /**
@@ -1326,6 +1354,10 @@ interface PortRangeOptionsBigInt {
  *
  * @param options - Options for port range validation.
  * @returns A value parser for port ranges.
+ * @throws {TypeError} If `options.type` is provided but is neither `"number"`
+ *   nor `"bigint"`.
+ * @throws {TypeError} If `separator` contains digit characters, since digits
+ *   in the separator would cause ambiguous splitting of numeric port input.
  * @since 0.10.0
  *
  * @example
@@ -1447,13 +1479,19 @@ interface DomainOptions {
    * List of allowed top-level domains (e.g., ["com", "org", "net"]).
    * If specified, only domains with these TLDs are accepted.
    */
-  readonly allowedTLDs?: readonly string[];
+  readonly allowedTlds?: readonly string[];
   /**
    * Minimum number of domain labels (parts separated by dots).
    *
    * @default 2
    */
   readonly minLabels?: number;
+  /**
+   * Maximum domain length in characters.
+   * @default 253
+   * @since 1.0.0
+   */
+  readonly maxLength?: number;
   /**
    * If `true`, converts domain to lowercase.
    *
@@ -1479,13 +1517,20 @@ interface DomainOptions {
      * Can be a static message or a function that receives the TLD
      * and allowed TLDs.
      */
-    tldNotAllowed?: Message | ((tld: string, allowedTLDs: readonly string[]) => Message);
+    tldNotAllowed?: Message | ((tld: string, allowedTlds: readonly string[]) => Message);
     /**
      * Custom error message when domain has too few labels.
      * Can be a static message or a function that receives the domain
      * and minimum labels.
      */
     tooFewLabels?: Message | ((domain: string, minLabels: number) => Message);
+    /**
+     * Custom error message when domain is too long.
+     * Can be a static message or a function that receives the domain
+     * and max length.
+     * @since 1.0.0
+     */
+    tooLong?: Message | ((domain: string, maxLength: number) => Message);
   };
 }
 /**
@@ -1497,6 +1542,13 @@ interface DomainOptions {
  *
  * @param options Parser options for domain validation.
  * @returns A parser that accepts valid domain names as strings.
+ * @throws {RangeError} If `maxLength` is not a positive integer.
+ * @throws {RangeError} If `minLabels` is not a positive integer.
+ * @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
+ *   contains dots, has leading/trailing whitespace, or is not a valid DNS
+ *   label.
+ * @throws {TypeError} If `allowSubdomains` is `false` and `minLabels` is
+ *   greater than 2, since non-subdomain domains have exactly 2 labels.
  *
  * @example
  * ``` typescript
@@ -1510,7 +1562,7 @@ interface DomainOptions {
  * option("--root", domain({ allowSubdomains: false }))
  *
  * // Restrict to specific TLDs
- * option("--domain", domain({ allowedTLDs: ["com", "org", "net"] }))
+ * option("--domain", domain({ allowedTlds: ["com", "org", "net"] }))
  *
  * // Normalize to lowercase
  * option("--domain", domain({ lowercase: true }))