valgen 7.0.0 → 7.0.3

package/rules/utility-rules/string-utils.js

@@ -14,7 +14,23 @@ export function stringSplit(splitter, limit) {
     });
 }
 /**
- * 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 function trim() {
@@ -26,7 +42,24 @@ export function trim() {
 }
 // *************************************************************
 /**
- * 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 function trimEnd() {
@@ -38,7 +71,24 @@ export function trimEnd() {
 }
 // *************************************************************
 /**
- * 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 function trimStart() {