valgen 7.0.0 → 7.0.3

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

@@ -1,8 +1,23 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is "boolean".
- * Converts input value to boolean if the coerce option is set to 'true'.
+ * Validates that the value is a `boolean`. With `coerce: true`, converts
+ * `1`/`0` and common boolean-like strings (`'true'`, `'yes'`, `'false'`,
+ * `'no'`, etc., case-insensitive) into `true`/`false`.
  * @validator isBoolean
+ * @param options - Validation options.
+ * @returns The validated (and possibly coerced) `boolean` value.
+ * @throws `Value must be a boolean` if the input is not an actual `boolean`
+ *   and cannot be coerced.
+ * @throws `Invalid boolean string` if `coerce: true` and a string input
+ *   matches neither the true nor the false pattern.
+ * @example
+ * ```ts
+ * import { isBoolean } from 'valgen';
+ *
+ * isBoolean(true); // => true
+ * isBoolean(1, { coerce: true }); // => true
+ * isBoolean('yes', { coerce: true }); // => true
+ * ```
  */
 export declare function isBoolean(options?: isBoolean.Options): import("../../core/validator.js").Validator<boolean | undefined, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isBoolean {

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

@@ -2,9 +2,24 @@ import { validator, } from '../../core/index.js';
 const TRUE_PATTERN = /^(?:true|t|1|yes|y)$/i;
 const FALSE_PATTERN = /^(?:false|f|0|no|n)$/i;
 /**
- * Validates if value is "boolean".
- * Converts input value to boolean if the coerce option is set to 'true'.
+ * Validates that the value is a `boolean`. With `coerce: true`, converts
+ * `1`/`0` and common boolean-like strings (`'true'`, `'yes'`, `'false'`,
+ * `'no'`, etc., case-insensitive) into `true`/`false`.
  * @validator isBoolean
+ * @param options - Validation options.
+ * @returns The validated (and possibly coerced) `boolean` value.
+ * @throws `Value must be a boolean` if the input is not an actual `boolean`
+ *   and cannot be coerced.
+ * @throws `Invalid boolean string` if `coerce: true` and a string input
+ *   matches neither the true nor the false pattern.
+ * @example
+ * ```ts
+ * import { isBoolean } from 'valgen';
+ *
+ * isBoolean(true); // => true
+ * isBoolean(1, { coerce: true }); // => true
+ * isBoolean('yes', { coerce: true }); // => true
+ * ```
  */
 export function isBoolean(options) {
     return validator(isBoolean.name, (input, context, _this) => {

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

@@ -1,29 +1,71 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if value is a "Date" instance. If the `coerce` option is `true`,
- * also accepts an ISO 8601 formatted date string or a numeric timestamp and
- * converts it to a Date instance.
+ * Validates that the value is a `Date` instance, with an optional
+ * precision-trimming step. With `coerce: true`, also accepts a `number`
+ * (epoch milliseconds) or a date-like `string` and converts it to a `Date`.
+ * Without `coerce`, a date *string* is rejected even if well-formed ISO
+ * 8601 - only actual `Date` instances validate by default.
  * @validator isDate
+ * @param options - Validation options.
+ * @returns The validated `Date` instance, with fields below `trim`'s
+ *   precision zeroed out when `trim` is given.
+ * @throws `Value is not valid date` if the input isn't (or can't be coerced
+ *   into) a valid `Date`.
+ * @example
+ * ```ts
+ * import { isDate, vg } from 'valgen';
+ *
+ * isDate(new Date(1)); // => new Date(1)
+ * isDate('2020-01-10T08:30:15Z', { coerce: true });
+ * // => new Date('2020-01-10T08:30:15Z')
+ * vg.isDate({ trim: 'day', coerce: true })('2020-05-10T08:30:15.123');
+ * // => new Date('2020-05-10T00:00:00')
+ * ```
  */
 export declare function isDate(options?: isDate.Options): import("../../core/validator.js").Validator<Date, string | number | Date, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isDate {
     type Precision = 'year' | 'yr' | 'month' | 'mo' | 'day' | 'd' | 'hours' | 'hr' | 'minutes' | 'min' | 'seconds' | 'sec' | 'milliseconds' | 'ms' | 'tz';
     interface Options extends ValidationOptions {
+        /** Zeroes out the resulting `Date`'s fields below this precision (e.g. `'day'` zeroes hours/minutes/seconds/ms); only `year` through `seconds` have an effect - `milliseconds`/`ms`/`tz` are no-ops. */
         trim?: Precision;
     }
 }
 /**
- * Validates if value is DFS (date-formatted string).
- * Converts input value to DFS if the "coerce" option is set to 'true'.
+ * Validates that the value is (or, with `coerce: true`, can be normalized
+ * into) a date-formatted string within a `[precisionMin, precisionMax]`
+ * range. Accepts ISO-8601-like strings as well as `Date`/`number` values
+ * when `coerce: true`.
  * @validator isDateString
+ * @param options - Validation options.
+ * @returns The original string when valid (or, with `coerce: true`, the
+ *   normalized/trimmed date string).
+ * @throws `Minimum date precision should be <precisionMin>` if the parsed
+ *   precision is below `precisionMin`.
+ * @throws `Maximum date precision should be <precisionMax>` if the parsed
+ *   precision is above `precisionMax` (and the input wasn't already a `Date`).
+ * @throws `Value "<input>" is not a valid date string` if the input can't
+ *   be parsed as a date at all.
+ * @example
+ * ```ts
+ * import { isDateString, vg } from 'valgen';
+ *
+ * isDateString('2020-01-10T08:30:15Z'); // => '2020-01-10T08:30:15Z'
+ * vg.isDateString({ precisionMin: 'day' })('2020-11-01'); // => '2020-11-01'
+ * vg.isDateString({ coerce: true, trim: true, precisionMax: 'day' })('2020-11-01T00:00:00+03:00');
+ * // => '2020-11-01'
+ * ```
  */
 export declare function isDateString(options?: isDateString.Options): import("../../core/validator.js").Validator<string, string | number | Date, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isDateString {
     type Precision = isDate.Precision;
     interface Options extends ValidationOptions {
+        /** The minimum precision the input string must carry (e.g. `'day'` rejects a bare year). @defaultValue 'minutes' */
         precisionMin?: Precision;
+        /** The maximum precision accepted; a string more precise than this fails unless the input was already a `Date`. @defaultValue 'tz' */
         precisionMax?: Precision;
+        /** When `coerce: true`, truncates the output string down to `precisionMax` instead of only validating precision. @defaultValue false */
         trim?: boolean;
+        /** When coercing, controls whether `-`/`:`/`T` separators are included in the output (`false` produces a compact form like `20201101102345.123`). @defaultValue true */
         separators?: boolean;
     }
 }

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

@@ -2,10 +2,27 @@ import * as datefns from 'date-fns';
 import {} from 'ts-gems';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if value is a "Date" instance. If the `coerce` option is `true`,
- * also accepts an ISO 8601 formatted date string or a numeric timestamp and
- * converts it to a Date instance.
+ * Validates that the value is a `Date` instance, with an optional
+ * precision-trimming step. With `coerce: true`, also accepts a `number`
+ * (epoch milliseconds) or a date-like `string` and converts it to a `Date`.
+ * Without `coerce`, a date *string* is rejected even if well-formed ISO
+ * 8601 - only actual `Date` instances validate by default.
  * @validator isDate
+ * @param options - Validation options.
+ * @returns The validated `Date` instance, with fields below `trim`'s
+ *   precision zeroed out when `trim` is given.
+ * @throws `Value is not valid date` if the input isn't (or can't be coerced
+ *   into) a valid `Date`.
+ * @example
+ * ```ts
+ * import { isDate, vg } from 'valgen';
+ *
+ * isDate(new Date(1)); // => new Date(1)
+ * isDate('2020-01-10T08:30:15Z', { coerce: true });
+ * // => new Date('2020-01-10T08:30:15Z')
+ * vg.isDate({ trim: 'day', coerce: true })('2020-05-10T08:30:15.123');
+ * // => new Date('2020-05-10T00:00:00')
+ * ```
  */
 export function isDate(options) {
     const trim = options?.trim;
@@ -34,9 +51,29 @@ export function isDate(options) {
     }, options);
 }
 /**
- * Validates if value is DFS (date-formatted string).
- * Converts input value to DFS if the "coerce" option is set to 'true'.
+ * Validates that the value is (or, with `coerce: true`, can be normalized
+ * into) a date-formatted string within a `[precisionMin, precisionMax]`
+ * range. Accepts ISO-8601-like strings as well as `Date`/`number` values
+ * when `coerce: true`.
  * @validator isDateString
+ * @param options - Validation options.
+ * @returns The original string when valid (or, with `coerce: true`, the
+ *   normalized/trimmed date string).
+ * @throws `Minimum date precision should be <precisionMin>` if the parsed
+ *   precision is below `precisionMin`.
+ * @throws `Maximum date precision should be <precisionMax>` if the parsed
+ *   precision is above `precisionMax` (and the input wasn't already a `Date`).
+ * @throws `Value "<input>" is not a valid date string` if the input can't
+ *   be parsed as a date at all.
+ * @example
+ * ```ts
+ * import { isDateString, vg } from 'valgen';
+ *
+ * isDateString('2020-01-10T08:30:15Z'); // => '2020-01-10T08:30:15Z'
+ * vg.isDateString({ precisionMin: 'day' })('2020-11-01'); // => '2020-11-01'
+ * vg.isDateString({ coerce: true, trim: true, precisionMax: 'day' })('2020-11-01T00:00:00+03:00');
+ * // => '2020-11-01'
+ * ```
  */
 export function isDateString(options) {
     const trim = options?.trim;

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

@@ -1,12 +1,34 @@
 import { type ValidationOptions, type Validator } from '../../core/index.js';
 /**
- * Validates if the given value is one of enum values.
+ * Validates that the value is one of a fixed set of enumeration members.
+ * `values` may be a single value, an array of allowed values, or a plain
+ * object/TypeScript enum (its non-numeric-key values are used, so both
+ * string enums and numeric enums with reverse mappings work correctly).
  * @validator isEnum
+ * @param values - The allowed value(s): a single value, an array, or an
+ *   object/enum whose values are used.
+ * @param options - Validation options.
+ * @returns The input value, unchanged (original casing is preserved even
+ *   under `caseInSensitive`).
+ * @throws `Value must be one of enumeration member` (suffixed
+ *   ` (<enumName>)` when `enumName` is set) if the value doesn't match any
+ *   allowed member, or is `null`/`undefined`.
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.isEnum(['a', 'b'])('a'); // => 'a'
+ * vg.isEnum(['a', 'b'], { enumName: 'Suit' })('c');
+ * // throws: 'Value must be one of enumeration member (Suit)'
+ * vg.isEnum(['A', 'B'], { caseInSensitive: true })('a'); // => 'a'
+ * ```
  */
 export declare function isEnum<T1>(values: any, options?: isEnum.Options): Validator<T1, any>;
 export declare namespace isEnum {
     interface Options extends ValidationOptions {
+        /** Compares `string` values case-insensitively (matching is done on `.toUpperCase()`), but the original input casing is returned. @defaultValue false */
         caseInSensitive?: boolean;
+        /** Included in the failure message as `... (enumName)` for clearer errors. */
         enumName?: string;
     }
 }

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

@@ -1,7 +1,27 @@
 import { validator, } from '../../core/index.js';
 /**
- * Validates if the given value is one of enum values.
+ * Validates that the value is one of a fixed set of enumeration members.
+ * `values` may be a single value, an array of allowed values, or a plain
+ * object/TypeScript enum (its non-numeric-key values are used, so both
+ * string enums and numeric enums with reverse mappings work correctly).
  * @validator isEnum
+ * @param values - The allowed value(s): a single value, an array, or an
+ *   object/enum whose values are used.
+ * @param options - Validation options.
+ * @returns The input value, unchanged (original casing is preserved even
+ *   under `caseInSensitive`).
+ * @throws `Value must be one of enumeration member` (suffixed
+ *   ` (<enumName>)` when `enumName` is set) if the value doesn't match any
+ *   allowed member, or is `null`/`undefined`.
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.isEnum(['a', 'b'])('a'); // => 'a'
+ * vg.isEnum(['a', 'b'], { enumName: 'Suit' })('c');
+ * // throws: 'Value must be one of enumeration member (Suit)'
+ * vg.isEnum(['A', 'B'], { caseInSensitive: true })('a'); // => 'a'
+ * ```
  */
 export function isEnum(values, options) {
     const caseInSensitive = !!options?.caseInSensitive;

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

@@ -1,8 +1,28 @@
 import type { Type } from 'ts-gems';
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if the value instance of given class or classes
+ * Validates that the value is an instance of a given class. With
+ * `coerce: true`, a *plain* object (per `@jsopen/objects`' `isPlainObject`)
+ * is mutated in place - via `Object.setPrototypeOf` - to become an instance
+ * of `clazz`; an object that is already an instance of some other class is
+ * not coerced.
  * @validator isInstanceOf
+ * @param clazz - The class the value must be an instance of.
+ * @param options - Validation options.
+ * @returns The input value, unchanged (or coerced in place into an
+ *   instance of `clazz`).
+ * @throws `Value must be an instance of "<clazz.name>"` if the input is
+ *   `null`, `undefined`, a primitive, or an instance of a different class.
+ * @example
+ * ```ts
+ * import { isInstanceOf, vg } from 'valgen';
+ *
+ * class Class1 {}
+ * const c1 = new Class1();
+ *
+ * isInstanceOf(Class1, c1); // => c1
+ * isInstanceOf(Class1, {}, { coerce: true }); // => instance of Class1
+ * ```
  */
 export declare function isInstanceOf<T extends object>(clazz: Type<T>, options?: isInstanceOf.Options): import("../../core/validator.js").Validator<T, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isInstanceOf {

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

@@ -1,8 +1,28 @@
 import { isPlainObject } from '@jsopen/objects';
 import { validator, } from '../../core/index.js';
 /**
- * Validates if the value instance of given class or classes
+ * Validates that the value is an instance of a given class. With
+ * `coerce: true`, a *plain* object (per `@jsopen/objects`' `isPlainObject`)
+ * is mutated in place - via `Object.setPrototypeOf` - to become an instance
+ * of `clazz`; an object that is already an instance of some other class is
+ * not coerced.
  * @validator isInstanceOf
+ * @param clazz - The class the value must be an instance of.
+ * @param options - Validation options.
+ * @returns The input value, unchanged (or coerced in place into an
+ *   instance of `clazz`).
+ * @throws `Value must be an instance of "<clazz.name>"` if the input is
+ *   `null`, `undefined`, a primitive, or an instance of a different class.
+ * @example
+ * ```ts
+ * import { isInstanceOf, vg } from 'valgen';
+ *
+ * class Class1 {}
+ * const c1 = new Class1();
+ *
+ * isInstanceOf(Class1, c1); // => c1
+ * isInstanceOf(Class1, {}, { coerce: true }); // => instance of Class1
+ * ```
  */
 export function isInstanceOf(clazz, options) {
     return validator(isInstanceOf.name, (input, context, _this) => {

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

@@ -1,8 +1,23 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if the value is "integer".
- * Converts the input value to an integer number if the coerce option is set to 'true'.
+ * Validates that the value is an integer `number`. With `coerce: true`,
+ * allows parsing a `string` (via `parseFloat`) or converting a lossless
+ * `bigint` into an integer `number`.
  * @validator isInteger
+ * @param options - Validation options.
+ * @returns The validated (and possibly coerced) integer `number`.
+ * @throws `Value must be a valid integer value` if the input is `NaN`, a
+ *   non-integer float, or (without coercion, or when coercion would lose
+ *   precision for a `bigint`) not an integer `number`.
+ * @example
+ * ```ts
+ * import { isInteger } from 'valgen';
+ *
+ * isInteger(1); // => 1
+ * isInteger('4', { coerce: true }); // => 4
+ * isInteger(10000000000000000001n, { coerce: true });
+ * // throws: 'Value must be a valid integer value' (precision would be lost)
+ * ```
  */
 export declare function isInteger(options?: isInteger.Options): import("../../core/validator.js").Validator<number, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isInteger {

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

@@ -1,8 +1,23 @@
 import { validator, } from '../../core/index.js';
 /**
- * Validates if the value is "integer".
- * Converts the input value to an integer number if the coerce option is set to 'true'.
+ * Validates that the value is an integer `number`. With `coerce: true`,
+ * allows parsing a `string` (via `parseFloat`) or converting a lossless
+ * `bigint` into an integer `number`.
  * @validator isInteger
+ * @param options - Validation options.
+ * @returns The validated (and possibly coerced) integer `number`.
+ * @throws `Value must be a valid integer value` if the input is `NaN`, a
+ *   non-integer float, or (without coercion, or when coercion would lose
+ *   precision for a `bigint`) not an integer `number`.
+ * @example
+ * ```ts
+ * import { isInteger } from 'valgen';
+ *
+ * isInteger(1); // => 1
+ * isInteger('4', { coerce: true }); // => 4
+ * isInteger(10000000000000000001n, { coerce: true });
+ * // throws: 'Value must be a valid integer value' (precision would be lost)
+ * ```
  */
 export function isInteger(options) {
     return validator(isInteger.name, (input, context, _this) => {

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

@@ -1,7 +1,17 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if the value is "null".
+ * Validates that the value is exactly `null`; even `undefined` fails.
  * @validator isNull
+ * @param options - Validation options.
+ * @returns `null`.
+ * @throws `Value must be null` if the input is anything other than `null`.
+ * @example
+ * ```ts
+ * import { isNull } from 'valgen';
+ *
+ * isNull(null); // => null
+ * isNull(undefined); // throws ValidationError: 'Value must be null'
+ * ```
  */
 export declare function isNull(options?: isNull.Options): import("../../core/validator.js").Validator<null, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isNull {
@@ -9,8 +19,20 @@ export declare namespace isNull {
     }
 }
 /**
- * Validates if the value is not "null".
+ * Validates that the value is anything other than `null` - notably,
+ * `undefined`, `''`, `0`, and `NaN` all pass.
  * @validator isNotNull
+ * @param options - Validation options.
+ * @returns The input value, unchanged.
+ * @throws `Value is null` if the input is `null`.
+ * @example
+ * ```ts
+ * import { isNotNull } from 'valgen';
+ *
+ * isNotNull(undefined); // => undefined
+ * isNotNull(0); // => 0
+ * isNotNull(null); // throws ValidationError: 'Value is null'
+ * ```
  */
 export declare function isNotNull(options?: isNotNull.Options): import("../../core/validator.js").Validator<unknown, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isNotNull {
@@ -18,8 +40,20 @@ export declare namespace isNotNull {
     }
 }
 /**
- * Validates if the value is "null" or "undefined".
+ * Validates that the value is `null` or `undefined`.
  * @validator isNullish
+ * @param options - Validation options.
+ * @returns The input value (`null` or `undefined`), unchanged.
+ * @throws `Value is not nullish` if the input is anything other than
+ *   `null` or `undefined`.
+ * @example
+ * ```ts
+ * import { isNullish } from 'valgen';
+ *
+ * isNullish(null); // => null
+ * isNullish(undefined); // => undefined
+ * isNullish(''); // throws ValidationError: 'Value is not nullish'
+ * ```
  */
 export declare function isNullish(options?: isNullish.Options): import("../../core/validator.js").Validator<null, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isNullish {
@@ -27,8 +61,21 @@ export declare namespace isNullish {
     }
 }
 /**
- * Validates if the value is not "null" nor "undefined".
+ * Validates that the value is neither `null` nor `undefined` - `0`, `''`,
+ * and `NaN` all pass.
  * @validator isNotNullish
+ * @param options - Validation options.
+ * @returns The input value, unchanged.
+ * @throws `Value is null` if the input is `null`.
+ * @throws `Value is undefined` if the input is `undefined`.
+ * @example
+ * ```ts
+ * import { isNotNullish } from 'valgen';
+ *
+ * isNotNullish(0); // => 0
+ * isNotNullish(null); // throws ValidationError: 'Value is null'
+ * isNotNullish(undefined); // throws ValidationError: 'Value is undefined'
+ * ```
  */
 export declare function isNotNullish(options?: isNotNullish.Options): import("../../core/validator.js").Validator<unknown, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isNotNullish {

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

@@ -1,7 +1,17 @@
 import { validator, } from '../../core/index.js';
 /**
- * Validates if the value is "null".
+ * Validates that the value is exactly `null`; even `undefined` fails.
  * @validator isNull
+ * @param options - Validation options.
+ * @returns `null`.
+ * @throws `Value must be null` if the input is anything other than `null`.
+ * @example
+ * ```ts
+ * import { isNull } from 'valgen';
+ *
+ * isNull(null); // => null
+ * isNull(undefined); // throws ValidationError: 'Value must be null'
+ * ```
  */
 export function isNull(options) {
     return validator(isNull.name, (input, context, _this) => {
@@ -11,8 +21,20 @@ export function isNull(options) {
     }, options);
 }
 /**
- * Validates if the value is not "null".
+ * Validates that the value is anything other than `null` - notably,
+ * `undefined`, `''`, `0`, and `NaN` all pass.
  * @validator isNotNull
+ * @param options - Validation options.
+ * @returns The input value, unchanged.
+ * @throws `Value is null` if the input is `null`.
+ * @example
+ * ```ts
+ * import { isNotNull } from 'valgen';
+ *
+ * isNotNull(undefined); // => undefined
+ * isNotNull(0); // => 0
+ * isNotNull(null); // throws ValidationError: 'Value is null'
+ * ```
  */
 export function isNotNull(options) {
     return validator(isNotNull.name, (input, context, _this) => {
@@ -22,8 +44,20 @@ export function isNotNull(options) {
     }, options);
 }
 /**
- * Validates if the value is "null" or "undefined".
+ * Validates that the value is `null` or `undefined`.
  * @validator isNullish
+ * @param options - Validation options.
+ * @returns The input value (`null` or `undefined`), unchanged.
+ * @throws `Value is not nullish` if the input is anything other than
+ *   `null` or `undefined`.
+ * @example
+ * ```ts
+ * import { isNullish } from 'valgen';
+ *
+ * isNullish(null); // => null
+ * isNullish(undefined); // => undefined
+ * isNullish(''); // throws ValidationError: 'Value is not nullish'
+ * ```
  */
 export function isNullish(options) {
     return validator(isNullish.name, (input, context, _this) => {
@@ -33,8 +67,21 @@ export function isNullish(options) {
     }, options);
 }
 /**
- * Validates if the value is not "null" nor "undefined".
+ * Validates that the value is neither `null` nor `undefined` - `0`, `''`,
+ * and `NaN` all pass.
  * @validator isNotNullish
+ * @param options - Validation options.
+ * @returns The input value, unchanged.
+ * @throws `Value is null` if the input is `null`.
+ * @throws `Value is undefined` if the input is `undefined`.
+ * @example
+ * ```ts
+ * import { isNotNullish } from 'valgen';
+ *
+ * isNotNullish(0); // => 0
+ * isNotNullish(null); // throws ValidationError: 'Value is null'
+ * isNotNullish(undefined); // throws ValidationError: 'Value is undefined'
+ * ```
  */
 export function isNotNullish(options) {
     return validator(isNotNullish.name, (input, context, _this) => {

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

@@ -1,8 +1,23 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if the value is a number.
- * Converts input value to number if the coerce option is set to 'true'.
+ * Validates that the value is a `number`. With `coerce: true`, allows
+ * parsing a `string` (via `parseFloat`) or converting a lossless `bigint`
+ * into a `number`.
  * @validator isNumber
+ * @param options - Validation options.
+ * @returns The validated (and possibly coerced) `number`.
+ * @throws `Value must be a number` if the input is `NaN`, `null`,
+ *   `undefined`, or (without coercion, or when coercion would lose
+ *   precision for a `bigint`) not a finite `number`.
+ * @example
+ * ```ts
+ * import { isNumber } from 'valgen';
+ *
+ * isNumber(1.1); // => 1.1
+ * isNumber('4.5', { coerce: true }); // => 4.5
+ * isNumber(10000000000000000001n, { coerce: true });
+ * // throws: 'Value must be a number' (precision would be lost)
+ * ```
  */
 export declare function isNumber(options?: isNumber.Options): import("../../core/validator.js").Validator<number, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isNumber {

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

@@ -1,8 +1,23 @@
 import { validator, } from '../../core/index.js';
 /**
- * Validates if the value is a number.
- * Converts input value to number if the coerce option is set to 'true'.
+ * Validates that the value is a `number`. With `coerce: true`, allows
+ * parsing a `string` (via `parseFloat`) or converting a lossless `bigint`
+ * into a `number`.
  * @validator isNumber
+ * @param options - Validation options.
+ * @returns The validated (and possibly coerced) `number`.
+ * @throws `Value must be a number` if the input is `NaN`, `null`,
+ *   `undefined`, or (without coercion, or when coercion would lose
+ *   precision for a `bigint`) not a finite `number`.
+ * @example
+ * ```ts
+ * import { isNumber } from 'valgen';
+ *
+ * isNumber(1.1); // => 1.1
+ * isNumber('4.5', { coerce: true }); // => 4.5
+ * isNumber(10000000000000000001n, { coerce: true });
+ * // throws: 'Value must be a number' (precision would be lost)
+ * ```
  */
 export function isNumber(options) {
     return validator(isNumber.name, (input, context, _this) => {