valgen 7.0.0 → 7.0.3

package/rules/utility-rules/nullable.js

@@ -1,6 +1,32 @@
 import { 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 function nullable(nested, options) {

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

@@ -1,13 +1,62 @@
 import type { ValidationOptions, Validator } from '../../core/index.js';
 type DiscriminatorRecord = Record<string, Validator>;
 /**
- * Tries each rule against the input in order and returns the first one that
- * passes. An optional discriminator record narrows which rule to try based
- * on a distinguishing field of the input.
+ * Tries a list of rules against the input in order and returns the result of
+ * the first one that passes.
+ *
+ * Each entry is either a plain {@link Validator}, or a
+ * `[Validator, discriminatorRecord]` tuple. For a plain entry, `oneOf` calls
+ * it directly; if it throws or fails, it moves on to the next entry
+ * (short-circuits on the first *success*, not the first failure). For a
+ * `[validator, discriminator]` tuple, `input` must be an object: `oneOf`
+ * first runs each rule in `discriminator` against the matching property of
+ * `input` (e.g. `discriminator.kind(input.kind)`); only if every
+ * discriminator key passes does it go on to run the tuple's main `validator`
+ * against the whole `input`. If any discriminator key fails (or `input`
+ * isn't an object), that entry is skipped entirely - the main validator
+ * never runs - and `oneOf` moves to the next candidate. This lets you
+ * dispatch between differently-shaped objects using a cheap "tag" check
+ * (e.g. a `kind` field) instead of trying and catching a full shape
+ * validation for each candidate. An unexpected exception thrown by a
+ * discriminator or a rule (as opposed to a normal validation failure) is
+ * caught and treated the same as a failure.
+ *
+ * @param rules - The candidates to try, in order: either a plain validator,
+ *   or a `[validator, discriminator]` tuple.
+ * @param options - Shared validation options (`coerce`, `onFail`); `oneOf`
+ *   has no options of its own.
+ * @returns A validator that returns the first candidate's result to pass.
+ * @throws {@link ValidationError} reporting the *last* candidate's own
+ *   failure message directly (a normal validation message, or an unexpected
+ *   exception's message) when no entry passes - since it can only report a
+ *   single message anyway, the actual reason is more useful than a vague
+ *   "didn't match". The generic `Value didn't match one of required rules`
+ *   message is only used as a fallback when nothing was actually tried (e.g.
+ *   an empty `rules` array).
+ *
+ * @example
+ * ```ts
+ * import { isNull, isNumber, isObject, isString, vg } from 'valgen';
+ *
+ * // simple form: first rule that passes wins
+ * const simple = vg.oneOf([isNull, isNumber]);
+ * simple(6); // => 6
+ * simple('x'); // throws: "Value must be a number" (the last candidate's own error, reported directly)
+ *
+ * // discriminated form: pick the object shape based on `kind`
+ * const pet = vg.oneOf([
+ *   isString,
+ *   [isObject, { kind: vg.isEqual('dog') }],
+ *   [isObject, { kind: vg.isEqual('cat') }],
+ *   vg.isEqual(5),
+ * ]);
+ * pet({ kind: 'cat', name: 'Molly' }); // => { kind: 'cat', name: 'Molly' }
+ * ```
  * @validator oneOf
  */
 export declare function oneOf(rules: (Validator | [Validator, DiscriminatorRecord])[], options?: oneOf.Options): Validator<any, any, import("../../core/types.js").ExecutionOptions>;
 export declare namespace oneOf {
+    /** Options accepted by {@link oneOf}. Only the shared {@link ValidationOptions} - no `oneOf`-specific fields. */
     interface Options extends ValidationOptions {
     }
 }

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

@@ -1,8 +1,56 @@
 import { validator } from '../../core/index.js';
 /**
- * Tries each rule against the input in order and returns the first one that
- * passes. An optional discriminator record narrows which rule to try based
- * on a distinguishing field of the input.
+ * Tries a list of rules against the input in order and returns the result of
+ * the first one that passes.
+ *
+ * Each entry is either a plain {@link Validator}, or a
+ * `[Validator, discriminatorRecord]` tuple. For a plain entry, `oneOf` calls
+ * it directly; if it throws or fails, it moves on to the next entry
+ * (short-circuits on the first *success*, not the first failure). For a
+ * `[validator, discriminator]` tuple, `input` must be an object: `oneOf`
+ * first runs each rule in `discriminator` against the matching property of
+ * `input` (e.g. `discriminator.kind(input.kind)`); only if every
+ * discriminator key passes does it go on to run the tuple's main `validator`
+ * against the whole `input`. If any discriminator key fails (or `input`
+ * isn't an object), that entry is skipped entirely - the main validator
+ * never runs - and `oneOf` moves to the next candidate. This lets you
+ * dispatch between differently-shaped objects using a cheap "tag" check
+ * (e.g. a `kind` field) instead of trying and catching a full shape
+ * validation for each candidate. An unexpected exception thrown by a
+ * discriminator or a rule (as opposed to a normal validation failure) is
+ * caught and treated the same as a failure.
+ *
+ * @param rules - The candidates to try, in order: either a plain validator,
+ *   or a `[validator, discriminator]` tuple.
+ * @param options - Shared validation options (`coerce`, `onFail`); `oneOf`
+ *   has no options of its own.
+ * @returns A validator that returns the first candidate's result to pass.
+ * @throws {@link ValidationError} reporting the *last* candidate's own
+ *   failure message directly (a normal validation message, or an unexpected
+ *   exception's message) when no entry passes - since it can only report a
+ *   single message anyway, the actual reason is more useful than a vague
+ *   "didn't match". The generic `Value didn't match one of required rules`
+ *   message is only used as a fallback when nothing was actually tried (e.g.
+ *   an empty `rules` array).
+ *
+ * @example
+ * ```ts
+ * import { isNull, isNumber, isObject, isString, vg } from 'valgen';
+ *
+ * // simple form: first rule that passes wins
+ * const simple = vg.oneOf([isNull, isNumber]);
+ * simple(6); // => 6
+ * simple('x'); // throws: "Value must be a number" (the last candidate's own error, reported directly)
+ *
+ * // discriminated form: pick the object shape based on `kind`
+ * const pet = vg.oneOf([
+ *   isString,
+ *   [isObject, { kind: vg.isEqual('dog') }],
+ *   [isObject, { kind: vg.isEqual('cat') }],
+ *   vg.isEqual(5),
+ * ]);
+ * pet({ kind: 'cat', name: 'Molly' }); // => { kind: 'cat', name: 'Molly' }
+ * ```
  * @validator oneOf
  */
 export function oneOf(rules, options) {
@@ -13,8 +61,21 @@ export function oneOf(rules, options) {
         let discriminator;
         let v;
         let passed = false;
-        // Mock fail method to prevent errors
-        context.fail = () => (passed = false);
+        // Every candidate failing is normal control flow here (that's how
+        // "try the next one" works), so a candidate's own context.fail must
+        // not throw or accumulate into the real error list. But swallowing it
+        // completely would hide the *reason* every candidate failed - including
+        // a genuine bug in a candidate rule, which would otherwise look
+        // identical to "the input just didn't match". So the mock still
+        // records the last failure's message, and it's reported directly as
+        // the final error (oneOf can only report one message anyway) instead
+        // of being discarded in favor of a generic one.
+        let lastFailMessage;
+        context.fail = (_rule, message) => {
+            passed = false;
+            lastFailMessage =
+                message instanceof Error ? message.message : String(message);
+        };
         for (i = 0; i < l; i++) {
             passed = true;
             if (Array.isArray(rules[i])) {
@@ -39,7 +100,16 @@ export function oneOf(rules, options) {
                     if (!passed)
                         continue;
                 }
-                catch {
+                catch (e) {
+                    // A discriminator/rule that throws directly (bypassing
+                    // context.fail entirely, e.g. a plain function rather than one
+                    // built with validator()) must still count as "this candidate
+                    // failed" - otherwise `passed` is left at its top-of-loop `true`
+                    // and, if this is the last candidate, oneOf would silently
+                    // return an unvalidated value instead of failing.
+                    passed = false;
+                    lastFailMessage =
+                        e?.message != null ? String(e.message) : String(e);
                     continue;
                 }
             }
@@ -51,14 +121,16 @@ export function oneOf(rules, options) {
                     if (passed)
                         break;
                 }
-                catch {
-                    //
+                catch (e) {
+                    passed = false;
+                    lastFailMessage =
+                        e?.message != null ? String(e.message) : String(e);
                 }
         }
         // Restore fail method
         delete context.fail;
         if (passed)
             return v;
-        context.fail(_this, `Value didn't match one of required rules`, input);
+        context.fail(_this, lastFailMessage || `Value didn't match one of required rules`, input);
     }, options);
 }

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

@@ -1,11 +1,39 @@
 import type { Maybe } from 'ts-gems';
 import { type ValidationOptions, type Validator } from '../../core/index.js';
 /**
- * Makes the sub-rule optional
+ * Wraps a rule so that `undefined` passes through untouched, and anything
+ * else (including `null`) is delegated to the nested rule.
+ *
+ * If `input === undefined`, it is returned as-is without calling the nested
+ * rule. Unlike {@link nullable}, `null` is **not** special-cased - it is
+ * passed straight through to the nested rule, so `optional(x)(null)` fails
+ * unless `x` itself accepts `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-`undefined` input.
+ * @param options - Shared validation options (`coerce`, `onFail`); `optional`
+ *   has no options of its own.
+ * @returns A validator that returns `undefined` unchanged, or the nested
+ *   rule's result for anything else.
+ * @throws Whatever `nested` throws when the input is not `undefined` and
+ *   fails the nested rule (including a `null` input, unless `nested` itself
+ *   accepts `null`).
+ *
+ * @example
+ * ```ts
+ * import { isString, vg } from 'valgen';
+ *
+ * vg.optional(isString)(''); // => ''
+ * vg.optional(isString)(undefined); // => undefined
+ * vg.optional(isString)(null); // throws (null is not undefined, and isString rejects null)
+ * ```
  * @validator optional
  */
 export declare function optional<T, I>(nested: Validator<T, I>, options?: optional.Options): Validator<Maybe<T>, Maybe<I>, import("../../core/types.js").ExecutionOptions>;
 export declare namespace optional {
+    /** Options accepted by {@link optional}. Only the shared {@link ValidationOptions} - no `optional`-specific fields. */
     interface Options extends ValidationOptions {
     }
 }

package/rules/utility-rules/optional.js

@@ -1,6 +1,33 @@
 import { validator, } from '../../core/index.js';
 /**
- * Makes the sub-rule optional
+ * Wraps a rule so that `undefined` passes through untouched, and anything
+ * else (including `null`) is delegated to the nested rule.
+ *
+ * If `input === undefined`, it is returned as-is without calling the nested
+ * rule. Unlike {@link nullable}, `null` is **not** special-cased - it is
+ * passed straight through to the nested rule, so `optional(x)(null)` fails
+ * unless `x` itself accepts `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-`undefined` input.
+ * @param options - Shared validation options (`coerce`, `onFail`); `optional`
+ *   has no options of its own.
+ * @returns A validator that returns `undefined` unchanged, or the nested
+ *   rule's result for anything else.
+ * @throws Whatever `nested` throws when the input is not `undefined` and
+ *   fails the nested rule (including a `null` input, unless `nested` itself
+ *   accepts `null`).
+ *
+ * @example
+ * ```ts
+ * import { isString, vg } from 'valgen';
+ *
+ * vg.optional(isString)(''); // => ''
+ * vg.optional(isString)(undefined); // => undefined
+ * vg.optional(isString)(null); // throws (null is not undefined, and isString rejects null)
+ * ```
  * @validator optional
  */
 export function optional(nested, options) {

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

@@ -1,11 +1,48 @@
 import { type ValidationOptions, type Validator } from '../../core/index.js';
 /**
- * Chains rules so each one's output becomes the next one's input.
+ * Chains a list of validators so that each one's output becomes the next
+ * one's input: `rules[0]`'s output becomes `rules[1]`'s input, and so on.
+ *
+ * Short-circuits on the first rule that records a failure: as soon as a step
+ * adds to the shared context's error list, `pipe` stops immediately and does
+ * not run the remaining rules. If every rule succeeds, returns the last
+ * rule's output - or, if `options.returnIndex` is given, the output of that
+ * specific step (even though later steps still ran for validation purposes).
+ *
+ * @typeParam T - The output type on success.
+ * @param rules - The validators to chain, in order.
+ * @param options - Validation options, including {@link pipe.Options.returnIndex}.
+ * @returns A validator that feeds the input through each rule in sequence
+ *   and returns the final (or `returnIndex`-selected) step's output.
+ * @throws {@link ValidationError} from whichever rule first records a failure.
+ *
+ * @example
+ * ```ts
+ * import { isBoolean, isNumber, isString, vg } from 'valgen';
+ *
+ * vg.pipe([isString, vg.matches(/^[a-z]+$/)])('abc'); // => 'abc'
+ *
+ * // each step's output feeds the next: string -> number -> boolean
+ * vg.pipe([isString, isNumber, isBoolean])(1, { coerce: true }); // => true
+ *
+ * // returnIndex pins the result to an earlier step, while later steps still validate
+ * vg.pipe([isString, isNumber, vg.isGte(5)], { returnIndex: 1 })('123', {
+ *   coerce: true,
+ * }); // => 123
+ * ```
  * @validator pipe
  */
 export declare function pipe<T>(rules: Validator[], options?: pipe.Options): Validator<T>;
 export declare namespace pipe {
+    /** Options accepted by {@link pipe}. */
     interface Options extends ValidationOptions {
+        /**
+         * Return the intermediate output produced after `rules[returnIndex]`
+         * instead of the final step's output. All steps still run (and their
+         * results still feed forward into subsequent steps) - this only changes
+         * which intermediate value is handed back to the caller.
+         * @defaultValue undefined (the last step's output is returned)
+         */
         returnIndex?: number;
     }
 }

package/rules/utility-rules/pipe.js

@@ -1,6 +1,35 @@
 import { validator, } from '../../core/index.js';
 /**
- * Chains rules so each one's output becomes the next one's input.
+ * Chains a list of validators so that each one's output becomes the next
+ * one's input: `rules[0]`'s output becomes `rules[1]`'s input, and so on.
+ *
+ * Short-circuits on the first rule that records a failure: as soon as a step
+ * adds to the shared context's error list, `pipe` stops immediately and does
+ * not run the remaining rules. If every rule succeeds, returns the last
+ * rule's output - or, if `options.returnIndex` is given, the output of that
+ * specific step (even though later steps still ran for validation purposes).
+ *
+ * @typeParam T - The output type on success.
+ * @param rules - The validators to chain, in order.
+ * @param options - Validation options, including {@link pipe.Options.returnIndex}.
+ * @returns A validator that feeds the input through each rule in sequence
+ *   and returns the final (or `returnIndex`-selected) step's output.
+ * @throws {@link ValidationError} from whichever rule first records a failure.
+ *
+ * @example
+ * ```ts
+ * import { isBoolean, isNumber, isString, vg } from 'valgen';
+ *
+ * vg.pipe([isString, vg.matches(/^[a-z]+$/)])('abc'); // => 'abc'
+ *
+ * // each step's output feeds the next: string -> number -> boolean
+ * vg.pipe([isString, isNumber, isBoolean])(1, { coerce: true }); // => true
+ *
+ * // returnIndex pins the result to an earlier step, while later steps still validate
+ * vg.pipe([isString, isNumber, vg.isGte(5)], { returnIndex: 1 })('123', {
+ *   coerce: true,
+ * }); // => 123
+ * ```
  * @validator pipe
  */
 export function pipe(rules, options) {

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

@@ -1,10 +1,48 @@
 import type { Nullish } from 'ts-gems';
 import { type ValidationOptions, type Validator } from '../../core/index.js';
 /**
- * Check if value is not nullish before calling nested rule
+ * Wraps a rule so that `null`/`undefined` input fails (or falls back to a
+ * default) before being handed to the nested rule.
+ *
+ * If `input == null` (i.e. `null` or `undefined`) and `options.default` is
+ * set, `input` is replaced with `options.default`. If, after that
+ * substitution, `input` is still `null`/`undefined` (no default was
+ * configured, or the default itself is nullish), it fails with
+ * `Value required`. Otherwise, delegates to `nested(input)` - so a
+ * configured `default` must itself satisfy the nested rule, or validation
+ * still fails (just with the nested rule's own error instead of
+ * `Value required`).
+ *
+ * @typeParam T - The nested validator's output type.
+ * @typeParam I - The nested validator's input type.
+ * @param nested - The validator to delegate to once the input is non-nullish.
+ * @param options - Validation options, including {@link RequiredValidatorOptions.default}.
+ * @returns A validator that returns the nested rule's result for a
+ *   non-nullish (or defaulted) input.
+ * @throws {@link ValidationError} with `Value required` when the input is
+ *   `null`/`undefined` and no usable default is configured; otherwise
+ *   whatever `nested` throws.
+ *
+ * @example
+ * ```ts
+ * import { isString, vg } from 'valgen';
+ *
+ * vg.required(isString)(''); // => ''
+ * vg.required(isString)(undefined); // throws: "Value required"
+ *
+ * // with a default value, substituted (and still validated) when input is nullish
+ * vg.required(isString, { default: 'hello world' })(undefined); // => 'hello world'
+ * ```
  * @validator required
  */
 export declare function required<T, I>(nested: Validator<T, I>, options?: RequiredValidatorOptions): Validator<Nullish<T>, I, import("../../core/types.js").ExecutionOptions>;
+/** Options accepted by {@link required}. */
 export interface RequiredValidatorOptions extends ValidationOptions {
+    /**
+     * Value substituted when `input` is `null` or `undefined`. The substituted
+     * default is then still run through the nested rule like any other input -
+     * it is not returned raw.
+     * @defaultValue undefined
+     */
     default?: any;
 }

package/rules/utility-rules/required.js

@@ -1,6 +1,37 @@
 import { validator, } from '../../core/index.js';
 /**
- * Check if value is not nullish before calling nested rule
+ * Wraps a rule so that `null`/`undefined` input fails (or falls back to a
+ * default) before being handed to the nested rule.
+ *
+ * If `input == null` (i.e. `null` or `undefined`) and `options.default` is
+ * set, `input` is replaced with `options.default`. If, after that
+ * substitution, `input` is still `null`/`undefined` (no default was
+ * configured, or the default itself is nullish), it fails with
+ * `Value required`. Otherwise, delegates to `nested(input)` - so a
+ * configured `default` must itself satisfy the nested rule, or validation
+ * still fails (just with the nested rule's own error instead of
+ * `Value required`).
+ *
+ * @typeParam T - The nested validator's output type.
+ * @typeParam I - The nested validator's input type.
+ * @param nested - The validator to delegate to once the input is non-nullish.
+ * @param options - Validation options, including {@link RequiredValidatorOptions.default}.
+ * @returns A validator that returns the nested rule's result for a
+ *   non-nullish (or defaulted) input.
+ * @throws {@link ValidationError} with `Value required` when the input is
+ *   `null`/`undefined` and no usable default is configured; otherwise
+ *   whatever `nested` throws.
+ *
+ * @example
+ * ```ts
+ * import { isString, vg } from 'valgen';
+ *
+ * vg.required(isString)(''); // => ''
+ * vg.required(isString)(undefined); // throws: "Value required"
+ *
+ * // with a default value, substituted (and still validated) when input is nullish
+ * vg.required(isString, { default: 'hello world' })(undefined); // => 'hello world'
+ * ```
  * @validator required
  */
 export function required(nested, options) {

package/rules/utility-rules/string-utils.d.ts

@@ -1,5 +1,29 @@
 /**
- * Applies "String.replace" method
+ * Runs `String(input).replace(searchValue, replacer)`, mirroring
+ * `String.prototype.replace`.
+ *
+ * `null`/`undefined` input is passed through unchanged (the replace is
+ * skipped). Any other input is coerced with `String(input)` and then
+ * `.replace(searchValue, replacer)` is applied, exactly like the native
+ * method - `searchValue` can be a string, a `RegExp` (with or without the
+ * global flag), or any object implementing `Symbol.replace`, and the
+ * replacer can be a literal string or a substitution callback.
+ *
+ * @param searchValue - The pattern to search for: a string, `RegExp`, or any
+ *   object implementing `Symbol.replace`.
+ * @param replacer - The replacement: a literal string, or a callback
+ *   returning the substitution for each match.
+ * @returns A validator that returns the replaced string, or the passed-through
+ *   nullish value.
+ * @throws Never fails/throws on its own.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.stringReplace(/-/g, '_')('a-b'); // => 'a_b'
+ * vg.stringReplace('-', '_')(null); // => null
+ * ```
  * @validator stringReplace
  */
 export declare function stringReplace(searchValue: string | RegExp, replaceValue: string): any;
@@ -11,7 +35,27 @@ export declare function stringReplace(searchValue: {
     [Symbol.replace](string: string, replacer: (substring: string, ...args: any[]) => string): string;
 }, replacer: (substring: string, ...args: any[]) => string): any;
 /**
- * Applies "String.split" method
+ * Runs `String(input).split(separator, limit)`, mirroring
+ * `String.prototype.split`.
+ *
+ * `null`/`undefined` input is passed through unchanged (the split is
+ * skipped). Any other input is coerced with `String(input)` and then
+ * `.split(separator, limit)` is applied, exactly like the native method.
+ *
+ * @param separator - The delimiter: a string, `RegExp`, or any object
+ *   implementing `Symbol.split`.
+ * @param limit - Maximum number of substrings to include in the result.
+ * @returns A validator that returns the resulting array, or the
+ *   passed-through nullish value.
+ * @throws Never fails/throws on its own.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.stringSplit(',')('a,b'); // => ['a', 'b']
+ * vg.stringSplit(',')(null); // => null
+ * ```
  * @validator split
  */
 export declare function stringSplit(separator: string | RegExp, limit?: number): any;
@@ -19,17 +63,67 @@ export declare function stringSplit(splitter: {
     [Symbol.split](string: string, limit?: number): string[];
 }, limit?: number): any;
 /**
- * Removes whitespace from both ends of a string
+ * Removes whitespace from both ends of a string, mirroring
+ * `String.prototype.trim`.
+ *
+ * `null`/`undefined` input is passed through unchanged. Any other input is
+ * coerced with `String(input)` and then `.trim()` is applied.
+ *
+ * @returns A validator that returns the trimmed string, or the
+ *   passed-through nullish value.
+ * @throws Never fails/throws on its own.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.trim()(' a '); // => 'a'
+ * vg.trim()(null); // => null
+ * ```
  * @validator trim
  */
 export declare function trim(): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 /**
- * Removes whitespace from the end of a string
+ * Removes whitespace from the end of a string, mirroring
+ * `String.prototype.trimEnd`.
+ *
+ * `null`/`undefined` input is passed through unchanged. Any other input is
+ * coerced with `String(input)` and then `.trimEnd()` is applied (leading
+ * whitespace is left untouched).
+ *
+ * @returns A validator that returns the trimmed string, or the
+ *   passed-through nullish value.
+ * @throws Never fails/throws on its own.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.trimEnd()(' a '); // => ' a'
+ * vg.trimEnd()(null); // => null
+ * ```
  * @validator trimEnd
  */
 export declare function trimEnd(): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;
 /**
- * Removes whitespace from the beginning of a string
+ * Removes whitespace from the beginning of a string, mirroring
+ * `String.prototype.trimStart`.
+ *
+ * `null`/`undefined` input is passed through unchanged. Any other input is
+ * coerced with `String(input)` and then `.trimStart()` is applied (trailing
+ * whitespace is left untouched).
+ *
+ * @returns A validator that returns the trimmed string, or the
+ *   passed-through nullish value.
+ * @throws Never fails/throws on its own.
+ *
+ * @example
+ * ```ts
+ * import { vg } from 'valgen';
+ *
+ * vg.trimStart()(' a '); // => 'a '
+ * vg.trimStart()(null); // => null
+ * ```
  * @validator trimStart
  */
 export declare function trimStart(): import("../../core/validator.js").Validator<string, string, import("../../core/types.js").ExecutionOptions>;