valgen 7.0.0 → 7.0.3

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

@@ -1,18 +1,60 @@
 import { type IPVersion as _IPVersion } from '@browsery/validator';
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is an IP
+ * Validates that a string is a valid IP address (v4 or v6). Delegates to
+ * `validatorJS.isIP(input, version)`. Without a version, either IPv4 or IPv6
+ * is accepted; with a version, only that version passes.
  * @validator isIP
+ * @param version - Restricts validation to `'4'`/`4` or `'6'`/`6`; omit to
+ *   accept either version.
+ * @param options - Validation options.
+ * @returns The validated IP address string, unchanged.
+ * @throws `Value must be a valid IP` (or `Value must be a valid IP v${version}`
+ *   when `version` is given) when the input is not a string, or is not a
+ *   valid IP address of the requested version.
+ * @example
+ * ```ts
+ * import { isIP, vg } from 'valgen';
+ *
+ * isIP('192.168.1.1'); // => '192.168.1.1'
+ * isIP('not-an-ip'); // throws ValidationError: "Value must be a valid IP"
+ *
+ * const isIPv4 = vg.isIP(4);
+ * isIPv4('10.0.0.1'); // => '10.0.0.1'
+ * isIPv4('2001:db8::1'); // throws ValidationError: "Value must be a valid IP v4"
+ * ```
  */
 export declare function isIP(version?: isIP.IPVersion, options?: ValidationOptions): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 /**
- * Validates if value is an IP
+ * Validates that a string is a valid IP address range in CIDR notation (v4
+ * or v6). Delegates to `validatorJS.isIPRange(input, version)`, requiring a
+ * `/`-delimited subnet mask.
  * @validator isIPRange
+ * @param version - Restricts validation to `'4'`/`4` or `'6'`/`6`; omit to
+ *   accept either version.
+ * @param options - Validation options.
+ * @returns The validated CIDR range string, unchanged.
+ * @throws `Value must be a valid IP range` (or `Value must be a valid IP
+ *   v${version} range` when `version` is given) when the input is not a
+ *   string, or is not a valid CIDR range of the requested version (e.g. a
+ *   missing subnet mask).
+ * @example
+ * ```ts
+ * import { isIPRange, vg } from 'valgen';
+ *
+ * isIPRange('192.168.1.0/24'); // => '192.168.1.0/24'
+ * isIPRange('192.168.1.0'); // throws ValidationError: "Value must be a valid IP range"
+ *
+ * const isIPv4Range = vg.isIPRange(4);
+ * isIPv4Range('192.168.1.0/24'); // => '192.168.1.0/24'
+ * ```
  */
 export declare function isIPRange(version?: isIPRange.IPVersion, options?: ValidationOptions): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isIP {
+    /** The IP versions accepted by {@link isIP}'s `version` argument. */
     type IPVersion = _IPVersion;
 }
 export declare namespace isIPRange {
+    /** The IP versions accepted by {@link isIPRange}'s `version` argument. */
     type IPVersion = _IPVersion;
 }

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

@@ -2,8 +2,28 @@ import validatorJS, {} from '@browsery/validator';
 import {} from 'ts-gems';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is an IP
+ * Validates that a string is a valid IP address (v4 or v6). Delegates to
+ * `validatorJS.isIP(input, version)`. Without a version, either IPv4 or IPv6
+ * is accepted; with a version, only that version passes.
  * @validator isIP
+ * @param version - Restricts validation to `'4'`/`4` or `'6'`/`6`; omit to
+ *   accept either version.
+ * @param options - Validation options.
+ * @returns The validated IP address string, unchanged.
+ * @throws `Value must be a valid IP` (or `Value must be a valid IP v${version}`
+ *   when `version` is given) when the input is not a string, or is not a
+ *   valid IP address of the requested version.
+ * @example
+ * ```ts
+ * import { isIP, vg } from 'valgen';
+ *
+ * isIP('192.168.1.1'); // => '192.168.1.1'
+ * isIP('not-an-ip'); // throws ValidationError: "Value must be a valid IP"
+ *
+ * const isIPv4 = vg.isIP(4);
+ * isIPv4('10.0.0.1'); // => '10.0.0.1'
+ * isIPv4('2001:db8::1'); // throws ValidationError: "Value must be a valid IP v4"
+ * ```
  */
 export function isIP(version, options) {
     return validator(isIP.name, (input, context, _this) => {
@@ -16,8 +36,28 @@ export function isIP(version, options) {
     }, options);
 }
 /**
- * Validates if value is an IP
+ * Validates that a string is a valid IP address range in CIDR notation (v4
+ * or v6). Delegates to `validatorJS.isIPRange(input, version)`, requiring a
+ * `/`-delimited subnet mask.
  * @validator isIPRange
+ * @param version - Restricts validation to `'4'`/`4` or `'6'`/`6`; omit to
+ *   accept either version.
+ * @param options - Validation options.
+ * @returns The validated CIDR range string, unchanged.
+ * @throws `Value must be a valid IP range` (or `Value must be a valid IP
+ *   v${version} range` when `version` is given) when the input is not a
+ *   string, or is not a valid CIDR range of the requested version (e.g. a
+ *   missing subnet mask).
+ * @example
+ * ```ts
+ * import { isIPRange, vg } from 'valgen';
+ *
+ * isIPRange('192.168.1.0/24'); // => '192.168.1.0/24'
+ * isIPRange('192.168.1.0'); // throws ValidationError: "Value must be a valid IP range"
+ *
+ * const isIPv4Range = vg.isIPRange(4);
+ * isIPv4Range('192.168.1.0/24'); // => '192.168.1.0/24'
+ * ```
  */
 export function isIPRange(version, options) {
     return validator(isIPRange.name, (input, context, _this) => {

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

@@ -1,7 +1,24 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is an ISSN
+ * Validates that a string is a valid ISSN (International Standard Serial
+ * Number). Delegates to `validatorJS.isISSN(input, { case_sensitive })`.
  * @validator isISSN
+ * @param options - Validation options.
+ * @returns The validated ISSN string, unchanged.
+ * @throws `Value must be a valid ISSN` when the input is not a string, is
+ *   not a valid ISSN, or (with `caseSensitive: true`) has a lowercase `x`
+ *   check digit.
+ * @example
+ * ```ts
+ * import { isISSN, vg } from 'valgen';
+ *
+ * isISSN('0378-5955'); // => '0378-5955'
+ * isISSN('1234-1234'); // throws ValidationError: "Value must be a valid ISSN"
+ *
+ * isISSN('1000-002x'); // => '1000-002x' (lowercase check digit allowed by default)
+ * const strict = vg.isISSN({ caseSensitive: true });
+ * strict('1000-002x'); // throws ValidationError: "Value must be a valid ISSN"
+ * ```
  */
 export declare function isISSN(options?: isISSN.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isISSN {
@@ -9,7 +26,7 @@ export declare namespace isISSN {
         /**
          * If set to `true`, ISSNs with a lowercase `x` as the check digit are rejected.
          *
-         * @default false
+         * @defaultValue false
          */
         caseSensitive?: boolean;
     }

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

@@ -1,8 +1,25 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is an ISSN
+ * Validates that a string is a valid ISSN (International Standard Serial
+ * Number). Delegates to `validatorJS.isISSN(input, { case_sensitive })`.
  * @validator isISSN
+ * @param options - Validation options.
+ * @returns The validated ISSN string, unchanged.
+ * @throws `Value must be a valid ISSN` when the input is not a string, is
+ *   not a valid ISSN, or (with `caseSensitive: true`) has a lowercase `x`
+ *   check digit.
+ * @example
+ * ```ts
+ * import { isISSN, vg } from 'valgen';
+ *
+ * isISSN('0378-5955'); // => '0378-5955'
+ * isISSN('1234-1234'); // throws ValidationError: "Value must be a valid ISSN"
+ *
+ * isISSN('1000-002x'); // => '1000-002x' (lowercase check digit allowed by default)
+ * const strict = vg.isISSN({ caseSensitive: true });
+ * strict('1000-002x'); // throws ValidationError: "Value must be a valid ISSN"
+ * ```
  */
 export function isISSN(options) {
     const opts = {

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

@@ -1,7 +1,22 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value a valid JWT token
+ * Validates that a string is structurally a valid JWT (JSON Web Token).
+ * Delegates to `validatorJS.isJWT(input)`, which checks for three base64url
+ * segments separated by `.` (it does not verify a signature).
  * @validator isJWT
+ * @param options - Validation options.
+ * @returns The validated JWT string, unchanged.
+ * @throws `Value must be valid JWT token` when the input is not a string, or
+ *   does not have the three-segment base64url structure of a JWT.
+ * @example
+ * ```ts
+ * import { isJWT } from 'valgen';
+ *
+ * const jwt =
+ *   'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U';
+ * isJWT(jwt); // => jwt
+ * isJWT('abc.def'); // throws ValidationError: "Value must be valid JWT token"
+ * ```
  */
 export declare function isJWT(options?: isJWT.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isJWT {

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

@@ -1,8 +1,23 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value a valid JWT token
+ * Validates that a string is structurally a valid JWT (JSON Web Token).
+ * Delegates to `validatorJS.isJWT(input)`, which checks for three base64url
+ * segments separated by `.` (it does not verify a signature).
  * @validator isJWT
+ * @param options - Validation options.
+ * @returns The validated JWT string, unchanged.
+ * @throws `Value must be valid JWT token` when the input is not a string, or
+ *   does not have the three-segment base64url structure of a JWT.
+ * @example
+ * ```ts
+ * import { isJWT } from 'valgen';
+ *
+ * const jwt =
+ *   'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U';
+ * isJWT(jwt); // => jwt
+ * isJWT('abc.def'); // throws ValidationError: "Value must be valid JWT token"
+ * ```
  */
 export function isJWT(options) {
     return validator(isJWT.name, (input, context, _this) => {

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

@@ -1,7 +1,19 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value a Lowercase string
+ * Validates that a string contains only lowercase characters. Delegates to
+ * `validatorJS.isLowercase(input)`.
  * @validator isLowercase
+ * @param options - Validation options.
+ * @returns The validated lowercase string, unchanged.
+ * @throws `Value must be a lowercase string` when the input is not a
+ *   string, or contains any non-lowercase characters.
+ * @example
+ * ```ts
+ * import { isLowercase } from 'valgen';
+ *
+ * isLowercase('abc'); // => 'abc'
+ * isLowercase('ABC'); // throws ValidationError: "Value must be a lowercase string"
+ * ```
  */
 export declare function isLowercase(options?: isLowercase.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isLowercase {

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

@@ -1,8 +1,20 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value a Lowercase string
+ * Validates that a string contains only lowercase characters. Delegates to
+ * `validatorJS.isLowercase(input)`.
  * @validator isLowercase
+ * @param options - Validation options.
+ * @returns The validated lowercase string, unchanged.
+ * @throws `Value must be a lowercase string` when the input is not a
+ *   string, or contains any non-lowercase characters.
+ * @example
+ * ```ts
+ * import { isLowercase } from 'valgen';
+ *
+ * isLowercase('abc'); // => 'abc'
+ * isLowercase('ABC'); // throws ValidationError: "Value must be a lowercase string"
+ * ```
  */
 export function isLowercase(options) {
     return validator(isLowercase.name, (input, context, _this) => {

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

@@ -1,7 +1,22 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is an MACAddress
+ * Validates that a string is a valid MAC address. Delegates to
+ * `validatorJS.isMACAddress(input, { no_separators, eui })`.
  * @validator isMACAddress
+ * @param options - Validation options.
+ * @returns The validated MAC address string, unchanged.
+ * @throws `Value must be a valid MAC address` when the input is not a
+ *   string, or does not match the requested MAC address format.
+ * @example
+ * ```ts
+ * import { isMACAddress, vg } from 'valgen';
+ *
+ * isMACAddress('01:02:03:04:05:ab'); // => '01:02:03:04:05:ab'
+ * isMACAddress('0102030405ab'); // throws ValidationError: "Value must be a valid MAC address"
+ *
+ * const noSeparators = vg.isMACAddress({ noSeparators: true });
+ * noSeparators('0102030405ab'); // => '0102030405ab'
+ * ```
  */
 export declare function isMACAddress(options?: isMACAddress.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isMACAddress {
@@ -12,11 +27,13 @@ export declare namespace isMACAddress {
          *
          * e.g. `01 02 03 04 05 ab` or `01-02-03-04-05-ab`.
          *
-         * @default false
+         * @defaultValue false
          */
         noSeparators?: boolean;
         /**
          * Setting `eui` allows for validation against EUI-48 or EUI-64 instead of both.
+         *
+         * @defaultValue undefined
          */
         eui?: '48' | '64';
     }

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

@@ -2,8 +2,23 @@ import validatorJS, {} from '@browsery/validator';
 import {} from 'ts-gems';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is an MACAddress
+ * Validates that a string is a valid MAC address. Delegates to
+ * `validatorJS.isMACAddress(input, { no_separators, eui })`.
  * @validator isMACAddress
+ * @param options - Validation options.
+ * @returns The validated MAC address string, unchanged.
+ * @throws `Value must be a valid MAC address` when the input is not a
+ *   string, or does not match the requested MAC address format.
+ * @example
+ * ```ts
+ * import { isMACAddress, vg } from 'valgen';
+ *
+ * isMACAddress('01:02:03:04:05:ab'); // => '01:02:03:04:05:ab'
+ * isMACAddress('0102030405ab'); // throws ValidationError: "Value must be a valid MAC address"
+ *
+ * const noSeparators = vg.isMACAddress({ noSeparators: true });
+ * noSeparators('0102030405ab'); // => '0102030405ab'
+ * ```
  */
 export function isMACAddress(options) {
     const opts = {

package/rules/format-rules/is-mobile-phone.d.ts

@@ -1,8 +1,24 @@
 import { type MobilePhoneLocale as _MobilePhoneLocale } from '@browsery/validator';
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a valid mobile phone number
+ * Validates that a string is a valid mobile phone number. Delegates to
+ * `validatorJS.isMobilePhone(input, options.locale, { strictMode })`.
  * @validator isMobilePhone
+ * @param options - Validation options.
+ * @returns The validated mobile phone number string, unchanged.
+ * @throws `Value must be a valid Mobile Phone Number` when the input is not
+ *   a string, or is not a valid mobile phone number for the requested
+ *   locale(s)/strictness.
+ * @example
+ * ```ts
+ * import { isMobilePhone, vg } from 'valgen';
+ *
+ * isMobilePhone('+14155552671'); // => '+14155552671'
+ * isMobilePhone('12345'); // throws ValidationError: "Value must be a valid Mobile Phone Number"
+ *
+ * const trStrict = vg.isMobilePhone({ locale: 'tr-TR', strictMode: true });
+ * trStrict('+905321234567'); // => '+905321234567'
+ * ```
  */
 export declare function isMobilePhone(options?: isMobilePhone.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isMobilePhone {
@@ -10,12 +26,12 @@ export declare namespace isMobilePhone {
         /**
          * If this is set to `true`, the mobile phone number must be supplied with the country code and therefore must start with `+`.
          *
-         * @default false
+         * @defaultValue false
          */
         strictMode?: boolean;
         /**
          * Locale or locales of the mobile phone
-         * @default 'any'
+         * @defaultValue 'any'
          */
         locale?: 'any' | MobilePhoneLocale | MobilePhoneLocale[];
     }

package/rules/format-rules/is-mobile-phone.js

@@ -1,8 +1,24 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a valid mobile phone number
+ * Validates that a string is a valid mobile phone number. Delegates to
+ * `validatorJS.isMobilePhone(input, options.locale, { strictMode })`.
  * @validator isMobilePhone
+ * @param options - Validation options.
+ * @returns The validated mobile phone number string, unchanged.
+ * @throws `Value must be a valid Mobile Phone Number` when the input is not
+ *   a string, or is not a valid mobile phone number for the requested
+ *   locale(s)/strictness.
+ * @example
+ * ```ts
+ * import { isMobilePhone, vg } from 'valgen';
+ *
+ * isMobilePhone('+14155552671'); // => '+14155552671'
+ * isMobilePhone('12345'); // throws ValidationError: "Value must be a valid Mobile Phone Number"
+ *
+ * const trStrict = vg.isMobilePhone({ locale: 'tr-TR', strictMode: true });
+ * trStrict('+905321234567'); // => '+905321234567'
+ * ```
  */
 export function isMobilePhone(options) {
     const opts = {

package/rules/format-rules/is-object-id.d.ts

@@ -1,10 +1,29 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is an "ObjectId".
+ * Validates that a value is a valid MongoDB `ObjectId` (a 24-char hex
+ * string, a 12-byte `Uint8Array`, or an object exposing `toHexString()`).
+ * Unlike most format rules, this is not a wrapper around
+ * `@browsery/validator`'s own `isObjectId` - it implements its own check,
+ * using `validatorJS.isHexadecimal` only for the string case.
  * @validator isObjectId
+ * @param options - Validation options.
+ * @returns The validated value, unchanged (its original type - string,
+ *   `Uint8Array`, or `ObjectIdLike`).
+ * @throws `Value must be a valid ObjectId` when the input is not a
+ *   24-character hex string, a 12-byte `Uint8Array`, or an object whose
+ *   `toHexString()` result passes the same check.
+ * @example
+ * ```ts
+ * import { isObjectId } from 'valgen';
+ *
+ * const idString = '64897efbdf01a60ac1b678ea';
+ * isObjectId(idString); // => '64897efbdf01a60ac1b678ea'
+ * isObjectId(undefined); // throws ValidationError: "Value must be a valid ObjectId"
+ * ```
  */
 export declare function isObjectId(options?: ValidationOptions): import("../../core/validator.js").Validator<string | Uint8Array<ArrayBufferLike> | isObjectId.ObjectIdLike, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isObjectId {
+    /** An object exposing a MongoDB-style `toHexString()` method, accepted as input alongside plain hex strings and 12-byte `Uint8Array`s. */
     interface ObjectIdLike {
         id: string | Uint8Array;
         toHexString(): string;

package/rules/format-rules/is-object-id.js

@@ -1,8 +1,26 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is an "ObjectId".
+ * Validates that a value is a valid MongoDB `ObjectId` (a 24-char hex
+ * string, a 12-byte `Uint8Array`, or an object exposing `toHexString()`).
+ * Unlike most format rules, this is not a wrapper around
+ * `@browsery/validator`'s own `isObjectId` - it implements its own check,
+ * using `validatorJS.isHexadecimal` only for the string case.
  * @validator isObjectId
+ * @param options - Validation options.
+ * @returns The validated value, unchanged (its original type - string,
+ *   `Uint8Array`, or `ObjectIdLike`).
+ * @throws `Value must be a valid ObjectId` when the input is not a
+ *   24-character hex string, a 12-byte `Uint8Array`, or an object whose
+ *   `toHexString()` result passes the same check.
+ * @example
+ * ```ts
+ * import { isObjectId } from 'valgen';
+ *
+ * const idString = '64897efbdf01a60ac1b678ea';
+ * isObjectId(idString); // => '64897efbdf01a60ac1b678ea'
+ * isObjectId(undefined); // throws ValidationError: "Value must be a valid ObjectId"
+ * ```
  */
 export function isObjectId(options) {
     return validator(isObjectId.name, (input, context, _this) => {

package/rules/format-rules/is-passport-number.d.ts

@@ -1,6 +1,22 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a passport number
+ * Validates that a string is a valid passport number for the given country,
+ * by delegating to `validatorJS.isPassportNumber(input, countryCode)`.
+ *
+ * @param countryCode - The ISO country code to validate the passport number against.
+ * @param options - Validation options.
+ * @returns The validated passport number string, unchanged.
+ * @throws `Value must be a valid <countryCode> Passport Number` when the input
+ *   isn't a valid passport number for `countryCode`.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * const isUSPassport = vg.isPassportNumber('US');
+ * isUSPassport('123456789'); // => '123456789'
+ * isUSPassport('12345'); // throws ValidationError: "Value must be a valid US Passport Number"
+ * ```
  * @validator isPassportNumber
  */
 export declare function isPassportNumber(countryCode: string, options?: isPassportNumber.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;

package/rules/format-rules/is-passport-number.js

@@ -1,7 +1,23 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a passport number
+ * Validates that a string is a valid passport number for the given country,
+ * by delegating to `validatorJS.isPassportNumber(input, countryCode)`.
+ *
+ * @param countryCode - The ISO country code to validate the passport number against.
+ * @param options - Validation options.
+ * @returns The validated passport number string, unchanged.
+ * @throws `Value must be a valid <countryCode> Passport Number` when the input
+ *   isn't a valid passport number for `countryCode`.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * const isUSPassport = vg.isPassportNumber('US');
+ * isUSPassport('123456789'); // => '123456789'
+ * isUSPassport('12345'); // throws ValidationError: "Value must be a valid US Passport Number"
+ * ```
  * @validator isPassportNumber
  */
 export function isPassportNumber(countryCode, options) {

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

@@ -1,6 +1,21 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a port number
+ * Validates that a value is a valid TCP/UDP port number, and coerces it to a
+ * `number`. Accepts a `string` or `number` input; numbers are stringified
+ * before being checked with `validatorJS.isPort(input)`.
+ *
+ * @param options - Validation options.
+ * @returns The port parsed as an integer `number` - not the original string.
+ * @throws `Value must be a valid port number` when the input isn't a valid port.
+ *
+ * @example
+ * ```ts
+ * import { isPort } from 'valgen';
+ *
+ * isPort('80'); // => 80
+ * isPort(80); // => 80
+ * isPort('70000'); // throws ValidationError: "Value must be a valid port number"
+ * ```
  * @validator isPort
  */
 export declare function isPort(options?: isPort.Options): import("../../core/validator.js").Validator<number, string | number, import("../../core/types.js").ExecutionOptions>;

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

@@ -2,7 +2,22 @@ import validatorJS from '@browsery/validator';
 import {} from 'ts-gems';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a port number
+ * Validates that a value is a valid TCP/UDP port number, and coerces it to a
+ * `number`. Accepts a `string` or `number` input; numbers are stringified
+ * before being checked with `validatorJS.isPort(input)`.
+ *
+ * @param options - Validation options.
+ * @returns The port parsed as an integer `number` - not the original string.
+ * @throws `Value must be a valid port number` when the input isn't a valid port.
+ *
+ * @example
+ * ```ts
+ * import { isPort } from 'valgen';
+ *
+ * isPort('80'); // => 80
+ * isPort(80); // => 80
+ * isPort('70000'); // throws ValidationError: "Value must be a valid port number"
+ * ```
  * @validator isPort
  */
 export function isPort(options) {

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

@@ -1,6 +1,20 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a BIC (Bank Identification Code) or SWIFT code
+ * Validates that a string is a valid BIC (Bank Identification Code) or SWIFT
+ * code, by delegating to `validatorJS.isBIC(input)`.
+ *
+ * @param options - Validation options.
+ * @returns The validated BIC/SWIFT code string, unchanged.
+ * @throws `Value must be a valid BIC (Bank Identification Code) or SWIFT code`
+ *   when the input isn't a valid BIC/SWIFT code.
+ *
+ * @example
+ * ```ts
+ * import { isSWIFT } from 'valgen';
+ *
+ * isSWIFT('DEUTDEFF500'); // => 'DEUTDEFF500'
+ * isSWIFT('1234DEFF'); // throws ValidationError: "Value must be a valid BIC (Bank Identification Code) or SWIFT code"
+ * ```
  * @validator isSWIFT
  */
 export declare function isSWIFT(options?: isSWIFT.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;

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

@@ -1,7 +1,21 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a BIC (Bank Identification Code) or SWIFT code
+ * Validates that a string is a valid BIC (Bank Identification Code) or SWIFT
+ * code, by delegating to `validatorJS.isBIC(input)`.
+ *
+ * @param options - Validation options.
+ * @returns The validated BIC/SWIFT code string, unchanged.
+ * @throws `Value must be a valid BIC (Bank Identification Code) or SWIFT code`
+ *   when the input isn't a valid BIC/SWIFT code.
+ *
+ * @example
+ * ```ts
+ * import { isSWIFT } from 'valgen';
+ *
+ * isSWIFT('DEUTDEFF500'); // => 'DEUTDEFF500'
+ * isSWIFT('1234DEFF'); // throws ValidationError: "Value must be a valid BIC (Bank Identification Code) or SWIFT code"
+ * ```
  * @validator isSWIFT
  */
 export function isSWIFT(options) {

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

@@ -1,6 +1,27 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a time formatted string
+ * Validates (and optionally coerces) a time-of-day value in `HH:mm`,
+ * `HH:mm:ss`, or `HH:mm:ss.SSS` format, with or without separators. Not a
+ * wrapper around `@browsery/validator` - it uses its own regex and checks
+ * hour ≤ 23, minutes/seconds ≤ 59.
+ *
+ * @param options - Validation options. When `coerce` is `true`, a `Date`
+ *   input is converted to a `HH:mm:ss[.SSS]` string, and a compact form
+ *   without separators (e.g. `'1230'`) is normalized to colon-separated form;
+ *   without `coerce`, the input string is returned unchanged.
+ * @returns The validated (and possibly coerced) time string.
+ * @throws `Value must be a valid Time` when the input isn't a recognized
+ *   time-of-day value.
+ *
+ * @example
+ * ```ts
+ * import { isTime } from 'valgen';
+ *
+ * isTime('12:30', { coerce: true }); // => '12:30'
+ * isTime('1230', { coerce: true }); // => '12:30'
+ * isTime(new Date('2025-01-10T08:30:15'), { coerce: true }); // => '08:30:15'
+ * isTime('25:00'); // throws ValidationError: "Value must be a valid Time"
+ * ```
  * @validator isTime
  */
 export declare function isTime(options?: isTime.Options): import("../../core/validator.js").Validator<string, string | Date, import("../../core/types.js").ExecutionOptions>;