valgen 7.0.0 → 7.0.3

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

@@ -1,7 +1,20 @@
 import { validator, } 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 function isEqual(compare, options) {
@@ -14,8 +27,20 @@ export function isEqual(compare, options) {
     }, options);
 }
 /**
- * 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 function isNotEqual(compare, options) {

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

@@ -1,12 +1,37 @@
 import { type ValidationOptions, type Validator } from '../../core/index.js';
 import type { range } from './range.js';
 /**
- * Checks if value is greater than "minValue"
+ * Checks that the value is greater than `minValue`. Supports `number`,
+ * `bigint`, `Date`, and `string` comparisons (numbers and bigints can be
+ * compared against each other). Despite the `Nullish<T>` return type, there
+ * is **no** null/undefined passthrough here - nullish input falls through
+ * every branch and fails.
+ *
+ * @typeParam T - The type of `minValue` (`range.Input`: `number | bigint | Date | string`).
+ * @param minValue - The value the input must be strictly greater than.
+ * @param options - Validation options, including `caseInsensitive` for
+ * string comparisons.
+ * @returns The input value unchanged when it is greater than `minValue`.
+ * @throws `Value must be greater than <minValue>` (string `minValue` quoted,
+ * e.g. `"B"`) if the comparison fails, or if `input`/`minValue` are not a
+ * matching comparable type.
+ * @example
+ * ```ts
+ * vg.isGt(5)(6);     // => 6
+ * vg.isGt(5)(5);     // throws ValidationError: "...must be greater than 5"
+ * vg.isGt('B')('C'); // => 'C'
+ * ```
  * @validator isGt
  */
 export declare function isGt<T extends range.Input>(minValue: T, options?: isGt.Options): Validator;
 export declare namespace isGt {
     interface Options extends ValidationOptions {
+        /**
+         * For string comparisons, also passes if the lower-cased input is
+         * greater than the lower-cased `minValue` (in addition to the
+         * case-sensitive comparison).
+         * @defaultValue false
+         */
         caseInsensitive?: boolean;
     }
 }

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

@@ -1,6 +1,25 @@
 import { validator, } from '../../core/index.js';
 /**
- * Checks if value is greater than "minValue"
+ * Checks that the value is greater than `minValue`. Supports `number`,
+ * `bigint`, `Date`, and `string` comparisons (numbers and bigints can be
+ * compared against each other). Despite the `Nullish<T>` return type, there
+ * is **no** null/undefined passthrough here - nullish input falls through
+ * every branch and fails.
+ *
+ * @typeParam T - The type of `minValue` (`range.Input`: `number | bigint | Date | string`).
+ * @param minValue - The value the input must be strictly greater than.
+ * @param options - Validation options, including `caseInsensitive` for
+ * string comparisons.
+ * @returns The input value unchanged when it is greater than `minValue`.
+ * @throws `Value must be greater than <minValue>` (string `minValue` quoted,
+ * e.g. `"B"`) if the comparison fails, or if `input`/`minValue` are not a
+ * matching comparable type.
+ * @example
+ * ```ts
+ * vg.isGt(5)(6);     // => 6
+ * vg.isGt(5)(5);     // throws ValidationError: "...must be greater than 5"
+ * vg.isGt('B')('C'); // => 'C'
+ * ```
  * @validator isGt
  */
 export function isGt(minValue, options) {

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

@@ -1,12 +1,36 @@
 import { type ValidationOptions, type Validator } from '../../core/index.js';
 import type { range } from './range.js';
 /**
- * Checks if value is greater than or equal to minValue
+ * Checks that the value is greater than or equal to `minValue`. Supports
+ * `number`, `bigint`, `Date`, and `string` comparisons. Despite the
+ * `Nullish<T>` return type, there is **no** null/undefined passthrough here
+ * - nullish input falls through every branch and fails. This validator is
+ * also reused internally by `lengthMin` via
+ * `pipe([getLength(), isGte(minValue, { onFail: ... })])`.
+ *
+ * @typeParam T - The type of `minValue` (`range.Input`: `number | bigint | Date | string`).
+ * @param minValue - The value the input must be greater than or equal to.
+ * @param options - Validation options, including `caseInsensitive` for
+ * string comparisons.
+ * @returns The input value unchanged when it is `>= minValue`.
+ * @throws `Value must be greater than or equal to <minValue>` (string
+ * `minValue` quoted) if the comparison fails, or if `input`/`minValue` are
+ * not a matching comparable type.
+ * @example
+ * ```ts
+ * vg.isGte(5)(5); // => 5
+ * vg.isGte(5)(4); // throws ValidationError: "...must be greater than or equal to 5"
+ * ```
  * @validator isGte
  */
 export declare function isGte<T extends range.Input>(minValue: T, options?: isGte.Options): Validator<T>;
 export declare namespace isGte {
     interface Options extends ValidationOptions {
+        /**
+         * For string comparisons, also passes if the lower-cased input is `>=`
+         * the lower-cased `minValue`.
+         * @defaultValue false
+         */
         caseInsensitive?: boolean;
     }
 }

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

@@ -1,6 +1,25 @@
 import { validator, } from '../../core/index.js';
 /**
- * Checks if value is greater than or equal to minValue
+ * Checks that the value is greater than or equal to `minValue`. Supports
+ * `number`, `bigint`, `Date`, and `string` comparisons. Despite the
+ * `Nullish<T>` return type, there is **no** null/undefined passthrough here
+ * - nullish input falls through every branch and fails. This validator is
+ * also reused internally by `lengthMin` via
+ * `pipe([getLength(), isGte(minValue, { onFail: ... })])`.
+ *
+ * @typeParam T - The type of `minValue` (`range.Input`: `number | bigint | Date | string`).
+ * @param minValue - The value the input must be greater than or equal to.
+ * @param options - Validation options, including `caseInsensitive` for
+ * string comparisons.
+ * @returns The input value unchanged when it is `>= minValue`.
+ * @throws `Value must be greater than or equal to <minValue>` (string
+ * `minValue` quoted) if the comparison fails, or if `input`/`minValue` are
+ * not a matching comparable type.
+ * @example
+ * ```ts
+ * vg.isGte(5)(5); // => 5
+ * vg.isGte(5)(4); // throws ValidationError: "...must be greater than or equal to 5"
+ * ```
  * @validator isGte
  */
 export function isGte(minValue, options) {

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

@@ -1,12 +1,35 @@
 import { type ValidationOptions, type Validator } from '../../core/index.js';
 import type { range } from './range.js';
 /**
- * Checks if the value is lower than maxValue
+ * Checks that the value is lower than `maxValue`. Supports `number`,
+ * `bigint`, `Date`, and `string` comparisons. Despite the `Nullish<T>`
+ * return type, there is **no** null/undefined passthrough here - nullish
+ * input falls through every branch and fails.
+ *
+ * @typeParam T - The type of `maxValue` (`range.Input`: `number | bigint | Date | string`).
+ * @param maxValue - The value the input must be strictly lower than.
+ * @param options - Validation options, including `caseInsensitive` for
+ * string comparisons.
+ * @returns The input value unchanged when it is lower than `maxValue`.
+ * @throws `Value must be lower than <maxValue>` (string `maxValue` quoted)
+ * if the comparison fails, or if `input`/`maxValue` are not a matching
+ * comparable type.
+ * @example
+ * ```ts
+ * vg.isLt(5)(4);     // => 4
+ * vg.isLt(5)(5);     // throws ValidationError: "...must be lower than 5"
+ * vg.isLt('B')('A'); // => 'A'
+ * ```
  * @validator isLt
  */
 export declare function isLt<T extends range.Input>(maxValue: T, options?: isLt.Options): Validator;
 export declare namespace isLt {
     interface Options extends ValidationOptions {
+        /**
+         * For string comparisons, also passes if the lower-cased input is lower
+         * than the lower-cased `maxValue`.
+         * @defaultValue false
+         */
         caseInsensitive?: boolean;
     }
 }

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

@@ -1,6 +1,24 @@
 import { validator, } from '../../core/index.js';
 /**
- * Checks if the value is lower than maxValue
+ * Checks that the value is lower than `maxValue`. Supports `number`,
+ * `bigint`, `Date`, and `string` comparisons. Despite the `Nullish<T>`
+ * return type, there is **no** null/undefined passthrough here - nullish
+ * input falls through every branch and fails.
+ *
+ * @typeParam T - The type of `maxValue` (`range.Input`: `number | bigint | Date | string`).
+ * @param maxValue - The value the input must be strictly lower than.
+ * @param options - Validation options, including `caseInsensitive` for
+ * string comparisons.
+ * @returns The input value unchanged when it is lower than `maxValue`.
+ * @throws `Value must be lower than <maxValue>` (string `maxValue` quoted)
+ * if the comparison fails, or if `input`/`maxValue` are not a matching
+ * comparable type.
+ * @example
+ * ```ts
+ * vg.isLt(5)(4);     // => 4
+ * vg.isLt(5)(5);     // throws ValidationError: "...must be lower than 5"
+ * vg.isLt('B')('A'); // => 'A'
+ * ```
  * @validator isLt
  */
 export function isLt(maxValue, options) {

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

@@ -1,12 +1,36 @@
 import { type ValidationOptions, type Validator } from '../../core/index.js';
 import type { range } from './range.js';
 /**
- * Checks if the value is lower than or equal to maxValue
+ * Checks that the value is lower than or equal to `maxValue`. Supports
+ * `number`, `bigint`, `Date`, and `string` comparisons. Despite the
+ * `Nullish<T>` return type, there is **no** null/undefined passthrough here
+ * - nullish input falls through every branch and fails. This validator is
+ * also reused internally by `lengthMax` via
+ * `pipe([getLength(), isLte(maxValue, { onFail: ... })])`.
+ *
+ * @typeParam T - The type of `maxValue` (`range.Input`: `number | bigint | Date | string`).
+ * @param maxValue - The value the input must be lower than or equal to.
+ * @param options - Validation options, including `caseInsensitive` for
+ * string comparisons.
+ * @returns The input value unchanged when it is `<= maxValue`.
+ * @throws `Value must be lower than or equal to <maxValue>` (string
+ * `maxValue` quoted) if the comparison fails, or if `input`/`maxValue` are
+ * not a matching comparable type.
+ * @example
+ * ```ts
+ * vg.isLte(5)(5); // => 5
+ * vg.isLte(5)(6); // throws ValidationError: "...must be lower than or equal to 5"
+ * ```
  * @validator isLte
  */
 export declare function isLte<T extends range.Input>(maxValue: T, options?: isLte.Options): Validator;
 export declare namespace isLte {
     interface Options extends ValidationOptions {
+        /**
+         * For string comparisons, also passes if the lower-cased input is `<=`
+         * the lower-cased `maxValue`.
+         * @defaultValue false
+         */
         caseInsensitive?: boolean;
     }
 }

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

@@ -1,6 +1,25 @@
 import { validator, } from '../../core/index.js';
 /**
- * Checks if the value is lower than or equal to maxValue
+ * Checks that the value is lower than or equal to `maxValue`. Supports
+ * `number`, `bigint`, `Date`, and `string` comparisons. Despite the
+ * `Nullish<T>` return type, there is **no** null/undefined passthrough here
+ * - nullish input falls through every branch and fails. This validator is
+ * also reused internally by `lengthMax` via
+ * `pipe([getLength(), isLte(maxValue, { onFail: ... })])`.
+ *
+ * @typeParam T - The type of `maxValue` (`range.Input`: `number | bigint | Date | string`).
+ * @param maxValue - The value the input must be lower than or equal to.
+ * @param options - Validation options, including `caseInsensitive` for
+ * string comparisons.
+ * @returns The input value unchanged when it is `<= maxValue`.
+ * @throws `Value must be lower than or equal to <maxValue>` (string
+ * `maxValue` quoted) if the comparison fails, or if `input`/`maxValue` are
+ * not a matching comparable type.
+ * @example
+ * ```ts
+ * vg.isLte(5)(5); // => 5
+ * vg.isLte(5)(6); // throws ValidationError: "...must be lower than or equal to 5"
+ * ```
  * @validator isLte
  */
 export function isLte(maxValue, options) {

package/rules/logical-rules/length.d.ts

@@ -1,10 +1,46 @@
 /**
- * Checks the length is at least "minValue"
+ * Checks that the length of the value is at least `minValue`.
+ *
+ * Not a hand-rolled rule - it is composed from other validators:
+ * `allOf([pipe([getLength(), isGte(minValue, { onFail: ... })])])`.
+ * `getLength()` extracts the length/size of a string, array, or any object
+ * exposing a `length`/`size` property; `pipe` feeds that length into
+ * `isGte`; `allOf` wraps the pipeline so the composed validator still
+ * returns the *original* input (not the extracted length) on success.
+ *
+ * @param minValue - The minimum length the value must have.
+ * @returns The original input value unchanged when its length is
+ * `>= minValue`.
+ * @throws `Value length must be at least <minValue>` if the value's length
+ * is too short (or `Unable to get length` if `getLength()` cannot determine
+ * a length for the input).
+ * @example
+ * ```ts
+ * vg.lengthMin(3)('1234'); // => '1234'
+ * vg.lengthMin(3)('ab');   // throws ValidationError: "Value length must be at least 3"
+ * ```
  * @validator lengthMin
  */
 export declare const lengthMin: (minValue: number) => import("../../index.js").Validator<any, any, import("../../index.js").ExecutionOptions>;
 /**
- * Checks if the length is at most "maxValue"
+ * Checks that the length of the value is at most `maxValue`.
+ *
+ * Like `lengthMin`, this is composed from other validators:
+ * `allOf([pipe([getLength(), isLte(maxValue, { onFail: ... })])])`.
+ *
+ * @param maxValue - The maximum length the value may have.
+ * @returns The original input value unchanged when its length is
+ * `<= maxValue`.
+ * @throws `The length of {{label}} must be at most <maxValue>` if the
+ * value's length is too long (`{{label}}` resolves to `Value` when no
+ * `label`/`location`/`property` is set on the context), or
+ * `Unable to get length` if `getLength()` cannot determine a length for the
+ * input.
+ * @example
+ * ```ts
+ * vg.lengthMax(3)('12');   // => '12'
+ * vg.lengthMax(3)('1245'); // throws ValidationError: "The length of Value must be at most 3"
+ * ```
  * @validator lengthMax
  */
 export declare const lengthMax: (maxValue: number) => import("../../index.js").Validator<any, any, import("../../index.js").ExecutionOptions>;

package/rules/logical-rules/length.js

@@ -4,7 +4,26 @@ import { pipe } from '../utility-rules/pipe.js';
 import { isGte } from './is-gte.js';
 import { isLte } from './is-lte.js';
 /**
- * Checks the length is at least "minValue"
+ * Checks that the length of the value is at least `minValue`.
+ *
+ * Not a hand-rolled rule - it is composed from other validators:
+ * `allOf([pipe([getLength(), isGte(minValue, { onFail: ... })])])`.
+ * `getLength()` extracts the length/size of a string, array, or any object
+ * exposing a `length`/`size` property; `pipe` feeds that length into
+ * `isGte`; `allOf` wraps the pipeline so the composed validator still
+ * returns the *original* input (not the extracted length) on success.
+ *
+ * @param minValue - The minimum length the value must have.
+ * @returns The original input value unchanged when its length is
+ * `>= minValue`.
+ * @throws `Value length must be at least <minValue>` if the value's length
+ * is too short (or `Unable to get length` if `getLength()` cannot determine
+ * a length for the input).
+ * @example
+ * ```ts
+ * vg.lengthMin(3)('1234'); // => '1234'
+ * vg.lengthMin(3)('ab');   // throws ValidationError: "Value length must be at least 3"
+ * ```
  * @validator lengthMin
  */
 export const lengthMin = (minValue) => allOf([
@@ -16,7 +35,24 @@ export const lengthMin = (minValue) => allOf([
     ]),
 ]);
 /**
- * Checks if the length is at most "maxValue"
+ * Checks that the length of the value is at most `maxValue`.
+ *
+ * Like `lengthMin`, this is composed from other validators:
+ * `allOf([pipe([getLength(), isLte(maxValue, { onFail: ... })])])`.
+ *
+ * @param maxValue - The maximum length the value may have.
+ * @returns The original input value unchanged when its length is
+ * `<= maxValue`.
+ * @throws `The length of {{label}} must be at most <maxValue>` if the
+ * value's length is too long (`{{label}}` resolves to `Value` when no
+ * `label`/`location`/`property` is set on the context), or
+ * `Unable to get length` if `getLength()` cannot determine a length for the
+ * input.
+ * @example
+ * ```ts
+ * vg.lengthMax(3)('12');   // => '12'
+ * vg.lengthMax(3)('1245'); // throws ValidationError: "The length of Value must be at most 3"
+ * ```
  * @validator lengthMax
  */
 export const lengthMax = (maxValue) => allOf([

package/rules/logical-rules/range.d.ts

@@ -1,10 +1,34 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Checks if value is between minValue and maxValue
+ * Checks that the value is between `minValue` and `maxValue`, inclusive on
+ * both ends. Supports `number`, `bigint`, `Date`, and `string` comparisons.
+ * Despite the `Nullish<T>` return type, there is **no** null/undefined
+ * passthrough here - nullish input falls through every branch and fails.
+ * Unlike `isGt`/`isGte`/`isLt`/`isLte`, numbers and bigints are not mixed
+ * across `input`/`minValue`/`maxValue` here - all three must independently
+ * be a number or a bigint - and there is no `caseInsensitive` option for
+ * string comparisons.
+ *
+ * @typeParam T - The type of `minValue`/`maxValue` (`range.Input`:
+ * `number | bigint | Date | string`).
+ * @param minValue - The lower bound (inclusive).
+ * @param maxValue - The upper bound (inclusive).
+ * @param options - Validation options (`onFail`, `coerce`, ...).
+ * @returns The input value unchanged when `minValue <= input <= maxValue`.
+ * @throws `Value must be between <minValue> and <maxValue>` (values
+ * interpolated directly, not quoted even for strings) if the input is out
+ * of bounds, or if its type doesn't match `minValue`/`maxValue`.
+ * @example
+ * ```ts
+ * vg.range(5, 10)(7); // => 7
+ * vg.range(5, 10)(4); // throws ValidationError: "Value must be between 5 and 10"
+ * ```
  * @validator range
  */
 export declare function range<T extends range.Input>(minValue: T, maxValue: T, options?: range.Options): import("../../core/validator.js").Validator<T, T, import("../../core/types.js").ExecutionOptions>;
 export declare namespace range {
+    /** The value types `range` (and `isGt`/`isGte`/`isLt`/`isLte`) support comparing. */
     type Input = number | bigint | Date | string;
+    /** Options for {@link range} - a plain alias for `ValidationOptions`, adding no extra properties. */
     type Options = ValidationOptions;
 }

package/rules/logical-rules/range.js

@@ -1,6 +1,28 @@
 import { validator, } from '../../core/index.js';
 /**
- * Checks if value is between minValue and maxValue
+ * Checks that the value is between `minValue` and `maxValue`, inclusive on
+ * both ends. Supports `number`, `bigint`, `Date`, and `string` comparisons.
+ * Despite the `Nullish<T>` return type, there is **no** null/undefined
+ * passthrough here - nullish input falls through every branch and fails.
+ * Unlike `isGt`/`isGte`/`isLt`/`isLte`, numbers and bigints are not mixed
+ * across `input`/`minValue`/`maxValue` here - all three must independently
+ * be a number or a bigint - and there is no `caseInsensitive` option for
+ * string comparisons.
+ *
+ * @typeParam T - The type of `minValue`/`maxValue` (`range.Input`:
+ * `number | bigint | Date | string`).
+ * @param minValue - The lower bound (inclusive).
+ * @param maxValue - The upper bound (inclusive).
+ * @param options - Validation options (`onFail`, `coerce`, ...).
+ * @returns The input value unchanged when `minValue <= input <= maxValue`.
+ * @throws `Value must be between <minValue> and <maxValue>` (values
+ * interpolated directly, not quoted even for strings) if the input is out
+ * of bounds, or if its type doesn't match `minValue`/`maxValue`.
+ * @example
+ * ```ts
+ * vg.range(5, 10)(7); // => 7
+ * vg.range(5, 10)(4); // throws ValidationError: "Value must be between 5 and 10"
+ * ```
  * @validator range
  */
 export function range(minValue, maxValue, options) {

package/rules/type-rules/is-any.d.ts

@@ -1,5 +1,16 @@
 /**
- * Does nothing, just returns the original input value.
+ * Does nothing and always succeeds, returning the original input value
+ * unchanged - useful as a permissive item/value rule inside `isArray`,
+ * `isRecord`, `isTuple`, etc.
  * @validator isAny
+ * @returns The input value, unmodified.
+ * @example
+ * ```ts
+ * import { isAny, vg } from 'valgen';
+ *
+ * isAny('anything'); // => 'anything'
+ * isAny(null); // => null
+ * vg.isRecord(vg.isString, isAny)({ a: 1, b: 'x' }); // => { a: 1, b: 'x' }
+ * ```
  */
 export declare const isAny: () => import("../../core/validator.js").Validator<any, any, import("../../core/types.js").ExecutionOptions>;

package/rules/type-rules/is-any.js

@@ -1,6 +1,17 @@
 import { validator } from '../../core/index.js';
 /**
- * Does nothing, just returns the original input value.
+ * Does nothing and always succeeds, returning the original input value
+ * unchanged - useful as a permissive item/value rule inside `isArray`,
+ * `isRecord`, `isTuple`, etc.
  * @validator isAny
+ * @returns The input value, unmodified.
+ * @example
+ * ```ts
+ * import { isAny, vg } from 'valgen';
+ *
+ * isAny('anything'); // => 'anything'
+ * isAny(null); // => null
+ * vg.isRecord(vg.isString, isAny)({ a: 1, b: 'x' }); // => { a: 1, b: 'x' }
+ * ```
  */
 export const isAny = () => validator(isAny.name, (input) => input);

package/rules/type-rules/is-array.d.ts

@@ -1,8 +1,29 @@
 import type { ValidationOptions, Validator } from '../../core/index.js';
 /**
- * Validates if the value is "array" and applies validation for each item.
- * Converts input value to array if the coerce option is set to 'true'.
+ * Validates that the value is an array, optionally validating (and
+ * coercing) each item against `itemValidator`. With `coerce: true`, a
+ * non-null, non-array input is wrapped into a single-item array before
+ * validating.
  * @validator isArray
+ * @param itemValidator - Optional rule applied to each array element; when
+ *   omitted, only array-ness is checked.
+ * @param options - Validation options.
+ * @returns The validated array, with each item replaced by its (possibly
+ *   coerced) validated value.
+ * @throws `Value must be an array` if the input is `null`, `undefined`, or
+ *   not an array (and not coercible into one).
+ * @throws `Item at index [i] is not valid. <underlying message>` if an item
+ *   fails `itemValidator`.
+ * @example
+ * ```ts
+ * import { isArray, vg } from 'valgen';
+ * import { isInteger } from 'valgen';
+ *
+ * isArray([true]); // => [true]
+ * vg.isArray(isInteger)([1, 2]); // => [1, 2]
+ * vg.isArray(isInteger)(['1', '2']);
+ * // throws: 'Item at index [0] is not valid. Value must be a valid integer value'
+ * ```
  */
 export declare function isArray<T, I>(itemValidator?: Validator<T, I>, options?: isArray.Options): Validator<T[], I | I[], import("../../core/types.js").ExecutionOptions>;
 export declare namespace isArray {

package/rules/type-rules/is-array.js

@@ -1,8 +1,29 @@
 import { validator } from '../../core/index.js';
 /**
- * Validates if the value is "array" and applies validation for each item.
- * Converts input value to array if the coerce option is set to 'true'.
+ * Validates that the value is an array, optionally validating (and
+ * coercing) each item against `itemValidator`. With `coerce: true`, a
+ * non-null, non-array input is wrapped into a single-item array before
+ * validating.
  * @validator isArray
+ * @param itemValidator - Optional rule applied to each array element; when
+ *   omitted, only array-ness is checked.
+ * @param options - Validation options.
+ * @returns The validated array, with each item replaced by its (possibly
+ *   coerced) validated value.
+ * @throws `Value must be an array` if the input is `null`, `undefined`, or
+ *   not an array (and not coercible into one).
+ * @throws `Item at index [i] is not valid. <underlying message>` if an item
+ *   fails `itemValidator`.
+ * @example
+ * ```ts
+ * import { isArray, vg } from 'valgen';
+ * import { isInteger } from 'valgen';
+ *
+ * isArray([true]); // => [true]
+ * vg.isArray(isInteger)([1, 2]); // => [1, 2]
+ * vg.isArray(isInteger)(['1', '2']);
+ * // throws: 'Item at index [0] is not valid. Value must be a valid integer value'
+ * ```
  */
 export function isArray(itemValidator, options) {
     return validator(isArray.name, (input, context, _this) => {

package/rules/type-rules/is-bigint.d.ts

@@ -1,8 +1,20 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is "BigInt".
- * Converts input value to BigInt if the coerce option is set to 'true'.
+ * Validates that the value is a `bigint`. With `coerce: true`, allows
+ * converting a `number` or a numeric `string` to `bigint` via
+ * `BigInt(input)`.
  * @validator isBigint
+ * @param options - Validation options.
+ * @returns The `bigint` value.
+ * @throws `Value must be a BigInt` if the input is not a `bigint` (and,
+ *   with `coerce`, cannot be converted into one via `BigInt(input)`).
+ * @example
+ * ```ts
+ * import { isBigint } from 'valgen';
+ *
+ * isBigint(1n); // => 1n
+ * isBigint('4', { coerce: true }); // => 4n
+ * ```
  */
 export declare function isBigint(options?: isBigint.Options): import("../../core/validator.js").Validator<bigint, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isBigint {

package/rules/type-rules/is-bigint.js

@@ -1,8 +1,20 @@
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is "BigInt".
- * Converts input value to BigInt if the coerce option is set to 'true'.
+ * Validates that the value is a `bigint`. With `coerce: true`, allows
+ * converting a `number` or a numeric `string` to `bigint` via
+ * `BigInt(input)`.
  * @validator isBigint
+ * @param options - Validation options.
+ * @returns The `bigint` value.
+ * @throws `Value must be a BigInt` if the input is not a `bigint` (and,
+ *   with `coerce`, cannot be converted into one via `BigInt(input)`).
+ * @example
+ * ```ts
+ * import { isBigint } from 'valgen';
+ *
+ * isBigint(1n); // => 1n
+ * isBigint('4', { coerce: true }); // => 4n
+ * ```
  */
 export function isBigint(options) {
     return validator(isBigint.name, (input, context, _this) => {