valgen 7.0.0 → 7.0.3

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

@@ -1,13 +1,46 @@
 import { type Type, type ValidationOptions, type Validator as Validator_ } from '../../core/index.js';
 /**
- * Validates the object according to schema. Converts properties according to
- * schema rules if the coerce option is set to 'true'. Supports
- * `additionalFields` (allow/strip/reject/validate unknown properties -
- * defaults to allowing them when no schema is given, and rejecting them
- * otherwise), `caseInSensitive` (match property names ignoring case), and
- * `detectCircular` (guard against circular references when the schema
- * validates itself, e.g. via `forwardRef`).
+ * Validates an object against a property `schema`, with support for nested
+ * schemas, renaming/relabeling fields via `[Validator, PropertyOptions]`
+ * tuples, controlling unknown properties via `additionalFields`,
+ * case-insensitive key matching via `caseInSensitive`, and
+ * circular-reference detection via `detectCircular`. Converts properties
+ * according to schema rules if the `coerce` option is set to `true`.
  * @validator isObject
+ * @typeParam T - The validated output object type.
+ * @typeParam I - The accepted input type.
+ * @param schema - Maps property keys to a `Validator` (or a
+ *   `[Validator, PropertyOptions]` tuple to customize the error `label` or
+ *   rename the output key via `as`); omit for a schema-less "is this an
+ *   object" check.
+ * @param options - Validation options.
+ * @returns The validated object; when `ctor` is set, its prototype is
+ *   `ctor.prototype` (so `instanceof ctor` is `true`). Properties whose
+ *   validated value is `undefined` are omitted from the output.
+ * @throws `Value must be an object` if the (possibly JSON-parsed) input is
+ *   not a non-null object.
+ * @throws `Object has no field '<key>' and does not accept additional
+ *   fields` (or `<name> has no field...` when `name`/`ctor` is set) if
+ *   `additionalFields: 'error'` and the input has an undeclared property.
+ * @throws Whatever the failing property's own rule throws, located at that
+ *   property's path (e.g. `address.country`).
+ * @example
+ * ```ts
+ * import { isNumber, isString, vg } from 'valgen';
+ *
+ * class Person {
+ *   declare name: string;
+ *   declare age: number;
+ * }
+ * const personDef: vg.isObject.Schema = {
+ *   name: [vg.required(isString), { label: 'Full Name', as: 'fullName' }],
+ *   age: [vg.required(isNumber), { label: 'Age' }],
+ * };
+ * const validatePerson = vg.isObject(personDef, { ctor: Person });
+ *
+ * validatePerson({ name: 'John', age: '22' }, { coerce: true });
+ * // => { fullName: 'John', age: 22 }  (instance of Person)
+ * ```
  */
 export declare function isObject<T extends object = object, I = object | string>(schema?: isObject.Schema, options?: isObject.Options<T>): isObject.Validator<T, I>;
 export declare namespace isObject {
@@ -20,10 +53,15 @@ export declare namespace isObject {
     };
     type Schema = Record<string | number, Validator_ | [Validator_, PropertyOptions]>;
     interface Options<T> extends ValidationOptions {
+        /** Used as the error `context` label for this object (e.g. a class name). @defaultValue `ctor?.name` */
         name?: string;
+        /** Sets the prototype of the output object to `ctor.prototype` (`instanceof ctor` becomes `true`); may also define static `[preValidation]`/`[postValidation]` hooks invoked before/after this rule's own logic. */
         ctor?: Type<T>;
+        /** Controls properties not declared in `schema`: `true` passes them through unchanged, `false` silently drops them, a `Validator` applies that rule to each of them, and `'error'` throws when any are present. @defaultValue `true` if `schema` is omitted entirely; otherwise `false` */
         additionalFields?: boolean | Validator_ | 'error';
+        /** Matches input property names to schema keys case-insensitively; on a case-insensitive duplicate (e.g. both `name` and `Name` present), only the first-encountered key is used. @defaultValue false */
         caseInSensitive?: boolean;
+        /** Tracks input objects already being converted (per root validation call) and returns the same (in-progress) output object instead of recursing infinitely when a cycle is found. @defaultValue false */
         detectCircular?: boolean;
     }
 }

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

@@ -1,14 +1,47 @@
 import { postValidation, preValidation } from '../../constants.js';
 import { isValidator, validator, } from '../../core/index.js';
 /**
- * Validates the object according to schema. Converts properties according to
- * schema rules if the coerce option is set to 'true'. Supports
- * `additionalFields` (allow/strip/reject/validate unknown properties -
- * defaults to allowing them when no schema is given, and rejecting them
- * otherwise), `caseInSensitive` (match property names ignoring case), and
- * `detectCircular` (guard against circular references when the schema
- * validates itself, e.g. via `forwardRef`).
+ * Validates an object against a property `schema`, with support for nested
+ * schemas, renaming/relabeling fields via `[Validator, PropertyOptions]`
+ * tuples, controlling unknown properties via `additionalFields`,
+ * case-insensitive key matching via `caseInSensitive`, and
+ * circular-reference detection via `detectCircular`. Converts properties
+ * according to schema rules if the `coerce` option is set to `true`.
  * @validator isObject
+ * @typeParam T - The validated output object type.
+ * @typeParam I - The accepted input type.
+ * @param schema - Maps property keys to a `Validator` (or a
+ *   `[Validator, PropertyOptions]` tuple to customize the error `label` or
+ *   rename the output key via `as`); omit for a schema-less "is this an
+ *   object" check.
+ * @param options - Validation options.
+ * @returns The validated object; when `ctor` is set, its prototype is
+ *   `ctor.prototype` (so `instanceof ctor` is `true`). Properties whose
+ *   validated value is `undefined` are omitted from the output.
+ * @throws `Value must be an object` if the (possibly JSON-parsed) input is
+ *   not a non-null object.
+ * @throws `Object has no field '<key>' and does not accept additional
+ *   fields` (or `<name> has no field...` when `name`/`ctor` is set) if
+ *   `additionalFields: 'error'` and the input has an undeclared property.
+ * @throws Whatever the failing property's own rule throws, located at that
+ *   property's path (e.g. `address.country`).
+ * @example
+ * ```ts
+ * import { isNumber, isString, vg } from 'valgen';
+ *
+ * class Person {
+ *   declare name: string;
+ *   declare age: number;
+ * }
+ * const personDef: vg.isObject.Schema = {
+ *   name: [vg.required(isString), { label: 'Full Name', as: 'fullName' }],
+ *   age: [vg.required(isNumber), { label: 'Age' }],
+ * };
+ * const validatePerson = vg.isObject(personDef, { ctor: Person });
+ *
+ * validatePerson({ name: 'John', age: '22' }, { coerce: true });
+ * // => { fullName: 'John', age: 22 }  (instance of Person)
+ * ```
  */
 export function isObject(schema, options) {
     const ctor = options?.ctor;

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

@@ -1,8 +1,27 @@
 import type { ValidationOptions, Validator } from '../../core/index.js';
 /**
- * Validates the record object according to given "key" and "value" rules
- * Converts properties according to rules if the coerce option is set to 'true'.
+ * Validates a plain object as a "dictionary": every key must satisfy
+ * `keyRule` and every value must satisfy `valueRule`. With `coerce: true`,
+ * both keys and values may be coerced by their respective rules.
  * @validator isRecord
+ * @param keyRule - Rule every own key of the input is validated against.
+ * @param valueRule - Rule every value of the input is validated against.
+ * @param options - Validation options.
+ * @returns An object with the validated (and possibly coerced) keys and values.
+ * @throws `Value must be an object` if the input is `null`, `undefined`, or
+ *   not an object.
+ * @throws `<key> is not a valid key. <underlying message>` if a key fails
+ *   `keyRule`.
+ * @example
+ * ```ts
+ * import { isAny, isString, vg } from 'valgen';
+ *
+ * const validate = vg.isRecord(isString, isAny);
+ * validate(null as any); // throws ValidationError: 'Value must be an object'
+ *
+ * vg.isRecord(isString, isString)({ a: 1 as any, b: true as any }, { coerce: true });
+ * // => { a: '1', b: 'true' }
+ * ```
  */
 export declare function isRecord<TKeys extends string | number | symbol, TValues>(keyRule: Validator<TKeys>, valueRule: Validator<TValues>, options?: isRecord.Options): Validator<Record<TKeys, TValues>, Record<TKeys, TValues>, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isRecord {

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

@@ -1,8 +1,27 @@
 import { validator } from '../../core/index.js';
 /**
- * Validates the record object according to given "key" and "value" rules
- * Converts properties according to rules if the coerce option is set to 'true'.
+ * Validates a plain object as a "dictionary": every key must satisfy
+ * `keyRule` and every value must satisfy `valueRule`. With `coerce: true`,
+ * both keys and values may be coerced by their respective rules.
  * @validator isRecord
+ * @param keyRule - Rule every own key of the input is validated against.
+ * @param valueRule - Rule every value of the input is validated against.
+ * @param options - Validation options.
+ * @returns An object with the validated (and possibly coerced) keys and values.
+ * @throws `Value must be an object` if the input is `null`, `undefined`, or
+ *   not an object.
+ * @throws `<key> is not a valid key. <underlying message>` if a key fails
+ *   `keyRule`.
+ * @example
+ * ```ts
+ * import { isAny, isString, vg } from 'valgen';
+ *
+ * const validate = vg.isRecord(isString, isAny);
+ * validate(null as any); // throws ValidationError: 'Value must be an object'
+ *
+ * vg.isRecord(isString, isString)({ a: 1 as any, b: true as any }, { coerce: true });
+ * // => { a: '1', b: 'true' }
+ * ```
  */
 export function isRecord(keyRule, valueRule, options) {
     return validator(isRecord.name, (input, context, _this) => {

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

@@ -1,8 +1,22 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if the value is a string.
- * Converts input value to string if the coerce option is set to 'true'.
+ * Validates that the value is a `string`. With `coerce: true`, converts any
+ * non-`string`, non-nullish value into a `string` - an object with a
+ * `toJSON` method is stringified via `toJSON()`, other objects via
+ * `JSON.stringify`, and everything else via `String()`.
  * @validator isString
+ * @param options - Validation options.
+ * @returns The validated (and possibly coerced) `string`.
+ * @throws `Value must be a string` if the input is `null`, `undefined`, or
+ *   (without coercion) not a `string`.
+ * @example
+ * ```ts
+ * import { isString } from 'valgen';
+ *
+ * isString('1'); // => '1'
+ * isString(1, { coerce: true }); // => '1'
+ * isString({ toJSON: () => 'test' }, { coerce: true }); // => 'test'
+ * ```
  */
 export declare function isString(options?: isString.Options): import("../../core/validator.js").Validator<string, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isString {

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

@@ -1,8 +1,22 @@
 import { validator, } from '../../core/index.js';
 /**
- * Validates if the value is a string.
- * Converts input value to string if the coerce option is set to 'true'.
+ * Validates that the value is a `string`. With `coerce: true`, converts any
+ * non-`string`, non-nullish value into a `string` - an object with a
+ * `toJSON` method is stringified via `toJSON()`, other objects via
+ * `JSON.stringify`, and everything else via `String()`.
  * @validator isString
+ * @param options - Validation options.
+ * @returns The validated (and possibly coerced) `string`.
+ * @throws `Value must be a string` if the input is `null`, `undefined`, or
+ *   (without coercion) not a `string`.
+ * @example
+ * ```ts
+ * import { isString } from 'valgen';
+ *
+ * isString('1'); // => '1'
+ * isString(1, { coerce: true }); // => '1'
+ * isString({ toJSON: () => 'test' }, { coerce: true }); // => 'test'
+ * ```
  */
 export function isString(options) {
     return validator(isString.name, (input, context, _this) => {

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

@@ -1,8 +1,27 @@
 import { type ValidationOptions, type Validator } from '../../core/index.js';
 /**
- * Validates if the value is "tuple" and applies validation for each item.
- * Converts input value to tuple if the coerce option is set to 'true'.
+ * Validates that the value is an array of a fixed length, applying a
+ * distinct validator to each positional item. With `coerce: true`, a
+ * non-array, non-null input is wrapped into a single-item array before
+ * validating (only useful when `items.length === 1`).
  * @validator isTuple
+ * @param items - The per-position validators; the input array must have
+ *   exactly this many elements.
+ * @param options - Validation options.
+ * @returns A new array with each item replaced by its validated (and
+ *   possibly coerced) value.
+ * @throws `Value must be a tuple` if the input is `null`, `undefined`, or
+ *   not an array (and not coercible into one).
+ * @throws `Value must be a tuple of length <N>` if the array's length
+ *   doesn't exactly match `items.length`.
+ * @example
+ * ```ts
+ * import { isBoolean, isNumber, isString, vg } from 'valgen';
+ *
+ * vg.isTuple([isBoolean])([true]); // => [true]
+ * vg.isTuple([isString, isNumber, isBoolean])([1, '2', 0], { coerce: true });
+ * // => ['1', 2, false]
+ * ```
  */
 export declare function isTuple<T1, I1>(items: [Validator<T1, I1>], options?: isTuple.Options): Validator<[T1], [I1]>;
 export declare function isTuple<T1, I1, T2, I2>(items: [Validator<T1, I1>, Validator<T2, I2>], options?: isTuple.Options): Validator<[T1, T2], [I1, I2]>;

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

@@ -1,10 +1,22 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if the value is undefined.
- * If `coerce` is `true`, always succeeds and returns `undefined` regardless
- * of the input value - "coerce" here means "force to undefined", not
- * "convert values that merely look like undefined".
+ * Validates that the value is `undefined`. With `coerce: true`, the rule
+ * never fails - every input, including `null` or `5`, resolves to
+ * `undefined` ("coerce" here means "force to undefined", not "convert
+ * values that merely look like undefined").
  * @validator isUndefined
+ * @param options - Validation options.
+ * @returns `undefined`.
+ * @throws `Value must be undefined` if the input is anything other than
+ *   `undefined` (and `coerce` is not set).
+ * @example
+ * ```ts
+ * import { isUndefined } from 'valgen';
+ *
+ * isUndefined(undefined); // => undefined
+ * isUndefined(5); // throws ValidationError: 'Value must be undefined'
+ * isUndefined(0, { coerce: true }); // => undefined
+ * ```
  */
 export declare function isUndefined(options?: isUndefined.Options): import("../../core/validator.js").Validator<any, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace isUndefined {

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

@@ -1,10 +1,22 @@
 import { validator, } from '../../core/index.js';
 /**
- * Validates if the value is undefined.
- * If `coerce` is `true`, always succeeds and returns `undefined` regardless
- * of the input value - "coerce" here means "force to undefined", not
- * "convert values that merely look like undefined".
+ * Validates that the value is `undefined`. With `coerce: true`, the rule
+ * never fails - every input, including `null` or `5`, resolves to
+ * `undefined` ("coerce" here means "force to undefined", not "convert
+ * values that merely look like undefined").
  * @validator isUndefined
+ * @param options - Validation options.
+ * @returns `undefined`.
+ * @throws `Value must be undefined` if the input is anything other than
+ *   `undefined` (and `coerce` is not set).
+ * @example
+ * ```ts
+ * import { isUndefined } from 'valgen';
+ *
+ * isUndefined(undefined); // => undefined
+ * isUndefined(5); // throws ValidationError: 'Value must be undefined'
+ * isUndefined(0, { coerce: true }); // => undefined
+ * ```
  */
 export function isUndefined(options) {
     return validator(isUndefined.name, (input, context, _this) => {

package/rules/utility-rules/all-of.d.ts

@@ -1,10 +1,37 @@
 import type { ValidationOptions, Validator } from '../../core/index.js';
 /**
- * Test given value against to all codecs and returns original input
+ * Runs every rule in `rules` against the same, unchanged input and requires
+ * all of them to pass. Unlike {@link pipe}, one rule's output never feeds
+ * into the next - every rule sees the original input.
+ *
+ * Does not short-circuit: every rule is evaluated even after an earlier one
+ * has already failed, so a failing input can surface issues from multiple
+ * rules at once. The accumulated failures are thrown together as a single
+ * `ValidationError` when the outermost call completes.
+ *
+ * @typeParam T - The output type on success (the unchanged input's type).
+ * @param rules - The validators to run, each against the same input.
+ * @param options - Shared validation options (`coerce`, `onFail`); `allOf`
+ *   has no options of its own.
+ * @returns A validator that returns the original input unchanged if every
+ *   rule in `rules` passes.
+ * @throws {@link ValidationError} if one or more rules fail - reporting each
+ *   failing rule's own message.
+ *
+ * @example
+ * ```ts
+ * import { isNumber, vg } from 'valgen';
+ *
+ * // must be a number AND greater than 5 AND less than 10
+ * const codec = vg.allOf([isNumber, vg.isGt(5), vg.isLt(10)]);
+ * codec(6); // => 6
+ * codec('x'); // throws: "Value must be a number"
+ * ```
  * @validator allOf
  */
 export declare function allOf<T = any>(rules: Validator[], options?: allOf.Options): Validator<T>;
 export declare namespace allOf {
+    /** Options accepted by {@link allOf}. Only the shared {@link ValidationOptions} - no `allOf`-specific fields. */
     interface Options extends ValidationOptions {
     }
 }

package/rules/utility-rules/all-of.js

@@ -1,6 +1,32 @@
 import { validator } from '../../core/index.js';
 /**
- * Test given value against to all codecs and returns original input
+ * Runs every rule in `rules` against the same, unchanged input and requires
+ * all of them to pass. Unlike {@link pipe}, one rule's output never feeds
+ * into the next - every rule sees the original input.
+ *
+ * Does not short-circuit: every rule is evaluated even after an earlier one
+ * has already failed, so a failing input can surface issues from multiple
+ * rules at once. The accumulated failures are thrown together as a single
+ * `ValidationError` when the outermost call completes.
+ *
+ * @typeParam T - The output type on success (the unchanged input's type).
+ * @param rules - The validators to run, each against the same input.
+ * @param options - Shared validation options (`coerce`, `onFail`); `allOf`
+ *   has no options of its own.
+ * @returns A validator that returns the original input unchanged if every
+ *   rule in `rules` passes.
+ * @throws {@link ValidationError} if one or more rules fail - reporting each
+ *   failing rule's own message.
+ *
+ * @example
+ * ```ts
+ * import { isNumber, vg } from 'valgen';
+ *
+ * // must be a number AND greater than 5 AND less than 10
+ * const codec = vg.allOf([isNumber, vg.isGt(5), vg.isLt(10)]);
+ * codec(6); // => 6
+ * codec('x'); // throws: "Value must be a number"
+ * ```
  * @validator allOf
  */
 export function allOf(rules, options) {

package/rules/utility-rules/exists.d.ts

@@ -1,10 +1,39 @@
 import { type ValidationOptions } from '../../core/index.js';
 /**
- * Validates if property exists
+ * Checks that a property is present on its parent object, independent of
+ * whether its value is `undefined`.
+ *
+ * Passes when `input !== undefined` (any defined value, including `null` or
+ * `0`, is fine). When `input === undefined`, it still passes if the
+ * surrounding object explicitly *has* the property (checked via
+ * `Object.getOwnPropertyDescriptor` on `context.scope`/`context.property`) -
+ * this only works when `exists()` is nested inside an object schema (e.g.
+ * `vg.isObject({...})`) that populates `context.scope`/`context.property`;
+ * used standalone, an `undefined` input always fails.
+ *
+ * @param options - Shared validation options (`coerce`, `onFail`); `exists`
+ *   has no options of its own.
+ * @returns A validator that returns the input unchanged when the property exists.
+ * @throws {@link ValidationError} with `` `{{label}}` must exist `` (e.g.
+ *   `` `a` must exist ``, or `Value must exist` at the root) when the
+ *   property is truly absent.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.exists()(0); // => 0
+ * vg.exists()(null); // => null
+ * vg.exists()(undefined); // throws: "Value must exist"
+ *
+ * const objVal = vg.isObject({ a: vg.exists() });
+ * objVal({}); // throws: "`a` must exist"
+ * ```
  * @validator exists
  */
 export declare function exists(options?: exists.Options): import("../../core/validator.js").Validator<any, unknown, import("../../core/types.js").ExecutionOptions>;
 export declare namespace exists {
+    /** Options accepted by {@link exists}. Only the shared {@link ValidationOptions} - no `exists`-specific fields. */
     interface Options extends ValidationOptions {
     }
 }

package/rules/utility-rules/exists.js

@@ -1,6 +1,34 @@
 import { validator, } from '../../core/index.js';
 /**
- * Validates if property exists
+ * Checks that a property is present on its parent object, independent of
+ * whether its value is `undefined`.
+ *
+ * Passes when `input !== undefined` (any defined value, including `null` or
+ * `0`, is fine). When `input === undefined`, it still passes if the
+ * surrounding object explicitly *has* the property (checked via
+ * `Object.getOwnPropertyDescriptor` on `context.scope`/`context.property`) -
+ * this only works when `exists()` is nested inside an object schema (e.g.
+ * `vg.isObject({...})`) that populates `context.scope`/`context.property`;
+ * used standalone, an `undefined` input always fails.
+ *
+ * @param options - Shared validation options (`coerce`, `onFail`); `exists`
+ *   has no options of its own.
+ * @returns A validator that returns the input unchanged when the property exists.
+ * @throws {@link ValidationError} with `` `{{label}}` must exist `` (e.g.
+ *   `` `a` must exist ``, or `Value must exist` at the root) when the
+ *   property is truly absent.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.exists()(0); // => 0
+ * vg.exists()(null); // => null
+ * vg.exists()(undefined); // throws: "Value must exist"
+ *
+ * const objVal = vg.isObject({ a: vg.exists() });
+ * objVal({}); // throws: "`a` must exist"
+ * ```
  * @validator exists
  */
 export function exists(options) {

package/rules/utility-rules/fixed.d.ts

@@ -1,5 +1,23 @@
 /**
- * Ignores the input and always returns the given constant value.
+ * Ignores whatever input it is given and always returns the same constant
+ * value. Never inspects or validates the input and never calls
+ * `context.fail` - it always succeeds. Useful for injecting a constant field
+ * into an object schema, or as the "otherwise" branch of another combinator
+ * (e.g. `iif`).
+ *
+ * @typeParam T - The type of the constant `value` returned on every call.
+ * @typeParam I - The (ignored) input type.
+ * @param value - The constant value to return, regardless of what is passed
+ *   in at call time.
+ * @returns A validator that always returns `value`.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.fixed(0)(1); // => 0
+ * vg.fixed(null)(1); // => null
+ * ```
  * @validator fixed
  */
 export declare function fixed<T, I>(value: T): import("../../core/validator.js").Validator<T, I, import("../../core/types.js").ExecutionOptions>;

package/rules/utility-rules/fixed.js

@@ -1,6 +1,24 @@
 import { validator } from '../../core/index.js';
 /**
- * Ignores the input and always returns the given constant value.
+ * Ignores whatever input it is given and always returns the same constant
+ * value. Never inspects or validates the input and never calls
+ * `context.fail` - it always succeeds. Useful for injecting a constant field
+ * into an object schema, or as the "otherwise" branch of another combinator
+ * (e.g. `iif`).
+ *
+ * @typeParam T - The type of the constant `value` returned on every call.
+ * @typeParam I - The (ignored) input type.
+ * @param value - The constant value to return, regardless of what is passed
+ *   in at call time.
+ * @returns A validator that always returns `value`.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.fixed(0)(1); // => 0
+ * vg.fixed(null)(1); // => null
+ * ```
  * @validator fixed
  */
 export function fixed(value) {

package/rules/utility-rules/get-length.d.ts

@@ -4,8 +4,31 @@ type ExtractLengthInput = string | any[] | ArrayBuffer | {
     size: number;
 };
 /**
- * Returns length of an Array, String, ArrayBuffer, Buffer, Set, Map, or any
- * object with a "length" or "size" property.
+ * Extracts a numeric length or size from a string, array, `ArrayBuffer`,
+ * `Set`/`Map`, or any object exposing a `length`/`size` property. Takes no
+ * options; it's typically piped into a comparison rule to enforce a min/max
+ * length.
+ *
+ * @returns A validator that returns `input.length` for strings and arrays,
+ *   `input.byteLength` for an `ArrayBuffer`, `input.length` for any object
+ *   with a numeric `length` property (checked before `size`), or otherwise
+ *   `input.size` for any object with a numeric `size` property (this covers
+ *   `Set` and `Map`).
+ * @throws {@link ValidationError} with `Unable to get length` for anything
+ *   else (e.g. numbers, booleans, plain objects without `length`/`size`).
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.getLength()('1234'); // => 4
+ * vg.getLength()([1, 2, 3, 4]); // => 4
+ * vg.getLength()(new Set([1, 2, 3, 4])); // => 4
+ *
+ * // combine with a comparison rule to enforce a minimum length
+ * const minLength3 = vg.pipe([vg.getLength(), vg.isGte(3)]);
+ * minLength3('ab'); // throws (length 2 < 3)
+ * ```
  * @validator getLength
  */
 export declare function getLength(): import("../../core/validator.js").Validator<number, ExtractLengthInput, import("../../core/types.js").ExecutionOptions>;

package/rules/utility-rules/get-length.js

@@ -1,7 +1,30 @@
 import { validator } from '../../core/index.js';
 /**
- * Returns length of an Array, String, ArrayBuffer, Buffer, Set, Map, or any
- * object with a "length" or "size" property.
+ * Extracts a numeric length or size from a string, array, `ArrayBuffer`,
+ * `Set`/`Map`, or any object exposing a `length`/`size` property. Takes no
+ * options; it's typically piped into a comparison rule to enforce a min/max
+ * length.
+ *
+ * @returns A validator that returns `input.length` for strings and arrays,
+ *   `input.byteLength` for an `ArrayBuffer`, `input.length` for any object
+ *   with a numeric `length` property (checked before `size`), or otherwise
+ *   `input.size` for any object with a numeric `size` property (this covers
+ *   `Set` and `Map`).
+ * @throws {@link ValidationError} with `Unable to get length` for anything
+ *   else (e.g. numbers, booleans, plain objects without `length`/`size`).
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.getLength()('1234'); // => 4
+ * vg.getLength()([1, 2, 3, 4]); // => 4
+ * vg.getLength()(new Set([1, 2, 3, 4])); // => 4
+ *
+ * // combine with a comparison rule to enforce a minimum length
+ * const minLength3 = vg.pipe([vg.getLength(), vg.isGte(3)]);
+ * minLength3('ab'); // throws (length 2 < 3)
+ * ```
  * @validator getLength
  */
 export function getLength() {

package/rules/utility-rules/nullable.d.ts

@@ -1,11 +1,38 @@
 import type { Nullish } from 'ts-gems';
 import { type ValidationOptions, type Validator } from '../../core/index.js';
 /**
- * Makes the sub-rule nullable (accepts undefined or null)
+ * Wraps a rule so that `null` or `undefined` pass through untouched, and
+ * anything else is delegated to the nested rule.
+ *
+ * If `input == null` (i.e. `null` **or** `undefined`), it is returned as-is
+ * without ever calling the nested rule - despite the name, `nullable`
+ * tolerates both `null` and `undefined`, not just `null`. For any other
+ * input, delegates to `nested(input)` and returns/throws exactly what the
+ * nested rule does.
+ *
+ * @typeParam T - The nested validator's output type.
+ * @typeParam I - The nested validator's input type.
+ * @param nested - The validator to delegate to for non-nullish input.
+ * @param options - Shared validation options (`coerce`, `onFail`); `nullable`
+ *   has no options of its own.
+ * @returns A validator that returns `null`/`undefined` unchanged, or the
+ *   nested rule's result for anything else.
+ * @throws Whatever `nested` throws when the input is non-nullish and fails
+ *   the nested rule.
+ *
+ * @example
+ * ```ts
+ * import { isString, vg } from 'valgen';
+ *
+ * vg.nullable(isString)(''); // => ''
+ * vg.nullable(isString)(undefined); // => undefined
+ * vg.nullable(isString)(null); // => null
+ * ```
  * @validator nullable
  */
 export declare function nullable<T, I>(nested: Validator<T, I>, options?: nullable.Options): Validator<Nullish<T>, Nullish<I>, import("../../core/types.js").ExecutionOptions>;
 export declare namespace nullable {
+    /** Options accepted by {@link nullable}. Only the shared {@link ValidationOptions} - no `nullable`-specific fields. */
     interface Options extends ValidationOptions {
     }
 }