valgen 7.0.0 → 7.0.3

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

@@ -1,7 +1,28 @@
 import { validator, } from '../../core/index.js';
 const TIME_PATTERN = /^(\d{2}):?(\d{2})(?::?(\d{2}))?(?:\.(\d{1,3}))?$/;
 /**
- * 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 function isTime(options) {

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

@@ -1,6 +1,20 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value a Uppercase string
+ * Validates that a string contains only uppercase characters, by delegating
+ * to `validatorJS.isUppercase(input)`.
+ *
+ * @param options - Validation options.
+ * @returns The validated string, unchanged.
+ * @throws `Value must be an uppercase string` when the input contains any
+ *   non-uppercase characters.
+ *
+ * @example
+ * ```ts
+ * import { isUppercase } from 'valgen';
+ *
+ * isUppercase('ABC'); // => 'ABC'
+ * isUppercase('abc'); // throws ValidationError: "Value must be an uppercase string"
+ * ```
  * @validator isUppercase
  */
 export declare function isUppercase(options?: isUppercase.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;

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

@@ -1,7 +1,21 @@
 import validatorJS from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value a Uppercase string
+ * Validates that a string contains only uppercase characters, by delegating
+ * to `validatorJS.isUppercase(input)`.
+ *
+ * @param options - Validation options.
+ * @returns The validated string, unchanged.
+ * @throws `Value must be an uppercase string` when the input contains any
+ *   non-uppercase characters.
+ *
+ * @example
+ * ```ts
+ * import { isUppercase } from 'valgen';
+ *
+ * isUppercase('ABC'); // => 'ABC'
+ * isUppercase('abc'); // throws ValidationError: "Value must be an uppercase string"
+ * ```
  * @validator isUppercase
  */
 export function isUppercase(options) {

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

@@ -1,11 +1,109 @@
 import { type IsURLOptions as _IsURLOptions } from '@browsery/validator';
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is an URL
+ * Validates that a string is a valid URL, by delegating directly to
+ * `validatorJS.isURL(input, options)`; all `IsURLOptions` fields pass through
+ * unchanged.
+ *
+ * @param options - Validation options - see {@link isURL.Options} for the
+ *   forwarded `IsURLOptions` fields.
+ * @returns The validated URL string, unchanged.
+ * @throws `Value must be a valid URL` when the input isn't a valid URL.
+ *
+ * @example
+ * ```ts
+ * import { isURL, vg } from 'valgen';
+ *
+ * isURL('https://example.com'); // => 'https://example.com'
+ * isURL('not a url'); // throws ValidationError: "Value must be a valid URL"
+ *
+ * const httpsOnly = vg.isURL({ protocols: ['https'] });
+ * httpsOnly('http://example.com'); // throws ValidationError: "Value must be a valid URL"
+ * ```
  * @validator isURL
  */
 export declare function isURL(options?: isURL.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isURL {
     interface Options extends ValidationOptions, _IsURLOptions {
+        /**
+         * Allowed protocols.
+         * @defaultValue `['http','https','ftp']`
+         */
+        protocols?: string[];
+        /**
+         * Require a top-level domain.
+         * @defaultValue `true`
+         */
+        require_tld?: boolean;
+        /**
+         * Require the protocol (`scheme://`) to be present.
+         * @defaultValue `false`
+         */
+        require_protocol?: boolean;
+        /**
+         * Require a host part.
+         * @defaultValue `true`
+         */
+        require_host?: boolean;
+        /**
+         * Require an explicit port.
+         * @defaultValue `false`
+         */
+        require_port?: boolean;
+        /**
+         * Restrict to protocols in `protocols`.
+         * @defaultValue `true`
+         */
+        require_valid_protocol?: boolean;
+        /**
+         * Allow underscores in the host.
+         * @defaultValue `false`
+         */
+        allow_underscores?: boolean;
+        /**
+         * Only accept these hosts.
+         * @defaultValue `false`
+         */
+        host_whitelist?: (string | RegExp)[];
+        /**
+         * Reject these hosts.
+         * @defaultValue `false`
+         */
+        host_blacklist?: (string | RegExp)[];
+        /**
+         * Allow a trailing `.` after the domain.
+         * @defaultValue `false`
+         */
+        allow_trailing_dot?: boolean;
+        /**
+         * Allow `//example.com`-style URLs.
+         * @defaultValue `false`
+         */
+        allow_protocol_relative_urls?: boolean;
+        /**
+         * Reject `user:pass@host` credentials.
+         * @defaultValue `false`
+         */
+        disallow_auth?: boolean;
+        /**
+         * Allow a `#fragment`.
+         * @defaultValue `true`
+         */
+        allow_fragments?: boolean;
+        /**
+         * Allow a `?query=components` section.
+         * @defaultValue `true`
+         */
+        allow_query_components?: boolean;
+        /**
+         * Enforce the max length check.
+         * @defaultValue `true`
+         */
+        validate_length?: boolean;
+        /**
+         * Max URL length when `validate_length` is enabled.
+         * @defaultValue `2084`
+         */
+        max_allowed_length?: number | false;
     }
 }

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

@@ -1,7 +1,25 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is an URL
+ * Validates that a string is a valid URL, by delegating directly to
+ * `validatorJS.isURL(input, options)`; all `IsURLOptions` fields pass through
+ * unchanged.
+ *
+ * @param options - Validation options - see {@link isURL.Options} for the
+ *   forwarded `IsURLOptions` fields.
+ * @returns The validated URL string, unchanged.
+ * @throws `Value must be a valid URL` when the input isn't a valid URL.
+ *
+ * @example
+ * ```ts
+ * import { isURL, vg } from 'valgen';
+ *
+ * isURL('https://example.com'); // => 'https://example.com'
+ * isURL('not a url'); // throws ValidationError: "Value must be a valid URL"
+ *
+ * const httpsOnly = vg.isURL({ protocols: ['https'] });
+ * httpsOnly('http://example.com'); // throws ValidationError: "Value must be a valid URL"
+ * ```
  * @validator isURL
  */
 export function isURL(options) {

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

@@ -1,7 +1,29 @@
 import { type UUIDVersion as _UUIDVersion } from '@browsery/validator';
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a "UUID".
+ * Validates that a string is a valid UUID, optionally restricted to a
+ * specific version, by delegating to `validatorJS.isUUID(input, version)`.
+ * Without a version, any UUID version passes; with a version, only a UUID of
+ * that version passes.
+ *
+ * @param version - The UUID version to restrict to (e.g. `1`-`8`, `'nil'`,
+ *   `'max'`, `'loose'`, `'all'`); omit to accept any version.
+ * @param options - Validation options.
+ * @returns The validated UUID string, unchanged.
+ * @throws `Value must be a valid UUID` (or `Value must be a valid UUID v<version>`
+ *   when `version` is given) when the input isn't a matching UUID.
+ *
+ * @example
+ * ```ts
+ * import { isUUID, isUUID4, vg } from 'valgen';
+ *
+ * const uuidV4 = '01e0fee8-60d5-42a5-997c-b55a4f3e973f';
+ * isUUID(uuidV4); // => uuidV4 (any version accepted)
+ * isUUID4(uuidV4); // => uuidV4
+ *
+ * const isUUIDv1 = vg.isUUID(1);
+ * isUUIDv1(uuidV4); // throws ValidationError: "Value must be a valid UUID v1"
+ * ```
  * @validator isUUID
  */
 export declare function isUUID(version?: isUUID.UUIDVersion, options?: isUUID.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;

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

@@ -1,7 +1,29 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a "UUID".
+ * Validates that a string is a valid UUID, optionally restricted to a
+ * specific version, by delegating to `validatorJS.isUUID(input, version)`.
+ * Without a version, any UUID version passes; with a version, only a UUID of
+ * that version passes.
+ *
+ * @param version - The UUID version to restrict to (e.g. `1`-`8`, `'nil'`,
+ *   `'max'`, `'loose'`, `'all'`); omit to accept any version.
+ * @param options - Validation options.
+ * @returns The validated UUID string, unchanged.
+ * @throws `Value must be a valid UUID` (or `Value must be a valid UUID v<version>`
+ *   when `version` is given) when the input isn't a matching UUID.
+ *
+ * @example
+ * ```ts
+ * import { isUUID, isUUID4, vg } from 'valgen';
+ *
+ * const uuidV4 = '01e0fee8-60d5-42a5-997c-b55a4f3e973f';
+ * isUUID(uuidV4); // => uuidV4 (any version accepted)
+ * isUUID4(uuidV4); // => uuidV4
+ *
+ * const isUUIDv1 = vg.isUUID(1);
+ * isUUIDv1(uuidV4); // throws ValidationError: "Value must be a valid UUID v1"
+ * ```
  * @validator isUUID
  */
 export function isUUID(version, options) {

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

@@ -1,8 +1,25 @@
 import { type VATCountryCode as _VATCountryCode } from '@browsery/validator';
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a VAT number
- * @validator isVAT
+ * Validates that a string is a valid VAT (Value Added Tax) number for the
+ * given EU country code, by delegating to `validatorJS.isVAT(input, countryCode)`.
+ *
+ * @param countryCode - The EU VAT country code to validate the number against
+ *   (e.g. `'AT'`, `'BE'`, `'BG'`, ...).
+ * @param options - Validation options.
+ * @returns The validated VAT number string, unchanged.
+ * @throws `Value must be a valid VAT number` when the input isn't a valid VAT
+ *   number for `countryCode`.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * const isATVat = vg.isVATNumber('AT');
+ * isATVat('ATU12345678'); // => 'ATU12345678'
+ * isATVat('12345'); // throws ValidationError: "Value must be a valid VAT number"
+ * ```
+ * @validator isVATNumber
  */
 export declare function isVATNumber(countryCode: isVATNumber.CountryCode, options?: isVATNumber.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isVATNumber {

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

@@ -1,8 +1,25 @@
 import validatorJS, {} from '@browsery/validator';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a VAT number
- * @validator isVAT
+ * Validates that a string is a valid VAT (Value Added Tax) number for the
+ * given EU country code, by delegating to `validatorJS.isVAT(input, countryCode)`.
+ *
+ * @param countryCode - The EU VAT country code to validate the number against
+ *   (e.g. `'AT'`, `'BE'`, `'BG'`, ...).
+ * @param options - Validation options.
+ * @returns The validated VAT number string, unchanged.
+ * @throws `Value must be a valid VAT number` when the input isn't a valid VAT
+ *   number for `countryCode`.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * const isATVat = vg.isVATNumber('AT');
+ * isATVat('ATU12345678'); // => 'ATU12345678'
+ * isATVat('12345'); // throws ValidationError: "Value must be a valid VAT number"
+ * ```
+ * @validator isVATNumber
  */
 export function isVATNumber(countryCode, options) {
     return validator(isVATNumber.name, (input, context, _this) => {

package/rules/format-rules/matches.d.ts

@@ -1,11 +1,37 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value matches the given regular expression, or returns undefined if nullish
+ * Validates that a string matches a given regular expression pattern.
+ * Returns `undefined` for nullish input instead of failing. A string pattern
+ * is compiled via `new RegExp(format)`.
+ *
+ * @param format - The pattern to match against - a `RegExp`, or a string
+ *   compiled into one.
+ * @param options - Validation options.
+ * @returns The validated string, unchanged, or `undefined` when the input
+ *   was `null`/`undefined`.
+ * @throws `Value must match <formatName> format` (using `'requested'` when
+ *   `formatName` is omitted) when the input isn't a string or doesn't match.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * const isDigits = vg.matches(/\d+/);
+ * isDigits('0123'); // => '0123'
+ * isDigits('abc'); // throws ValidationError: "Value must match requested format"
+ *
+ * const isPositiveNumber = vg.matches(/\d+/, { formatName: 'positive number' });
+ * isPositiveNumber('abc'); // throws ValidationError: "Value must match positive number format"
+ * ```
  * @validator matches
  */
 export declare function matches(format: string | RegExp, options?: matches.Options): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 export declare namespace matches {
     interface Options extends ValidationOptions {
+        /**
+         * Name used in the error message (`Value must match <formatName> format`).
+         * @defaultValue `'requested'`
+         */
         formatName?: string;
     }
 }

package/rules/format-rules/matches.js

@@ -1,6 +1,28 @@
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value matches the given regular expression, or returns undefined if nullish
+ * Validates that a string matches a given regular expression pattern.
+ * Returns `undefined` for nullish input instead of failing. A string pattern
+ * is compiled via `new RegExp(format)`.
+ *
+ * @param format - The pattern to match against - a `RegExp`, or a string
+ *   compiled into one.
+ * @param options - Validation options.
+ * @returns The validated string, unchanged, or `undefined` when the input
+ *   was `null`/`undefined`.
+ * @throws `Value must match <formatName> format` (using `'requested'` when
+ *   `formatName` is omitted) when the input isn't a string or doesn't match.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * const isDigits = vg.matches(/\d+/);
+ * isDigits('0123'); // => '0123'
+ * isDigits('abc'); // throws ValidationError: "Value must match requested format"
+ *
+ * const isPositiveNumber = vg.matches(/\d+/, { formatName: 'positive number' });
+ * isPositiveNumber('abc'); // throws ValidationError: "Value must match positive number format"
+ * ```
  * @validator matches
  */
 export function matches(format, options) {

package/rules/logical-rules/is-defined.d.ts

@@ -1,11 +1,23 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is not "undefined". Note that "null" is considered
- * defined; use `isNotNullish` to reject both "undefined" and "null".
+ * Validates that a value is not `undefined`. Note that `null` is considered
+ * defined - use `isNotNullish` to reject both `undefined` and `null`.
+ *
+ * @param options - Validation options (`onFail`, `coerce`, ...).
+ * @returns The input value unchanged as long as it is not `undefined`,
+ * including `0`, `''`, and `null`.
+ * @throws `Value must be defined` if the input is `undefined`.
+ * @example
+ * ```ts
+ * isDefined(0);          // => 0
+ * isDefined(null);       // => null
+ * isDefined(undefined);  // throws ValidationError: "Value must be defined"
+ * ```
  * @validator isDefined
  */
 export declare function isDefined(options?: isDefined.Options): import("../../core/validator.js").Validator<any, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isDefined {
+    /** Options for {@link isDefined} - adds no properties beyond `ValidationOptions`. */
     interface Options extends ValidationOptions {
     }
 }

package/rules/logical-rules/is-defined.js

@@ -1,7 +1,18 @@
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is not "undefined". Note that "null" is considered
- * defined; use `isNotNullish` to reject both "undefined" and "null".
+ * Validates that a value is not `undefined`. Note that `null` is considered
+ * defined - use `isNotNullish` to reject both `undefined` and `null`.
+ *
+ * @param options - Validation options (`onFail`, `coerce`, ...).
+ * @returns The input value unchanged as long as it is not `undefined`,
+ * including `0`, `''`, and `null`.
+ * @throws `Value must be defined` if the input is `undefined`.
+ * @example
+ * ```ts
+ * isDefined(0);          // => 0
+ * isDefined(null);       // => null
+ * isDefined(undefined);  // throws ValidationError: "Value must be defined"
+ * ```
  * @validator isDefined
  */
 export function isDefined(options) {

package/rules/logical-rules/is-empty.d.ts

@@ -1,19 +1,57 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Checks if the value is empty. Value should be string, array, set, map or object
+ * Checks that the value is empty. The value should be a string, array, Set,
+ * Map, Buffer, ArrayBuffer, or plain object.
+ *
+ * `null`/`undefined` pass through unchanged (treated as empty), and `Date`
+ * instances always pass since a date has no "empty" concept.
+ *
+ * @param options - Validation options (`onFail`, `coerce`, ...).
+ * @returns The input value unchanged when it is considered empty.
+ * @throws `Value must be an empty string` / `Value must be an empty array` /
+ * `Value must be an empty Set` / `Value must be an empty Map` / `Value must
+ * be an empty Buffer` / `Value must be an empty ArrayBuffer` / `Value must be
+ * an empty Object`, depending on the input's type, or the generic `Value
+ * must be empty` for any other non-empty type (e.g. `NaN`).
+ * @example
+ * ```ts
+ * isEmpty('');   // => ''
+ * isEmpty([]);   // => []
+ * isEmpty('dd'); // throws ValidationError: "Value must be an empty string"
+ * ```
  * @validator isEmpty
  */
 export declare function isEmpty(options?: isEmpty.Options): import("../../core/validator.js").Validator<any, any, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isEmpty {
+    /** Options for {@link isEmpty} - adds no properties beyond `ValidationOptions`. */
     interface Options extends ValidationOptions {
     }
 }
 /**
- * Checks if the value is not empty. Value should be string, array, set, map or object
+ * Checks that the value is not empty. The value should be a string, array,
+ * Set, Map, Buffer, ArrayBuffer, or plain object.
+ *
+ * Unlike `isEmpty`, nullish input is rejected here rather than treated as
+ * passing, and `Date` instances always pass.
+ *
+ * @param options - Validation options (`onFail`, `coerce`, ...).
+ * @returns The input value unchanged when it is considered non-empty.
+ * @throws `Value must not be empty` for `null`/`undefined`/an empty string,
+ * `Value must not be NaN` for `NaN`, `Array must not be empty`, `Set must
+ * not be empty`, `Map must not be empty`, `Buffer must not be empty`,
+ * `ArrayBuffer must not be empty`, or `Object must not be empty`, depending
+ * on the input's type.
+ * @example
+ * ```ts
+ * isNotEmpty('abc'); // => 'abc'
+ * isNotEmpty('');    // throws ValidationError: "Value must not be empty"
+ * isNotEmpty([]);    // throws ValidationError: "Array must not be empty"
+ * ```
  * @validator isNotEmpty
  */
 export declare function isNotEmpty(options?: isNotEmpty.Options): import("../../core/validator.js").Validator<any, any, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isNotEmpty {
+    /** Options for {@link isNotEmpty} - adds no properties beyond `ValidationOptions`. */
     interface Options extends ValidationOptions {
     }
 }

package/rules/logical-rules/is-empty.js

@@ -1,6 +1,24 @@
 import { validator, } from '../../core/index.js';
 /**
- * Checks if the value is empty. Value should be string, array, set, map or object
+ * Checks that the value is empty. The value should be a string, array, Set,
+ * Map, Buffer, ArrayBuffer, or plain object.
+ *
+ * `null`/`undefined` pass through unchanged (treated as empty), and `Date`
+ * instances always pass since a date has no "empty" concept.
+ *
+ * @param options - Validation options (`onFail`, `coerce`, ...).
+ * @returns The input value unchanged when it is considered empty.
+ * @throws `Value must be an empty string` / `Value must be an empty array` /
+ * `Value must be an empty Set` / `Value must be an empty Map` / `Value must
+ * be an empty Buffer` / `Value must be an empty ArrayBuffer` / `Value must be
+ * an empty Object`, depending on the input's type, or the generic `Value
+ * must be empty` for any other non-empty type (e.g. `NaN`).
+ * @example
+ * ```ts
+ * isEmpty('');   // => ''
+ * isEmpty([]);   // => []
+ * isEmpty('dd'); // throws ValidationError: "Value must be an empty string"
+ * ```
  * @validator isEmpty
  */
 export function isEmpty(options) {
@@ -48,7 +66,25 @@ export function isEmpty(options) {
     }, options);
 }
 /**
- * Checks if the value is not empty. Value should be string, array, set, map or object
+ * Checks that the value is not empty. The value should be a string, array,
+ * Set, Map, Buffer, ArrayBuffer, or plain object.
+ *
+ * Unlike `isEmpty`, nullish input is rejected here rather than treated as
+ * passing, and `Date` instances always pass.
+ *
+ * @param options - Validation options (`onFail`, `coerce`, ...).
+ * @returns The input value unchanged when it is considered non-empty.
+ * @throws `Value must not be empty` for `null`/`undefined`/an empty string,
+ * `Value must not be NaN` for `NaN`, `Array must not be empty`, `Set must
+ * not be empty`, `Map must not be empty`, `Buffer must not be empty`,
+ * `ArrayBuffer must not be empty`, or `Object must not be empty`, depending
+ * on the input's type.
+ * @example
+ * ```ts
+ * isNotEmpty('abc'); // => 'abc'
+ * isNotEmpty('');    // throws ValidationError: "Value must not be empty"
+ * isNotEmpty([]);    // throws ValidationError: "Array must not be empty"
+ * ```
  * @validator isNotEmpty
  */
 export function isNotEmpty(options) {

package/rules/logical-rules/is-equal.d.ts

@@ -1,21 +1,48 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if the value is strictly equal ("===") to "compare".
- * `null`/`undefined` input is passed through unchanged.
+ * Validates that the value is strictly equal (`===`) to `compare`.
+ * `null`/`undefined` input is always passed through unchanged, regardless of
+ * `compare`.
+ *
+ * @typeParam T - The type of `compare`.
+ * @param compare - The value the input must strictly equal.
+ * @param options - Validation options (`onFail`, `coerce`, ...).
+ * @returns The input value unchanged when it strictly equals `compare` (or
+ * is nullish).
+ * @throws `Value must be equal to "<compare>"` if `input !== compare`.
+ * @example
+ * ```ts
+ * vg.isEqual('a')('a'); // => 'a'
+ * vg.isEqual('a')('b'); // throws ValidationError: "Value must be equal to..."
+ * ```
  * @validator isEqual
  */
 export declare function isEqual<T>(compare: T, options?: isEqual.Options): import("../../core/validator.js").Validator<any, any, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isEqual {
+    /** Options for {@link isEqual} - adds no properties beyond `ValidationOptions`. */
     interface Options extends ValidationOptions {
     }
 }
 /**
- * Validates if the value is not strictly equal ("===") to "compare".
- * `null`/`undefined` input is passed through unchanged.
+ * Validates that the value is not strictly equal (`===`) to `compare`.
+ * `null`/`undefined` input is always passed through unchanged, regardless of
+ * `compare`.
+ *
+ * @param compare - The value the input must not strictly equal.
+ * @param options - Validation options (`onFail`, `coerce`, ...).
+ * @returns The input value unchanged when it does not strictly equal
+ * `compare` (or is nullish).
+ * @throws `Value must not be equal to "<compare>"` if `input === compare`.
+ * @example
+ * ```ts
+ * vg.isNotEqual('a')('b'); // => 'b'
+ * vg.isNotEqual('a')('a'); // throws ValidationError: "Value must not be equal to..."
+ * ```
  * @validator isNotEqual
  */
 export declare function isNotEqual(compare: any, options?: isNotEqual.Options): import("../../core/validator.js").Validator<any, any, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isNotEqual {
+    /** Options for {@link isNotEqual} - adds no properties beyond `ValidationOptions`. */
     interface Options extends ValidationOptions {
     }
 }