valgen 7.0.1 → 7.0.3

package/rules/format-rules/is-base64.d.ts

@@ -1,11 +1,30 @@
 import { type IsBase64Options as _IsBase64Options } from '@browsery/validator';
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a "Base64" string.
+ * Validates that a string is Base64-encoded. Delegates to
+ * `validatorJS.isBase64(input, options)`.
  * @validator isBase64
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid Base64 string: `Value must be a Base64 string`
+ * @example
+ * ```ts
+ * isBase64('SGVsbG8gV29ybGQ='); // => 'SGVsbG8gV29ybGQ='
+ * isBase64('not-base64!!'); // throws ValidationError: "Value must be a Base64 string"
+ * ```
  */
 export declare function isBase64(options?: isBase64.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isBase64 {
     interface Options extends ValidationOptions, _IsBase64Options {
+        /**
+         * If `true`, expects URL-safe Base64 (`-`/`_` instead of `+`/`/`).
+         * @defaultValue false
+         */
+        urlSafe?: boolean;
+        /**
+         * Whether trailing `=` padding is required.
+         * @defaultValue !urlSafe
+         */
+        padding?: boolean;
     }
 }

package/rules/format-rules/is-base64.js

@@ -1,8 +1,17 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a "Base64" string.
+ * Validates that a string is Base64-encoded. Delegates to
+ * `validatorJS.isBase64(input, options)`.
  * @validator isBase64
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid Base64 string: `Value must be a Base64 string`
+ * @example
+ * ```ts
+ * isBase64('SGVsbG8gV29ybGQ='); // => 'SGVsbG8gV29ybGQ='
+ * isBase64('not-base64!!'); // throws ValidationError: "Value must be a Base64 string"
+ * ```
  */
 export function isBase64(options) {
     return validator(isBase64.name, (input, context, _this) => {

package/rules/format-rules/is-btc-address.d.ts

@@ -1,7 +1,16 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a BTC address.
+ * Validates that a string is a valid Bitcoin (BTC) address. Delegates to
+ * `validatorJS.isBtcAddress`.
  * @validator isBtcAddress
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid BTC address: `Value must be a valid BTC address`
+ * @example
+ * ```ts
+ * isBtcAddress('1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2'); // => '1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2'
+ * isBtcAddress('notabtcaddress'); // throws ValidationError: "Value must be a valid BTC address"
+ * ```
  */
 export declare function isBtcAddress(options?: isBtcAddress.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isBtcAddress {

package/rules/format-rules/is-btc-address.js

@@ -1,8 +1,17 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a BTC address.
+ * Validates that a string is a valid Bitcoin (BTC) address. Delegates to
+ * `validatorJS.isBtcAddress`.
  * @validator isBtcAddress
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid BTC address: `Value must be a valid BTC address`
+ * @example
+ * ```ts
+ * isBtcAddress('1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2'); // => '1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2'
+ * isBtcAddress('notabtcaddress'); // throws ValidationError: "Value must be a valid BTC address"
+ * ```
  */
 export function isBtcAddress(options) {
     return validator(isBtcAddress.name, (input, context, _this) => {

package/rules/format-rules/is-credit-card.d.ts

@@ -1,12 +1,27 @@
 import { type IsCreditCardOptions as _IsCreditCardOptions } from '@browsery/validator';
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a credit card number
+ * Validates that a string is a valid credit card number (Luhn checksum plus
+ * an optional provider-specific pattern). Delegates to
+ * `validatorJS.isCreditCard(input, options)`.
  * @validator isCreditCard
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid credit card number: `Value must be a valid Credit Card number`
+ * @example
+ * ```ts
+ * isCreditCard('4111111111111111'); // => '4111111111111111'
+ * isCreditCard('4111111111111112'); // throws ValidationError: "Value must be a valid Credit Card number"
+ * ```
  */
 export declare function isCreditCard(options?: isCreditCard.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isCreditCard {
     interface Options extends ValidationOptions, _IsCreditCardOptions {
+        /**
+         * Restricts validation to a specific card provider/network.
+         * @defaultValue undefined
+         */
+        provider?: Provider;
     }
     type Provider = _IsCreditCardOptions['provider'];
 }

package/rules/format-rules/is-credit-card.js

@@ -1,8 +1,18 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a credit card number
+ * Validates that a string is a valid credit card number (Luhn checksum plus
+ * an optional provider-specific pattern). Delegates to
+ * `validatorJS.isCreditCard(input, options)`.
  * @validator isCreditCard
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid credit card number: `Value must be a valid Credit Card number`
+ * @example
+ * ```ts
+ * isCreditCard('4111111111111111'); // => '4111111111111111'
+ * isCreditCard('4111111111111112'); // throws ValidationError: "Value must be a valid Credit Card number"
+ * ```
  */
 export function isCreditCard(options) {
     return validator(isCreditCard.name, (input, context, _this) => {

package/rules/format-rules/is-decimal.d.ts

@@ -1,8 +1,18 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Check if the string represents a decimal number,
- * such as `0.1`, `.3`, `1.1`, `1.00003`, `4.0` etc.
+ * Validates that a string represents a decimal number, such as `0.1`, `.3`,
+ * `1.1`, `1.00003`, `4.0` etc. Delegates to `validatorJS.isDecimal(input)`
+ * with no options passed through, so it always uses the underlying
+ * library's default rules.
  * @validator isDecimal
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a decimal number string: `Value must be a decimal number string`
+ * @example
+ * ```ts
+ * isDecimal('1.5'); // => '1.5'
+ * isDecimal('abc'); // throws ValidationError: "Value must be a decimal number string"
+ * ```
  */
 export declare function isDecimal(options?: isDecimal.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isDecimal {

package/rules/format-rules/is-decimal.js

@@ -1,9 +1,19 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Check if the string represents a decimal number,
- * such as `0.1`, `.3`, `1.1`, `1.00003`, `4.0` etc.
+ * Validates that a string represents a decimal number, such as `0.1`, `.3`,
+ * `1.1`, `1.00003`, `4.0` etc. Delegates to `validatorJS.isDecimal(input)`
+ * with no options passed through, so it always uses the underlying
+ * library's default rules.
  * @validator isDecimal
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a decimal number string: `Value must be a decimal number string`
+ * @example
+ * ```ts
+ * isDecimal('1.5'); // => '1.5'
+ * isDecimal('abc'); // throws ValidationError: "Value must be a decimal number string"
+ * ```
  */
 export function isDecimal(options) {
     return validator(isDecimal.name, (input, context, _this) => {

package/rules/format-rules/is-ean.d.ts

@@ -1,7 +1,17 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is an EAN (European Article Number)
+ * Validates that a string is a valid EAN (European Article Number).
+ * Delegates to `validatorJS.isEAN(input)` (checksum-validated EAN-8/EAN-13
+ * style codes).
  * @validator isEAN
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid EAN: `Value must be a valid EAN (European Article Number)`
+ * @example
+ * ```ts
+ * isEAN('4006381333931'); // => '4006381333931'
+ * isEAN('1234567890123'); // throws ValidationError: "Value must be a valid EAN (European Article Number)"
+ * ```
  */
 export declare function isEAN(options?: isEAN.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isEAN {

package/rules/format-rules/is-ean.js

@@ -1,8 +1,18 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is an EAN (European Article Number)
+ * Validates that a string is a valid EAN (European Article Number).
+ * Delegates to `validatorJS.isEAN(input)` (checksum-validated EAN-8/EAN-13
+ * style codes).
  * @validator isEAN
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid EAN: `Value must be a valid EAN (European Article Number)`
+ * @example
+ * ```ts
+ * isEAN('4006381333931'); // => '4006381333931'
+ * isEAN('1234567890123'); // throws ValidationError: "Value must be a valid EAN (European Article Number)"
+ * ```
  */
 export function isEAN(options) {
     return validator(isEAN.name, (input, context, _this) => {

package/rules/format-rules/is-email.d.ts

@@ -1,7 +1,19 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a valid Email
+ * Validates that a string is a well-formed email address. Wraps
+ * `validatorJS.isEmail`, always passing `allow_display_name: true` as a
+ * base, then layers additional checks (display name requirement/
+ * prohibition, host black/white list, blacklisted characters) as separate
+ * re-validation passes, each producing a specific error message.
  * @validator isEmail
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a well-formed email address: `Value must match required e-mail format`
+ * @example
+ * ```ts
+ * isEmail('me@domain.com'); // => 'me@domain.com'
+ * isEmail('invalid'); // throws ValidationError: "Value must match required e-mail format"
+ * ```
  */
 export declare function isEmail(options?: isEmail.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isEmail {
@@ -9,38 +21,38 @@ export declare namespace isEmail {
         /**
          * If set to `true`, the validator will also match `Display Name <email-address>`.
          *
-         * @default false
+         * @defaultValue false
          */
         allowDisplayName?: boolean;
         /**
          * If set to `true`, the validator will reject strings without the format `Display Name <email-address>`.
          *
-         * @default false
+         * @defaultValue false
          */
         requireDisplayName?: boolean;
         /**
          * If set to `false`, the validator will not allow any non-English UTF8 character in email address' local part.
          *
-         * @default true
+         * @defaultValue true
          */
         utf8LocalPart?: boolean;
         /**
          * If set to `true`, the validator will not check for the standard max length of an email.
          *
-         * @default false
+         * @defaultValue false
          */
         ignoreMaxLength?: boolean;
         /**
          * If set to `true`, the validator will allow IP addresses in the host part.
          *
-         * @default false
+         * @defaultValue false
          */
         allowIpDomain?: boolean;
         /**
          * If set to `true`, some additional validation will be enabled,
          * e.g. disallowing certain syntactically valid email addresses that are rejected by GMail.
          *
-         * @default false
+         * @defaultValue false
          */
         domainSpecificValidation?: boolean;
         /**

package/rules/format-rules/is-email.js

@@ -1,8 +1,20 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a valid Email
+ * Validates that a string is a well-formed email address. Wraps
+ * `validatorJS.isEmail`, always passing `allow_display_name: true` as a
+ * base, then layers additional checks (display name requirement/
+ * prohibition, host black/white list, blacklisted characters) as separate
+ * re-validation passes, each producing a specific error message.
  * @validator isEmail
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a well-formed email address: `Value must match required e-mail format`
+ * @example
+ * ```ts
+ * isEmail('me@domain.com'); // => 'me@domain.com'
+ * isEmail('invalid'); // throws ValidationError: "Value must match required e-mail format"
+ * ```
  */
 export function isEmail(options) {
     const emailOptions = {

package/rules/format-rules/is-eth-address.d.ts

@@ -1,7 +1,16 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is an ETH (Ethereum) address.
+ * Validates that a string is a valid Ethereum (ETH) address. Delegates to
+ * `validatorJS.isEthereumAddress`.
  * @validator isETHAddress
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid ETH address: `Value must be valid ETH (Ethereum) address`
+ * @example
+ * ```ts
+ * isETHAddress('0xb794f5ea0ba39494ce839613fffba74279579268'); // => '0xb794f5ea0ba39494ce839613fffba74279579268'
+ * isETHAddress('0xnothex'); // throws ValidationError: "Value must be valid ETH (Ethereum) address"
+ * ```
  */
 export declare function isETHAddress(options?: isETHAddress.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isETHAddress {

package/rules/format-rules/is-eth-address.js

@@ -1,8 +1,17 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is an ETH (Ethereum) address.
+ * Validates that a string is a valid Ethereum (ETH) address. Delegates to
+ * `validatorJS.isEthereumAddress`.
  * @validator isETHAddress
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid ETH address: `Value must be valid ETH (Ethereum) address`
+ * @example
+ * ```ts
+ * isETHAddress('0xb794f5ea0ba39494ce839613fffba74279579268'); // => '0xb794f5ea0ba39494ce839613fffba74279579268'
+ * isETHAddress('0xnothex'); // throws ValidationError: "Value must be valid ETH (Ethereum) address"
+ * ```
  */
 export function isETHAddress(options) {
     return validator(isETHAddress.name, (input, context, _this) => {

package/rules/format-rules/is-fqdn.d.ts

@@ -1,14 +1,25 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is an FQDN
+ * Validates that a string is a fully qualified domain name (e.g.
+ * `domain.com`). Delegates to `validatorJS.isFQDN(input, { allow_wildcard })`.
+ * Only `allowWildcard` is forwarded; other underlying options
+ * (`require_tld`, `allow_underscores`, etc.) are not currently exposed.
  * @validator isFQDN
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid FQDN: `Value must be valid FQDN`
+ * @example
+ * ```ts
+ * isFQDN('example.com'); // => 'example.com'
+ * isFQDN('*.example.com'); // throws ValidationError: "Value must be valid FQDN" (wildcard rejected by default)
+ * ```
  */
 export declare function isFQDN(options?: isFQDN.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isFQDN {
     interface Options extends ValidationOptions {
         /**
          * If set to true, the validator will allow domain starting with `*.` (e.g. `*.example.com` or `*.shop.example.com`).
-         * @default false
+         * @defaultValue false
          */
         allowWildcard?: boolean;
     }

package/rules/format-rules/is-fqdn.js

@@ -1,8 +1,19 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is an FQDN
+ * Validates that a string is a fully qualified domain name (e.g.
+ * `domain.com`). Delegates to `validatorJS.isFQDN(input, { allow_wildcard })`.
+ * Only `allowWildcard` is forwarded; other underlying options
+ * (`require_tld`, `allow_underscores`, etc.) are not currently exposed.
  * @validator isFQDN
+ * @param options - Validation options.
+ * @returns The input string, unchanged, if valid.
+ * @throws if `input` is not a valid FQDN: `Value must be valid FQDN`
+ * @example
+ * ```ts
+ * isFQDN('example.com'); // => 'example.com'
+ * isFQDN('*.example.com'); // throws ValidationError: "Value must be valid FQDN" (wildcard rejected by default)
+ * ```
  */
 export function isFQDN(options) {
     const opts = {

package/rules/format-rules/is-hash.d.ts

@@ -1,10 +1,26 @@
 import { type HashAlgorithm as _HashAlgorithm } from '@browsery/validator';
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value a hash of type algorithm
+ * Validates that a string is a hash digest of the given algorithm. Delegates
+ * to `validatorJS.isHash(input, algorithm)`, which checks that the string is
+ * a hex string of the length expected for the given algorithm.
  * @validator isHash
+ * @param algorithm - The hash algorithm the input is expected to match.
+ * @param options - Validation options.
+ * @returns The validated hash string, unchanged.
+ * @throws `Value must be a valid ${algorithm} hash` when the input is not a
+ *   string, or is not a hex string of the expected length for `algorithm`.
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * const isMd5 = vg.isHash('md5');
+ * isMd5('5d41402abc4b2a76b9719d911017c592'); // => '5d41402abc4b2a76b9719d911017c592'
+ * isMd5('too-short'); // throws ValidationError: "Value must be a valid md5 hash"
+ * ```
  */
 export declare function isHash(algorithm: isHash.HashAlgorithm, options?: ValidationOptions): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isHash {
+    /** The hash algorithms accepted by {@link isHash}'s `algorithm` argument. */
     type HashAlgorithm = _HashAlgorithm;
 }

package/rules/format-rules/is-hash.js

@@ -1,8 +1,23 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value a hash of type algorithm
+ * Validates that a string is a hash digest of the given algorithm. Delegates
+ * to `validatorJS.isHash(input, algorithm)`, which checks that the string is
+ * a hex string of the length expected for the given algorithm.
  * @validator isHash
+ * @param algorithm - The hash algorithm the input is expected to match.
+ * @param options - Validation options.
+ * @returns The validated hash string, unchanged.
+ * @throws `Value must be a valid ${algorithm} hash` when the input is not a
+ *   string, or is not a hex string of the expected length for `algorithm`.
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * const isMd5 = vg.isHash('md5');
+ * isMd5('5d41402abc4b2a76b9719d911017c592'); // => '5d41402abc4b2a76b9719d911017c592'
+ * isMd5('too-short'); // throws ValidationError: "Value must be a valid md5 hash"
+ * ```
  */
 export function isHash(algorithm, options) {
     return validator(isHash.name, (input, context, _this) => {

package/rules/format-rules/is-hex-color.d.ts

@@ -1,7 +1,19 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a Hex Color
+ * Validates that a string is a valid hexadecimal color (e.g. `#fff`,
+ * `#ffffff`). Delegates to `validatorJS.isHexColor(input)`.
  * @validator isHexColor
+ * @param options - Validation options.
+ * @returns The validated hex color string, unchanged.
+ * @throws `Value must be a valid Hex Color` when the input is not a string,
+ *   or is not a valid hex color.
+ * @example
+ * ```ts
+ * import { isHexColor } from 'valgen';
+ *
+ * isHexColor('#fff'); // => '#fff'
+ * isHexColor('notacolor'); // throws ValidationError: "Value must be a valid Hex Color"
+ * ```
  */
 export declare function isHexColor(options?: isHexColor.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isHexColor {

package/rules/format-rules/is-hex-color.js

@@ -1,8 +1,20 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a Hex Color
+ * Validates that a string is a valid hexadecimal color (e.g. `#fff`,
+ * `#ffffff`). Delegates to `validatorJS.isHexColor(input)`.
  * @validator isHexColor
+ * @param options - Validation options.
+ * @returns The validated hex color string, unchanged.
+ * @throws `Value must be a valid Hex Color` when the input is not a string,
+ *   or is not a valid hex color.
+ * @example
+ * ```ts
+ * import { isHexColor } from 'valgen';
+ *
+ * isHexColor('#fff'); // => '#fff'
+ * isHexColor('notacolor'); // throws ValidationError: "Value must be a valid Hex Color"
+ * ```
  */
 export function isHexColor(options) {
     return validator(isHexColor.name, (input, context, _this) => {

package/rules/format-rules/is-hex.d.ts

@@ -1,7 +1,19 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Check if the string is a hexadecimal number.
+ * Validates that a string is a hexadecimal number. Delegates to
+ * `validatorJS.isHexadecimal(input)`.
  * @validator isHex
+ * @param options - Validation options.
+ * @returns The validated hexadecimal string, unchanged.
+ * @throws `Value must be an hexadecimal string` when the input is not a
+ *   string, or is not a valid hexadecimal number.
+ * @example
+ * ```ts
+ * import { isHex } from 'valgen';
+ *
+ * isHex('1a2B3c'); // => '1a2B3c'
+ * isHex('zzz'); // throws ValidationError: "Value must be an hexadecimal string"
+ * ```
  */
 export declare function isHex(options?: isHex.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isHex {

package/rules/format-rules/is-hex.js

@@ -1,8 +1,20 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Check if the string is a hexadecimal number.
+ * Validates that a string is a hexadecimal number. Delegates to
+ * `validatorJS.isHexadecimal(input)`.
  * @validator isHex
+ * @param options - Validation options.
+ * @returns The validated hexadecimal string, unchanged.
+ * @throws `Value must be an hexadecimal string` when the input is not a
+ *   string, or is not a valid hexadecimal number.
+ * @example
+ * ```ts
+ * import { isHex } from 'valgen';
+ *
+ * isHex('1a2B3c'); // => '1a2B3c'
+ * isHex('zzz'); // throws ValidationError: "Value must be an hexadecimal string"
+ * ```
  */
 export function isHex(options) {
     return validator(isHex.name, (input, context, _this) => {

package/rules/format-rules/is-iban.d.ts

@@ -1,11 +1,42 @@
-import { type IsIBANOptions as _IsIBANOptions } from '@browsery/validator';
+import { type IBANLocale as _IBANLocale, type IsIBANOptions as _IsIBANOptions } from '@browsery/validator';
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is an IBAN (International Bank Account Number)
+ * Validates that a string is a valid IBAN (International Bank Account
+ * Number). Delegates to `validatorJS.isIBAN(input, options)`, which checks
+ * structure and the mod-97 checksum for the country.
  * @validator isIBAN
+ * @param options - Validation options, including `whitelist`/`blacklist`
+ *   country restrictions.
+ * @returns The validated IBAN string, unchanged.
+ * @throws `Value must be a valid IBAN (International Bank Account Number)`
+ *   when the input is not a string, fails the checksum, or is excluded by
+ *   `whitelist`/`blacklist`.
+ * @example
+ * ```ts
+ * import { isIBAN, vg } from 'valgen';
+ *
+ * isIBAN('DE89370400440532013000'); // => 'DE89370400440532013000'
+ * isIBAN('DE89370400440532013001'); // throws ValidationError: "Value must be a valid IBAN (International Bank Account Number)"
+ *
+ * const deOnly = vg.isIBAN({ whitelist: ['DE'] });
+ * deOnly('DE89370400440532013000'); // => 'DE89370400440532013000'
+ * ```
  */
 export declare function isIBAN(options?: isIBAN.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isIBAN {
     interface Options extends ValidationOptions, _IsIBANOptions {
+        /**
+         * Only accept IBANs from these country codes.
+         *
+         * @defaultValue undefined
+         */
+        whitelist?: IBANLocale[];
+        /**
+         * Reject IBANs from these country codes.
+         *
+         * @defaultValue undefined
+         */
+        blacklist?: IBANLocale[];
     }
+    type IBANLocale = _IBANLocale;
 }

package/rules/format-rules/is-iban.js

@@ -1,8 +1,26 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is an IBAN (International Bank Account Number)
+ * Validates that a string is a valid IBAN (International Bank Account
+ * Number). Delegates to `validatorJS.isIBAN(input, options)`, which checks
+ * structure and the mod-97 checksum for the country.
  * @validator isIBAN
+ * @param options - Validation options, including `whitelist`/`blacklist`
+ *   country restrictions.
+ * @returns The validated IBAN string, unchanged.
+ * @throws `Value must be a valid IBAN (International Bank Account Number)`
+ *   when the input is not a string, fails the checksum, or is excluded by
+ *   `whitelist`/`blacklist`.
+ * @example
+ * ```ts
+ * import { isIBAN, vg } from 'valgen';
+ *
+ * isIBAN('DE89370400440532013000'); // => 'DE89370400440532013000'
+ * isIBAN('DE89370400440532013001'); // throws ValidationError: "Value must be a valid IBAN (International Bank Account Number)"
+ *
+ * const deOnly = vg.isIBAN({ whitelist: ['DE'] });
+ * deOnly('DE89370400440532013000'); // => 'DE89370400440532013000'
+ * ```
  */
 export function isIBAN(options) {
     return validator(isIBAN.name, (input, context, _this) => {